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

> Discover FluidVoice, the open-source macOS dictation tool replacing cloud services with local, private speech recognition. Enjoy on-device models and optional AI enhancement.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift), which instantiates the SwiftUI `App` and injects global services via `AppServices`:

```swift
// 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`](https://github.com/altic-dev/FluidVoice/blob/main/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:

```swift
// 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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) routes transcripts through a local LLM rather than external APIs:

```swift
// 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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/CommandModeService.swift) interprets spoken instructions as executable actions:

```swift
// 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`](https://github.com/altic-dev/FluidVoice/blob/main/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:

```swift
// 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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/ASRService.swift)
- **Pluggable model system** via [`ModelRepository.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ModelRepository.swift) supporting multiple speech recognition backends
- **Private AI enhancement** through [`PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) and the Fluid Intelligence runtime
- **Voice automation capabilities** implemented in [`CommandModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/CommandModeService.swift) and [`RewriteModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/ASRService.swift) and [`ModelRepository.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) operates locally on Apple Silicon.

### How does FluidVoice maintain user privacy?

Audio captured by [`ASRService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/CommandModeService.swift) and [`RewriteModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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.