Keyboard Shortcuts in ShortcutManager.swift: OpenSuperWhisper Recording Controls

OpenSuperWhisper defines two primary global shortcuts in ShortcutManager.swift: toggleRecord (Option + back‑tick) to start or stop transcription and escape (Esc) to cancel an active session, alongside configurable modifier‑only and mouse‑button triggers.

The ShortcutManager.swift file serves as the central input hub for the OpenSuperWhisper macOS app, mapping physical keystrokes to voice‑recording actions using the KeyboardShortcuts library. Located at OpenSuperWhisper/ShortcutManager.swift, this manager registers hotkey observers during app launch and dynamically switches between standard shortcuts and alternative trigger modes based on user preferences. Understanding these shortcuts allows users to dictate efficiently without leaving their current application context.

Default Keyboard Shortcuts Defined in ShortcutManager.swift

The manager declares two named shortcuts inside a KeyboardShortcuts.Name extension block. These constants act as identifiers for the global hotkey system.

Toggle Recording (Option + `)

The toggleRecord shortcut defaults to Option + ` (back‑tick). When activated, it either initiates a new recording session near the current cursor position or terminates an ongoing recording. The handler distinguishes between tap‑to‑toggle and hold‑to‑record modes based on AppPreferences.shared.holdToRecord.

Cancel Recording (Escape)

The escape shortcut binds to the Esc key. Although KeyboardShortcuts.disable(.escape) hides it from the UI preferences to avoid conflicts with system text editing, the onKeyUp handler remains available for programmatic use. Invoking it forces an immediate cancellation of the active recording and hides the indicator window.

Shortcut Handlers and Recording Logic

Inside OpenSuperWhisper/ShortcutManager.swift, the setupKeyboardShortcuts() method wires onKeyDown and onKeyUp observers to the toggleRecord name, while onKeyUp handles the escape event. These callbacks manipulate the shared IndicatorWindowManager instance to control the on‑screen recording interface.

The key‑down handler for toggleRecord implements the core state machine:

private func handleKeyDown() {
    holdWorkItem?.cancel()
    holdMode = false

    // Show indicator and start recording if none is active
    if self.activeVm == nil {
        let cursor = FocusUtils.getCurrentCursorPosition()
        let vm = IndicatorWindowManager.shared.show(nearPoint: cursor)
        vm.startRecording()
        self.activeVm = vm
    } else if !self.holdMode {
        // Stop the ongoing recording
        IndicatorWindowManager.shared.stopRecording()
        self.activeVm = nil
    }

    // Optional “hold‑to‑record” logic
    if AppPreferences.shared.holdToRecord {
        let workItem = DispatchWorkItem { self.holdMode = true }
        holdWorkItem = workItem
        DispatchQueue.main.asyncAfter(deadline: .now() + holdThreshold, execute: workItem)
    }
}

The escape handler provides an emergency stop mechanism:

KeyboardShortcuts.onKeyUp(for: .escape) { [weak self] in
    Task { @MainActor in
        if self?.activeVm != nil {
            IndicatorWindowManager.shared.stopForce()
            self?.activeVm = nil
        }
    }
}
KeyboardShortcuts.disable(.escape)   // UI‑wise the shortcut is hidden

Alternative Trigger Modes in ShortcutManager.swift

Beyond traditional keystrokes, ShortcutManager.swift supports modifier‑only and mouse‑button hotkeys configured via AppPreferences.swift. When either alternative is enabled, the manager disables the standard toggleRecord shortcut to prevent conflicting triggers.

Modifier‑Only Hotkeys

Users can configure the app to record while holding a single modifier key (Command, Option, Control, or Shift). When AppPreferences.shared.modifierOnlyHotkey is non‑zero, the manager disables the default shortcut and activates ModifierKeyMonitor.swift:

let modifierKey = ModifierKey(rawValue: AppPreferences.shared.modifierOnlyHotkey) ?? .none
if modifierKey != .none {
    KeyboardShortcuts.disable(.toggleRecord)
    ModifierKeyMonitor.shared.onKeyDown = { self.handleKeyDown() }
    ModifierKeyMonitor.shared.onKeyUp   = { self.handleKeyUp() }
    ModifierKeyMonitor.shared.start(modifierKey: modifierKey)
}

Mouse‑Button Triggers

Similarly, mouse‑button hotkeys route through MouseButtonMonitor.swift. The setupRecordingTrigger() method checks AppPreferences.shared.mouseButtonHotkey and, if set, disables keyboard shortcuts in favor of the mouse monitor. This design ensures only one trigger mode remains active at any time, preventing accidental double‑registration.

Key Files in the Shortcut System

File	Role
OpenSuperWhisper/ShortcutManager.swift	Central hub for defining and handling the app’s shortcuts.
OpenSuperWhisper/Utils/AppPreferences.swift	Stores user‑selected hotkey settings (modifier‑only & mouse‑button).
OpenSuperWhisper/ModifierKeyMonitor.swift	Monitors modifier‑only hotkeys when enabled.
OpenSuperWhisper/MouseButtonMonitor.swift	Monitors mouse‑button hotkeys when enabled.
OpenSuperWhisper/Indicator/IndicatorWindowManager.swift	Shows the on‑screen indicator and controls the recording lifecycle.

Summary

• toggleRecord (Option + `) is the default global shortcut to start or stop a recording session.
• escape (Esc) cancels an active recording programmatically, though it is hidden from the UI preferences.
• Alternative triggers include modifier‑only keys and mouse buttons, managed by ModifierKeyMonitor.swift and MouseButtonMonitor.swift.
• Mutual exclusivity is enforced: enabling modifier‑only or mouse‑button modes automatically disables the standard toggleRecord shortcut.
• State management occurs in handleKeyDown(), which interacts with IndicatorWindowManager to show, start, or stop the recording interface.

Frequently Asked Questions

What is the default hotkey to start recording in OpenSuperWhisper?

The default hotkey is Option + ` (back‑tick), defined as the toggleRecord shortcut in ShortcutManager.swift. Pressing this combination when no recording is active opens the indicator window and begins transcription; pressing it again stops the recording.

How do I cancel an active recording using the keyboard?

Press the Esc key. Although the escape shortcut is disabled in the KeyboardShortcuts preferences UI to avoid conflicts, the handler remains active in code. It immediately calls IndicatorWindowManager.shared.stopForce() to abort the session and hide the indicator.

Can I use modifier keys alone (like just Command) to trigger recording?

Yes. In the app preferences, enable a modifier‑only hotkey. When active, ShortcutManager.swift disables the standard toggleRecord shortcut and routes input through ModifierKeyMonitor.swift, allowing you to hold Command, Option, Control, or Shift to record.

Where does OpenSuperWhisper store my custom hotkey preferences?

User preferences are persisted in OpenSuperWhisper/Utils/AppPreferences.swift. This file tracks settings for modifierOnlyHotkey, mouseButtonHotkey, and holdToRecord, which ShortcutManager.swift reads during initialization to determine which trigger mode to activate.

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