MACOS UI AUTOMATION BRANCH PLAN Copy Section

macOS UI Automation Plan (Separate Branch)

Goal Copy Chapter

Branch Strategy Copy Chapter

Scope Copy Chapter

Out of Scope Copy Chapter

Phase 1: Testability Hooks (Accessibility IDs) Copy Chapter

Files likely to touch Copy Section

IDs to add first Copy Section

Phase 2: UI Smoke Suite (XCUITest) XCUITest)')" title="Copy chapter prompt for LLMs"> Copy Chapter

New target/files Copy Section

Initial smoke tests Copy Section

Phase 3: Deterministic UI Test Runtime Copy Chapter

Files likely to touch Copy Section

Additions Copy Section

Phase 4: Logic/Concurrency Guard Tests Copy Chapter

Files likely to touch Copy Section

Assertions Copy Section

CI / Execution Copy Chapter

Performance and Low-Resource Principles Copy Chapter

Definition of Done Copy Chapter

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

Notes Copy Chapter

---

CONTRIBUTING Copy Section

Contributing to FluidVoice

Thanks for taking the time to improve FluidVoice. This repository keeps GitHub Issues focused on actionable work, and uses Discussions for questions, ideas, and early design conversations.

Start with Discussions Copy Chapter

Start a GitHub Discussion first when you want to:

- Ask a support question.
- Propose a broad idea or feature.
- Explore a design direction.
- Report behavior that you are not sure is a FluidVoice bug.
- Ask whether a change would be accepted before writing code.

Feature ideas should usually begin in the Ideas discussion category. Maintainers may turn an accepted or prioritized discussion into a tracked issue.

Issues Copy Chapter

Issues are for work that maintainers can triage and act on.

Use a bug issue only when you can provide:

- A clear description of the bug.
- Exact reproduction steps.
- Expected behavior and actual behavior.
- FluidVoice version, macOS version, and architecture.
- Logs, crash reports, screenshots, or recordings when relevant.

Feature issues show guidance to start with Discussions first, but this is advisory for now. Maintainers may still redirect broad or unclear feature ideas to Discussions during triage.

Incomplete bug reports may be labeled needs reproduction. If the missing reproduction details are not provided after 14 days, the issue may be closed.

Pull Requests Copy Chapter

Pull requests should be tied to an accepted issue, Discussion, or roadmap item. Before opening a PR:

- Fill out every required section of the PR template.
- Select a type of change.
- Link the related issue or accepted Discussion.
- Describe how you tested the change.
- Attach screenshots or video for UI, UX, settings, onboarding, overlay, menu bar, or visual behavior changes.

If a PR has no UI or visual behavior changes, check the "No UI/visual changes" box in the template. The PR Policy workflow still requires screenshots or video when changed files touch visual surfaces.

PRs that do not follow the template will be blocked by the PR Policy check. If required information is still missing after 48 hours, the PR may be closed so maintainers can keep review queues focused.

Repository Settings Copy Chapter

Maintainers should enable GitHub Discussions with these categories:

- Ideas
- Help
- General

Maintainers should require the existing build/test check and the PR Policy check before merging to main.

---

README Copy Section

FluidVoice

<p align="center">
<a href="https://github.com/altic-dev/FluidVoice/stargazers"><img src="https://img.shields.io/github/stars/altic-dev/FluidVoice?style=social" alt="GitHub stars"/></a>
<a href="https://github.com/sponsors/altic-dev"><img src="https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors&logoColor=white" alt="Sponsor FluidVoice"/></a>
<a href="https://x.com/fluidvoiceapp"><img src="https://img.shields.io/badge/X-%40fluidvoiceapp-black?logo=x&logoColor=white" alt="X @fluidvoiceapp"/></a>
<br />
<a href="https://huggingface.co/nvidia/parakeet_realtime_eou_120m-v1"><img src="https://img.shields.io/badge/Models-Nemotron%20Speech%203.5%20%7C%20Parakeet%20Flash%20%7C%20Parakeet%20v3%20%26%20v2%20%7C%20Cohere%20%7C%20Apple%20Speech%20%7C%20Whisper-blue" alt="Supported Models"/></a>
<br /><br />
<a href="https://trendshift.io/repositories/16601?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-16601" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/16601" alt="altic-dev%2FFluidVoice | Trendshift" width="250" height="55"/></a>
</p>

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

---

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

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

<table>
<tr>
<td width="50%" align="center"><b>Email Template</b></td>
<td width="50%" align="center"><b>Flowers</b></td>
</tr>
<tr>
<td width="50%"><video src="https://github.com/user-attachments/assets/36747e9d-1ea3-4d27-8d38-eaacb6d57285" width="100%"></video></td>
<td width="50%"><video src="https://github.com/user-attachments/assets/5f6063ab-0506-4687-b825-c7bf4ab66ed6" width="100%"></video></td>
</tr>
<tr>
<td width="50%" align="center"><b>Change Time & Name</b></td>
<td width="50%" align="center"><b>Emoji</b></td>
</tr>
<tr>
<td width="50%"><video src="https://github.com/user-attachments/assets/6c7a7c4c-17a8-453d-8eff-1aa1fa9f6077" width="100%"></video></td>
<td width="50%"><video src="https://github.com/user-attachments/assets/04e00f3d-a602-448d-9bde-50b5e8f61ac6" width="100%"></video></td>
</tr>
<tr>
<td width="50%" align="center"><b>Hyphens & Numbers</b></td>
<td width="50%"></td>
</tr>
<tr>
<td width="50%"><video src="https://github.com/user-attachments/assets/47175f2b-9f06-452e-b892-42488e4ba536" width="100%"></video></td>
<td width="50%"></td>
</tr>
</table>

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, analytics, and beta builds are all opt-in. The core dictation experience works out of the box with zero configuration beyond permissions and a hotkey

---

Supported Models Copy Chapter

| 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 to ~2.9 GB | Apple Silicon + Intel |

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:

brew install --cask fluidvoice

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
permission to be removed and granted again after rebuilding.

---

Contributing Copy Chapter

Contributions are welcome! Please create an issue first to discuss major changes before submitting a pull request.

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:

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
- Create an issue first so work is trackable before review
- Discuss non-trivial changes before opening a PR
- Follow the PR template
- Test thoroughly on your machine
- Never commit personal team IDs or API keys
- Check git diff before committing

---

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 (Opt-In) Copy Section

Anonymous analytics are enabled by default to track app health and feature usage. You can disable at any time from Settings → Share Anonymous Analytics.

Collected:

- App version, build, macOS version
- Low-cardinality feature/config flags (e.g. app mode, major settings)
- Approximate usage ranges (not exact values)
- High-level success/error 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.

---