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

Install FluidVoice on macOS via Homebrew or manual download, grant microphone and accessibility permissions, configure a global hotkey, and optionally enable on-device AI processing for private voice dictation.

FluidVoice is a Swift-based macOS application that delivers on-device, AI-enhanced voice dictation without sending audio to cloud servers. According to the altic-dev/FluidVoice source code, the app architecture centers on a SwiftUI app harness that coordinates audio capture, transcription pipelines, and optional AI post-processing—all while respecting user privacy through local execution.

Prerequisites and System Requirements

FluidVoice requires macOS 15.0 or later. The app depends on several core Apple frameworks:

• Core Audio for low-latency microphone capture (via CoreAudioCaptureSupportBridge)
• Accessibility APIs for global hotkey registration and text insertion
• Speech Recognition frameworks for transcription
• Swift Package Manager for dependency resolution

Ensure your Mac has sufficient storage for models: base transcription models range from 100MB–1GB, while the optional Fluid Intelligence AI model requires approximately 3.5 GB.

Installation Methods

Install via Homebrew (Recommended)

The fastest path to set up FluidVoice for macOS uses the official Homebrew Cask:

brew install --cask fluidvoice

This downloads the latest signed release, handles quarantine, and places FluidVoice in /Applications.

Manual Installation from GitHub Releases

1. Visit the FluidVoice releases page
2. Download the .dmg for your architecture (Intel or Apple Silicon)
3. Mount the disk image and drag FluidVoice to /Applications

Build from Source (Developers)

To compile FluidVoice directly from the repository:

git clone https://github.com/altic-dev/FluidVoice.git
cd FluidVoice
open Fluid.xcodeproj

Or use the provided build script for automated compilation:

./build.sh

The build.sh script resolves signing identity and outputs the debug build to DerivedData/Build/Products/Debug/FluidVoice Debug.app. All third-party dependencies—including OpenAI, PostHog, and AppleSpeech packages—are declared in [Package.swift](https://github.com/altic-dev/FluidVoice/blob/main/Package.swift) and fetched automatically.

Granting Required macOS Permissions

On first launch, FluidVoice triggers three permission dialogs defined in Info.plist:

Permission	Purpose	Plist Key
Microphone	Capture speech audio for transcription	NSMicrophoneUsageDescription
Accessibility	Register global hotkeys and insert text into other apps	NSAccessibilityUsageDescription
Speech Recognition	Enable on-device transcription (if using Apple Speech)	NSSpeechRecognitionUsageDescription

To verify or modify permissions later, open System Settings → Privacy & Security and locate FluidVoice in each category.

Configuring the Global Hotkey

The MenuBarManager class handles hotkey registration. To configure yours:

1. Open FluidVoice Settings (gear icon in menu bar)
2. Navigate to Hotkey
3. Press your desired key combination

The underlying registration uses HotKey from Sauce:

func registerHotkey(_ keyCombo: KeyCombo) {
    hotkey = HotKey(keyCombo: keyCombo) { [weak self] in
        self?.appServices.startCapture()
    }
}

This hotkey works system-wide, activating voice capture regardless of which app is frontmost.

Selecting and Downloading Speech Models

FluidVoice supports multiple transcription backends. During onboarding or in Settings → Models, choose from:

• Apple Speech — Uses Apple's Neural Engine, no additional download
• Parakeet — On-device Whisper variant, ~500 MB download
• Nemotron — NVIDIA-optimized model for Apple Silicon
• Whisper — OpenAI's original model, various sizes available

Models download on-demand to ~/Library/Application Support/FluidVoice/models. The SettingsStore persists your selection across launches.

Enabling Fluid Intelligence (Optional On-Device AI)

For private, offline post-processing of transcriptions, enable Fluid Intelligence during onboarding or in Settings. This feature:

• Downloads a ~3.5 GB local AI model
• Runs entirely on-device using Core ML and the Neural Engine
• Provides grammar correction, formatting, and context-aware edits
• Requires no internet connection and sends no data to servers

The AI pipeline is hosted in AppServices, which coordinates between the audio engine and model inference:

class AppServices {
    static let shared = AppServices()
    private let audioEngine = AudioEngine()
    
    func startCapture() {
        audioEngine.start()
        // Audio routed to ASR, then optional Fluid Intelligence
    }
}

Adding Cloud AI Providers (Optional)

For users preferring cloud-based post-processing, FluidVoice supports external providers:

1. Open Settings → AI Providers
2. Select OpenAI, Groq, or Custom
3. Enter your API key

Keys are stored securely in the macOS Keychain—the app never writes them to disk or plist files. You can switch between local Fluid Intelligence and cloud providers per-transcription using the menu bar interface.

Understanding the App Architecture

The main entry point [fluidApp.swift](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift) initializes the SwiftUI lifecycle and injects core services:

import SwiftUI

@main
struct FluidApp: App {
    @StateObject private var menuBarManager = MenuBarManager()
    @StateObject private var appServices = AppServices.shared
    @ObservedObject private var settings = SettingsStore.shared

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(menuBarManager)
                .environmentObject(appServices)
        }
    }
}

Audio capture flows through the CoreAudioCaptureSupportBridge—a thin C header bridging Swift to low-latency Core Audio APIs defined in [CoreAudioCaptureSupportBridge.h](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/CoreAudioCaptureSupportBridge.h).

Troubleshooting Common Setup Issues

Issue	Cause	Resolution
"FluidVoice cannot be opened"	Unidentified developer	Right-click → Open, or xattr -d com.apple.quarantine /Applications/FluidVoice.app
Hotkey not responding	Accessibility permission denied	Re-grant in System Settings → Privacy & Security → Accessibility
No audio detected	Microphone permission denied	Check permission and verify input device in System Settings → Sound
Model download fails	Insufficient disk space	Free space in ~/Library/Application Support/FluidVoice or select smaller model

Summary

• Install via brew install --cask fluidvoice or manual download from GitHub releases
• Grant permissions for Microphone, Accessibility, and Speech Recognition on first launch
• Configure hotkey in Settings to activate capture from any application
• Select transcription model matching your latency and accuracy needs
• Enable Fluid Intelligence for private, on-device AI post-processing (3.5 GB download)
• Add cloud providers optionally, with API keys secured in macOS Keychain
• Build from source using Xcode or ./build.sh for development

Frequently Asked Questions

Does FluidVoice work on Intel Macs?

Yes. FluidVoice supports both Intel and Apple Silicon architectures. The build.sh script and GitHub releases provide universal binaries that run natively on either platform, with Apple Silicon builds optimized for the Neural Engine.

Is my voice data sent to the cloud?

Only if you explicitly enable a cloud AI provider. By default, FluidVoice performs all transcription and optional AI processing on-device. The AppServices class routes audio through local models unless you configure an external API key.

How do I update FluidVoice?

Homebrew users run brew upgrade --cask fluidvoice. Manual installations check for updates automatically via the Sparkle framework (configured in Info.plist). The app prompts when new versions are available and can self-update with one click.

Can I use FluidVoice without the menu bar icon?

No—the menu bar icon is required for global hotkey functionality. The MenuBarManager class registers the hotkey through CGEvent.tapCreate, which requires a running process with menu bar presence. Disabling the icon would break the core activation mechanism.

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