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

> Explore FluidVoice text insertion modes: Clipboard Free Insert for speed and reliablePaste for wider app compatibility. Learn how to choose the best method for your needs.

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

---

**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`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Persistence/SettingsStore.swift). The `TextInsertionMode` type declares exactly two cases with distinct behavioral contracts:

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

```swift
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.

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

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

```

Programmatic mode switching persists automatically through the store:

```swift
SettingsStore.shared.textInsertionMode = .reliablePaste

```

## UI Integration in SettingsView

The mode selector appears in [`Sources/Fluid/UI/SettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/SettingsView.swift) (lines 851-865) as a SwiftUI `Picker` with inline descriptions:

```swift
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`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/SettingsStore.swift) (definition/persistence), [`TypingService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/TypingService.swift) (execution routing), and [`SettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/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`](https://github.com/altic-dev/FluidVoice/blob/main/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`.