# How OpenSuperWhisper Implements Auto-Paste into the Focused Application

> Discover how OpenSuperWhisper seamlessly implements auto-paste into your focused application. Learn about its efficient system pasteboard and CGEvent API usage.

- Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

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

```swift
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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ContentView.swift) implements this conditional logic:

```swift
// 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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/ClipboardUtil.swift), which contains the `insertText(_:)`, `sendCmdV()`, and restoration logic. The feature toggle is defined in [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift), while the transcription completion logic that invokes these utilities is typically found in [`OpenSuperWhisper/ContentView.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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.