How OpenSuperWhisper Implements Auto-Paste into the Focused Application

OpenSuperWhisper implements auto-paste by copying transcription text to the system pasteboard, synthesizing a Cmd+V keystroke using macOS CGEvent APIs, and restoring the original clipboard contents after a short delay to prevent data loss.

OpenSuperWhisper is an open-source macOS transcription application that automatically inserts recognized text into whichever window is currently active. This article examines exactly how the app implements auto-paste into the focused application through a dedicated utility class that coordinates clipboard management, keyboard event simulation, and state preservation.

How the Auto-Paste Pipeline Works

When transcription completes, the application checks the user’s preference in Settings.swift. If auto-paste is enabled, the pipeline calls ClipboardUtil.insertText(_:); otherwise, it only copies the text to the clipboard without triggering a paste operation.

The auto-paste workflow follows four distinct steps:

1. Save the current pasteboard contents to preserve the user’s existing clipboard data.
2. Write the transcription to NSPasteboard.general as a string.
3. Synthesize a Cmd+V keystroke using Core Graphics events that the focused application receives.
4. Restore the original clipboard after a 1.5-second delay, but only if the pasteboard hasn't been modified by another process.

This approach ensures that the transcription appears exactly where the user expects it—at the current cursor position in the active window—while minimizing disruption to the user’s clipboard history.

Deep Dive into ClipboardUtil.swift

The core logic resides in OpenSuperWhisper/Utils/ClipboardUtil.swift, a utility that encapsulates the pasteboard manipulation and event simulation required for reliable auto-paste functionality.

Inserting Text and Preserving State

The insertText(_:) method orchestrates the entire operation by first capturing the existing clipboard state before inserting new content:

static func insertText(_ text: String) {
    let pasteboard = NSPasteboard.general
    let saved = saveCurrentPasteboardContents(from: pasteboard)    // 1️⃣ Save old data
    pasteboard.declareTypes([.string], owner: nil)
    pasteboard.setString(text, forType: .string)                   // 2️⃣ Put new text
    let changeCount = pasteboard.changeCount
    simulatePaste()                                                // 3️⃣ Cmd+V
    // 4️⃣ Restore after a short delay, only if the pasteboard still holds our text
    if let saved = saved {
        DispatchQueue.main.asyncAfter(deadline: .now() + clipboardRestoreDelay) {
            restoreIfUnchanged(saved,
                               expectedChangeCount: changeCount,
                               pasteboard: pasteboard)
        }
    }
}

The method records the changeCount before simulating the paste operation, which serves as a revision token to detect external clipboard modifications during the restoration window.

Layout-Aware Keystroke Simulation

The simulatePaste() function delegates to sendCmdV(), which creates a hardware-independent keystroke event that respects the user’s current keyboard layout. This is critical because the physical key producing the letter "V" varies across QWERTY, AZERTY, and other layouts.

private static func sendCmdV() {
    let qwertyKeyCodeV: CGKeyCode = 9
    let keyCodeV: CGKeyCode = isQwertyCommandLayout()
        ? qwertyKeyCodeV
        : (findKeycodeForCharacter("v") ?? qwertyKeyCodeV)

    guard let src = CGEventSource(stateID: .combinedSessionState),
          let down = CGEvent(keyboardEventSource: src, virtualKey: keyCodeV, keyDown: true),
          let up   = CGEvent(keyboardEventSource: src, virtualKey: keyCodeV, keyDown: false)
    else { return }

    down.flags = .maskCommand
    up.flags   = .maskCommand
    down.post(tap: .cghidEventTap)
    up.post(tap: .cghidEventTap)
}

The isQwertyCommandLayout() and findKeycodeForCharacter(_:) helper functions query the active keyboard layout to determine the correct virtual key code, ensuring that the synthesized Cmd+V works correctly on non-QWERTY keyboards.

Safe Clipboard Restoration

After the clipboardRestoreDelay (set to 1.5 seconds), the restoreIfUnchanged(_:expectedChangeCount:pasteboard:) method verifies that the pasteboard's changeCount matches the expected value before restoring the saved contents. This prevents the utility from overwriting text that the user may have copied immediately after the auto-paste occurred.

User Control via Settings

The auto-paste behavior is controlled by a toggle in OpenSuperWhisper/Settings.swift labeled "Auto-paste Transcription". When enabled, the transcription completion handler invokes ClipboardUtil.insertText(transcribedText); when disabled, it calls ClipboardUtil.copyToClipboard(transcribedText) instead, leaving the manual paste action to the user.

The transcription engine or ContentView.swift implements this conditional logic:

// Called when a transcription finishes and auto-paste is enabled
if settings.autoPasteEnabled {
    // This copies the transcription, sends Cmd+V, and restores the old clipboard
    ClipboardUtil.insertText(transcribedText)
} else {
    // Only copies the text; the user must paste manually
    ClipboardUtil.copyToClipboard(transcribedText)
}

Summary

• OpenSuperWhisper implements auto-paste into the focused application using ClipboardUtil.swift, which coordinates clipboard management and keystroke simulation.
• The four-step workflow saves existing clipboard data, writes transcription text, synthesizes a Cmd+V event using CGEvent, and restores the original clipboard after 1.5 seconds.
• Keyboard layout awareness ensures the simulated paste works across QWERTY, AZERTY, and other layouts by resolving the correct virtual key code for the "V" character.
• Safety mechanisms including changeCount validation prevent the utility from overwriting user-initiated clipboard changes during the restoration window.
• User control is exposed through Settings.swift, allowing toggling between automatic insertion and manual clipboard copying.

Frequently Asked Questions

How does OpenSuperWhisper ensure the paste command works on non-QWERTY keyboards?

The app queries the active keyboard layout using isQwertyCommandLayout() and findKeycodeForCharacter(_:) to determine the correct virtual key code for the "V" character. If the user is on a QWERTY layout, it uses the hardcoded key code 9; otherwise, it looks up the dynamic key code based on the current input source, ensuring the synthesized Cmd+V event triggers the paste command regardless of physical keyboard layout.

What prevents OpenSuperWhisper from overwriting important clipboard data?

Before inserting text, the utility saves the existing pasteboard contents. After a 1.5-second delay, restoreIfUnchanged(_:expectedChangeCount:pasteboard:) checks whether the pasteboard's changeCount has been modified by external applications. If the count matches the expected value captured before the paste operation, the original clipboard is restored; if the user has copied new content in the interim, the restoration is skipped to prevent data loss.

Which source files control the auto-paste functionality in OpenSuperWhisper?

The primary implementation lives in OpenSuperWhisper/Utils/ClipboardUtil.swift, which contains the insertText(_:), sendCmdV(), and restoration logic. The feature toggle is defined in OpenSuperWhisper/Settings.swift, while the transcription completion logic that invokes these utilities is typically found in OpenSuperWhisper/ContentView.swift or the main transcription engine file.

Can users disable auto-paste and manually paste transcriptions instead?

Yes. Users can disable the "Auto-paste Transcription" toggle in the settings. When disabled, the transcription pipeline calls ClipboardUtil.copyToClipboard(_:) instead of insertText(_:), which places the text on the system clipboard without synthesizing a keystroke, allowing the user to manually paste the transcription using Cmd+V or their preferred method.

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