Text Insertion Modes in FluidVoice: A Complete Guide to Clipboard‑Free vs. Clipboard Paste

FluidVoice supports two text insertion modes: standard (Clipboard Free Insert) for fastest direct AX API insertion, and reliablePaste (Clipboard Paste) for broader app compatibility using temporary clipboard operations.

The altic-dev/FluidVoice repository implements these dual strategies to balance speed against cross-application reliability. Whether dictating into native macOS apps or proprietary software with limited accessibility support, users control insertion behavior through a single SettingsStore.TextInsertionMode setting that propagates throughout the typing engine, UI layer, and automatic dictionary correction systems.

The Two Text Insertion Modes in FluidVoice

FluidVoice's insertion architecture centers on an enum defined in Sources/Fluid/Persistence/SettingsStore.swift. The TextInsertionMode type declares exactly two cases with distinct behavioral contracts:

// Sources/Fluid/Persistence/SettingsStore.swift
enum TextInsertionMode: String, CaseIterable, Identifiable {
    case standard
    case reliablePaste
    
    var displayName: String { ... }
    var description: String { ... }
}

Standard Mode: Clipboard Free Insert

Use case: Maximum speed in well-behaved applications.

In standard mode, the typing engine attempts direct text insertion via macOS Accessibility (AX) APIs without ever modifying the system clipboard. This eliminates clipboard flicker and preserves the user's pasteboard history. According to the source in Sources/Fluid/Services/TypingService.swift, if direct insertion fails, the engine performs a transparent fallback to paste operations—still without altering clipboard contents.

Implementation path in TypingService.swift (lines 59-66):

switch SettingsStore.shared.textInsertionMode {
case .standard:
    // Direct AX-based insertion, clipboard untouched
    tryInsertDirectly(text)

Reliable Paste Mode: Clipboard Paste

Use case: Maximum compatibility with problematic applications.

The reliablePaste mode trades temporary clipboard modification for broader app support. The TypingService temporarily copies transcribed text to the clipboard, executes a standard paste command, then restores the previous clipboard contents. This brief window of clipboard change enables text insertion in apps that block or mishandle AX API events.

case .reliablePaste:
    // Temporary clipboard manipulation with automatic restore
    tryInsertViaClipboard(text)
}

How FluidVoice Stores and Retrieves the Insertion Mode

The mode persistence layer lives in SettingsStore.swift (lines 5395-5419). The enum provides user-facing metadata through computed properties:

Property	Standard	ReliablePaste
displayName	"Clipboard Free Insert"	"Clipboard Paste"
description	Fastest path, no clipboard changes	Compatibility path, brief clipboard change

Retrieving the active mode anywhere in the codebase:

let mode = SettingsStore.shared.textInsertionMode
print("Current insertion mode: \(mode.displayName)")

Programmatic mode switching persists automatically through the store:

SettingsStore.shared.textInsertionMode = .reliablePaste

UI Integration in SettingsView

The mode selector appears in Sources/Fluid/UI/SettingsView.swift (lines 851-865) as a SwiftUI Picker with inline descriptions:

Picker("Text Insertion Mode", selection: $settings.textInsertionMode) {
    ForEach(SettingsStore.TextInsertionMode.allCases) { mode in
        Text(mode.displayName).tag(mode)
    }
}
Text(settings.textInsertionMode.description)
    .font(.caption)
    .foregroundColor(.secondary)

This binds bidirectionally to SettingsStore.shared.textInsertionMode, ensuring immediate effect on subsequent dictation operations.

Cross-System Consumption of the Mode Setting

The TextInsertionMode value propagates beyond core typing:

• Automatic dictionary correction tracking (Sources/Fluid/Services/AutomaticDictionaryCorrectionTracker.swift) adjusts its heuristics based on insertion path
• UI state across multiple views reflects the current selection without redundant storage
• TypingService routing evaluates the mode on every insertion request

Summary

• FluidVoice provides two insertion modes controlled by SettingsStore.TextInsertionMode
• Standard mode uses direct AX API insertion with zero clipboard impact
• Reliable paste mode temporarily manipulates the clipboard for broader app compatibility, then restores previous contents
• All components read from a single source of truth in SettingsStore.shared.textInsertionMode
• Implementation spans SettingsStore.swift (definition/persistence), TypingService.swift (execution routing), and SettingsView.swift (user interface)

Frequently Asked Questions

How do I change text insertion modes in FluidVoice?

Open FluidVoice's settings/preferences and locate the "Text Insertion Mode" picker. Select Clipboard Free Insert for speed or Clipboard Paste for compatibility with problematic applications. The change takes effect immediately for subsequent dictation.

Does reliable paste mode destroy my clipboard history?

No. The reliablePaste implementation in TypingService.swift saves the existing clipboard contents, inserts the transcribed text via paste, then automatically restores the original clipboard state. The interruption lasts milliseconds and is generally imperceptible during normal use.

Why does FluidVoice need two different insertion methods?

macOS applications vary widely in accessibility compliance. Native Cocoa apps typically accept AX API insertion (standard mode), while web apps, Electron-based software, and some enterprise tools block these events. The dual-mode architecture lets users optimize for their specific application mix without code changes.

Can I detect programmatically which mode is active?

Yes. Query SettingsStore.shared.textInsertionMode from any Swift code in the FluidVoice project. The returned enum provides displayName for UI presentation and can be switched using standard Swift assignment to .standard or .reliablePaste.

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