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

> Learn how to set up FluidVoice for macOS with our complete guide. Install via Homebrew or manually, grant permissions, and configure hotkeys for efficient voice dictation.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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:

```bash
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](https://github.com/altic-dev/FluidVoice/releases)
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:

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

```

Or use the provided build script for automated compilation:

```bash
./build.sh

```

The [`build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/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)](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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/MenuBarManager.swift) 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](https://github.com/Clipy/Sauce):

```swift
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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/SettingsStore.swift) 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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/AppServices.swift), which coordinates between the audio engine and model inference:

```swift
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/fluidApp.swift)](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift) initializes the SwiftUI lifecycle and injects core services:

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