# FluidVoice Configuration Options: Complete Guide to SettingsStore and Customization

> Explore FluidVoice configuration options with our complete guide to SettingsStore and customization. Learn how FluidVoice manages settings securely using UserDefaults and the macOS Keychain.

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

---

**FluidVoice stores all user-adjustable settings in the `SettingsStore` singleton, which serializes complex objects as JSON in `UserDefaults` while securing sensitive data like API keys in the macOS Keychain.**

FluidVoice is an open-source macOS dictation application that provides extensive customization through its centralized configuration system. All settings are managed through the `SettingsStore` class located in [`Sources/Fluid/Persistence/SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Persistence/SettingsStore.swift), offering programmatic access to AI processing parameters, prompt profiles, and system integration preferences. Understanding these **FluidVoice configuration options** allows you to tailor dictation shortcuts, custom LLM providers, and per-application behaviors to specific workflow requirements.

## Core Configuration Architecture

### The SettingsStore Singleton

The heart of FluidVoice's configuration system is the **`SettingsStore`** singleton, defined in [`Sources/Fluid/Persistence/SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Persistence/SettingsStore.swift). This class acts as a thin wrapper around `UserDefaults` and `Keychain`, exposing type-safe properties for all user-adjustable values. The store handles JSON encoding for complex objects like prompt profiles and provider definitions, while delegating sensitive credentials to the `KeychainService`.

### Persistence Mechanisms

FluidVoice uses a tiered persistence strategy:

