How to Set Up FluidVoice on macOS: Complete Installation and Configuration Guide

Install FluidVoice via Homebrew with brew install --cask fluidvoice, grant Microphone and Accessibility permissions, configure your global hotkey, and select a speech model to begin local voice dictation.

FluidVoice is an open-source, SwiftUI-based voice-to-text dictation application designed exclusively for macOS. This guide walks you through the complete process to set up FluidVoice on macOS, from installation through the entry point in Sources/Fluid/fluidApp.swift to configuring the audio pipeline and AI enhancements. All configuration persists through the SettingsStore class and initializes through the FluidApp struct.

Installation Methods

Install via Homebrew (Recommended)

The fastest way to set up FluidVoice on macOS is using Homebrew. Run the following command in Terminal:

brew install --cask fluidvoice

This downloads the latest release and installs the app to /Applications.

Manual Installation

Alternatively, download the latest .dmg from the GitHub Releases page. Open the disk image and drag FluidVoice to your /Applications folder. This method requires manual updates when new versions release.

Granting Required Permissions

FluidVoice requires two core permissions to function. When the app first launches, macOS presents standard system dialogs requesting access.

Microphone Access

The Microphone permission enables the audio capture pipeline in ASRService. Without this, the app cannot receive audio input. Approve the dialog or manually add FluidVoice in System Settings → Privacy & Security → Microphone.

Accessibility Permissions

Accessibility access allows FluidVoice to insert transcribed text into other applications using Accessibility.write(text:). Grant this in System Settings → Privacy & Security → Accessibility to enable text injection into the foreground window.

Configuring Your Dictation Environment

After installation, configure the global hotkey and speech model through the Settings interface.

Setting the Global Hotkey

FluidVoice uses GlobalHotkeyManager to listen for system-wide shortcuts that trigger dictation. The default hotkey is ⌃ Space (Control+Space), instantiated in ContentView.swift.

To update the hotkey programmatically, modify SettingsStore and notify the manager:

import Fluid

let newShortcut = HotkeyShortcut(keyCode: 49, modifierFlags: [.control])
SettingsStore.shared.primaryDictationShortcuts = [newShortcut]
AppServices.shared.hotkeyManager?.updatePrimaryShortcuts([newShortcut])

This mirrors the implementation in ContentView.swift lines 84-90 within the applyShortcutStateChanges method.

Selecting a Speech Recognition Model

In Settings → Voice Engine, choose from available models including Apple, Nemotron, Parakeet, and Whisper. The available models populate from SettingsStore.availableModelsByProvider, loaded at startup via loadProviderState() in ContentView.swift. Select a model matching your latency requirements and hardware capabilities.

Enabling Advanced Features (Optional)

Fluid Intelligence AI Enhancement

For on-device post-processing including smart punctuation and capitalization, enable Fluid Intelligence in Settings → AI Enhancements. This feature uses the AIProvider protocol implementations such as AppleIntelligenceProvider or FunctionCallingProvider, configured through AIEnhancementSettingsView.swift.

Programmatic Configuration

For developers extending FluidVoice, the SDK exposes core services through AppServices.

Initializing the Audio Pipeline

Manually start the speech recognition service:

import Fluid

let services = AppServices.shared
services.asr.initialize()
Task {
    await services.asr.start()
}

This pattern appears in ContentView.swift within scheduleDelayedAudioInitialization().

Retrieving Current Prompts

Access the active dictation prompt template:

import Fluid

let prompt = SettingsStore.shared.effectivePromptBody(for: .dictate)
print("Current dictation prompt:\n\(prompt)")

This method is defined in SettingsStore.swift.

Starting Your First Dictation

Press your configured global hotkey to activate the floating Notch overlay managed by NotchOverlayManager and MenuBarManager. Speak naturally, and watch the live transcription appear. When dictation completes, the text automatically inserts into the active application via macOS accessibility APIs.

Verification and Testing

To verify the build from source or run a debug session, use the repository's build script:

./build.sh
open Fluid.xcodeproj

The build.sh script compiles the Xcode project, allowing you to inspect the AppServices initialization and ContentView lifecycle directly.

Key Source Files

Understanding the codebase helps with advanced configuration:

• Sources/Fluid/fluidApp.swift: Entry point (@main) that creates the SwiftUI app and injects AppServices and MenuBarManager.
• Sources/Fluid/ContentView.swift: Hosts the main UI, initializes GlobalHotkeyManager, and manages the audio pipeline lifecycle.
• Sources/Fluid/Persistence/SettingsStore.swift: Centralized UserDefaults wrapper storing hotkeys, model selections, and AI configuration.
• Sources/Fluid/Networking/AIProvider.swift: Abstract protocol for AI backends including local and cloud providers.

Summary

• Install FluidVoice using brew install --cask fluidvoice or manual download.
• Grant Microphone and Accessibility permissions in System Settings.
• Configure a global hotkey (default ⌃ Space) in Settings.
• Select a speech model from the provider list in Settings → Voice Engine.
• Optionally enable Fluid Intelligence for AI-enhanced formatting.
• Begin dictating; text automatically inserts into the active window via Accessibility.write(text:).

Frequently Asked Questions

Is FluidVoice compatible with Apple Silicon and Intel Macs?

Yes. FluidVoice supports both Apple Silicon and Intel architectures. The SwiftUI codebase in Sources/Fluid/fluidApp.swift and underlying speech recognition services compile natively for both platforms, with model selection adapting to available hardware capabilities.

Does FluidVoice require an internet connection?

No. FluidVoice runs entirely locally for core dictation functions. The ASRService processes audio on-device using local models like Apple's Neural Engine or Whisper variants. Internet connectivity is only required if you configure cloud AI providers through FunctionCallingProvider for advanced enhancements.

How do I customize the dictation prompt templates?

Modify prompt templates programmatically by accessing SettingsStore.shared.effectivePromptBody(for: .dictate). This method retrieves the current prompt configuration stored in SettingsStore.swift, allowing you to customize formatting instructions passed to the AI enhancement pipeline.

Why does FluidVoice need Accessibility permissions?

Accessibility permissions enable the Accessibility.write(text:) method to synthesize keystrokes and insert transcribed text into any foreground application. Without this permission, FluidVoice cannot deliver text to your target apps, though it will still display transcription in the overlay.

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