Keyboard Event Injection

Relevant source files

The following files were used as context for generating this wiki page:

• patches/rdev/src/lib.rs
• patches/rdev/src/macos/keyboard.rs
• apps/desktop/src-tauri/src/app.rs
• packages/desktop-native-apis/src/bindings.ts
• apps/desktop/src/components/root/AppSideEffects.tsx
• README.md

Keyboard Event Injection is a core capability of mausVoice that allows the application to programmatically insert text and simulate physical keypresses into other active applications. This system is the final stage of the voice-to-text pipeline, where transcribed and AI-cleaned text is "typed" into whichever field currently has focus on the user's operating system.

The system relies on a combination of high-level TypeScript orchestration and low-level Rust implementations. It leverages the rdev library for cross-platform event simulation and provides multiple methods for data entry, including direct clipboard pasting and character-by-character simulation, to ensure compatibility across diverse target applications.

Sources: README.md:46-60, apps/desktop/src-tauri/src/app.rs:252-254, patches/rdev/src/lib.rs:1-10

Architecture and Data Flow

The injection process is triggered after the transcription and AI cleanup phases are complete. The TypeScript "Brain" invokes specific Tauri commands in Rust, which then interface with the operating system's input APIs.

Injection Flow

The following diagram illustrates the sequence from the finalization of text to its appearance in a target application.

Insertion Methods

mausVoice supports different strategies for injecting text to handle various application behaviors and performance requirements.

Keystroke Simulation

This method simulates physical keyboard events for each character in the text. It is often slower than pasting but works in applications that block clipboard operations.

• API Command: simulate_type
• Parameters: text (string), delayMs (number)
• Mechanism: Uses the rdev::simulate function to send KeyPress and KeyRelease events sequentially.

Sources: packages/desktop-native-apis/src/bindings.ts:252-257, patches/rdev/src/lib.rs:244-246

Clipboard Pasting

The default and fastest method for large blocks of text. The application briefly occupies the system clipboard to perform the operation.

• API Command: paste
• Logic:
  1. Save current clipboard (optional/platform-dependent).
  2. Write target text to clipboard.
  3. Simulate the platform-specific "Paste" shortcut (Cmd+V on macOS, Ctrl+V on Windows).
  4. Restore previous clipboard content (if skipClipboardRestore is false).

Sources: packages/desktop-native-apis/src/bindings.ts:162-167, apps/desktop/src-tauri/src/app.rs:252-254

Technical Implementation (Rust/Native)

The native layer handles the heavy lifting of interacting with OS-specific event taps and input managers.

rdev Integration

The rdev library (v0.5.0-2) is used to abstract OS-specific keyboard layouts and event codes. It provides a unified EventType enum for simulation.

Struct/Enum	Description
EventType::KeyPress(Key)	Simulates pressing a specific key down.
EventType::KeyRelease(Key)	Simulates releasing a specific key.
UnicodeInfo	Contains interpreted character information based on current layout.

Sources: patches/rdev/src/lib.rs:115-132, patches/rdev/src/macos/keyboard.rs:206-215

macOS Implementation Details

On macOS, the system requires Accessibility API permissions to observe or modify events. The fork of rdev used in this project specifically utilizes NSEvent.addGlobalMonitorForEvents for observation, but requires CGEventTap for modification or "grabbing" of events.

• Keyboard Translation: The UCKeyTranslate function is used to convert physical scan codes into Unicode characters while respecting the user's current keyboard layout.
• Modifier State: Modifier keys (Shift, Option, Command, Control) are tracked to ensure simulated keys are interpreted correctly (e.g., simulating 's' while Shift is down results in 'S').

Sources: patches/rdev/src/macos/keyboard.rs:64-75, patches/rdev/src/lib.rs:43-60

Configuration and Constraints

Injection behavior can be customized via user preferences and application-specific targets.

Parameter	Type	Default	Description
insertionMethod	string	"paste"	Determines if simulateType or paste is used.
typingSpeedMs	number	Platform-dependent	The delay between simulated keystrokes.
pasteKeybind	string	null	Custom shortcut to trigger if the target app doesn't use standard paste.

Sources: packages/desktop-native-apis/src/bindings.ts:468-472, apps/desktop/src/components/root/AppSideEffects.tsx:431-435

Java Access Bridge (JAB)

Special handling is required for Java-based applications (e.g., Swing/AWT components). The enableJavaAccessBridge command ensures that these applications surface their text fields to the OS-level accessibility APIs, allowing mausVoice to read and write values directly rather than relying solely on simulation.

Sources: packages/desktop-native-apis/src/bindings.ts:89-106

Summary

The Keyboard Event Injection module bridges the gap between AI-generated text and the user's workflow. By utilizing the rdev library for low-level event simulation and providing flexible insertion strategies (Pasting vs. Simulation), mausVoice ensures that voice-typed text lands accurately and quickly into any focused application field across macOS, Windows, and Linux.