How to Set Up a Local Instance of FluidVoice: Complete macOS Development Guide

Setting up a local FluidVoice instance requires cloning the SwiftUI-based macOS app from GitHub, building it in Xcode with proper code signing, and granting Microphone and Accessibility permissions to enable real-time voice-to-text dictation.

FluidVoice is a macOS-only voice-to-text dictation application built with SwiftUI and a modular architecture of Swift services. When you run a local instance, you execute the same production codebase that powers the released app, compiled directly from source. This guide walks through the complete setup process using the actual source files from altic-dev/FluidVoice.

Prerequisites for Local FluidVoice Development

Before building, ensure your environment meets these requirements:

• macOS (FluidVoice is macOS-only)
• Xcode with Swift Package Manager support
• Apple Development certificate for code signing (free "Personal Team" certificates work)
• Microphone and Accessibility permissions available to grant

The app cannot run on iOS, iPadOS, or Linux due to its dependency on CoreAudio and macOS Accessibility APIs.

Step-by-Step Setup Process

1. Clone the FluidVoice Repository

Start by cloning the repository and entering the project directory:

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

2. Open the Xcode Project

The project file Fluid.xcodeproj contains the Fluid target and all Swift Package Manager (SPM) dependencies:

open Fluid.xcodeproj

3. Configure Code Signing

FluidVoice requires an Apple Development certificate for proper signing. The repository includes build.sh to automate this process:

./build.sh          # signed build using first available development identity

./build.sh unsigned # unsigned build for CI environments

The script extracts your development team automatically, or you can set FLUIDVOICE_DEVELOPMENT_TEAM manually. If no certificate exists, Xcode prompts you to create a free "Personal Team" certificate.

Without proper signing, macOS Accessibility permissions (required for typing into other apps) will not function correctly.

4. Build and Run the Application

In Xcode:

1. Select the Fluid scheme
2. Press Run (⌘R)

The compiled binary appears at DerivedData/Build/Products/Debug/FluidVoice Debug.app.

For command-line builds:

./build.sh

5. Grant Required System Permissions

On first launch, macOS requests two essential permissions:

Permission	Purpose	Source Component
Microphone	Audio capture for speech recognition	FluidAudioProvider.swift
Accessibility	Type transcription into any application	TextSelectionService via MenuBarManager

To manually open system preferences, use the menu bar shortcut provided by MenuBarManager.openPreferencesFromUI().

6. Optional: Enable Fluid Intelligence

Fluid Intelligence provides on-device AI enhancement for capitalization, punctuation, and context-aware formatting. During onboarding:

1. Download the optional AI model (~3.5 GB)
2. The LocalAPI server (LocalAPIServer.swift) handles the download
3. Models are cached locally; no network traffic occurs after download

To enable programmatically:

let aiService = PrivateAIProvider.shared
aiService.enableLocalModel(at: URL(fileURLWithPath: "/path/to/fluid_intelligence.bin"))

Core Architecture Overview

Understanding the component structure helps with debugging and customization:

Component	File Path	Responsibility
FluidApp	Sources/Fluid/fluidApp.swift	@main entry point; creates SwiftUI window, injects MenuBarManager and AppServices
MenuBarManager	Sources/Fluid/Services/MenuBarManager.swift	Status-item management, overlay lifecycle, user action routing
FluidAudioProvider	Sources/Fluid/Services/FluidAudioProvider.swift	CoreAudio bridge feeding raw PCM to ASR providers
ASR Services	Sources/Fluid/Services/WhisperProvider.swift (and siblings)	TranscriptionProvider implementations: WhisperProvider, ParakeetRealtimeProvider, NemotronProvider
PrivateAIProvider	Sources/Fluid/Services/PrivateAIProvider.swift	Optional cloud or local AI post-processing
LocalAPIServer	Sources/Fluid/Services/LocalAPI/LocalAPIServer.swift	On-device HTTP server for Fluid Intelligence inference
AnalyticsService	Sources/Fluid/Analytics/AnalyticsService.swift	Anonymous usage collection (opt-in); guarantees no audio/text leaves device without explicit cloud AI enablement

Running Integration Tests

Verify your local instance with the test suite:

xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS'

Programmatic Control Examples

Custom Launch Script (CI/Automated Demos)

import SwiftUI

@main
struct DemoLauncher {
    static func main() {
        // Directly instantiate the main app struct
        FluidApp.main()
    }
}

Trigger Recording from Code

let asrService = ASRService.shared   // Concrete TranscriptionProvider subclass
asrService.startRecording()          // Begins audio capture via FluidAudioProvider
// … transcription streams via partialTranscription …
asrService.stopRecording()           // Triggers finalTranscription and overlay hide

Troubleshooting Common Issues

Issue	Cause	Solution
Accessibility permission denied	Unsigned build or revoked certificate	Use ./build.sh with valid development team
No audio input	Microphone permission blocked	Check Security & Privacy → Microphone
Overlay doesn't appear	MenuBarManager initialization failed	Verify AppServices singleton creation in fluidApp.swift
Local AI won't download	LocalAPIServer port conflict	Check port availability; server logs in Console

Summary

• Clone from https://github.com/altic-dev/FluidVoice.git
• Build using Xcode or ./build.sh with proper code signing
• Grant Microphone and Accessibility permissions on first launch
• Enable optional Fluid Intelligence for on-device AI enhancement
• Test with xcodebuild test or the scheme's Run action

A properly configured local FluidVoice instance provides full access to the same real-time dictation, multi-provider ASR switching, and optional AI post-processing available in production releases.

Frequently Asked Questions

Can I run FluidVoice on Windows or Linux?

No. FluidVoice is macOS-only due to dependencies on CoreAudio for audio capture and macOS Accessibility APIs for text insertion. The entire architecture in Sources/Fluid/Services/ assumes Apple platform frameworks. Porting would require replacing FluidAudioProvider.swift and TextSelectionService with platform-specific alternatives.

Do I need a paid Apple Developer account?

No. A free "Personal Team" certificate from Xcode satisfies the signing requirement. The build.sh script automatically configures this, or you can create one when Xcode prompts during first build. Paid accounts are only needed for App Store distribution.

What data leaves my machine when using FluidVoice?

Nothing by default. According to AnalyticsService.swift, the app collects only anonymous usage statistics (opt-in). Audio and transcripts remain on-device unless you deliberately enable a cloud AI provider. The optional Fluid Intelligence model runs entirely through LocalAPIServer.swift without network calls after initial download.

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