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

> Learn how to set up FluidVoice on macOS. Install via Homebrew, grant permissions, and configure settings for local voice dictation.

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

---

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

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

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

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

```swift
import Fluid

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

```

This pattern appears in [`ContentView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ContentView.swift) within `scheduleDelayedAudioInitialization()`.

### Retrieving Current Prompts

Access the active dictation prompt template:

```swift
import Fluid

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

```

This method is defined in [`SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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:

```bash
./build.sh
open Fluid.xcodeproj

```

The [`build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift)**: Entry point (`@main`) that creates the SwiftUI app and injects `AppServices` and `MenuBarManager`.
- **[`Sources/Fluid/ContentView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/ContentView.swift)**: Hosts the main UI, initializes `GlobalHotkeyManager`, and manages the audio pipeline lifecycle.
- **[`Sources/Fluid/Persistence/SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Persistence/SettingsStore.swift)**: Centralized `UserDefaults` wrapper storing hotkeys, model selections, and AI configuration.
- **[`Sources/Fluid/Networking/AIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/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.