FluidVoice Documentation

1. Project Overview & Quickstart (altic-dev/FluidVoice) Copy Chapter

File: README.md Copy Chapter

FluidVoice

Open source voice-to-text dictation app for macOS with on-device AI enhancement.

Install with Homebrew: brew install --cask fluidvoice

Manual download: latest release

[!WARNING]
fluidvoice.org is not affiliated with, operated by, or endorsed by FluidVoice or Altic. Its claims to be our official website are unauthorized.

Our official website is altic.dev/fluid. Our official domains also include fluidvoice.com and fluidvoice.app.

For official downloads, use this repository's GitHub Releases.

If fluidvoice.org appears in your search results claiming to be our official website, please report the misleading result to the search provider.

[!NOTE]
FluidVoice is on macOS today. iOS and Windows are on the way — join the waitlist to get notified when we launch: altic.dev/fluid/waitlist

[!IMPORTANT]
This project is free and open source under GPLv3. If FluidVoice is useful to you, please star the repository — it helps visibility and keeps development going.

Support FluidVoice Copy Chapter

If FluidVoice helps you, you can support continued development and future platform work for iOS and Windows on GitHub Sponsors.

What's New in 1.6.0 Copy Chapter

• Insanely fast Parakeet — rebuilt Parakeet implementation with pretty much zero delay between speaking and seeing words on screen
• Fluid Intelligence — fully local AI model for on-device dictation enhancement. No cloud, no API keys, no data leaving your Mac
• Better Theming — adaptive light/dark theme with a compact toolbar switcher
• Refreshed Onboarding — language-first voice engine setup, real dictation tryout, and AI enhancement setup in one clean pass

[!WARNING]
Based on early feedback, Fluid Intelligence may cause you to unsubscribe from other dictation apps and save money. You've been warned.

Fluid Intelligence Copy Chapter

FluidVoice is fully open source under GPLv3. Fluid Intelligence is a separate, privately maintained local AI runtime that powers advanced on-device dictation enhancement — smart formatting, context-aware capitalization, and post-processing — all running locally on your Mac.

The app works great on its own with any supported speech model and optional cloud AI providers. Fluid Intelligence adds a fully local, private AI layer for users who want on-device enhancement without sending data anywhere.

We're keeping Fluid Intelligence private for now so we can sustainably offer the core dictation experience for free. This may change in the future.

Fluid Intelligence Sneak Peek Copy Chapter

Demo Copy Chapter

Command Mode — Take any action on your Mac using FluidVoice Copy Section

https://github.com/user-attachments/assets/ffb47afd-1621-432a-bdca-baa4b8526301

Write Mode — Write or rewrite text in any text box in any app Copy Section

https://github.com/user-attachments/assets/c57ef6d5-f0a1-4a3f-a121-637533442c24

Features Copy Chapter

• Fluid Intelligence — on-device AI enhancement for smart formatting, context-aware capitalization, and post-processing, all running locally on your Mac with zero data leaving your machine
• Command Mode — control your Mac by voice: launch apps, run shortcuts, trigger system actions, and automate workflows without touching the keyboard
• Write Mode — write or rewrite text directly in any text field across any app. Select text and rewrite it, or dictate new content inline
• Live Preview — real-time transcription overlay with notch support, so you see words appear as you speak
• Multiple Speech Models — Nemotron Speech 3.5, Parakeet Flash, Parakeet TDT v3 & v2, Cohere Transcribe, Apple Speech, and Whisper. Pick the model that fits your language and latency needs
• AI Enhancement — optional post-processing via OpenAI, Groq, custom providers, or local Fluid Intelligence for cleaner, more accurate transcripts
• Audio History — optional local recording history with budget controls and ZIP export, so you can review past dictations without cloud storage
• Today-Usage Stats — daily usage tracking at a glance with a stats header card and toolbar pill
• Adaptive Theming — light/dark theme that follows your system, with a compact toolbar switcher
• Global Hotkey — instant voice capture from anywhere, no app switching needed
• Smart Typing — direct insertion into any app via accessibility APIs for reliable, app-independent text entry
• Menu Bar Integration — quick access, status, and settings from the menu bar
• Auto-Updates — seamless updates with an optional beta channel for early previews
• Per-App Configuration — assign different prompt sets to different apps, so your dictation adapts to whatever you're working in. Fully optional
• Notch-Aware Overlay — transcription overlay that fits cleanly around the MacBook notch, or use a standard overlay if your Mac doesn't have one
• Local-First — your voice and text never leave your machine unless you opt in to a cloud AI provider
• Fastest Parakeet on Mac — one of the fastest native implementations of Parakeet on macOS, with near-instant transcription and minimal latency
• Configurable Overlay — choose from pill-shaped to large overlay sizes to show live preview, or keep it minimal. Everything is optional
• Everything is Optional — AI enhancement, Fluid Intelligence, audio history, detailed analytics, and beta builds are optional. The core dictation experience works out of the box with zero configuration beyond permissions and a hotkey

Supported Models Copy Chapter

Parakeet TDT v3 Languages Copy Section

Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, and Ukrainian.

Parakeet TDT v2 Languages Copy Section