- **Simple scalars** (booleans, strings) are saved directly in `UserDefaults` via the `defaults` field
- **Complex collections** (arrays of profiles, bindings, configurations) are JSON-encoded using `JSONEncoder`/`JSONDecoder` on each read/write operation
- **Sensitive data** such as provider API keys are stored securely in the macOS Keychain via `KeychainService.shared` (defined in [`Sources/Fluid/Services/KeychainService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/KeychainService.swift))

## Available Configuration Categories

### Dictation Modes and Prompt Profiles

FluidVoice supports distinct operational modes controlled by the **`PromptMode`** enum (`Sources/Fluid/Persistence/SettingsStore.swift#L43-L58`):

- `dictate` – Standard dictation enhancement mode
- `edit` – Text editing and rewriting mode (legacy values `write` and `rewrite` are also supported for backwards compatibility)

**Prompt profiles** allow users to define named system prompts that can be selected per-app or globally. These are stored as `DictationPromptProfile` structs (`SettingsStore.swift#L19-L27`) containing:

- `id` – Unique identifier
- `name` – Display name
- `prompt` – The actual system prompt text
- `mode` – Associated `PromptMode`
- `includeContext` – Boolean flag for context inclusion
- `timestamps` – Creation/modification metadata

### Shortcut Configurations and AI Providers

The application supports two **dictation shortcut slots** (`DictationShortcutSlot` enum: `primary` and `secondary`) defined at `SettingsStore.swift#L96-L102`. Each slot is configured via **`DictationPromptConfiguration`** (`SettingsStore.swift#L28-L33`), which specifies:

- `shortcut` – Optional `HotkeyShortcut` (key code and modifier flags)
- `providerID` – Identifier for the AI provider
- `modelName` – Specific model to use for that shortcut

For custom LLM integration, **`SavedProvider`** structs (`SettingsStore.swift#L234-L242`) store:
- Provider name and unique ID
- Base URL for API endpoints
- API key (stored in Keychain)
- Available model list

### App-Specific Prompt Bindings

**`AppPromptBinding`** structs (`SettingsStore.swift#L68-L77`) enable per-application customization by overriding prompts for specific bundle IDs. Each binding contains:
- `mode` – The prompt mode to apply
- `bundleID` – Target application identifier
- `appName` – Human-readable application name
- `profileID` – Optional reference to a custom `DictationPromptProfile`

### AI Processing and Reasoning Controls

Global AI behavior is controlled by **`enableAIProcessing`** (`SettingsStore.swift#L250-L253`), a boolean that toggles the entire AI pipeline including dictation enhancement and reasoning.

For advanced model control, **`ModelReasoningConfig`** (`SettingsStore.swift#L191-L210`) stores per-model "thinking" parameters such as `reasoning_effort` and `enable_thinking`, allowing fine-tuned control over model behavior during transcription processing.

### System Integration Settings

FluidVoice integrates deeply with macOS through several system-level configurations:

- **`launchAtStartupEnabled`** – Controls login item registration (`SettingsStore.swift#L20-L24`)
- **`launchAtStartupErrorMessage`** and **`launchAtStartupStatusMessage`** – Status reporting for startup registration
- **`showMainWindowAtLoginLaunch`** – Boolean determining whether the main window appears automatically when FluidVoice launches at login (`SettingsStore.swift#L158-L167`)

Additionally, users can override built-in default prompts using:
- **`defaultDictationPromptOverride`** – Replaces the standard dictation system prompt
- **`defaultEditPromptOverride`** – Replaces the standard edit/rewrite system prompt

## Accessing and Modifying Configuration Programmatically

All configuration values are accessible through `SettingsStore.shared`. Below are practical examples for common customization tasks.

### Check AI Processing Status

```swift
import Fluid

let aiEnabled = SettingsStore.shared.enableAIProcessing   // Returns true or false

```

### Configure a Dictation Shortcut

```swift
import Fluid

// Create a new configuration with Command+1 shortcut using OpenAI GPT-4o
let newConfig = SettingsStore.DictationPromptConfiguration(
    shortcut: HotkeyShortcut(keyCode: 0x31, modifiers: [.command]),
    providerID: "openai",
    modelName: "gpt-4o"
)

// Apply to the primary shortcut slot
SettingsStore.shared.setDictationPromptConfiguration(newConfig, for: .primary)

```

### Create a Custom Prompt Profile

```swift
import Fluid

let profile = SettingsStore.DictationPromptProfile(
    name: "MyBusiness",
    prompt: SettingsStore.defaultPromptBodyText(for: .dictate) + "\n\nYou are a business‑style transcriber.",
    mode: .dictate,
    includeContext: true
)

// Append to stored profiles
var profiles = SettingsStore.shared.dictationPromptProfiles
profiles.append(profile)
SettingsStore.shared.dictationPromptProfiles = profiles

```

### Override Default System Prompts

```swift
import Fluid

SettingsStore.shared.defaultDictationPromptOverride = """
You are a concise dictation cleaner. Remove filler words and keep only the final sentence.
"""

```

### Add a Custom AI Provider

```swift
import Fluid

let provider = SettingsStore.SavedProvider(
    name: "Local LLaMA",
    baseURL: "http://127.0.0.1:8080/v1",
    apiKey: ""          // Empty for local servers without authentication
)

var providers = SettingsStore.shared.savedProviders
providers.append(provider)
SettingsStore.shared.savedProviders = providers

```

### Configure Startup Behavior

```swift
import Fluid

SettingsStore.shared.launchAtStartupEnabled = true
SettingsStore.shared.showMainWindowAtLoginLaunch = false

```

## UI Integration Points

The configuration system powers several key UI components:

- **AI Settings pane** – `Sources/Fluid/UI/AISettingsView+AdvancedSettings.swift` and [`AIEnhancementSettingsViewModel.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AIEnhancementSettingsViewModel.swift) manage `dictationPromptConfigurations`, prompt overrides, and `ModelReasoningConfig` values
- **Prompt editor** – [`Sources/Fluid/UI/AISettings/AIEnhancementSettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/AISettings/AIEnhancementSettingsView.swift) displays and edits `DictationPromptProfile` objects
- **Shortcut preferences** – [`Sources/Fluid/UI/RecordingView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/RecordingView.swift) reads `DictationShortcutSlot` and associated `DictationPromptConfiguration` data
- **App-specific bindings** – [`Sources/Fluid/UI/NotchContentViews.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/NotchContentViews.swift) and [`Sources/Fluid/Services/NotchOverlayManager.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/NotchOverlayManager.swift) use `appPromptBinding(for:appBundleID:)` to apply per-application prompts dynamically

## Summary

- **FluidVoice configuration options** are centralized in the `SettingsStore` singleton ([`SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/SettingsStore.swift)), which provides type-safe access to all settings.
- Complex objects like `DictationPromptProfile`, `SavedProvider`, and `AppPromptBinding` are JSON-encoded for `UserDefaults` storage, while API keys are secured in the macOS Keychain.
- Configuration categories include dictation modes (dictate vs. edit), shortcut slot configurations, per-app prompt bindings, AI reasoning parameters, and system integration settings.
- All values are accessible programmatically via `SettingsStore.shared`, allowing automation and extension of the application's behavior.
- UI components in `AISettingsView`, `RecordingView`, and `NotchContentViews` consume these settings to provide the user-facing configuration interface.

## Frequently Asked Questions

### How do I add a custom AI provider to FluidVoice?

Create a `SavedProvider` struct with your provider's name, base URL, and API key, then append it to `SettingsStore.shared.savedProviders`. The provider becomes available immediately in the AI provider selection dropdowns throughout the application. API keys are automatically stored in the macOS Keychain via `KeychainService`.

### Where are FluidVoice settings stored on macOS?

Simple settings reside in `UserDefaults` under the application's bundle identifier, while complex objects are JSON-serialized before storage. Sensitive information such as LLM API keys are stored in the macOS Keychain. You can inspect raw values using the `defaults` command line tool, though complex objects will appear as JSON strings.

### Can I set different prompts for different applications?

Yes. FluidVoice supports **app-specific prompt bindings** through the `AppPromptBinding` struct. You can create bindings that associate specific bundle IDs with custom `DictationPromptProfile` objects or default prompt overrides. The system automatically resolves the appropriate prompt when you activate dictation in different applications.

### How do I disable AI processing entirely?

Set `SettingsStore.shared.enableAIProcessing = false`. This boolean flag (`SettingsStore.swift#L250-L253`) disables the entire AI enhancement pipeline, causing FluidVoice to function as a standard dictation tool without LLM post-processing. This is useful for offline usage or when you require raw transcription output without modification.