## 1. Project Overview & Quickstart (altic-dev/CONTRIBUTING) # CONTRIBUTING Open-source repository altic-dev/CONTRIBUTING ### Repository Details - **Repository:** [altic-dev/CONTRIBUTING](https://github.com/altic-dev/CONTRIBUTING) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (altic-dev/docs) ## File: README.md # Mintlify Starter Kit Use the starter kit to get your docs deployed and ready to customize. Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with - Guide pages - Navigation - Customizations - API reference pages - Use of popular components **[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)** ## AI-assisted writing Set up your AI coding tool to work with Mintlify: ```bash npx skills add https://mintlify.com/docs ``` This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance. See the [AI tools guides](/ai-tools) for tool-specific setup. ## Development Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command: ``` npm i -g mint ``` Run the following command at the root of your documentation, where your `docs.json` is located: ``` mint dev ``` View your local preview at `http://localhost:3000`. ## Publishing changes Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. ## Need help? ### Troubleshooting - If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI. - If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. ### Resources - [Mintlify documentation](https://mintlify.com/docs) --- ## File: AGENTS.md > **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project. > For Mintlify product knowledge (components, configuration, writing standards), > install the Mintlify skill: `npx skills add https://mintlify.com/docs` # Documentation project instructions ## About this project - This is a documentation site built on [Mintlify](https://mintlify.com) - Pages are MDX files with YAML frontmatter - Configuration lives in `docs.json` - Use the Mintlify MCP server, `https://mcp.mintlify.com`, to edit content and settings via MCP - Use the Mintlify docs MCP server, `https://www.mintlify.com/docs/mcp`, to query information about using Mintlify via MCP ## Terminology {/* Add product-specific terms and preferred usage */} {/* Example: Use "workspace" not "project", "member" not "user" */} ## Style preferences {/* Add any project-specific style rules below */} - Use active voice and second person ("you") - Keep sentences concise — one idea per sentence - Use sentence case for headings - Bold for UI elements: Click **Settings** - Code formatting for file names, commands, paths, and code references ## Content boundaries {/* Define what should and shouldn't be documented */} {/* Example: Don't document internal admin features */} --- ## File: docs.json { "$schema": "https://mintlify.com/docs.json", "name": "Altic", "theme": "almond", "logo": { "light": "https://media.brand.dev/d8a69291-d9f0-4975-8ce8-5da1d560cd77.svg", "dark": "https://media.brand.dev/ad888a68-e307-4719-8ce4-6b5cb51c0c31.png" }, "favicon": "https://icons.duckduckgo.com/ip3/altic.dev.ico", "colors": { "primary": "#888889", "light": "#dbdcde" }, "font": { "headings": { "family": "Space Grotesk" } }, "navbar": { "primary": { "type": "github", "href": "https://github.com/altic-dev/FluidVoice" } }, "navigation": { "tabs": [ { "tab": "Docs", "groups": [ { "group": "Get Started", "pages": [ "introduction", "installation", "quickstart" ] }, { "group": "Core Features", "pages": [ "features/dictation-modes", "features/fluid-intelligence", "features/ai-enhancement", "features/per-app-prompts", "features/custom-dictionary", "features/history" ] }, { "group": "Speech Models", "pages": [ "models/overview", "models/choosing-a-model" ] }, { "group": "Configuration", "pages": [ "configuration/hotkeys", "configuration/overlay", "configuration/permissions", "configuration/updates" ] }, { "group": "Privacy & FAQ", "pages": [ "privacy", "faq" ] } ] }, { "tab": "Local API", "groups": [ { "group": "Overview", "pages": [ "api/overview", "api/authentication" ] }, { "group": "Endpoints", "pages": [ "api/health", "api/transcribe", "api/postprocess", "api/history", "api/dictionary" ] } ] } ] } } --- ## File: faq.mdx --- title: "FluidVoice Frequently Asked Questions and Common Answers" sidebarTitle: "FAQ" --- FluidVoice is a free, open-source macOS dictation app with on-device AI enhancement. If you're evaluating it, just getting started, or running into a question mid-setup, you'll find the most common answers below. Can't find what you're looking for? Join the community on [Discord](https://discord.gg/VUPHaKSvYV). Yes. FluidVoice is completely free and open source—no subscription, no paid tiers, no feature gating. The core dictation experience works out of the box at no cost. If FluidVoice is useful to you, you can support continued development (including future iOS and Windows work) through [GitHub Sponsors](https://github.com/sponsors/altic-dev). FluidVoice requires **macOS 15.0 Sequoia or later**. It will not run on older versions of macOS. You also need to grant microphone access for voice capture and accessibility permissions for typing into other apps. FluidVoice guides you through both during onboarding. Yes. FluidVoice supports Intel Macs using **Whisper models** (from version 1.5.1 onward). All other models—Nemotron, Parakeet, Cohere, and Apple Speech—require Apple Silicon. If you're on an Intel Mac, select a Whisper model during onboarding. FluidVoice supports a wide range of local speech recognition models: | Model | Best for | Download size | Hardware | |---|---|---|---| | Nemotron Speech 3.5 — Ultra Fast Low Latency | Streaming multilingual dictation | ~670 MB | Apple Silicon | | Nemotron 3.5 Multilingual | Higher-accuracy multilingual dictation | ~530 MB | Apple Silicon | | Parakeet Flash (Beta) | Lowest-latency English dictation | ~250 MB | Apple Silicon | | Parakeet TDT v3 | Fast multilingual dictation | ~500 MB | Apple Silicon | | Parakeet TDT v2 | Fast English-only dictation | ~500 MB | Apple Silicon | | Cohere Transcribe | High-accuracy multilingual dictation | ~1.4 GB | Apple Silicon | | Apple Speech | Zero-download native macOS speech | Built-in | Apple Silicon + Intel | | Whisper Tiny / Base / Small / Medium / Large | Broad compatibility, Intel support | ~75 MB – ~2.9 GB | Apple Silicon + Intel | Choose a model based on your language needs and how much disk space you want to use. **Fluid Intelligence** is a local AI runtime that runs the **Fluid-1** model directly on your Mac. It provides advanced on-device dictation enhancement: - Smart formatting and structure - Context-aware capitalization - Adaptive tone based on the active app - Post-processing of rough dictation into clean, polished text Everything runs locally—no cloud connection, no API key, and no data leaves your machine. Fluid Intelligence is fully optional and requires approximately **3.5 GB** of disk space for the model download. FluidVoice works great on its own without Fluid Intelligence. You can download and enable it during onboarding or at any time from Settings. Language support depends on which speech model you use: - **Nemotron Speech 3.5** — approximately 40 languages, including Spanish, Italian, Portuguese, Hindi, Korean, English, German, French, Russian, Turkish, Vietnamese, Dutch, Japanese, Arabic, Ukrainian, and more - **Parakeet Flash (Beta)** — English only - **Parakeet TDT v3** — 25 languages: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Russian, and Ukrainian - **Parakeet TDT v2** — English only - **Cohere Transcribe** — 14 languages: English, French, German, Italian, Spanish, Portuguese, Greek, Dutch, Polish, Mandarin Chinese, Japanese, Korean, Vietnamese, and Arabic - **Apple Speech** — depends on the speech recognition languages installed on your Mac - **Whisper** — up to 99 languages, depending on the model size you choose For the broadest language support, use Nemotron Speech 3.5 or Whisper. Yes. FluidVoice is local-first. All speech recognition runs on-device using local models—no internet connection is required for dictation. The only time FluidVoice requires a network connection is if you choose to use a cloud AI provider (OpenAI, Groq, or a custom provider) for post-processing. Fluid Intelligence and all built-in speech models run entirely offline. FluidVoice requires two permissions: 1. **Microphone** — to capture your voice for speech recognition. Without this, the hotkey does nothing. 2. **Accessibility** — to type transcribed text into any app via macOS Accessibility APIs. Without this, FluidVoice can transcribe but cannot insert text. FluidVoice requests both permissions during onboarding with guided instructions. You can also grant or revoke them at any time in **System Settings → Privacy & Security**. See the [Permissions guide](/configuration/permissions) for full details. No—not by default. Your voice recordings and transcribed text stay on your Mac. The only exception is if you explicitly choose a cloud AI provider (OpenAI, Groq, or a custom endpoint) for dictation enhancement. In that case, your transcription text is sent to that provider's API. If you use **Fluid Intelligence** instead, everything remains local. FluidVoice never sends your audio or text to ALTIC or any third party as part of normal operation. FluidVoice includes optional anonymous analytics (enabled by default) to help track app health and feature usage. **Collected:** - App version, build number, and macOS version - Low-cardinality feature and configuration flags (e.g., which mode is active) - Approximate usage ranges (not exact values) - High-level success and error outcomes **Never collected:** - Voice recordings, raw audio, or transcribed text - Selected text, prompts, or AI responses - Terminal commands, window titles, file paths, clipboard contents, or typed text - Any personal or private information To disable analytics, go to **Settings → Share Anonymous Analytics** and toggle it off. Install FluidVoice with Homebrew: ```bash brew install --cask fluidvoice ``` Or download the latest release directly from GitHub: [https://github.com/altic-dev/FluidVoice/releases/latest](https://github.com/altic-dev/FluidVoice/releases/latest) Connect with other FluidVoice users and follow development through these channels: - **Discord** — [discord.gg/VUPHaKSvYV](https://discord.gg/VUPHaKSvYV) — the main community hub for questions, feedback, and announcements - **GitHub** — [github.com/altic-dev/FluidVoice](https://github.com/altic-dev/FluidVoice) — source code, issues, and pull requests - **X / Twitter** — [@ALTIC_DEV](https://x.com/ALTIC_DEV) — development updates and announcements From **2026-02-23** onward, FluidVoice is licensed under the **GNU General Public License v3.0 (GPLv3)**. Versions published before that date were licensed under Apache License 2.0. You can read the full license in the [repository](https://github.com/altic-dev/FluidVoice/blob/main/LICENSE). --- ## File: index.mdx --- title: "FluidVoice: Private macOS Dictation and AI Enhancement" sidebarTitle: "Home" --- FluidVoice is a free, open-source macOS dictation app that keeps your voice and text entirely on your Mac. Pair it with Fluid-1 — the local AI model — for smart formatting, context-aware tone, and post-processing that never touches a server. Whether you want bare-bones fast dictation or a fully intelligent writing assistant, you're in the right place. Learn what FluidVoice is, how its two layers work together, and what you can do with it. Install FluidVoice, grant permissions, pick a model, and start dictating in under five minutes. Compare Nemotron, Parakeet, Cohere, Apple Speech, and Whisper to find the right fit for your language and latency needs. Integrate FluidVoice into your own tools with the built-in Local API — no cloud required. Run `brew install --cask fluidvoice` in Terminal, or download the latest release from GitHub. The app is free and requires no account. Allow microphone access so FluidVoice can hear you, and grant accessibility permissions so it can type into any app on your Mac. Pick a speech model during onboarding — start with Apple Speech for zero-download convenience or Parakeet TDT v3 for fast multilingual support. Then assign a global hotkey in Settings so you can trigger voice capture from any app. Press your hotkey, speak, and release. Your words land directly in whatever text field is focused — no copy-paste required. --- ## File: installation.mdx --- title: "Install FluidVoice via Homebrew or GitHub Direct Download" sidebarTitle: "Installation" --- FluidVoice is free and requires no account to install. You have two options: Homebrew (recommended for developers) or a direct download from FluidVoice website. ## System requirements Before installing, confirm your Mac meets the following requirements. | Requirement | Details | | --- | --- | | macOS version | 15.0 Sequoia or later | | Processor | Apple Silicon (M-series) recommended | | Intel Mac support | Whisper models only, from version 1.5.1\+ | | Microphone | Required for voice capture | | Accessibility permissions | Required for typing into other apps | | Disk space — voice model | ~1 GB | | Disk space — Fluid Intelligence | ~3.5 GB (optional) | If you are on an Intel Mac, FluidVoice still works — but only with Whisper models. All other speech models require Apple Silicon. ## Install FluidVoice Choose either method below. Both install the same release. ```bash Homebrew brew install --cask fluidvoice ``` ```bash Manual download # Visit the releases page and download the latest .dmg open https://github.com/altic-dev/FluidVoice/releases/latest ``` After the Homebrew command finishes, FluidVoice appears in your Applications folder and is ready to launch. If you used the manual download, open the `.dmg`, drag FluidVoice to Applications, then launch it from there. Homebrew makes future updates easy — run `brew upgrade --cask fluidvoice` any time to get the latest version. FluidVoice also supports in-app auto-updates for convenience. ## First launch and onboarding When you open FluidVoice for the first time, an onboarding flow guides you through the required setup: 1. **Microphone permission** — macOS will prompt you to allow microphone access. Click **Allow**. FluidVoice cannot capture your voice without this. 2. **Accessibility permission** — FluidVoice needs accessibility access to type into other apps via the macOS Accessibility API. Open **System Settings → Privacy & Security → Accessibility** and enable FluidVoice. 3. **Language and model selection** — FluidVoice recommends an optimal speech model based on your language selected. See the [Speech Models overview](/models/overview) for a full comparison. 4. **Fluid Intelligence setup (optional)** — download the local Fluid-1 AI model (~3.5 GB) for on-device dictation enhancement. You can skip this and add it later in Settings, or through the [FluidVoice overlay.](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/2b166cd9-8e19-41da-8730-582ec75f3769) 5. **Try dictation** — the onboarding flow includes a live dictation tryout so you can confirm everything works before closing the wizard. Both microphone access and accessibility permissions are required for core dictation functionality. If you skip the accessibility permission, FluidVoice can transcribe speech but cannot type the result into other apps. ## Disk space | Component | Size | Required? | | --- | --- | --- | | FluidVoice app | Small (\< 50 MB) | Yes | | Voice model (e.g. Parakeet TDT v3) | ~500 MB – ~1 GB | Yes (one model) | | Fluid Intelligence (Fluid-1 model) | ~3.5 GB | No — optional | You only need one voice model to get started. Apple Speech is built into macOS and requires no download at all, making it the fastest way to get up and running. But we do recommend Parakeet TDT v2 to achieve optimal accuracy. You can select this in the [Voice Engine settings](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/080f0b3a-68fd-4316-b547-2015b1df57ab). ## Intel Mac support Intel Mac support was added in FluidVoice 1.5.1. If you are on an Intel Mac, install FluidVoice and select a Whisper model during onboarding. Whisper supports up to 99 languages across five model sizes (Tiny to Large), so you have plenty of flexibility even without Apple Silicon. ## Updating FluidVoice FluidVoice checks for updates automatically. To update manually, go to **Settings → Automatic Updates** and click **Check for Updates**. You can also check for updates by right-clicking the FluidVoice icon in the menu bar. To get early access to new features, enable **Beta Releases** in the Settings page. --- ## File: introduction.mdx --- title: "FluidVoice: What It Is, How It Works, and Requirements" sidebarTitle: "Introduction" --- FluidVoice is a free, open-source dictation app for macOS that processes your voice entirely on your Mac. There are no subscriptions, no cloud accounts, and no data leaving your machine unless you explicitly choose a cloud AI provider. With over 70,000 downloads and a growing open-source community, FluidVoice is built for developers, writers, multilingual users, and anyone who wants a fast, private alternative to cloud-based dictation tools. ## Two layers, one local workflow FluidVoice is made up of two distinct components that work together. ### FluidVoice — the app FluidVoice is the open-source macOS app (GPLv3). It handles everything visible: the global hotkey, the live transcription overlay, local speech models, typing into any app via accessibility APIs, Custom Dictionary, Command Mode, Write Mode, transcription history, per-app configuration, file/ meeting transcription, and settings. The source code is publicly available on GitHub. ### Fluid-1 — the intelligence layer Fluid-1 is the local AI model that powers **Fluid Intelligence**, an optional on-device post-processing runtime. Once enabled, it cleans up rough dictation, applies context-aware capitalization and formatting, adapts tone to the active app, and handles dates, names, and numbers — all locally, with no API keys and no data leaving your Mac. Fluid Intelligence is privately maintained so the core dictation experience can remain free for everyone. FluidVoice works great on its own without Fluid Intelligence. The Fluid-1 model is an optional ~3.5 GB download you can add at any moment to further polish the text. ## Key capabilities **Dictation modes** Write Mode, and Command Mode needs a cloud AI provider. Please select an AI provider in the AI Enhancements page, and add an API key. - **Direct Dictation** — speak into any focused text field system-wide; your words land instantly via accessibility APIs. - **Edit Mode(Alpha)** — dictate new content inline or select existing text and rewrite it, all without leaving your current app. - **Command Mode(Alpha)** — control your Mac by voice: launch apps, trigger system shortcuts, and automate workflows hands-free. [**Fluid Intelligence**](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/f1a711a8-06a9-4086-9a34-679cb5f01f74) The Fluid-1 model runs locally and polishes every transcription before the text appears where your cursor is. It handles smart formatting, adaptive tone based on the focused app (casual in Slack, formal in Mail, structured in GitHub issues), auto-corrections, and context-aware capitalization — with zero data leaving your machine. You can toggle Fluid Intelligence through the [overlay](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/2b166cd9-8e19-41da-8730-582ec75f3769), or through the [AI Enhancements](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/8d613e06-4bba-4171-b81a-39e9fd030239) page. [**Multiple speech models**](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/64d3f7e5-8794-421b-8d0d-4fb3cbbca497) FluidVoice ships with support for eight model families, from the sub-250 MB Parakeet Flash to the multilingual Whisper Large. Each model has different language coverage, latency, and accuracy characteristics, so you can match the model to your workflow. You can learn how to choose between models [here](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/080f0b3a-68fd-4316-b547-2015b1df57ab). [**AI enhancement**](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/8d613e06-4bba-4171-b81a-39e9fd030239) Beyond Fluid Intelligence, you can connect OpenAI, Groq, or a custom provider for cloud-based post-processing through the AI Enhancement page. API keys are stored in macOS Keychain and never logged or transmitted by the app itself. See our [privacy info](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/db1a9b73-9d41-4401-863f-52b532833d71) for more information. [**Per-app prompts**](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/dae31b76-6683-4468-9014-35325c88d8b8) Assign different prompt sets to different apps so your dictation tone adapts automatically when you switch context. This feature is fully optional. [**Custom Dictionary**](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/f7a83c15-6659-489b-800d-5147daa3595f) FluidVoice exposes a local API so you can integrate dictation into your own tools, scripts, or workflows without any cloud dependency. ## System requirements | Requirement | Details | | --- | --- | | macOS version | 15.0 Sequoia or later | | Processor | Apple Silicon (M-series) recommended; required for most models | | Intel Mac support | Available via Whisper models (from version 1.5.1\+) | | Microphone | Required for voice capture | | Accessibility | Required for typing into other apps | | Disk space (voice model) | ~1 GB | | Disk space (Fluid Intelligence) | ~3.5 GB (optional) | FluidVoice requires macOS 15.0 Sequoia or later. It will not run on macOS 14 Sonoma or earlier. ## Where to go next Install via Homebrew or download the latest release from GitHub. Follow the step-by-step guide to go from install to first dictation. Compare all supported models and choose the right one for your language and latency needs. Connect OpenAI, Groq, or a custom provider for cloud-based post-processing. --- ## File: privacy.mdx --- title: "FluidVoice Privacy Policy: Local-First, No Data Sharing" sidebarTitle: "Privacy" --- _Last updated: July 5, 2026_ FluidVoice is a local-first macOS dictation app. We designed FluidVoice so your voice, audio, transcripts, selected text, prompts, and AI responses stay on your Mac unless you choose to use an external AI provider or another optional external service. ## Information We Do Not Collect FluidVoice does not collect or send the following to FluidVoice-operated servers: - Raw microphone audio - Transcription text - Selected text - Rewrite prompts or AI responses - Terminal commands or command outputs - Window titles, app names, file names, file paths, clipboard contents, or text you type - Account information, because FluidVoice does not require a FluidVoice account We do not use transcripts, audio, selected text, prompts, or AI responses to train AI models. ## Fluid-1 and Local AI Processing FluidVoice may include **Fluid-1**, also called **Fluid Intelligence**, a local post-processing model for dictation enhancement. When Fluid-1 is used, FluidVoice sends the transcript and limited context to the local Fluid Intelligence runtime on your Mac so the model can clean up formatting, punctuation, self-corrections, and transcription errors. Fluid-1 inference runs locally. Transcript text processed by Fluid-1 is not sent to FluidVoice servers for model processing. The Fluid-1 model file may be downloaded from a model hosting service, such as Hugging Face, and stored locally on your Mac. Model downloads are for retrieving model weights, not for processing your transcripts. FluidVoice may keep local in-memory runtime state, such as model sessions or prompt-prefix cache data, to improve performance. This is used for local inference performance and is not analytics data. ## Anonymous or Pseudonymous Analytics FluidVoice may collect anonymous or pseudonymous analytics to understand app health, reliability, performance, and feature usage. Analytics can be disabled at any time in **Settings → Share Anonymous Analytics**. Analytics may include: - App version, build number, macOS version, CPU architecture, chip family, and hardware model - A random anonymous install identifier - Coarse feature/configuration flags, such as whether streaming preview, AI processing, or Fluid-1 local processing is enabled - Usage buckets, such as word-count ranges rather than exact transcript text - Latency metrics, including transcription, post-processing, and local model runtime timing - High-level success, failure, and error categories - Provider/model metadata when relevant to performance or reliability Analytics do not include transcript content, raw audio, selected text, prompts, AI responses, clipboard contents, file paths, or terminal output. ## Local Data Stored on Your Mac FluidVoice stores app preferences locally on your Mac so the app can remember your settings. API keys for optional providers are stored in **macOS Keychain**. FluidVoice may also store local transcription history if **Save Transcription History** is enabled. This history can include raw and processed transcription text, timestamps, app/window context used for display, and related metadata. Audio history is separate and is disabled by default; if enabled, microphone audio is stored locally on your Mac with your history. Local model files, including Fluid-1 if installed, may be stored in Application Support on your Mac. Because FluidVoice does not store your transcripts or audio on FluidVoice servers, requests to access or delete that content should be handled locally in the app or on your Mac. You can disable transcription history and audio history in settings, and you can clear saved history from the app. ## Optional External Providers If you choose to enable a cloud AI provider, custom provider, or compatible local server, FluidVoice sends the text needed for that feature to the provider you configured. This may include transcribed text, selected text, prompts, or rewrite instructions, depending on the feature you use. Those providers process data under their own privacy policies. FluidVoice does not control their data practices. FluidVoice may also connect to external services to download speech or language models, check for updates, or submit anonymous or pseudonymous analytics. ## How We Use Information We use anonymous or pseudonymous analytics only to: - Measure app reliability and performance - Understand which features are used - Diagnose high-level error patterns - Improve transcription latency, local model performance, and product quality We do not sell personal information. We do not use FluidVoice analytics to track you across other apps or websites. ## Your Choices You can: - Disable anonymous or pseudonymous analytics in settings - Use local/on-device processing, including Fluid-1 where available - Avoid cloud AI providers - Disable transcription history - Disable audio history - Delete saved transcription history and audio history - Remove provider API keys from settings or macOS Keychain ## Contact For privacy questions, contact: [alticdev@gmail.com](mailto:alticdev@gmail.com) You can also open an issue at: [github.com/altic-dev/FluidVoice](https://github.com/altic-dev/FluidVoice) © 2026 FluidVoice. --- ## File: quickstart.mdx --- title: "FluidVoice Quickstart: Install, Permissions, and Dictate" sidebarTitle: "Quickstart" --- This guide walks you through everything you need to do to start dictating with FluidVoice. The first four steps are required; the remaining steps are optional enhancements you can add whenever you're ready. Most users are up and running in under five minutes. Install FluidVoice using Homebrew, by downloading the latest release from [GitHub](https://github.com/altic-dev/FluidVoice), or from [FluidVoice webpage](https://altic.dev/fluid) ```bash Homebrew brew install --cask fluidvoice ``` ```bash Manual download # Download the latest .dmg from GitHub Releases open https://github.com/altic-dev/FluidVoice/releases/latest ``` After installation, open FluidVoice from your Applications folder. The onboarding wizard starts automatically on first launch. FluidVoice requires macOS 15.0 Sequoia or later and an Apple Silicon Mac for most models. Intel Macs are supported via Whisper models (version 1.5.1\+). FluidVoice needs two permissions to work. macOS will prompt you for both during onboarding. **Microphone access** — allows FluidVoice to capture your voice. Without it, dictation cannot start. Click **Allow** when macOS shows the microphone prompt. **Accessibility access** — allows FluidVoice to type transcribed text directly into any app using the macOS Accessibility API. Without it, FluidVoice can transcribe but cannot insert text. To enable it, go to **System Settings → Privacy & Security → Accessibility** and toggle FluidVoice on. If you deny the accessibility permission, dictation will work but text will not be inserted into other apps. You can re-enable it at any time in System Settings. A global hotkey lets you trigger the dictation tool from any app without switching to FluidVoice. By default,**⌥ Option** key is set for trigger.** **For a custom key**,** open **Settings → Global Hotkey → Primary Dictation Shortcuts.** You can also personalize how you start and stop the recording: either by holding down the key (Hold mode), or a double-tap to start and stop recording (Toggle mode), or Auto mode. For this, go to **Settings → Global Hotkey → Activation Mode**. During onboarding, FluidVoice recommends you a speech model based on your language preferences. FluidVoice also offers you the option to pick a model of your choosing from our range of supported [models](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/64d3f7e5-8794-421b-8d0d-4fb3cbbca497). Each model offers a different balance of language support, latency, accuracy, and download size. You can either pick what FluidVoice recommends, or pick a model of your choosing. | Model | Best for | Languages | Size | | --- | --- | --- | --- | | Nemotron Speech 3.5 - Ultra fast low latency | Low latency with streaming multilingual | ~40 | ~670 MB | | Nemotron 3.5 Multilingual | Lower latency, Higher-accuracy multilingual | ~40 | ~530 MB | | Parakeet Flash (Beta) | Lowest-latency English | English | ~250 MB | | Parakeet TDT v3 | Fast multilingual default | 25 | ~500 MB | | Parakeet TDT v2 | Fast English-only | English | ~500 MB | | Cohere Transcribe | High-accuracy multilingual | 14 | ~1.4 GB | | Apple Speech | Zero-download, built-in | System languages | Built-in | | Whisper (Tiny–Large) | Broad compatibility, Intel | Up to 99 | ~75 MB–2.9 GB | If you're unsure, start with **Apple Speech** (no download required) or **Parakeet TDT v2 **for English, or **Parakeet TDT v3** for a fast multilingual experience on Apple Silicon. You can switch models at any time by going to the **Voice Engine** page. If you're on an Intel Mac, select a **Whisper** model. It's the only family that supports Intel hardware. Fluid Intelligence is a local AI layer that polishes your dictation after transcription — smart formatting, context-aware capitalization, adaptive tone per app, and handling of dates, names, and numbers. Everything runs on your Mac; no data leaves your machine. To enable it, click **Enable Fluid Intelligence** during onboarding, or go to **Settings → Fluid Intelligence** after setup. The Fluid-1 model download is approximately **3.5 GB**. Fluid Intelligence is completely optional. FluidVoice is fully functional without it. Enable it when you want on-device AI polish without any cloud dependency. Fluid Intelligence causes a very minimal delay in output, so FluidVoice gives you the option to toggle it on or off through the overlay itself. If you prefer cloud-based post-processing, you can also connect an AI provider for text enhancement. FluidVoice supports **OpenAI**, **Groq**, and **custom providers** (any OpenAI-compatible API endpoint). You can find more details on the [AI Enhancement](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/8d613e06-4bba-4171-b81a-39e9fd030239) page. Go to **AI Enhancement** **→ AI Providers** and enter your API key. Keys are stored securely in the macOS Keychain — not in the app, not in any log file. When macOS prompts for Keychain access, select **Always Allow** so FluidVoice can retrieve the key without interrupting your dictation flow. Cloud AI enhancement is opt-in. No text is sent to any external service unless you add a provider and enable enhancement. Press your hotkey, speak naturally, and press it again to stop recording. If you have turned on Hold activation mode in the Global Hotkey menu —  press your hotkey, speak naturally, and release. FluidVoice captures your voice, runs it through the locally downloaded speech model, and inserts the transcribed text directly into the focused text field — no copy-paste, no switching apps. - Use **Direct Dictation** for fast, inline text entry anywhere on your Mac. - Switch to **Edit Mode(alpha)  **to dictate into a dedicated overlay, or to select and rewrite existing text. - Switch to **Command Mode (alpha)** to control your Mac by voice — launch apps, trigger shortcuts, and run automations. The live overlay shows your words in real time as you speak, so you always know what's being captured. To get early access to new features before they ship in stable releases, go to **Settings → Automatic Updates → Beta Releases** and enable the beta channel. Beta builds are opt-in and you can switch back to stable at any time. --- ## File: .atlas-analysis.json { "projectType": "saas", "projectName": "FluidVoice", "projectDescription": "FluidVoice is a free, open-source macOS dictation app that uses on-device speech models and the optional Fluid-1 AI model to transcribe, format, and post-process voice input into any app — with zero data leaving your Mac.", "theme": "almond", "primaryColor": "#888889", "lightColor": "#dbdcde", "darkColor": null, "navigation": { "tabs": [ { "tab": "Docs", "groups": [ { "group": "Get Started", "pages": [ "introduction", "installation", "quickstart" ] }, { "group": "Core Features", "pages": [ "features/dictation-modes", "features/fluid-intelligence", "features/ai-enhancement", "features/per-app-prompts", "features/custom-dictionary", "features/history" ] }, { "group": "Speech Models", "pages": [ "models/overview", "models/choosing-a-model" ] }, { "group": "Configuration", "pages": [ "configuration/hotkeys", "configuration/overlay", "configuration/permissions", "configuration/updates" ] }, { "group": "Privacy & FAQ", "pages": [ "privacy", "faq" ] } ] }, { "tab": "Local API", "groups": [ { "group": "Overview", "pages": [ "api/overview", "api/authentication" ] }, { "group": "Endpoints", "pages": [ "api/health", "api/transcribe", "api/postprocess", "api/history", "api/dictionary" ] } ] } ] }, "keyFeatures": [ "On-device speech-to-text with multiple model options (Nemotron, Parakeet, Whisper, Apple Speech)", "Fluid Intelligence — local AI model for smart formatting, capitalization, and post-processing", "Command Mode — control macOS by voice (launch apps, run shortcuts, automate workflows)", "Write/Edit Mode — dictate or rewrite text in any text field across any app", "Per-app prompt profiles — adaptive tone and formatting per application", "System-wide global hotkey for instant voice capture from anywhere", "AI post-processing via OpenAI, Groq, custom providers, or fully local Fluid-1", "Custom dictionary — text replacements and vocabulary boost terms", "Local REST API for scripting and third-party integrations", "Audio history with budget controls and ZIP export", "Notch-aware overlay with configurable sizes", "40+ language support across models", "Auto-updates with optional beta channel", "Free and open source under GPLv3" ], "publicApiSurface": [ "GET /v1/health", "GET /v1/history", "POST /v1/transcribe", "POST /v1/postprocess", "GET /v1/dictionary/replacements", "POST /v1/dictionary/replacements", "GET /v1/dictionary/custom-words", "POST /v1/dictionary/custom-words" ] } --- ## File: api/authentication.mdx --- title: "FluidVoice Local API Security: Loopback-Only Access" sidebarTitle: "Security" --- The FluidVoice Local API does not use API keys, bearer tokens, or any other form of credential-based authentication. Instead, it relies entirely on network-level isolation: the server listens only on the loopback interface and rejects every connection that does not originate from `localhost`. ## How loopback restriction works When a new TCP connection arrives, FluidVoice checks the remote address before the request is even parsed. Connections from `127.0.0.1` (IPv4 loopback), `::1` (IPv6 loopback), or the hostname `localhost` are accepted. Every other remote address — including connections from other machines on your local network — is dropped immediately. This means you do **not** need to pass any header, query parameter, or token when calling the API. If your request reaches the server, it is already authorized by virtue of running on your Mac. The loopback restriction is the entire security boundary. Any process running as any user on your Mac can call the Local API. If you share your Mac with untrusted users or run untrusted software, keep this in mind — the API can read transcription history and modify your dictionary. ## What you do not need to do - You do not need to pass an `Authorization` header. - You do not need an API key or secret. - You do not need to configure any allowlist or token in FluidVoice settings. A minimal valid request looks like this — no credentials: ```bash curl http://localhost:47733/v1/health ``` ## Do not expose the port externally Do not forward port 47733 (or your custom port) through a reverse proxy, SSH tunnel, or firewall rule that makes it reachable from outside your Mac. The API has no authentication layer. Any process that can reach the port can read your transcription history and overwrite your dictionary without restriction. If you need to call the Local API from a remote machine, use an SSH local port forward instead of exposing the port directly: ```bash # Forward the remote FluidVoice port to your local machine over SSH ssh -L 47733:127.0.0.1:47733 your-mac-hostname ``` This keeps the traffic inside an encrypted SSH session and preserves the loopback-only guarantee on the remote Mac. --- ## File: api/dictionary.mdx --- title: "Dictionary API: Manage Replacements and Custom Words" sidebarTitle: "Dictionary" --- The Dictionary API gives you programmatic control over two features in FluidVoice: **text replacements** (trigger phrases that get substituted in your transcripts) and **custom words** (vocabulary hints that improve transcription accuracy for domain-specific terms). All four endpoints read from and write to the same data that FluidVoice uses live — changes take effect immediately. --- ## GET /v1/dictionary/replacements Returns all text replacement rules currently configured in FluidVoice. ```http GET /v1/dictionary/replacements ``` ### Example ```bash curl http://localhost:47733/v1/dictionary/replacements ``` ```json { "count": 2, "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "replacement": "123 Main Street, Springfield, IL 62701", "triggers": ["my address", "home address"] }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "replacement": "FluidVoice", "triggers": ["fluid voice", "fluidvoice"] } ] } ``` Total number of replacement rules in the list. Array of replacement rule objects. A UUID that uniquely identifies this replacement rule. Include this when updating a specific entry. One or more phrases that, when spoken, are replaced by `replacement` in the transcript. The text that replaces any matched trigger phrase. --- ## POST /v1/dictionary/replacements Adds new replacement rules or replaces all existing rules. Returns the updated full list. ```http POST /v1/dictionary/replacements ``` ### Write modes How incoming entries are merged with existing data. One of: - `"append"` *(default)* — adds new entries to the existing list. If an incoming entry has the same `id` or the same `replacement` (case-insensitive) as an existing one, the existing entry is updated in place. - `"replace"` — discards all existing replacement rules and stores only the entries you provide. ### Adding a single replacement The trigger phrases for this single entry. The replacement text for this single entry. ```bash curl http://localhost:47733/v1/dictionary/replacements \ -H "Content-Type: application/json" \ -d '{ "triggers": ["addr", "my address"], "replacement": "123 Main Street, Springfield, IL 62701" }' ``` ### Adding multiple replacements An array of replacement objects. Each object must include `triggers` and `replacement`. You may optionally include `id` to update a specific existing rule. ```bash curl http://localhost:47733/v1/dictionary/replacements \ -H "Content-Type: application/json" \ -d '{ "mode": "append", "entries": [ { "triggers": ["addr", "my address"], "replacement": "123 Main Street, Springfield, IL 62701" }, { "triggers": ["fluid voice", "fluidvoice"], "replacement": "FluidVoice" } ] }' ``` ### Replacing all rules ```bash curl http://localhost:47733/v1/dictionary/replacements \ -H "Content-Type: application/json" \ -d '{ "mode": "replace", "entries": [ { "triggers": ["my email"], "replacement": "alex@example.com" } ] }' ``` The response body is the same format as `GET /v1/dictionary/replacements`, reflecting the updated list. --- ## GET /v1/dictionary/custom-words Returns all custom vocabulary words currently configured in FluidVoice. ```http GET /v1/dictionary/custom-words ``` ### Example ```bash curl http://localhost:47733/v1/dictionary/custom-words ``` ```json { "count": 2, "items": [ { "aliases": ["fluid voice", "fluidvoice app"], "text": "FluidVoice", "weight": 1.5 }, { "aliases": [], "text": "kubernetes", "weight": 1.0 } ] } ``` Total number of custom words in the list. Array of custom word objects. The canonical form of the word or phrase as you want it to appear in transcripts. A boost weight that increases the likelihood the model will recognize this word. Higher values increase recognition probability. `null` uses the model's default weighting. Alternative phonetic spellings or spoken forms of the word (e.g. `["fluid voice", "fluidvoice app"]`). Helps the model recognize the word when it is pronounced in different ways. --- ## POST /v1/dictionary/custom-words Adds new custom words or replaces all existing custom words. Returns the updated full list. ```http POST /v1/dictionary/custom-words ``` ### Write modes How incoming entries are merged with existing data. One of: - `"append"` *(default)* — adds new words to the existing list. If an incoming word has the same `text` (case-insensitive) as an existing one, the existing entry is updated in place. - `"replace"` — discards all existing custom words and stores only the entries you provide. ### Adding a single custom word The canonical form of the word. Recognition boost weight. Omit to use the model default. Alternative phonetic forms. Omit or pass an empty array if not needed. ```bash curl http://localhost:47733/v1/dictionary/custom-words \ -H "Content-Type: application/json" \ -d '{ "text": "FluidVoice", "weight": 1.5, "aliases": ["fluid voice", "fluidvoice app"] }' ``` ### Adding multiple custom words ```bash curl http://localhost:47733/v1/dictionary/custom-words \ -H "Content-Type: application/json" \ -d '{ "mode": "append", "entries": [ { "text": "FluidVoice", "weight": 1.5, "aliases": ["fluid voice"] }, { "text": "kubernetes", "weight": 1.0, "aliases": ["kube", "k8s"] } ] }' ``` ### Replacing all custom words ```bash curl http://localhost:47733/v1/dictionary/custom-words \ -H "Content-Type: application/json" \ -d '{ "mode": "replace", "entries": [ { "text": "gRPC", "weight": 1.2, "aliases": ["grpc", "g-r-p-c"] } ] }' ``` The response body is the same format as `GET /v1/dictionary/custom-words`, reflecting the updated list. Custom words apply primarily to Parakeet models (Parakeet Flash, Parakeet TDT v3, and Parakeet TDT v2). Other speech models such as Apple Speech, Whisper, Nemotron, and Cohere Transcribe do not use the custom vocabulary boost terms from this API. --- ## File: api/health.mdx --- title: "GET /v1/health — FluidVoice Status and Version Check" sidebarTitle: "GET /v1/health" --- The health endpoint gives you a fast, lightweight way to confirm that FluidVoice is running and that the Local API is reachable. It returns the current app version, which you can use to guard against calling endpoints that may not exist in older releases. ## Request ```http GET /v1/health ``` No request body, query parameters, or headers are required. ## Response Always `"ok"` when the server is healthy and responding normally. The currently running FluidVoice app version string, for example `"1.6.0"`. Returns `"unknown"` if the version cannot be read from the app bundle. ## Example **Request** ```bash curl http://localhost:47733/v1/health ``` **Response** ```json { "status": "ok", "version": "1.6.0" } ``` ## Error responses | Status | Meaning | |--------|---------| | `404` | The path does not exist — check that you are using `/v1/health` exactly. | | `405` | You sent a non-GET method (e.g. POST) to this endpoint. | Call `/v1/health` at the start of any script that depends on the Local API. If the request fails to connect, FluidVoice is not running or the Local API is disabled. Direct users to **Settings → Advanced → Local API** to enable it. --- ## File: api/history.mdx --- title: "GET /v1/history — Browse Transcription History Entries" sidebarTitle: "GET /v1/history" --- The history endpoint returns a list of recent transcription entries from FluidVoice's local history store, ordered from most recent to oldest. Each entry includes both the raw speech model output and the final text after AI enhancement (if it was applied), along with metadata about which app and window were active at the time. ## Request ```http GET /v1/history ``` ### Query parameters The maximum number of history entries to return. Defaults to `100`. The maximum allowed value is `1000`. Values below `1` are clamped to `1`. Values above `1000` are clamped to `1000`. ### Examples **Fetch the most recent 100 entries (default):** ```bash curl "http://localhost:47733/v1/history" ``` **Fetch the 10 most recent entries:** ```bash curl "http://localhost:47733/v1/history?limit=10" ``` **Fetch up to 500 entries:** ```bash curl "http://localhost:47733/v1/history?limit=500" ``` ## Response ```json { "count": 2, "items": [ { "aiProcessingError": null, "appName": "Slack", "characterCount": 22, "finalText": "The deployment failed.", "id": "550e8400-e29b-41d4-a716-446655440000", "originalText": "hey so um the deploy broke", "processedText": "The deployment failed.", "rawText": "hey so um the deploy broke", "timestamp": "2025-01-15T09:41:00Z", "wasAIProcessed": true, "windowTitle": "#engineering" }, { "aiProcessingError": null, "appName": "Notion", "characterCount": 47, "finalText": "Add a section for onboarding docs to the wiki.", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "originalText": "add a section for onboarding docs to the wiki", "processedText": "Add a section for onboarding docs to the wiki.", "rawText": "add a section for onboarding docs to the wiki", "timestamp": "2025-01-15T09:38:22Z", "wasAIProcessed": true, "windowTitle": "Team Wiki" } ] } ``` The number of items returned in this response. Equal to or less than the requested `limit`. An array of transcription history entries, ordered from most recent to oldest. A UUID that uniquely identifies this history entry. The ISO 8601 date-time string recording when this dictation occurred (e.g. `"2025-01-15T09:41:00Z"`). The raw text produced directly by the speech model, before any AI enhancement. Same as `rawText`. The text that was ultimately typed into the target app. If AI enhancement ran successfully, this is the enhanced text. If enhancement was skipped or failed, this equals `rawText`. Same as `processedText`. The unmodified speech-model output. Alias for `originalText`. The text after AI post-processing. Alias for `finalText`. The name of the application that was frontmost when dictation occurred (e.g. `"Slack"`, `"Notion"`, `"Terminal"`). The title of the active window or document at the time of dictation (e.g. `"#engineering"`, `"Team Wiki"`). The number of characters in `finalText`. `true` if AI enhancement ran and produced a result for this entry; `false` if enhancement was skipped or not configured. An error message string if AI enhancement failed, or `null` if enhancement succeeded or was not attempted. ## Error responses | Status | Meaning | |--------|---------| | `405` | You used a method other than `GET`. | History entries are stored locally on your Mac. If you have not used FluidVoice yet, or if you have cleared history from the app, the `items` array will be empty and `count` will be `0`. --- ## File: api/overview.mdx --- title: "FluidVoice Local API: Automate Transcription Locally" sidebarTitle: "Overview" --- FluidVoice exposes a local HTTP server on your Mac that you can call from shell scripts, Raycast extensions, Automator actions, or any other tool that can make HTTP requests. The server listens exclusively on the loopback interface, so only processes running on your Mac can reach it — no authentication token is required, and no traffic ever leaves your machine. ## Base URL and default port ```text http://localhost:47733 ``` The default port is **47733**. If you change the port in settings, replace `47733` in every example with your chosen port. ## Request and response format All endpoints accept and return JSON unless otherwise noted. Every response sets `Content-Type: application/json; charset=utf-8`. Dates are formatted as ISO 8601 strings (e.g. `2025-01-15T09:41:00Z`). The maximum request body size is **25 MB** — requests larger than this are rejected with HTTP 413. ## Quick start Check that FluidVoice is running and get the current app version: ```bash curl http://localhost:47733/v1/health ``` ```json { "status": "ok", "version": "1.6.0" } ``` ## Security model The server only accepts connections from `127.0.0.1`, `::1`, or `localhost`. Any connection from a non-loopback address is dropped immediately. See [Security](/api/authentication) for details. ## Available endpoints | Method | Path | Description | | --- | --- | --- | | `GET` | `/v1/health` | Check that FluidVoice is running and retrieve the app version. | | `POST` | `/v1/transcribe` | Transcribe an audio file or raw audio bytes using the currently selected speech model. | | `POST` | `/v1/postprocess` | Run AI post-processing on a text string using the configured AI provider. | | `GET` | `/v1/history` | Retrieve recent transcription history entries. | | `GET` | `/v1/dictionary/replacements` | List all text replacement rules. | | `POST` | `/v1/dictionary/replacements` | Add or replace text replacement rules. | | `GET` | `/v1/dictionary/custom-words` | List custom vocabulary words used to boost transcription accuracy. | | `POST` | `/v1/dictionary/custom-words` | Add or replace custom vocabulary words. | ## Common use cases - **Shell scripts** — pipe audio files through FluidVoice from the terminal or a cron job. - **Raycast extensions** — trigger transcription or retrieve history without opening the app UI. - **Automator actions** — chain FluidVoice transcription into macOS workflows. - **Third-party integrations** — connect any tool that can send HTTP requests to a local server. - **Text pipelines** — transcribe audio in one step and call `/v1/postprocess` separately to polish the output on demand. --- ## File: api/postprocess.mdx --- title: "POST /v1/postprocess — AI Text Post-Processing API" sidebarTitle: "POST /v1/postprocess" --- The postprocess endpoint sends a text string through the AI enhancement pipeline configured in FluidVoice and returns polished output. This is the same enhancement step that runs automatically after dictation — you can call it independently to build multi-step pipelines where transcription and enhancement happen separately. FluidVoice uses whichever AI provider you have configured in **Settings → AI Enhancement**: Fluid Intelligence (fully local), OpenAI, Groq, a custom provider, or none. If no AI provider is enabled, the endpoint returns an error. ## Request ```http POST /v1/postprocess ``` The endpoint accepts either a JSON body or a plain text body. ### JSON body ```bash curl http://localhost:47733/v1/postprocess \ -H "Content-Type: application/json" \ -d '{"text": "hey so the deploy is scheduled for friday at nine am pacific right"}' ``` The raw transcription text to enhance. This is typically the unedited output from a speech model — informal, unpunctuated, or with filler words — that you want the AI provider to clean up. ### Plain text body If you prefer, send the text directly as a plain UTF-8 string with `Content-Type: text/plain`: ```bash curl http://localhost:47733/v1/postprocess \ -H "Content-Type: text/plain" \ -d "hey so the deploy is scheduled for friday at nine am pacific right" ``` ## Response ```json { "model": "fluid-1", "provider": "fluid-intelligence", "text": "The deployment is scheduled for Friday at 9 AM Pacific, right?" } ``` The enhanced, post-processed text returned by the AI provider. An identifier for the AI provider that processed the text (e.g. `"fluid-intelligence"`, `"openai"`, `"groq"`). The specific model used by the provider (e.g. `"fluid-1"`, `"gpt-4o"`, `"llama-3.3-70b-versatile"`). ## Error responses | Status | Body | Meaning | |--------|------|---------| | `400` | `{"error": "..."}` | No AI provider is configured, the text body is empty, or the provider returned an error. Check **Settings → AI Enhancement** to ensure a provider is enabled. | | `400` | `{"error": "Invalid JSON text payload."}` | The request had `Content-Type: application/json` but the body could not be parsed as JSON. | | `400` | `{"error": "Text body must be UTF-8."}` | A plain text body was sent but the bytes are not valid UTF-8. | If you have AI enhancement disabled in FluidVoice settings, this endpoint will return an error. Enable an AI provider in **Settings → AI Enhancement** before calling `/v1/postprocess`. You can chain `/v1/transcribe` and `/v1/postprocess` to build a two-step pipeline: transcribe an audio file first, then post-process the resulting text. This is useful when you want to inspect the raw transcript before enhancement, or when you want to apply enhancement to text from a different source. --- ## File: api/transcribe.mdx --- title: "POST /v1/transcribe — Transcribe Audio with FluidVoice" sidebarTitle: "POST /v1/transcribe" --- The transcribe endpoint runs speech recognition on audio you provide and returns the resulting transcript along with a confidence score and sample count. FluidVoice uses whichever speech model you have selected in **Settings → Speech Model** — you do not need to specify the model in your request. The endpoint accepts three input modes. Choose whichever is most convenient for your use case. ## Request ```http POST /v1/transcribe ``` Maximum request body size: **25 MB**. --- ### Mode A — File path (JSON body) Send a JSON object with the absolute path to an audio file already on disk. FluidVoice reads the file directly — no file upload required. ```bash curl http://localhost:47733/v1/transcribe \ -H "Content-Type: application/json" \ -d '{"path": "/Users/alex/Recordings/standup-notes.wav"}' ``` Absolute path to an audio file on disk. The file must be readable by FluidVoice. Supports any audio format that macOS AVFoundation can decode (WAV, M4A, AIFF, MP3, CAF, and others). --- ### Mode B — Base64-encoded audio (JSON body) Send a JSON object containing the audio data encoded as a base64 string. Include `filename` so FluidVoice can detect the audio format from the file extension. ```bash curl http://localhost:47733/v1/transcribe \ -H "Content-Type: application/json" \ -d '{ "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAA...", "filename": "recording.wav" }' ``` The raw audio file contents encoded as a standard base64 string. The decoded data must be a valid audio file in a format supported by macOS. A filename (e.g. `"recording.m4a"`) used to detect the audio format from the file extension. Defaults to `"audio.wav"` if omitted. Does not need to be a real file path — only the extension matters. --- ### Mode C — Raw audio bytes (binary body) Send the raw audio file bytes as the request body. Set `Content-Type` to the appropriate audio MIME type and use the `X-Filename` header to help FluidVoice identify the format. ```bash curl http://localhost:47733/v1/transcribe \ -H "Content-Type: audio/wav" \ -H "X-Filename: recording.wav" \ --data-binary @/Users/alex/Recordings/standup-notes.wav ``` The MIME type of the audio data, e.g. `audio/wav`, `audio/mp4`, `audio/aiff`. FluidVoice uses this as a hint but primarily relies on the file extension from `X-Filename`. A filename whose extension indicates the audio format (e.g. `"recording.wav"`, `"memo.m4a"`). Defaults to `"audio.wav"` if not provided. --- ## Response ```json { "confidence": 0.97, "provider": "Parakeet Flash", "sampleCount": 176400, "text": "The deployment is scheduled for Friday at nine AM Pacific." } ``` The transcribed text produced by the speech model. A confidence score between `0.0` and `1.0` indicating how certain the model is about the transcript. Higher is more confident. The number of audio samples processed. Divide by the sample rate (typically 16000 for most models) to get the audio duration in seconds. The display name of the speech model that produced the transcript, matching the model selected in FluidVoice settings (e.g. `"Parakeet Flash"`, `"Nemotron Speech 3.5"`, `"Apple Speech"`). ## Error responses | Status | Body | Meaning | |--------|------|---------| | `400` | `{"error": "Missing audio path or audioBase64."}` | The JSON body did not contain a valid `path` or `audioBase64` field. | | `400` | `{"error": "Missing audio body."}` | A binary request was sent with an empty body. | | `400` | `{"error": "Invalid JSON audio payload."}` | The request body could not be parsed as JSON. | | `413` | `{"error": "Request too large."}` | The request body exceeds 25 MB. | The transcription model used is always the one currently active in FluidVoice. If you need to use a specific model, change it in **Settings → Speech Model** before calling the endpoint. --- ## File: configuration/hotkeys.mdx --- title: "Configuring Global Hotkeys in FluidVoice for macOS" sidebarTitle: "Hotkeys" --- FluidVoice uses a global hotkey to start voice capture from any app on your Mac. Press your chosen key combination, speak, and your transcribed text lands wherever your cursor is—no switching windows, no clicking. This page explains how to set your hotkeys, choose an activation mode, and avoid conflicts with other apps. ## Primary and Secondary Hotkey Slots FluidVoice gives you two independent hotkey slots: - **Primary Dictation Shortcut** — your main trigger for dictation. This is the hotkey you'll use the vast majority of the time. - **Secondary Dictation Shortcut** — an optional second trigger you can assign to a different dictation profile or mode. For example, use your primary hotkey for casual dictation and your secondary for a formal-tone prompt profile. Both slots are configured independently and can use entirely different key combinations. ## How to Set a Hotkey Click the FluidVoice icon in your menu bar, then select **Settings**. Go to **Shortcuts**. Click the Change button to change your Hotkey shortcut, or select the Add shortcut button to add an additional Primary Dictation Shortcut Press the key or key combination you want to use. FluidVoice records it immediately. The field updates to show the captured shortcut. The **Option key (⌥) alone** is the recommended default. It's easy to reach, rarely conflicts with other apps, and is comfortable to hold during longer dictations. Other great options include **⌥Space** and **⌥⌘D**. ## Hotkey Activation Modes FluidVoice supports three activation modes. Choose the one that fits how you dictate: **Hold to record, release to stop.** Recording runs only while you keep the key pressed. Ideal for short, focused bursts. **Tap once to start, tap again to stop.** Great for longer dictations where you don't want to hold a key down. **Tap to toggle, hold for push-to-talk.** FluidVoice detects your intent and switches modes accordingly. To change the activation mode, go to **Settings → Hotkeys** and select your preferred mode from the **Activation Mode** picker. ## Avoiding Conflicts with Other Apps Global hotkeys intercept key combinations system-wide, so it's important to pick a combination that doesn't collide with shortcuts in apps you use regularly. **Tips for conflict-free hotkeys:** - **Use ⌥ (Option) alone.** Few apps claim the bare Option key as a global shortcut. - **Avoid ⌘-based combinations** like ⌘Space (Spotlight) or ⌘⇧4 (screenshot). - **Check your other apps.** Password managers, clipboard tools, and launcher apps often register their own global shortcuts. Open each app's settings to verify. - **Use the secondary slot** for a less-used combination rather than fighting for a prime key combo. If FluidVoice detects that your primary and secondary shortcuts conflict with each other, it displays a warning in Settings. --- ## File: configuration/overlay.mdx --- title: "Customize the FluidVoice Transcription Overlay Display" sidebarTitle: "Overlay" --- The FluidVoice overlay is a real-time transcription preview that appears on your screen while you speak. Words show up as they're recognized, giving you immediate visual feedback that the app is listening and accurately capturing what you say. The overlay is fully optional—you can resize it, reposition it, or turn it off entirely. ## Overlay Sizes FluidVoice offers four overlay sizes, ranging from minimal to expansive: A compact, pill-shaped indicator. Shows that recording is active without displaying transcription text. Ideal if you find the preview distracting. A small bar that shows a limited amount of live transcription text alongside the recording indicator. The default size. Displays a comfortable amount of transcription text in a floating panel. The largest overlay. Shows the most transcription text at once, useful for long-form dictation or when you want to closely track what's being captured. ## Overlay Position You can place the overlay at the **top** of your screen (in the notch area or floating) or at the **bottom**. The default position is bottom. To change the position, go to **Settings → Overlay → Overlay Position** and select your preferred placement. ### Notch-Aware Placement On MacBook models with a notch, FluidVoice can position the overlay so it fits cleanly around the notch rather than covering it. This keeps the overlay visible and unobtrusive at the same time. Notch overlay placement is only available on MacBook models equipped with a display notch (MacBook Pro 14-inch and 16-inch from 2021 or later, and MacBook Pro 13-inch notch models). On Macs without a notch, FluidVoice uses standard top positioning. ## How to Configure the Overlay Click the FluidVoice icon in your menu bar, then select **Settings**. Click on **Settings** sidebar, and go to **Overlay** Go to **Overlay Size**, and select your preferred overlay size: **Pill, Small, Medium, or Large.** Go to **Overlay Position,** and select **Top of Screen,** or **Bottom of Screen** for where the overlay appears on screen. Use the **Transcription Preview Length** slider to control how many characters of live transcription appear in the overlay. ## Transcription Preview Length The transcription preview character limit controls how much live text the overlay displays at once. You can set it anywhere from **50 to 800 characters**, in steps of 50. The default is **150 characters**. - **Lower values** (50–100) keep the overlay compact, showing only the most recently spoken words. - **Higher values** (400–800) display more context, useful when you want to review a longer passage while you're still speaking. ## Disabling the Overlay To hide the overlay entirely, set the size to **Pill** in **Settings → Overlay**. The pill indicator shows that FluidVoice is active without displaying any transcription text. You can also adjust the pill location by going to **Overlay → Bottom Ofset** to find the best bottom offset for the overlay for you. --- ## File: configuration/permissions.mdx --- title: "Required macOS Permissions for FluidVoice Dictation" sidebarTitle: "Permissions" --- FluidVoice needs two macOS permissions to work: **Microphone** access to capture your voice, and **Accessibility** access to type transcribed text into other apps. Without both permissions, dictation either can't start or can't deliver text where you need it. FluidVoice walks you through granting both during onboarding, but you can also grant or revoke them at any time through System Settings. ## Microphone Access ### Why it's needed FluidVoice records audio from your microphone and passes it to the on-device speech recognition model. Without microphone access, the app cannot hear you, and pressing your hotkey does nothing. ### How to grant microphone access Open **System Settings**. Select **Privacy & Security** in the sidebar. Click **Microphone** in the list of permission categories. Toggle **FluidVoice** on. ### What happens without it If FluidVoice doesn't have microphone access, pressing your hotkey produces no result. The app cannot record audio, so no transcription occurs. Check **System Settings → Privacy & Security → Microphone** if your hotkey appears to do nothing. --- ## Accessibility Access ### Why it's needed FluidVoice uses macOS Accessibility APIs to type transcribed text directly into any focused text field—whether that's a chat window, a code editor, a terminal, or a document. This is what makes system-wide dictation possible without clipboard interference. Without Accessibility permission, FluidVoice can transcribe your speech but **cannot type the resulting text into other apps**. You will see transcription in the overlay, but nothing will be inserted into the app you're using. ### How to grant accessibility access Go to **System Settings**. Select **Privacy & Security** in the sidebar. Click **Accessibility** in the list of permission categories. Toggle **FluidVoice** on. macOS may prompt you to unlock this section with your password or Touch ID. ### What happens without it Without Accessibility permission, FluidVoice can still run and transcribe audio, but it cannot insert text into other apps. **Command Mode** and **Edit Mode** specifically depend on Accessibility permission to send actions and text to other apps. If either mode isn't working, verify this permission is enabled. --- ## Guided Onboarding When you first launch FluidVoice, the onboarding flow requests both permissions with step-by-step instructions. Follow the prompts and grant access when macOS asks. If you skip a permission during onboarding, you can always return to **System Settings → Privacy & Security** to enable it later. ## Checking Your Current Permission Status To verify which permissions FluidVoice currently has: 1. Open **System Settings → Privacy & Security**. 2. Check **Microphone** — FluidVoice should appear with its toggle enabled. 3. Check **Accessibility** — FluidVoice should appear with its toggle enabled. If either toggle is off, enable it and relaunch FluidVoice. ## Revoking Permissions To revoke a permission, return to **System Settings → Privacy & Security**, find the relevant category, and toggle FluidVoice off. FluidVoice will stop using that permission immediately. You can re-enable it at any time. --- ## File: configuration/updates.mdx --- title: "Managing FluidVoice Updates and Beta Release Builds" sidebarTitle: "Updates" --- FluidVoice ships with automatic updates enabled by default. New releases bring new speech model support, feature additions, and bug fixes—and the update process runs in the background without interrupting your work. You can also opt into the beta channel to get new features and models before they reach the stable release. ## Automatic Updates FluidVoice checks for updates automatically and installs them when available. You don't need to do anything for your installation to stay current. To review or adjust update behavior: Click the FluidVoice icon in your menu bar, then select **Settings**. Select **Automatic Updates** in the Settings sidebar. Toggle automatic updates on or off, and optionally enable the beta channel. ## Beta Channel The beta channel gives you early access to features, new speech models, and improvements that are still being finalized before a stable release. To opt into beta builds: 1. Go to **Settings → App settings**. 2. Enable **Beta Releases**. FluidVoice will start receiving beta builds on your next update check. The beta channel is the fastest way to get access to new speech models and features—often weeks before they land in the stable release. If you're comfortable with occasional rough edges, it's worth enabling. Beta builds are less thoroughly tested than stable releases and may contain bugs or incomplete features. If you run into issues on a beta build, you can send us feedback by clicking on the **Feedback** page in the sidebar. You can even report an erroneous Transcription by going to **History**, and clicking on the Transcription, and then click the **Report** button in the **Transcription Details**. To opt out of Beta builds, you can disable the beta channel in Settings and wait for the next stable release. ## Checking for Updates Manually If you want to check for an update right now rather than waiting for the automatic check: - Click on FluidVoice in the macOS menu bar and select **Check for Updates**. - Alternatively, visit the [latest release page on GitHub](https://github.com/altic-dev/FluidVoice/releases/latest) to see what version is current and download it directly. ## What's in Each Release Each FluidVoice release may include: - **New speech model support** — additional models or updated versions of existing ones - **New features** — improvements to dictation modes, overlay, hotkeys, AI integration, and more - **Bug fixes** — stability improvements and corrections reported by the community - **Performance improvements** — faster transcription, lower latency, reduced resource usage Release notes for every version are published on the [GitHub releases page](https://github.com/altic-dev/FluidVoice/releases/latest). --- ## File: features/ai-enhancement.mdx --- title: "AI Enhancement: Cloud and Local Post-Processing" sidebarTitle: "AI Enhancement" --- AI Enhancement is an optional layer that sits between FluidVoice's speech model and your active app. After the speech model transcribes your voice, the enhancement provider receives the raw transcript, applies a system prompt to clean and reformat it, and returns the polished result — which FluidVoice then types into whatever app is in focus. You can use FluidVoice without any AI Enhancement configured, but enabling it transforms rough dictation into polished prose automatically. Use **Fluid Intelligence** if you want fully private AI enhancement for your dictation with no API key, no cost, and no data leaving your Mac. All processing happens on-device, including when you're offline. For **Edit Mode**, and **Command Mode**, in AI Enhancement, you will need to set an AI provider **other than Fluid Intelligence**. ## How to Add a Provider Go to **AI Enhancement** **→ AI Providers** Choose the provider from the provider list (eg. OpenAI). If you want Fluid Intelligence, select it and follow the model download prompt instead. Enter your API key in the key field. FluidVoice stores it securely in the **macOS Keychain** — it is never written to disk in plaintext or included in any log. When macOS asks about keychain access, select **Always allow**. Pick a model from the list. FluidVoice fetches available models for the provider automatically once the key is verified. Dictate a short sentence. The live preview overlay shows the raw transcript; the final text typed into the app reflects the AI-polished version. ## Setting Up a Custom Provider Custom providers let you connect FluidVoice to any OpenAI-compatible endpoint, including local model servers. In **AI Enhancement**, under **Providers**, click **Add Custom Provider** Provide the base URL of your endpoint. Examples: | Service | Base URL | | --- | --- | | Ollama (local) | `http://localhost:11434/v1` | | LM Studio (local) | `http://localhost:1234/v1` | | Self-hosted vLLM | `http://your-server:8000/v1` | | Enterprise proxy | `https://your-org.openai.azure.com/openai` | Type the model identifier exactly as your server expects it, for example `llama3.2`, `mistral`, or `deepseek-r1`. Local servers like Ollama typically don't require a key. Remote endpoints usually do. Leave the field empty if your server accepts unauthenticated requests. ## Per-Mode Enhancement FluidVoice applies AI Enhancement separately for **Dictate mode**, as compared to **Command Mode,** **Edit mode**. This means you can, for example, use Fluid Intelligence for standard dictation while using OpenAI for text rewrites — or disable enhancement entirely for one mode while keeping it active for the other. Configure each mode's provider and model independently in **Settings → AI Enhancement**. ## When Enhancement Runs AI Enhancement runs **after** the speech model finishes transcribing and **before** the text is typed into the active app. The sequence is: 1. You speak and release the hotkey. 2. The speech model transcribes your audio to a raw text string. 3. FluidVoice sends the raw transcript to your configured enhancement provider with the active system prompt. 4. The provider returns a cleaned, formatted version. 5. FluidVoice types the final result into the active app. The live preview overlay shows the raw transcript as you speak, then updates to the final polished text once enhancement completes. ## Disabling AI Enhancement To turn off AI Enhancement entirely, go to **AI Enhancement** and set the provider to **Off**. FluidVoice falls back to Direct Dictation: the raw transcript is typed into the active app without any post-processing. You can also disable enhancement for a specific mode (Dictate or Edit) while keeping it active for the other, using the per-mode controls in the same settings panel. API keys are stored in the macOS Keychain and are never transmitted except to the provider's own endpoint. FluidVoice does not collect or log your API keys, transcripts, or AI responses. --- ## File: features/custom-dictionary.mdx --- title: "Custom Dictionary: Replacements and Vocabulary Boost" sidebarTitle: "Custom Dictionary" --- FluidVoice's Custom Dictionary lets you teach the app your vocabulary, fix recurring transcription mistakes, and automatically clean up output. You can add words, define instant replacements, train the model by voice, and back everything up with JSON import/export. Changes to your dictionary take effect immediately — no app restart required. ## Open the Custom Dictionary - **From the menu bar:** Click the FluidVoice icon → **Custom Dictionary**. - **From the app:** Open **FluidVoice Settings → Custom Dictionary**. ## Your Dictionary Your Dictionary is your personal word list. Use it for names, jargon, technical terms, or anything FluidVoice should recognize but might not transcribe correctly out of the box. - Add a word or phrase you use often. - FluidVoice will prefer these entries during transcription. **Example entries:** | Word | Notes | | --- | --- | | `kubectl` | Technical CLI tool | | `GraphQL` | Product / technology name | | `Kubernetes` | Domain term | | `Xcode` | Apple product name | Vocabulary boosting applies to **Parakeet models** (Parakeet Flash, Parakeet TDT v3, Parakeet TDT v2). Other speech models handle custom words differently or may not support vocabulary injection. If you're using Whisper or Apple Speech, Instant Replacements are the more reliable tool for correcting specific words. ## Instant Replacements Instant Replacements correct text on the fly. When FluidVoice hears a trigger phrase, it immediately replaces it with whatever you define. - **Trigger:** what the speech model hears (e.g. `fluid voice`, `altic`). - **Replacement:** what should appear in the transcript instead. Replacements are applied live while you dictate. **Example entries:** | Triggers | Replacement | | --- | --- | | `addr`, `my address` | `123 Main Street, Springfield, IL 62701` | | `fluid voice`, `fluidvoice` | `FluidVoice` | | `open ai`, `openai` | `OpenAI` | | `sig` | Your email signature | ### Train a Replacement by Voice If a word is consistently misheard, use **Train by Voice** to fix it: Go to **Custom Dictionary → Train Replacement**. Enter the word or phrase you actually wanted. Record the way you naturally say it. Review the captured ASR variants. Save or merge the entry into your Instant Replacements. Newly trained replacements are placed at the top of your list so they're easy to find. ### Empty Replacements You can map a trigger to an **empty replacement** to delete unwanted text from the output. For example, map `¿` to nothing to prevent Spanish inverted question marks from appearing in your transcript. A replacement only needs at least one trigger to be valid; the replacement field can be left empty. ## Import and Export Your entire Custom Dictionary — both Instant Replacements and Custom Words — can be moved between devices or shared with teammates. - **Export:** produces a simple JSON file containing all replacement rules and custom words. - **Import:** choose whether to **merge** with your current dictionary or **replace** it entirely. Import/Export controls are in the header of the Custom Dictionary view. The exact JSON schema may vary by app version. Use the in-app export to get the current format. ## Automatic Dictionary Learning FluidVoice can learn from your corrections. When you fix a transcription error, the app can suggest or automatically add the corrected word or phrase to your dictionary over time, improving accuracy without manual training. ## API Access Power users can manage the dictionary programmatically via FluidVoice's local REST API: ```bash # List all replacements curl http://localhost:11111/v1/dictionary/replacements # Add a replacement (append mode) curl -X POST http://localhost:11111/v1/dictionary/replacements \ -H "Content-Type: application/json" \ -d '{"triggers": ["addr"], "replacement": "123 Main Street"}' # List all custom words curl http://localhost:11111/v1/dictionary/custom-words # Add a custom word curl -X POST http://localhost:11111/v1/dictionary/custom-words \ -H "Content-Type: application/json" \ -d '{"text": "kubectl"}' ``` ## Tips - **Keep triggers short and specific.** A single misheard word usually makes a better trigger than a long phrase. - **Order matters.** More specific replacements are typically checked first. - **Back up before replacing.** Use Export before large import/replace operations. - **Empty replacements** are useful for removing repeated filler words, punctuation, or artifacts from bilingual dictation. --- ## File: features/dictation-modes.mdx --- title: "FluidVoice Dictation Modes Explained" sidebarTitle: "Dictation Modes" --- FluidVoice gives you three distinct ways to put your voice to work. Direct Dictation gets raw speech on screen as fast as possible. Edit Mode sends your dictation through an AI layer that can rewrite your selected text, or add text to your textbox based on the instruction you speak. Command Mode turns your voice into a macOS automation agent: speak an instruction, and FluidVoice executes it. Switch between modes in an instant using dedicated hotkeys, so you can match your input method to whatever you're working on. You can also find the option to switch between modes on the overlay itself. To view a clear comparison between the modes, check out the Comparison box at the bottom of the page. ## Direct Dictation Direct Dictation is the fastest path from voice to text. FluidVoice transcribes your speech using the local model you've selected in Voice Engine page, and types the result straight into whichever textbox your cursor is in — no AI post-processing, no rewriting, no delay beyond the transcription itself. Use Direct Dictation when speed matters more than polish: coding, prompting, quick notes, chat messages, terminal commands, or any situation where you want exact control over what lands on screen. **Example — dictating a quick note:** You say: > "add milk eggs and bread to the shopping list" FluidVoice types: ```text add milk eggs and bread to the shopping list ``` The raw transcript lands exactly as spoken. ### How to activate Press your primary dictation hotkey (set during onboarding, or in **Settings → Global Hotkey**). The live preview overlay appears while you speak. Release the hotkey (or press it again, depending on your hotkey mode) to finish and type the result. Direct Dictation is the default mode when AI Enhancement is set to **Off**. Enable Fluid Intelligence or a cloud provider in **Settings → AI Enhancement** to switch to AI-assisted Write Mode automatically. ## Edit Mode Edit Mode requires an AI provider to be configured. At the moment, [Fluid Intelligence](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/f1a711a8-06a9-4086-9a34-679cb5f01f74) does not support Edit Mode. To set up an AI provider, go to **AI Enhancement → AI Providers.** Edit Mode is FluidVoice's AI text-editting assistant. It lets you either write new text based on your spoken instruction or edit text you already have selected. The performance of Edit Mode depends on the AI provider and the model you choose. To get the best results, make sure you choose the model that fits your workflow. ### What it does When you trigger Edit Mode, FluidVoice checks whether you have text selected in the active app: - **If text is selected**, it captures that text as context and you speak an instruction, e.g., "make this more formal," "shorten this," "fix the grammar", or "replace X word in this sentence with Y". - **If no text is selected**, you speak what you want the AI to write, e.g., "write a quick email to the team about the delay." The AI response appears in whichever text box your Cursor is placed in. **Example — rewriting selected text:** Select a rough paragraph in any app, then trigger Edit Mode and say: > "make this more concise and professional" FluidVoice rewrites the edited text in the place of the original text. **Example — writing from scratch:** With nothing selected, trigger Edit Mode and say: > "write a quick email to the team about the delay" FluidVoice writes the email in the textbox where your Cursor is. ### How to activate Press your Edit hotkey (default **⌥R**). Speak your instruction, then use the **Replace Original** or **Try Again** buttons in the Edit Mode window to apply or regenerate the result. ## Command Mode Command Mode requires an AI provider to be configured. At the moment, [Fluid Intelligence](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/f1a711a8-06a9-4086-9a34-679cb5f01f74) does not support Command Mode. To set up an AI provider, go to **AI Enhancement → AI Providers.** Command Mode turns your voice into a macOS automation agent. Speak a natural-language instruction and FluidVoice — powered by a language model — figures out what to do, runs the necessary system actions, verifies the result, and reports back. You can launch apps, run Shortcuts, manipulate files, create reminders, send messages, and automate workflows, all without touching the keyboard. The reliability of Command Mode is directly tied to the model you choose. More capable models plan, execute, and recover from errors more accurately, so pick a model that matches the complexity of the tasks you want to automate. Open the **Command Mode** page in the app to review your full command history, execution logs, error codes, instructions, and other diagnostic information for each session. This data is stored locally on your computer, and stays fully private. Command Mode runs an agentic loop: it checks prerequisites, executes the command, verifies the outcome, and retries or explains if something goes wrong. **Example — launching an app:** You say: > "open Safari and go to github dot com" FluidVoice executes: ```bash open -a Safari osascript -e 'tell application "Safari" to open location "https://github.com"' ``` **Example — creating a reminder:** You say: > "add a reminder to review the pull request tomorrow at 9 AM" FluidVoice executes: ```bash osascript -e 'tell application "Reminders" to make new reminder with properties {name:"Review the pull request", due date:date "tomorrow 9:00 AM"}' ``` **Example — file operations:** You say: > "create a folder called project-alpha in my Desktop" FluidVoice checks whether the folder exists, creates it, and confirms success. ### How to activate Enable Command Mode in **Settings → Command Mode**, assign a hotkey (default: **Right ⌘**), and press it to begin a session. Speak your instruction and wait for FluidVoice to complete the task. Command Mode can execute system commands on your Mac. Destructive operations (deleting files, moving items, running privileged commands) show a confirmation prompt before executing. Keep **Confirm before execute** enabled in **Settings → Command Mode** unless you have a specific reason to disable it. ## Switching Between Modes You can easily switch between different modes by selecting the mode you want on the FluidVoice overlay itself. If you want custom hotkeys to activate each mode separately, or you want a custom hotkey for a secondary dictation shortcut, the steps below walk you through the process. Open **Settings → Global Hotkey**. Assign separate hotkeys for your primary dictation shortcut, Edit Mode, and your Command Mode. You can also configure a secondary dictation shortcut that uses a different [prompt profile](https://app.mintlify.com/fluidvoice/fluidvoice/editor/main/~/dae31b76-6683-4468-9014-35325c88d8b8). Press your \*\*primary dictation hotkey **(default right ⌥) to start a Direct Dictation. Press your Command Mode hotkey (default right ⌘)** \*\* to start a Command Mode session. Press your **Edit hotkey** (default **⌥R**) after selecting text to rewrite it. The live preview overlay shows which mode is active and displays your transcription in real time as you speak. Release the hotkey to finish. ## Mode Comparison Edit Mode, and Command Mode require AI enhancement enabled, and an AI provider selected. Right now, Fluid Intelligence only works with Direct Dictation Mode, and not with Edit Mode, and Command Mode. Raw speech-to-text. No AI, no rewriting. Maximum speed, full control over output. Best for code, chat, quick notes. AI-polished dictation. Cleans filler words, fixes grammar, adapts tone. Also rewrites selected text on command. Voice-driven Mac automation. Launches apps, runs Shortcuts, manages files, creates reminders — all from natural speech. --- ## File: features/fluid-intelligence.mdx --- title: "Fluid Intelligence: Local AI Dictation Enhancement" sidebarTitle: "Fluid Intelligence" --- Fluid Intelligence is a local AI runtime that runs the **Fluid-1 model** directly on your Mac. When you dictate, Fluid-1 processes the raw speech transcript on your Computer before FluidVoice types anything into the active app — cleaning up filler words, applying correct capitalization, formatting numbers and dates, and adapting the tone to the app you're working in. Everything happens on-device. No data leaves your Mac, no API key is required, and no subscription is involved. Fluid Intelligence is entirely optional: FluidVoice works great without it. Fluid Intelligence requires an **Apple Silicon Mac** (M1 or later). It is not available on Intel Macs. The model download is approximately **3.5 GB**. We recommend using Fluid Intelligence when you accuracy is a bigger priority for you than speed. Because it is an additional AI layer on top of the Voice Engine, the transcription processing may take a few seconds. ## What Fluid-1 Does Fluid-1 is a small model trained on 100K\+ dictation data points, and purpose-built for dictation post-processing. Unlike general-purpose language models, it is tuned specifically to turn raw spoken transcripts into polished, correctly formatted text. Its capabilities include: Adds correct punctuation, paragraph breaks, and structure. Spoken instructions like "new line", "make a list", "new paragraph" are executed rather than transcribed. Capitalizes sentence starts, proper nouns, and headings correctly based on the surrounding context — not just simple rules. Detects the active app and adjusts tone automatically. Slack gets casual, Mail gets formal, GitHub Issues gets structured — using your per-app prompt profiles. Converts spoken numbers and times to their correct written form: "five thirty" → 5:30, "twelve fifty dollars" → \$12.50, "december twenty fifth" → December 25th. Removes "um", "uh", "like", "you know", and false starts so your dictated text reads like something you meant to write. Converts spoken emoji names to the actual emoji: "thumbs up emoji" → 👍, "heart emoji" → ❤️, "fire emoji" → 🔥. Correctly formats hyphenated words, compound terms, and technical phrases that speech models often run together. Detects spoken corrections ("no wait", "scratch that", "actually") and discards the text before them, keeping only what you meant to say. ## Fluid Intelligence vs. Cloud AI Providers FluidVoice supports several AI enhancement providers, including OpenAI and Groq. Fluid Intelligence is different in every meaningful way: | | Fluid Intelligence | Cloud Providers (OpenAI, Groq) | | --- | --- | --- | | **Runs on** | Your Mac, locally | Remote servers | | **Data leaves your Mac** | Never | Yes (transcripts sent to provider) | | **API key required** | No | Yes | | **Cost** | Free | Pay-per-use or subscription | | **Download required** | ~3.5 GB (one-time) | None | | **Hardware requirement** | Apple Silicon | Any | | **Latency** | On-device inference | Network round-trip | Fluid Intelligence is the only enhancement option where your voice and text never leave the device under any circumstances. If privacy is a priority, use Fluid Intelligence instead of cloud providers. ## How to Enable Fluid Intelligence Go to **AI Enhancement → AI Providers** Choose **Fluid Intelligence** from the provider list. If the model is not yet downloaded, FluidVoice prompts you to download it. Confirm the download (~3.5 GB). The model downloads in the background. You can continue using FluidVoice with another provider while the download completes. Once the download finishes, Fluid Intelligence activates automatically. Your next dictation session will use Fluid-1 for post-processing. You can also enable Fluid Intelligence during the initial onboarding flow. When FluidVoice asks about AI Enhancement setup, select **Fluid Intelligence** and follow the same download prompt. ## Other Ways to Use Fluid Intelligence Once the model is installed, you can switch Fluid Intelligence on or off without opening Settings. - **Toggle from the dictation overlay.** During any dictation session, use the Fluid Intelligence toggle in the overlay to enable or disable it on the fly. - **Assign a dedicated hotkey.** To keep a separate shortcut that always dictates with Fluid Intelligence, go to **Settings → Global Hotkey → Primary Dictation Shortcuts → Add Shortcut**, then enable **AI Prompt** for that shortcut and set the provider to **Fluid Intelligence**. Triggering this hotkey will dictate with Fluid Intelligence enabled, regardless of your default provider. ## Demo Scenarios These are real examples of what Fluid-1 handles in everyday dictation: **Email formatting** Raw transcript: > "hey um so i wanted to reach out about the meeting on thursday uh can we move it to friday at two pm thanks" Fluid-1 output: ```text wrap Hi, I wanted to reach out about the meeting on Thursday — can we move it to Friday at 2 PM? Thanks ``` **Casual tone with emoji** Raw transcript: > "just shipped the fix lgtm thumbs up fire emoji" Fluid-1 output: ```text wrap Just shipped the fix. LGTM 👍🔥 ``` **Hyphens and numbers** Raw transcript: > "the api key is twenty four characters and expires in thirty days" Fluid-1 output: ```text wrap The API key is 24 characters and expires in 30 days. ``` **Self-correction** Raw transcript: > "send the invoice to john no wait send it to sarah" Fluid-1 output: ```text wrap Send the invoice to Sarah. ``` **Spoken formatting instructions** Raw transcript: > "meeting notes new line action items new paragraph follow up with design team on the new mockups" Fluid-1 output: ```text wrap Meeting notes Action items Follow up with the design team on the new mockups. ``` **List generation** Raw transcript: > "make a grocery list eggs banana" Fluid-1 output: ```text wrap Grocery list: - Eggs - Banana ``` ## Fluid Intelligence as a Private Model Fluid Intelligence is a **separate, privately maintained** runtime from the open-source FluidVoice app. The core FluidVoice app is fully open-source under GPLv3. Fluid Intelligence is kept private so the team can sustainably fund ongoing model development and offer the core dictation experience for free. This may change in the future. ## Requirements - macOS 15.0 (Sequoia) or later - Apple Silicon Mac (M1, M2, M3, or later) - ~3.5 GB of available disk space for the model - No internet connection required after the initial download --- ## File: features/history.mdx --- title: "Transcription History and Usage Stats" sidebarTitle: "History & Stats" --- FluidVoice keeps a local record of every dictation session so you can review what was transcribed, compare the raw speech-to-text output with the AI-polished final text, and see which app was active at the time. Daily usage statistics appear in the menu bar and on the stats header card, giving you a quick sense of how much you're dictating. Everything stays on your Mac — history is never uploaded or synced to any external service. Audio history is **opt-in and disabled by default**. FluidVoice only saves audio recordings if you explicitly enable the setting. Transcription text history is saved by default and can be disabled separately. ## Transcription History Every dictation session produces a history entry containing: | Field | Description | | --- | --- | | **Timestamp** | Date and time the dictation occurred | | **App name** | The app that was in focus when you dictated | | **Raw text** | The original transcript from the speech model, before any AI processing | | **Processed text** | The post-processed result that was typed into the app | | **AI processed** | Whether an AI enhancement provider was applied | Having both the raw and processed text in the same entry makes it easy to see what the speech model heard versus what the AI changed, which is useful for tuning your prompts and spotting persistent transcription errors. ### How to Access History Open History by going to **History** in the FluidVoice application. The history view shows your recent dictations in reverse chronological order. Select any entry to expand it and see the full raw and processed text side by side. ### Clearing History Individual entries can be deleted from the history view by clicking on the entry, and pressing the **Delete Entry** button. ### Local API Access The local REST API exposes history for external tools and scripts: ```bash # Get the last 100 history entries (default limit) curl http://localhost:11111/v1/history # Get the last 50 entries curl http://localhost:11111/v1/history?limit=50 # Get up to 1000 entries (maximum) curl http://localhost:11111/v1/history?limit=1000 ``` Each response item includes the following fields: | Field | Description | | --- | --- | | `id` | Unique identifier for the history entry | | `timestamp` | ISO 8601 date and time of the dictation | | `rawText` | Original transcript from the speech model | | `processedText` | AI-polished text that was typed into the app | | `appName` | Name of the app that was in focus | | `windowTitle` | Title of the focused window at the time of dictation | | `characterCount` | Number of characters in the final output | | `wasAIProcessed` | Whether an AI enhancement provider was applied | | `aiProcessingError` | Error message if AI processing failed, otherwise null | The default limit is **100 entries**. The maximum is **1,000 entries**. --- ## Audio History When audio history is enabled, FluidVoice saves a local audio recording of each dictation session alongside the transcript entry. This lets you play back exactly what you said, which is useful for debugging transcription accuracy or reviewing dictation sessions later. ### Enabling Audio History Go to **Settings** Toggle **Save audio with transcription history** to on. Use the **Audio history budget** slider to set the maximum disk space for audio recordings (in gigabytes). When the budget is reached, older recordings are deleted automatically to make room for new ones. ### Exporting Audio To export all saved audio recordings as a single ZIP file: 1. Go to **Settings** 2. Click **Export Audio, and click Export ZIP button**. 3. Choose a save location. FluidVoice packages all recordings and downloads the archive. This is useful for backing up recordings, sharing sessions for debugging, or processing audio with external tools. Audio recordings are stored locally in your Application Support folder and never leave your device. They are not included in iCloud backups unless your Application Support directory is explicitly synced. Keep this in mind when setting your storage budget on Macs with limited disk space. --- ## Today-Usage Stats FluidVoice tracks your daily dictation activity and surfaces it in two places: - **Menu bar toolbar pill** — a compact counter showing today's word count or character count at a glance without opening the app - **Stats header card** — a more detailed summary visible at the top of the main FluidVoice window Usage statistics reset at midnight local time. They are stored locally and are not shared with any external service. --- ## Privacy All history — transcription text and audio recordings — is stored exclusively on your Mac. FluidVoice does not sync history to iCloud, does not upload it to any server, and does not include it in anonymous analytics. If you add an AI enhancement provider, the raw transcript is sent to that provider during processing, but the history record itself is always stored locally regardless of which provider you use. --- ## File: features/per-app-prompts.mdx --- title: "Per-App Prompt Profiles for Context-Aware Dictation" sidebarTitle: "Per-App Prompts" --- Per-app prompt profiles let you write custom AI instructions that activate automatically when a specific app is in focus. When you dictate in Slack, FluidVoice applies your Slack prompt. When you switch to Mail, it applies your Mail prompt — without any manual switching on your part. The same spoken words come out differently depending on where you're writing, matching the tone and format each context expects. FluidVoice detects the active app through macOS's accessibility API, which monitors the focused application continuously. No extra configuration is required for detection to work. ## Use Cases The same raw dictation adapts to whichever app is in focus: | App | Tone | What FluidVoice does | | --- | --- | --- | | **Slack** | Casual | Keeps language conversational, trims formality, adds emoji where natural | | **Mail** | Formal | Uses complete sentences, professional sign-offs, correct salutations | | **GitHub Issues** | Structured | Formats content with headers, bullet points, and action items | | **Notes / Quick Notes** | Personal | Preserves your natural speaking voice, minimal cleanup | | **Terminal / Code editors** | Raw | Outputs text exactly as spoken, no punctuation added | ## How to Create a Custom per-app prompt Go to **AI Enhancement → Advanced Prompts**. Click on **App Overrides**, then click the **Add App** button to see the list of available applications. Select the app you want to configure a custom prompt for. Once the app is chosen, pick a prompt to associate with it: - **Use an existing prompt** — choose one of your saved custom prompts from the list. - **Create a new prompt** — configure a new one with: - A custom shortcut - Your preferred AI provider and model - A prompt name - The prompt instructions themselves Use the built-in **Test mode** to verify the prompt works for your use case and refine it if needed before saving. ## Example Prompts ```text Slack — Casual Make the tone casual and conversational. Fix formatting and remove filler words. Add emoji where it feels natural and appropriate. Keep it concise. ``` ```text Mail — Formal Make the tone professional and formal. Fix grammar, punctuation, and sentence structure. Use complete sentences with proper salutations and sign-offs. ``` ```text GitHub Issues — Structured Format the output as a structured GitHub issue. Use markdown with clear headers (## Issue, ## Steps to Reproduce, ## Expected Behavior, ## Resolution). Use bullet points for lists. Keep language technical and precise. ``` ```text Quick Notes — Personal Preserve the speaker's natural voice and casual tone. Fix obvious errors only. Do not restructure sentences or change the register. ``` ```text Terminal / Code editors — Raw Output raw text only. Do not add punctuation, capitalization changes, or formatting. Do not modify technical terms, variable names, or commands. ``` ## Dictate Mode vs. Edit Mode Profiles Every prompt profile targets one of two modes: - **Dictate mode** — applies during standard voice dictation. The profile shapes how the AI cleans and formats your spoken words before they're typed into the app. - **Edit mode** — applies when you use the Edit hotkey to rewrite selected text. The profile shapes how the AI interprets and applies your rewrite instructions. You can create different profiles for Dictate mode and Edit mode within the same app. For example, your Slack Dictate profile could keep things casual, while your Slack Edit profile could be set to make rewrites shorter and more direct. ## Routing Scope Each mode has a **routing scope** setting that controls how broadly per-app profiles apply: - **All apps** — the selected prompt profile acts as the global default for every app. Per-app bindings override it for specific apps you've configured. - **Selected apps only** — per-app profiles are only active for apps that have an explicit binding. All other apps fall back to the built-in default prompt, ignoring any globally selected profile. Set the routing scope in **Settings → Prompts** for each mode independently. ## How App Detection Works FluidVoice uses macOS's accessibility API to monitor which application is currently focused. When you press your dictation hotkey, FluidVoice reads the active app and looks up any matching prompt binding for the current mode. The matching profile's instructions are sent to the AI provider as part of the system prompt — no manual selection required on your part. Detection is automatic and real-time. Switching apps between dictation sessions is enough for the correct profile to activate on your next dictation. Per-app prompt profiles require AI Enhancement to be enabled. If enhancement is set to **Off**, profiles have no effect and FluidVoice types the raw transcript directly. --- ## File: models/choosing-a-model.mdx --- title: "How to Choose the Right Speech Model" sidebarTitle: "Choosing a Model" --- With eight model families available, picking the right one for your setup comes down to a few straightforward questions: what hardware you have, which language you speak, how fast you need transcription to feel, and how much disk space you can spare. Work through the decision factors below, check the quick-pick table, and you'll have a model downloaded in minutes. You can try as many models as you like and switch between them at any time — open **Voice Engine**, and select a model whenever you want to experiment with a different option. --- ## Decision factors ### 1. Hardware Your Mac's chip is the first filter. - **Apple Silicon (M1 or later):** All models are available to you — Nemotron Speech 3.5, Parakeet Flash, Parakeet TDT v3 and v2, Cohere Transcribe, Apple Speech, and the full Whisper family. - **Intel Mac:** **Apple Speech** and the **Whisper** family are supported. Start with Whisper Small for a good balance of speed and accuracy, or use Apple Speech for zero-download convenience. ### 2. Language - **English only:** Any model works. For the lowest latency, choose **Parakeet Flash (Beta)** or **Parakeet TDT v2**. For accuracy, choose **Cohere Transcribe**. - **European language (non-English):** **Parakeet TDT v3** covers 25 European languages with a good speed-accuracy balance. **Nemotron Speech 3.5** covers ~40 languages and adds streaming capability. - **East Asian, Arabic, or other languages:** **Cohere Transcribe** covers Mandarin, Japanese, Korean, Vietnamese, and Arabic. **Whisper** (Medium or Large) covers up to 99 languages and is the most comprehensive option. - **Widest possible coverage:** **Whisper Large** covers 99 languages at the highest accuracy of the Whisper family. ### 3. Latency - **Lowest latency:** **Parakeet Flash (Beta)** — text appears on screen with near-zero delay. **Nemotron Speech 3.5 Ultra Fast Low Latency** delivers a similar real-time feel across ~40 languages. - **Highest accuracy:** **Cohere Transcribe** or **Nemotron 3.5 Multilingual** — both trade a little speed for cleaner transcripts. - **Balanced:** **Parakeet TDT v3** is FluidVoice's recommended default and a strong all-rounder. ### 4. Disk space - **Tight on space:** **Apple Speech** is built into macOS and uses no extra disk space at all. **Parakeet Flash** is the smallest download at ~250 MB. - **Moderate space available:** Parakeet TDT v3 (~500 MB) and Nemotron 3.5 Multilingual (~530 MB) offer strong results for their size. - **Space is not a concern:** **Cohere Transcribe** (~1.4 GB) and **Whisper Large** (~2.9 GB) give you the highest accuracy the lineup offers. ### 5. Offline use Every local model in FluidVoice runs entirely on-device — no internet connection is needed once the model is downloaded. **Apple Speech** also works offline after your macOS system language has been set up. None of your audio or transcribed text is sent to the cloud during dictation. --- ## Quick-pick table Use this table to jump straight to a recommendation based on your primary need. | I want… | Recommended model | | --- | --- | | The fastest English dictation | **Parakeet Flash (Beta)** | | Fast English dictation (stable release) | **Parakeet TDT v2** | | A non-English European language | **Nemotron Speech 3.5** or **Parakeet TDT v3** | | East Asian or Arabic language support | **Cohere Transcribe** | | The widest language support | **Whisper Large** | | Maximum accuracy | **Cohere Transcribe** | | Zero download, works immediately | **Apple Speech** | | Intel Mac support | **Whisper** or **Apple Speech** | | Streaming speed across many languages | **Nemotron Speech 3.5 Ultra Fast** | --- ## Recommended starting points Start with **Parakeet TDT v3**. It covers 25 languages, downloads in under a minute, and gives you a fast, accurate baseline to compare against. Choose **Parakeet Flash (Beta)**. It is the fastest model available and delivers near-zero perceived latency for English dictation. Try **Nemotron Speech 3.5 Multilingual** for ~40 languages with high accuracy, or **Cohere Transcribe** if you need Mandarin, Japanese, Korean, Vietnamese, or Arabic. Use **Apple Speech** for a zero-download start, or download **Whisper Small** (~466 MB) for broader language support and strong accuracy. **Apple Speech** is built-in and free. If you want a dedicated model, **Parakeet Flash** at ~250 MB is the smallest standalone download. Download **Cohere Transcribe** (~1.4 GB) for the highest-accuracy multilingual transcription in the lineup. --- ## How to switch models Select **Voice Engine** in the sidebar. View the full list of available models with their download sizes and language details. Choose the model you want. If it is not already on your Mac, click **Download** and wait for it to finish — FluidVoice switches to the new model automatically once the download completes. --- ## File: models/overview.mdx --- title: "Speech Models Available in FluidVoice — Full Comparison" sidebarTitle: "Models Overview" --- FluidVoice ships with support for eight distinct speech model families, ranging from the zero-download Apple Speech engine built into macOS to large multilingual models like Whisper Large. Each model runs entirely on your device — no audio leaves your Mac during transcription. The right choice depends on your language, how much disk space you can spare, and how fast you need words to appear on screen. All models download to local storage on your Mac and run entirely on-device. Your voice and transcribed text are never sent to the cloud. ## Model lineup | Model | Best for | Language support | Download size | Hardware | | --- | --- | --- | --- | --- | | Nemotron Speech 3.5 — Ultra Fast Low Latency | Streaming-capable multilingual dictation | ~40 languages | ~670 MB | Apple Silicon | | Nemotron 3.5 Multilingual | Higher-accuracy multilingual dictation | ~40 languages | ~530 MB | Apple Silicon | | Parakeet Flash (Beta) | Lowest-latency live English dictation | English | ~250 MB | Apple Silicon | | Parakeet TDT v3 | Fast default multilingual dictation | 25 languages | ~500 MB | Apple Silicon | | Parakeet TDT v2 | Fastest English-only dictation | English | ~500 MB | Apple Silicon | | Cohere Transcribe | High-accuracy multilingual dictation | 14 languages | ~1.4 GB | Apple Silicon | | Apple Speech | Zero-download native macOS speech | System languages | Built-in | Apple Silicon \+ Intel | | Whisper Tiny / Base / Small / Medium / Large | Broad compatibility, including Intel Macs | 99 languages | ~75 MB – ~2.9 GB | Apple Silicon \+ Intel | --- ## Model details ### Nemotron Speech 3.5 — Ultra Fast Low Latency Use this model when you want streaming-style multilingual dictation — words appear on screen as you speak with minimal lag. It covers roughly the same ~40-language range as the Multilingual variant but prioritises real-time throughput over peak accuracy. It requires Apple Silicon. ### Nemotron 3.5 Multilingual Choose this model when accuracy matters more than raw speed. It processes audio in a slightly less aggressive streaming mode than the Ultra Fast variant, producing cleaner transcripts across the same ~40-language range. It requires Apple Silicon. Nemotron Speech 3.5 supports approximately 40 languages. Refer to the [NVIDIA model card](https://huggingface.co/nvidia) for the full and up-to-date list. ### Parakeet Flash (Beta) Parakeet Flash delivers the lowest perceived latency of any model in FluidVoice — text lands on screen fast enough to feel instantaneous. It is English-only and is the best pick for developers, power users, or anyone who dictates in English and wants speed above all else. It requires Apple Silicon. ### Parakeet TDT v3 Parakeet TDT v3 is the recommended starting point for most multilingual users. It balances speed and accuracy across 25 European languages and is the default model FluidVoice suggests during onboarding. It requires Apple Silicon. Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian. ### Parakeet TDT v2 Use Parakeet TDT v2 when you dictate exclusively in English and want the fastest possible throughput. It is functionally similar to Parakeet Flash but draws on an earlier generation of the model architecture. It requires Apple Silicon. ### Cohere Transcribe Cohere Transcribe prioritises transcription accuracy over raw speed and covers 14 languages including Mandarin, Japanese, Korean, Vietnamese, and Arabic — languages not available in the Parakeet family. At ~1.4 GB it is the largest download in the lineup. It requires Apple Silicon. English, French, German, Italian, Spanish, Portuguese, Greek, Dutch, Polish, Mandarin, Japanese, Korean, Vietnamese, Arabic. ### Apple Speech Apple Speech uses the speech recognition engine built into macOS — no download required. It works on both Apple Silicon and Intel Macs and supports whatever languages your macOS installation has available. Use this model if you are on an Intel Mac and want the simplest possible setup, or if you are on Apple Silicon but have no disk space to spare. ### Whisper Tiny / Base / Small / Medium / Large The Whisper family offers the broadest language coverage (up to 99 languages) and is the only third-party option that runs on Intel Macs. Smaller variants (Tiny, Base) are fast and lightweight; larger variants (Medium, Large) trade speed for accuracy. Choose Whisper if you need a language that no other model covers, or if you are on an Intel Mac. Whisper supports up to 99 languages depending on the model size you choose. Larger models (Medium, Large) recognise a wider range of languages more accurately than smaller ones. Refer to the [OpenAI Whisper model card](https://github.com/openai/whisper#available-models-and-languages) for the complete language list. | Variant | Download size | Notes | | --- | --- | --- | | Tiny | ~75 MB | Fastest, lowest accuracy | | Base | ~142 MB | Good balance for simple use cases | | Small | ~466 MB | Recommended for Intel Macs | | Medium | ~1.5 GB | Strong multilingual accuracy | | Large | ~2.9 GB | Highest accuracy across 99 languages | --- ## How to download a model The onboarding flow prompts you to select and download a model before you start dictating. Follow the on-screen steps to choose your language and latency preference, then let the download finish. Open **Voice Engine**, select the model you want, and click **Download**. You can switch between any downloaded models at any time by selecting the model, and clicking **Activate**. --- ## File: sources/site/altic.dev/fluid.txt [Binary file]