Can FluidVoice Be Integrated with Existing Applications?

Yes—FluidVoice integrates with any macOS application automatically through the system's Accessibility API and global hot-key dispatcher without requiring plugins, SDKs, or code changes in target apps.

FluidVoice is a macOS-only dictation tool from altic-dev/FluidVoice designed for universal compatibility. Its three-layer architecture enables seamless FluidVoice integration with existing applications through standard system APIs rather than proprietary interfaces.

How FluidVoice Achieves Universal App Integration

The codebase reveals a deliberate architectural split that makes existing application integration completely generic:

Layer	Core Component	Integration Mechanism
Input → Voice	Bundled speech model + optional "Fluid Intelligence" post-processor	Self-contained; no external dependencies
Command & Text Engine	GlobalHotkeyManager, ContentView (line 226), TypingService	Dispatches to command-mode or typing pipelines based on hot-key input
OS Interaction	TypingService, TextSelectionService	Uses AXUIElement Accessibility API for process-independent text insertion

The Accessibility (AX) API operates process-independently. This means FluidVoice can inject text into any standard macOS text field, code editor, browser, or custom UI that exposes an AX element—without the target app knowing FluidVoice exists.

Integration Requirements: Just Two System Permissions

To enable FluidVoice integration with your existing applications, users only need to grant:

1. Microphone access — for speech capture
2. Accessibility permissions — for AXUIElement control of other apps

No SDK installation, no code modifications, no plugin development required.

Key Integration Points in the Source Code

Global Hot-Key Registration (GlobalHotkeyManager.swift)

The entry point for all existing app integration begins with system-wide hot-key capture:

// Sources/Fluid/Services/GlobalHotkeyManager.swift (lines 530-540)
GlobalHotkeyManager.shared.registerHotkey(
    keyCode: kVK_Space, 
    modifiers: [.command]
) {
    // Toggles between command mode and text insertion mode
    ContentView.shared.enterCommandMode()
}

This fires regardless of which application is active—enabling FluidVoice to integrate with existing applications even when they're full-screen or backgrounded.

Text Insertion via Accessibility API (TypingService.swift)

The core integration mechanism for writing into other apps:

// Sources/Fluid/Services/TypingService.swift (lines 31-70, 1241-1296)
let service = TypingService()
service.insertText("Hello, world!")

Internal implementation:

guard let element = getFocusedTextElement(),
      let pid = AXUIElementGetPid(element, &pid) else { 
    return false 
}

// Direct AX API text insertion into focused element
AXUIElementSetAttributeValue(
    element, 
    kAXValueAttribute as CFString,
    cfText  // The transcribed speech as CFString
)

The getFocusedTextElement() function uses AXUIElementCreateSystemWide() to locate the currently focused UI element across any running macOS application.

Text Selection & Editing (TextSelectionService.swift)

For advanced existing application integration, FluidVoice can read and manipulate selected text:

• Obtain selection ranges via AXUIElementCopyAttributeValue
• Replace selections using AXUIElementSetAttributeValue
• Navigate documents without explicit app cooperation

Command Mode: Beyond Text Insertion

FluidVoice integration with existing applications extends to system-level control. After hot-key activation and voice parsing (in ContentView.swift around line 226), the command pipeline can:

• Launch applications: NSWorkspace.shared.openApplication(at:)
• Trigger shortcuts: Simulate system or app-specific key combinations
• Execute AppleScript: For apps with robust scripting dictionaries
• Select menu items: Via accessibility action simulation

All through the same Accessibility API foundation—no special cases per target application.

Critical Implementation Files for Integration

File Path	Integration Role
Sources/Fluid/Services/TypingService.swift	Core text insertion via AX element handling and virtual-key lookup
Sources/Fluid/Services/TextSelectionService.swift	Selection reading/writing for advanced editing workflows
Sources/Fluid/Services/GlobalHotkeyManager.swift	System-wide hot-key registration for mode activation
Sources/Fluid/ContentView.swift	UI state machine: command vs. write mode switching (line 226)

Limitations of FluidVoice's Integration Approach

While FluidVoice integrates with existing applications broadly, consider these constraints:

• macOS only — Windows and Linux apps are unsupported
• AX API compliance required — unusual or custom UI frameworks may not expose standard accessibility elements
• No deep API integration — cannot trigger app-internal functions beyond what AppleScript or menu simulation allows
• Sandboxed apps — some App Store apps with restricted entitlements may limit accessibility access

Summary

• FluidVoice integration with existing applications is automatic and universal on macOS through the Accessibility API
• TypingService and TextSelectionService handle all cross-app text operations via AXUIElement calls
• GlobalHotkeyManager enables system-wide activation regardless of foreground application
• No plugins, SDKs, or target-app modifications required—only macOS Microphone and Accessibility permissions
• Works with text editors, IDEs, browsers, and any standard macOS UI that implements accessibility contracts

Frequently Asked Questions

Does FluidVoice require apps to implement a special SDK or API?

No. FluidVoice integrates with existing applications through macOS system APIs alone. The Accessibility framework (AXUIElement) provides generic access to UI elements without cooperation from the target application. As implemented in altic-dev/FluidVoice, TypingService.swift writes directly to focused text fields using standard system calls.

Can FluidVoice control applications or only type text?

Both. The ContentView.swift state machine (around line 226) routes recognized speech into two paths: text mode inserts dictation via TypingService, while command mode can launch apps, trigger shortcuts, simulate menu selections, and execute AppleScript. This enables FluidVoice integration with existing applications for both content creation and workflow control.

Why does FluidVoice need Accessibility permissions to integrate with other apps?

The Accessibility API is the only macOS mechanism that allows one process to inspect and manipulate another process's UI elements. AXUIElementCreateSystemWide() and AXUIElementSetAttributeValue—used throughout TypingService.swift (lines 31-70 and 1241-1296)—require this entitlement. Without it, FluidVoice could not locate focused text fields or insert transcribed speech.

Will FluidVoice work with web apps and electron applications?

Yes, provided the application exposes standard macOS accessibility elements. Most browsers (Safari, Chrome, Firefox) and Electron-based apps implement these contracts sufficiently for TextSelectionService to identify and write to text inputs. However, custom rendering engines or heavily modified accessibility trees may limit integration with existing applications in those specific cases.

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