The Problem
FluidVoice addresses the need for a fast, fully offline voice‑to‑text dictation experience on macOS without relying on cloud services. Users requiring low‑latency transcription, on‑device privacy, or operation in air‑gapped environments often face trade‑offs between model quality, language support, and system resources. The app aims to provide a native macOS experience with multiple local models (Parakeet, Apple Speech, Whisper) and optional AI enhancement, while keeping the interface unobtrusive via a menu‑bar overlay.
What This Does
The repository is a macOS Cocoa application built with Swift and Swift Package Manager. Key components include: Audio capture and buffering – Sources/Fluid/Services/ThreadSafeAudioBuffer.swift and Sources/Fluid/Services/AudioDeviceService.swift manage real‑time microphone input and feed it to the ASR pipeline. Automatic speech recognition – Four provider implementations live under Sources/Fluid/Services/: WhisperProvider.swift, ParakeetVocabularyStore.swift, AppleSpeechProvider.swift, and AppleSpeechAnalyzerProvider.swift. Each exposes a TranscriptionProvider protocol, allowing the app to swap models at runtime. AI enhancement – Sources/Fluid/Services/LLMClient.swift and Sources/Fluid/Services/DictationAIPostProcessingGate.swift forward post‑transcription text to configurable providers (OpenAI, Groq, custom endpoints). API keys are stored in the macOS Keychain via Sources/Fluid/Persistence/KeychainService.swift. User‑facing UI – The menu‑bar app, overlay, and typing service are assembled in Sources/Fluid/UI/, Sources/Fluid/Views/, and Sources/Fluid/Services/CommandModeService.swift. Hot‑key handling resides in Sources/Fluid/Services/GlobalHotkeyManager.swift. Build system – Dependencies are declared in Package.swift and resolved in Package.resolved. CI runs on GitHub Actions via .github/workflows/build.yml, producing macOS archives. Persistence – Transcription history is stored locally using Sources/Fluid/Persistence/TranscriptionHistoryStore.swift and Sources/Fluid/Persistence/FileTranscriptionHistoryStore.swift. Settings (hotkey, model selection, beta channel) are managed by Sources/Fluid/Persistence/SettingsStore.swift.
How To Use It
Setup Clone the repo: git clone https://github.com/altic-dev/Fluid-oss.git && cd Fluid-oss Open the Xcode project: open Fluid.xcodeproj Resolve SwiftPM packages (Xcode will prompt or run swift resolve).
Configuration
Grant microphone permission the first time the app launches. For AI enhancement, add an API key in Settings → AI Provider – the key is saved to Sources/Fluid/Persistence/KeychainService.swift via the macOS Keychain API. Opt‑in to beta releases via Settings → Automatic Updates → Beta Releases (the toggle references the updater logic in Sources/Fluid/Services/SimpleUpdater.swift).
Running it
Press ⌥ Space (default global hotkey) to start listening; the overlay appears with real‑time preview. Transcribed text is typed into the focused application by the TypingService.swift module. To stop, press the hotkey again or click the “Stop” button in the overlay.
Real‑World Use
A knowledge‑worker attending a remote meeting can enable FluidVoice, select the Parakeet TDT v3 model (default on Apple Silicon), and speak notes. The transcript appears in the overlay and is automatically typed into a nearby text editor or note‑taking app, all without sending audio to an external service. If the user wants polished prose, they can toggle an AI provider (e.g., OpenAI) through the settings panel; the post‑processing gate in Sources/Fluid/Services/DictationAIPostProcessingGate.swift reformats the raw transcript before insertion.
Code Health & Issues
Tests & CI – 5 test files exist under Tests/FluidDictationIntegrationTests/ and a GitHub Actions workflow (build.yml) runs on every push, providing basic regression coverage. License – LICENSE is present and Apache 2.0‑compatible, satisfying open‑source compliance. Dependency hygiene – Package.resolved pins exact versions of all SwiftPM dependencies, reducing surprise breakages. Potential risks – The Whisper model loading code (not shown in the excerpt but referenced in Sources/Fluid/Services/WhisperProvider.swift) can consume several gigabytes of RAM on large models; users on machines with limited memory may experience latency or crashes. Apple‑Speech provider – Requires macOS 26+ (future release) and the Speech Analyzer API; currently undocumented for earlier OS versions, which may limit compatibility for some users. No input validation – The hotkey configuration UI does not sanitize modifier combinations; conflicting system hotkeys could cause unexpected behavior, though the app gracefully falls back to the default.
Overall, the project shows good structural hygiene for a solo‑developer‑driven macOS app: tests, CI, license, and resolved dependencies are all present. The main trade‑off is model‑size memory footprint and the Apple‑Speech requirement on newer macOS versions.
The Bottom Line
FluidVoice is a capable, fully offline dictation client for macOS that lets power users choose between lightweight Parakeet models, Apple’s native engine, or the broader Whisper suite. It’s well‑suited for individuals or small teams prioritizing privacy and low latency, especially on Apple Silicon hardware. Teams needing extensive language coverage beyond the shipped models or guaranteed compatibility across all macOS releases may need to supplement with cloud‑based alternatives.