English.

Cohere Transcribe Languages Copy Section

English, French, German, Italian, Spanish, Portuguese, Greek, Dutch, Polish, Mandarin, Japanese, Korean, Vietnamese, and Arabic.

Apple Speech Languages Copy Section

System language support depends on the macOS speech recognition languages available on your machine.

Whisper Language Support Copy Section

Whisper supports up to 99 languages, depending on the model size you choose.

Quick Start Copy Chapter

1. Install with Homebrew:

   bash Copy

   brew install --cask fluidvoice

   Or download the latest release.

2. Grant permissions — FluidVoice will ask for microphone and accessibility access. Both are required for dictation and typing into other apps.

3. Set your hotkey — pick a global hotkey in settings that triggers voice capture from anywhere.

4. Go through onboarding — choose your voice model based on your language and latency needs. Models range from zero-download Apple Speech to high-accuracy Nemotron and Whisper.

5. (Optional) Enable Fluid Intelligence — download the local AI model during onboarding for on-device dictation enhancement. Everything runs locally, no data leaves your Mac.

6. (Optional) Bring your own AI provider — add an OpenAI, Groq, or custom provider API key for cloud-based enhancement. Keys are stored securely in macOS Keychain. Select "Always allow" for key access.

7. (Optional) Opt in to beta builds — Settings → Automatic Updates → Beta Releases for early access to new features.

Requirements Copy Chapter

• macOS 15.0 (Sequoia) or later
• Apple Silicon Mac for all models
• Intel Macs supported via Whisper models (from 1.5.1+)
• ~1 GB disk space for a voice model
• ~3.5 GB disk space for the Fluid Intelligence model (optional)
• Microphone access
• Accessibility permissions for typing

Building from Source Copy Chapter

git clone https://github.com/altic-dev/FluidVoice.git
cd FluidVoice
open Fluid.xcodeproj

Build and run in Xcode. All dependencies are managed via Swift Package Manager.

Run a signed Debug build using the script:

./build.sh

The signed build is written to DerivedData/Build/Products/Debug/FluidVoice Debug.app.
Keep launching that product after each rebuild so macOS can preserve its Accessibility
authorization.

For CI or contributors who do not have a signing identity, use the explicit unsigned
fallback:

./build.sh unsigned

Unsigned builds are tied to a specific executable version and may require Accessibility,
Screen Recording, and microphone permissions to be removed and granted again after rebuilding.

Contributing Copy Chapter

Contributions are welcome! Read the contribution guidelines before starting work.

• Every PR needs a linked issue, including bug fixes and small changes.
• Major features and UI or UX changes need maintainer or moderator approval before implementation. Open an issue and wait for explicit agreement on the scope.
• Major feature requests start in Discussions. After approval, create or link a tracking issue and reference both in the PR.
• Keep PRs focused and verifiable. Include a screenshot, image, or video, clear reproduction or verification steps, and testing results. Show before and after for UI or UX changes.

Development Setup Copy Section

1. Clone and open in Xcode as above.
2. Signing: FluidVoice → Signing & Capabilities → Automatically manage signing → pick your Team (Personal Team is fine). If you have certificates for multiple teams, select one without changing the project by running FLUIDVOICE_DEVELOPMENT_TEAM=YOUR_TEAM_ID ./build.sh.
3. Build and run — SPM handles dependencies.
4. (Optional) Pre-commit hook to prevent accidental team ID commits:
   bash Copy

   cp scripts/check-team-id.sh .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit

Pull Request Guidelines Copy Section

• One feature or fix per PR — keep changes focused and atomic
• Link a tracking issue — a Discussion alone does not replace it
• Get approval before implementing major features or UI or UX changes
• Follow the PR template, including reproduction steps and screenshot, image, or video evidence
• Report testing results and any checks you could not run
• AI-assisted coding is welcome; human review is required. A human must create or vet the final PR, understand the full diff, and verify the behavior. Briefly explain AI use and your own checks; keep descriptions, code comments, and review replies focused. See AI-assisted contribution guidelines.
• Never commit personal team IDs or API keys
• Check git diff before committing

These requirements are mandatory. PRs that do not follow the contribution guidelines will not be reviewed or merged until they comply, and may be closed.

Run Integration Tests Copy Chapter

xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS'

CI uses unsigned builds:

xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS' CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO

Privacy & Analytics Copy Chapter

FluidVoice is local-first. Your voice, audio, and transcribed text never leave your machine unless you explicitly opt in to a cloud AI provider.

What's Collected Copy Section

FluidVoice records one anonymous activity signal per local day and uploads the week's buffered signals together after the week ends. Detailed anonymous analytics are enabled by default and can be disabled at any time from Settings → Share Detailed Anonymous Analytics; when disabled, only the weekly activity batch is sent.

Daily activity:

• A random installation ID, activity date, app version, and macOS platform label

With detailed analytics enabled:

• Daily feature and model usage totals
• Onboarding progress
• Model download starts and high-level outcomes

Not Collected:

• Voice, raw audio, or transcribed text
• Selected text, prompts, or AI responses
• Terminal commands, window titles, file paths, clipboard, or typed content
• Any personal or private information

