What Is FluidVoice and What Problem Does It Solves? A Deep Dive into the Open‑Source macOS Dictation Platform

FluidVoice is an open‑source macOS voice‑to‑text dictation application that replaces cloud‑dependent speech recognition with a local‑first, privacy‑preserving workflow featuring on‑device models and optional AI enhancement.

FluidVoice solves a critical gap in macOS productivity tools: the forced choice between accurate but privacy‑risky cloud dictation services and limited offline alternatives. Built in SwiftUI and designed for power users, FluidVoice delivers sub‑30 ms latency transcription while keeping audio data on‑device unless users explicitly opt into cloud AI providers. According to the altic‑dev/FluidVoice source code, the application combines multiple speech recognition backends with a modular architecture that supports everything from real‑time dictation to voice‑driven command automation.

The Core Problem: Cloud‑Dependent Dictation Pipelines

Traditional macOS dictation tools present users with two unsatisfactory options:

1. Cloud‑first services expose spoken content to external APIs, creating privacy risks and network dependencies
2. Built‑in offline solutions offer limited model selection, higher latency, and minimal customization

FluidVoice eliminates this trade‑off by implementing a local‑first transcription stack where raw audio never leaves the machine during core speech recognition. The application achieves this through a pluggable model architecture defined in ModelRepository.swift, which manages downloads, caching, and runtime selection of speech models.

Architecture Overview: How FluidVoice Works

The FluidVoice codebase organizes functionality into discrete service layers coordinated through a singleton dependency container. Understanding this structure clarifies how the application achieves its performance and privacy goals.

Entry Point and Global Services

The application launches through Sources/Fluid/fluidApp.swift, which instantiates the SwiftUI App and injects global services via AppServices:

// In fluidApp.swift — simplified initialization flow
@main
struct FluidApp: App {
    init() {
        AppServices.shared.bootstrap()
        MenuBarManager.shared.configure()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

This pattern ensures GlobalHotkeyManager, ASRService, and MenuBarManager share consistent state throughout the application lifecycle.

Audio Capture and Speech Recognition

The ASRService.swift file implements the core transcription pipeline. It handles microphone input through a gated startup sequence, routes audio to the selected model, and streams interim results:

// In ASRService.swift — starting a dictation session
func start() async throws {
    let model = ModelRepository.shared.currentModel
    await audioEngine.prepare()
    try await model.warmup()
    audioEngine.startRecording()
}

Users can select from multiple speech models including Nemotron Speech 3.5, Parakeet Flash/TDT v2/v3, Apple Speech, Whisper, and Cohere — each offering different latency‑accuracy trade‑offs. Parakeet Flash, for example, achieves sub‑30 ms latency on Apple Silicon.

Model Management and Caching

ModelRepository.swift abstracts provider‑specific model handling:

• Downloads models on first use with progress reporting
• Caches compiled model artifacts for fast subsequent loading
• Persists user selection in SettingsStore.swift

This design allows FluidVoice to offer cutting‑edge speech models without bloating the initial download size.

Fluid Intelligence: Private AI Enhancement

Beyond raw transcription, FluidVoice addresses the limitation of unformatted speech‑to‑text output through Fluid Intelligence — a private on‑device AI runtime for post‑processing.

Local‑First Post‑Processing

When enabled, PrivateAIProvider.swift routes transcripts through a local LLM rather than external APIs:

// In DictationPostProcessingService.swift
func enhance(transcript: String) async throws -> String {
    if SettingsStore.shared.useFluidIntelligence {
        return try await PrivateAIProvider.shared.process(transcript)
    } else {
        return try await cloudProvider.process(transcript)
    }
}

Fluid Intelligence performs smart formatting, context‑aware capitalization, and punctuation insertion without network traffic. This capability transforms raw speech like "next line dear john comma new line thanks for meeting" into properly formatted correspondence.

Optional Cloud Fallback

For users requiring advanced capabilities, PrivateAIProvider.swift also supports OpenAI, Groq, and custom endpoints — but only when explicitly configured.

Voice‑Driven Interaction Modes

FluidVoice extends beyond dictation into active system interaction through two specialized modes.

Command Mode

CommandModeService.swift interprets spoken instructions as executable actions:

// In CommandModeService.swift — parsing and execution
func handle(_ text: String) async {
    let command = CommandParser.parse(text)
    await command.execute(using: AccessibilityService.shared)
}

Supported commands include launching applications, running Shortcuts, inserting text templates, and controlling window focus — all executed via macOS Accessibility APIs.

Rewrite Mode

RewriteModeService.swift implements a "select and improve" workflow: users highlight text in any application, trigger FluidVoice, and receive AI‑refined output inserted at the original location. This mode uses the same AccessibilityService pipeline as Command Mode for seamless integration with third‑party applications.

Real‑Time User Experience

The transcription overlay system demonstrates FluidVoice's attention to responsive design. NotchOverlayManager displays interim results in a non‑intrusive panel, while GlobalHotkeyManager ensures voice capture initiates instantly from any context:

// In GlobalHotkeyManager.swift — hotkey-to-dictation flow
func handleHotkey() {
    Task {
        await AppServices.shared.asr.start()
        NotchOverlayManager.shared.show()
    }
}

Once transcription finalizes, TypingService inserts text into the focused UI element, applies post‑processing if configured, or triggers mode‑specific handling.

Configuration and Persistence

SettingsStore.swift persists user preferences using SwiftData or equivalent persistence:

• Hotkey assignments
• Default speech model per provider
• AI enhancement preferences
• Custom dictionary entries
• Transcription history with search

This data remains local unless users explicitly enable cloud synchronization features.

Summary

FluidVoice solves the privacy‑performance trade‑off in macOS dictation through:

• Local‑first architecture where audio processing occurs on‑device in ASRService.swift
• Pluggable model system via ModelRepository.swift supporting multiple speech recognition backends
• Private AI enhancement through PrivateAIProvider.swift and the Fluid Intelligence runtime
• Voice automation capabilities implemented in CommandModeService.swift and RewriteModeService.swift
• Tight macOS integration using Accessibility APIs and global hotkey management

The result is a dictation platform that operates offline, respects user privacy, and delivers competitive latency with cloud alternatives.

Frequently Asked Questions

What makes FluidVoice different from Apple's built‑in dictation?

FluidVoice offers multiple selectable speech models, private on‑device AI post‑processing through Fluid Intelligence, and extensible voice command capabilities. While Apple Dictation uses a fixed backend and requires network connection for full functionality, FluidVoice in ASRService.swift runs entirely offline with models like Parakeet Flash achieving lower latency than Apple's cloud pipeline.

Does FluidVoice work without internet connectivity?

Yes. Core speech recognition in ASRService.swift and ModelRepository.swift functions completely offline once models are downloaded. Only optional AI enhancement through external providers (OpenAI, Groq) requires network access; the default Fluid Intelligence runtime in PrivateAIProvider.swift operates locally on Apple Silicon.

How does FluidVoice maintain user privacy?

Audio captured by ASRService.swift never leaves the machine during transcription. The application uses local speech models and, when AI enhancement is enabled, defaults to the on‑device Fluid Intelligence model rather than cloud APIs. Network traffic occurs only when users explicitly configure external providers in settings.

Can FluidVoice control other applications?

Yes. CommandModeService.swift and RewriteModeService.swift use macOS Accessibility APIs to inject text, trigger shortcuts, and manipulate focus across third‑party applications. This requires granting Accessibility permissions in System Settings, after which voice commands like "open Safari" or "rewrite this" execute system‑wide.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}