# Keyboard Shortcuts in ShortcutManager.swift: OpenSuperWhisper Recording Controls

> Discover keyboard shortcuts in OpenSuperWhisper's ShortcutManager.swift. Learn to toggle recording with Option+backtick and cancel with Esc for efficient transcription control.

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

---

**OpenSuperWhisper defines two primary global shortcuts in [`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

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

```swift
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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift) supports **modifier‑only** and **mouse‑button** hotkeys configured via [`AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ModifierKeyMonitor.swift):

```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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ShortcutManager.swift)** | Central hub for defining and handling the app’s shortcuts. |
| **[`OpenSuperWhisper/Utils/AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/AppPreferences.swift)** | Stores user‑selected hotkey settings (modifier‑only & mouse‑button). |
| **[`OpenSuperWhisper/ModifierKeyMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ModifierKeyMonitor.swift)** | Monitors modifier‑only hotkeys when enabled. |
| **[`OpenSuperWhisper/MouseButtonMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/MouseButtonMonitor.swift)** | Monitors mouse‑button hotkeys when enabled. |
| **[`OpenSuperWhisper/Indicator/IndicatorWindowManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ModifierKeyMonitor.swift) and [`MouseButtonMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift) disables the standard `toggleRecord` shortcut and routes input through [`ModifierKeyMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/AppPreferences.swift)**. This file tracks settings for `modifierOnlyHotkey`, `mouseButtonHotkey`, and `holdToRecord`, which [`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift) reads during initialization to determine which trigger mode to activate.