Community Copy Chapter

Join our Discord: https://discord.gg/VUPHaKSvYV

Follow development on X: @fluidvoiceapp

License Copy Chapter

From 2026-02-23 onward, this project is licensed under the GNU General Public License, Version 3.0 (GPLv3).

Versions published before this date were licensed under Apache License 2.0.

File: docs/MACOS_UI_AUTOMATION_BRANCH_PLAN.md Copy Chapter

macOS UI Automation Plan (Separate Branch)

Goal Copy Chapter

Build reliable automated test coverage for FluidVoice native macOS UI behavior (overlay, prompt picker, mode switching, context behavior), without blocking release stabilization work.

Branch Strategy Copy Chapter

• Branch name: B/macos-ui-automation
• Keep this work isolated from release branch changes.
• No schema/storage migrations in this branch unless explicitly required for testability.

Scope Copy Chapter

• Add stable accessibility identifiers for key UI controls.
• Add macOS XCUITest smoke coverage for Dictate/Edit/Command interaction flows.
• Add deterministic app launch mode for UI tests (--ui-testing) to reduce flakiness.
• Add targeted logic tests for migration/state synchronization edge cases.

Out of Scope Copy Chapter

• Per-prompt shortcut assignment.
• Product behavior redesign.
• Replacing rewrite internals in this phase.

Phase 1: Testability Hooks (Accessibility IDs) Copy Chapter

Files likely to touch Copy Section

• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/Views/BottomOverlayView.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/Views/NotchContentViews.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/UI/AISettingsView+AdvancedSettings.swift

IDs to add first Copy Section

• Prompt chip button
• Prompt menu tab: Dictate
• Prompt menu tab: Edit
• Prompt list row (profile)
• Selected checkmark container
• Right-side mode label
• Context toggle (editor)
• Save button (editor)

Phase 2: UI Smoke Suite (`XCUITest`) Copy Chapter

New target/files Copy Section

• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidVoiceUITests/FluidVoiceUITests.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidVoiceUITests/PromptPickerSmokeTests.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidVoiceUITests/ModeSwitchSmokeTests.swift

Initial smoke tests Copy Section

1. Prompt picker tab switch keeps chip/tab/checkmark aligned.
2. Dictate -> Edit live switch updates right-side label to Edit.
3. Edit -> Dictate live switch updates right-side label to Dictate.
4. Command mode entry/exit does not corrupt picker mode state.
5. Prompt selection persists after close/reopen of overlay.

Phase 3: Deterministic UI Test Runtime Copy Chapter

Files likely to touch Copy Section

• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/FluidApp.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/ContentView.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Sources/Fluid/Services/NotchOverlayManager.swift

Additions Copy Section

• --ui-testing launch argument handling.
• Disable or stub fragile external dependencies in test mode where needed (network/transcription side effects).
• Keep prompt composition logic intact; only remove nondeterminism.

Phase 4: Logic/Concurrency Guard Tests Copy Chapter

Files likely to touch Copy Section

• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidTests/SettingsStorePromptMigrationTests.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidTests/PromptPickerStateSyncTests.swift
• /Users/barathwajanandan/Documents/mac_apps/FluidVoice/Tests/FluidTests/LiveModeSwitchTests.swift

Assertions Copy Section

• Legacy write/rewrite prompt modes normalize to edit once.
• Normalized state does not re-write storage repeatedly.
• Live switch preserves context when already present.
• Processing guard blocks unsafe mode switch mutations.

CI / Execution Copy Chapter

• Add UI smoke job (macOS runner) gated on target branch or label.
• Keep runtime short (<= 3-5 minutes).
• Fail fast on first critical smoke failure.

Performance and Low-Resource Principles Copy Chapter

• Prefer small deterministic smoke tests over heavy end-to-end scripts.
• Avoid polling loops and long sleeps; use expectations with short timeouts.
• Reuse shared helpers to reduce startup overhead in tests.

Definition of Done Copy Chapter

1. Accessibility IDs exist for all prompt-picker critical controls.
2. Smoke suite passes locally and in CI.
3. No regression to Dictate/Edit/Command user-facing labels.
4. Migration/state sync tests cover known release-risk edges.
5. Test docs include how to run locally.

Local Run Commands (to finalize when branch starts) Copy Chapter

• Unit tests: xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS,arch=arm64' -only-testing:FluidTests
• UI tests: xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS,arch=arm64' -only-testing:FluidVoiceUITests

Notes Copy Chapter

• Keep internal compatibility symbols (rewrite*) unchanged in this automation branch unless needed for explicit test seams.
• Revisit per-prompt shortcut assignment in a later dedicated branch.

2. Official Technical Reference & Guides (altic-dev/docs) Copy Chapter

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

AI-assisted writing Copy Chapter

Set up your AI coding tool to work with Mintlify:

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 for tool-specific setup.

Development Copy Chapter

Install the Mintlify CLI to preview your documentation changes locally. To install, use the following command:

npm i 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 Copy Chapter

Install our GitHub app from your dashboard to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.

Need help? Copy Chapter

Troubleshooting Copy Section

• 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 Copy Section

• Mintlify documentation