Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more
import AppKit
import Foundation
nonisolated enum HotkeyHoldModeType: Hashable {
case transcription
case promptMode
case commandMode
case rewriteMode
case promptAssignment
}
private nonisolated enum ActivePrimaryShortcutPress: Equatable {
case keyboard(HotkeyShortcut)
case mouse(HotkeyShortcut)
var shortcut: HotkeyShortcut {
switch self {
case let .keyboard(shortcut), let .mouse(shortcut): return shortcut
}
}
var keyboardKeyCode: UInt16? {
guard case let .keyboard(shortcut) = self else { return nil }
return shortcut.keyCode
}
var mouseButton: Int? {
guard case let .mouse(shortcut) = self else { return nil }
return shortcut.mouseButton
}
}
/// Input timing only: never changes shortcut routing or retains a keyboard event.
struct HotkeyInputTiming {
let receivedAt: TimeInterval
let eventTimestamp: UInt64
let eventType: UInt32
let receivedTimestamp: UInt64
/// Quartz event timestamps and DispatchTime uptime are nanoseconds since boot.
/// Keep this clock separate from the ProcessInfo timestamp used by the pipeline.
var deliveryAgeMs: Double? {
guard self.eventTimestamp > 0, self.receivedTimestamp >= self.eventTimestamp else { return nil }
return Double(self.receivedTimestamp - self.eventTimestamp) / 1_000_000
}
}
/// Snapshot of the modifier-only tracking state fed into `ModifierOnlyShortcutFlagsDecision`.
struct ModifierOnlyShortcutTrackingState: Equatable {
/// Currently-pressed modifier key codes (output of `synchronizedPressedModifierKeyCodes`).
let pressedModifierKeyCodes: Set<UInt16>
/// The currently-active modifier-only mode, if any.
let activeModifierOnlyType: HotkeyHoldModeType?
/// The exact shortcut that owns the active modifier-only press.
let activeModifierOnlyShortcut: HotkeyShortcut?
/// Whether a non-configured key was pressed during the active modifier-only press.
let otherKeyPressedDuringModifier: Bool
/// Snapshot of the behavior's mode-key-pressed flag.
let isModeKeyPressed: Bool
}
/// Pure, side-effect-free decision describing how a modifier-only shortcut responds to a single
/// `flagsChanged` event. Extracted from `GlobalHotkeyManager.handleModifierOnlyShortcutFlagsChanged`
/// so the modifier-only start/finish state machine is unit-testable without the global event tap.
struct ModifierOnlyShortcutFlagsDecision: Equatable {
enum Outcome: Equatable {
/// The event neither starts nor finishes the press.
case ignore
/// The configured modifier was pressed: arm the modifier-only press.
case start
/// The configured modifier was released: finish the press; a clean tap only when
/// `wasCleanPress` is true.
case finish(wasCleanPress: Bool)
}
let outcome: Outcome
/// True when an extra modifier was pressed during an active press this event; the caller logs
/// and marks the press interrupted.
let markInterrupted: Bool
/// Value `activeModifierOnlyType` should hold after this event.
let activeModifierOnlyType: HotkeyHoldModeType?
/// Shortcut that should own the active modifier-only press after this event.
let activeModifierOnlyShortcut: HotkeyShortcut?
/// Value `otherKeyPressedDuringModifier` should hold after this event.
let otherKeyPressedDuringModifier: Bool
/// Mirrors the decision logic of `handleModifierOnlyShortcutFlagsChanged`. Branch 1 handles
/// shortcuts that carry explicit modifier key codes (e.g. a captured Left Option); branch 2
/// handles the flag-only form.
static func evaluate(
shortcut: HotkeyShortcut,
holdModeType: HotkeyHoldModeType,
isEnabled: Bool,
keyCode: UInt16,
modifiers: NSEvent.ModifierFlags,
state: ModifierOnlyShortcutTrackingState
) -> ModifierOnlyShortcutFlagsDecision {
let pressedModifierKeyCodes = state.pressedModifierKeyCodes
let activeModifierOnlyType = state.activeModifierOnlyType
let activeModifierOnlyShortcut = state.activeModifierOnlyShortcut
let otherKeyPressedDuringModifier = state.otherKeyPressedDuringModifier
let isModeKeyPressed = state.isModeKeyPressed
guard isEnabled, shortcut.isModifierOnlyShortcut else {
return .init(
outcome: .ignore,
markInterrupted: false,
activeModifierOnlyType: activeModifierOnlyType,
activeModifierOnlyShortcut: activeModifierOnlyShortcut,
otherKeyPressedDuringModifier: otherKeyPressedDuringModifier
)
}
let relevantModifiers = modifiers.intersection(HotkeyShortcut.relevantModifierMask)
let expectedModifierKeyCodes = shortcut.normalizedModifierKeyCodes
if !expectedModifierKeyCodes.isEmpty {
let pressedKeyCodes = HotkeyShortcut.normalizedModifierKeyCodes(from: Array(pressedModifierKeyCodes))
// Only arm on the FIRST press of the configured modifier itself. The `activeModifierOnlyType == nil`
// precondition prevents a mid-press re-arm: without it, releasing an unrelated modifier (e.g. Shift)
// or pressing a sibling modifier while the configured modifier is held can shrink `pressedModifierKeyCodes`
// back to the expected set and re-enter this block, erasing `otherKeyPressedDuringModifier` so the
// subsequent release reads as a clean tap and falsely starts recording (#688).
if activeModifierOnlyType == nil,
pressedKeyCodes == expectedModifierKeyCodes,
relevantModifiers == shortcut.expectedModifierFlags,
expectedModifierKeyCodes.contains(keyCode)
{
return .init(
outcome: .start,
markInterrupted: false,
activeModifierOnlyType: holdModeType,
activeModifierOnlyShortcut: shortcut,
otherKeyPressedDuringModifier: false
)
}
let isActiveModifierOnlyPress = activeModifierOnlyType == holdModeType && activeModifierOnlyShortcut == shortcut
let isLegacyModePress = activeModifierOnlyShortcut == nil && isModeKeyPressed
var markInterrupted = false
if isActiveModifierOnlyPress || isLegacyModePress {
let extraModifierKeyCodes = pressedKeyCodes.filter { !expectedModifierKeyCodes.contains($0) }
markInterrupted = !extraModifierKeyCodes.isEmpty
}
guard isActiveModifierOnlyPress || isLegacyModePress,
expectedModifierKeyCodes.contains(keyCode),
!pressedKeyCodes.contains(keyCode)
else {
return .init(
outcome: .ignore,
markInterrupted: markInterrupted,
activeModifierOnlyType: activeModifierOnlyType,
activeModifierOnlyShortcut: activeModifierOnlyShortcut,
otherKeyPressedDuringModifier: markInterrupted ? true : otherKeyPressedDuringModifier
)
}
let wasCleanPress = !(markInterrupted || otherKeyPressedDuringModifier)
return .init(
outcome: .finish(wasCleanPress: wasCleanPress),
markInterrupted: markInterrupted,
activeModifierOnlyType: nil,
activeModifierOnlyShortcut: nil,
otherKeyPressedDuringModifier: false
)
}
guard let expectedPressedModifiers = shortcut.expectedModifierFlags,
let triggerFlag = shortcut.modifierTriggerFlag
else {
return .init(
outcome: .ignore,
markInterrupted: false,
activeModifierOnlyType: activeModifierOnlyType,
activeModifierOnlyShortcut: activeModifierOnlyShortcut,
otherKeyPressedDuringModifier: otherKeyPressedDuringModifier
)
}
// Only arm on the FIRST press of a modifier that belongs to the shortcut. The
// `activeModifierOnlyType == nil` precondition prevents a mid-press re-arm (same #688 class
// as branch 1): a sibling-side modifier whose flag is in `expectedPressedModifiers` would
// otherwise re-enter `.start` and erase `otherKeyPressedDuringModifier`. Matching the
// modifier flag (not the literal key code) preserves the original side-agnostic start, so a
// Left-Option-stored shortcut still arms on Right Option.
if activeModifierOnlyType == nil,
relevantModifiers == expectedPressedModifiers,
let changedModifierFlag = HotkeyShortcut.modifierFlag(forKeyCode: keyCode),
expectedPressedModifiers.contains(changedModifierFlag)
{
return .init(
outcome: .start,
markInterrupted: false,
activeModifierOnlyType: holdModeType,
activeModifierOnlyShortcut: shortcut,
otherKeyPressedDuringModifier: false
)
}
let isActiveModifierOnlyPress = activeModifierOnlyType == holdModeType && activeModifierOnlyShortcut == shortcut
let isLegacyModePress = activeModifierOnlyShortcut == nil && isModeKeyPressed
var markInterrupted = false
if isActiveModifierOnlyPress || isLegacyModePress {
let unexpectedModifiers = relevantModifiers.subtracting(expectedPressedModifiers)
markInterrupted = !unexpectedModifiers.isEmpty
}
guard isActiveModifierOnlyPress || isLegacyModePress,
HotkeyShortcut.modifierFlag(forKeyCode: keyCode) == triggerFlag,
!relevantModifiers.contains(triggerFlag)
else {
return .init(
outcome: .ignore,
markInterrupted: markInterrupted,
activeModifierOnlyType: activeModifierOnlyType,
activeModifierOnlyShortcut: activeModifierOnlyShortcut,
otherKeyPressedDuringModifier: markInterrupted ? true : otherKeyPressedDuringModifier
)
}
let wasCleanPress = !(markInterrupted || otherKeyPressedDuringModifier)
return .init(
outcome: .finish(wasCleanPress: wasCleanPress),
markInterrupted: markInterrupted,
activeModifierOnlyType: nil,
activeModifierOnlyShortcut: nil,
otherKeyPressedDuringModifier: false
)
}
}
private final nonisolated class HotkeyState: @unchecked Sendable {
private let lock = NSLock()
var isKeyPressed = false
var isPromptModeKeyPressed = false
var isCommandModeKeyPressed = false
var isRewriteKeyPressed = false
var isPromptAssignmentKeyPressed = false
var pressedModifierKeyCodes: Set<UInt16> = []
var modifierOnlyKeyDown = false
var activeModifierOnlyType: HotkeyHoldModeType?
var activeModifierOnlyShortcut: HotkeyShortcut?
var otherKeyPressedDuringModifier = false
var modifierPressStartTime: Date?
var holdModeStartTriggeredTypes: Set<HotkeyHoldModeType> = []
var pendingReleaseStopTasks: [HotkeyHoldModeType: Task<Void, Never>] = [:]
var pendingReleaseStopTokens: [HotkeyHoldModeType: UUID] = [:]
var automaticPressStartTimes: [HotkeyHoldModeType: Date] = [:]
var automaticPressWasTargetActive: [HotkeyHoldModeType: Bool] = [:]
var automaticPressStartedTypes: Set<HotkeyHoldModeType> = []
var activePrimaryShortcutPress: ActivePrimaryShortcutPress?
var consumedPasteMouseButton: Int?
func withLock<T>(_ block: () -> T) -> T {
self.lock.lock()
defer { self.lock.unlock() }
return block()
}
}
@MainActor
final class GlobalHotkeyManager: NSObject {
enum CancelHandlingResult {
case unhandled
case dismissedOverlay
case cancelled
}
private nonisolated(unsafe) var state = HotkeyState()
private nonisolated(unsafe) var eventTap: CFMachPort?
private nonisolated(unsafe) var runLoopSource: CFRunLoopSource?
/// Keyboard tap events are serviced here, not on the main run loop, so main-thread
/// work after a paste never holds the synthetic Cmd+V (or any keystroke) in our tap.
private nonisolated(unsafe) var keyboardTapRunLoop: CFRunLoop?
private nonisolated(unsafe) var keyboardTapThread: Thread?
private nonisolated(unsafe) var mouseObserverTap: CFMachPort?
private nonisolated(unsafe) var mouseObserverSource: CFRunLoopSource?
private nonisolated(unsafe) var mouseShortcutTap: CFMachPort?
private nonisolated(unsafe) var mouseShortcutSource: CFRunLoopSource?
private nonisolated(unsafe) var monitoredMouseButtons: Set<Int> = []
private let asrService: ASRService
private var recordingActionRevisions: [HotkeyHoldModeType: UInt64] = [:]
private var pendingRecordingActionCounts: [HotkeyHoldModeType: Int] = [:]
private var activeRecordingActionShortcuts: [HotkeyHoldModeType: HotkeyShortcut] = [:]
private var pendingRecordingActions: [HotkeyHoldModeType: Task<Void, Never>] = [:]
private var primaryShortcuts: [HotkeyShortcut]
private var promptModeShortcut: HotkeyShortcut
private var commandModeShortcut: HotkeyShortcut?
private var rewriteModeShortcut: HotkeyShortcut
private var promptShortcutAssignments: [(selection: SettingsStore.DictationPromptSelection, shortcut: HotkeyShortcut)]
private var promptModeShortcutEnabled: Bool
private var commandModeShortcutEnabled: Bool
private var rewriteModeShortcutEnabled: Bool
private var startRecordingCallback: (() async -> Void)?
private var dictationModeCallback: (() async -> Void)?
private var stopAndProcessCallback: ((TimeInterval?) async -> Void)?
private var promptModeCallback: (() async -> Void)?
private var promptSelectionCallback: ((SettingsStore.DictationPromptSelection) async -> Void)?
private var commandModeCallback: (() async -> Void)?
private var rewriteModeCallback: (() async -> Void)?
private var isDictateRecordingProvider: (() -> Bool)?
private var isPromptModeRecordingProvider: (() -> Bool)?
private var isCommandRecordingProvider: (() -> Bool)?
private var isRewriteRecordingProvider: (() -> Bool)?
private var isShortcutCaptureActiveProvider: (() -> Bool)?
private var shortcutCaptureHandler: ((NSEvent) -> NSEvent?)?
private let isSessionLockedProvider: () -> Bool
private var cancelCallback: (() -> CancelHandlingResult)?
private var meetingRecordingCallback: (() -> Void)?
private var meetingShortcutPressedKey: UInt16?
private var pasteLastTranscriptionCallback: (() -> Void)?
private var hotkeyMode: HotkeyActivationMode = SettingsStore.shared.hotkeyMode
private let automaticTapThresholdSeconds: TimeInterval = 0.4
private var holdToMuteKeyState = HoldToMuteKeyState()
let holdToMuteSpaceTap = HoldToMuteSpaceTap()
private var muteRecordingGeneration: UInt64?
private var muteReleaseRecoveryTask: Task<Void, Never>?
// Event-replay tests opt out of consulting the real keyboard.
var holdToMuteChecksPhysicalKeyState = true
private var currentInputTiming: HotkeyInputTiming?
private var modifierPressReceivedAt: TimeInterval?
private var currentStopPressReceivedAt: TimeInterval?
private var activePromptAssignmentPress: (selection: SettingsStore.DictationPromptSelection, shortcut: HotkeyShortcut)?
private struct ModifierOnlyShortcutBehavior {
let shortcut: HotkeyShortcut
let isEnabled: Bool
let holdModeType: HotkeyHoldModeType
let holdStartMessage: String
let holdReleaseMessage: String
let toggleIgnoredMessage: String
let isModeKeyPressed: () -> Bool
let setModeKeyPressed: (Bool) -> Void
let onHoldStart: () -> Void
let onToggleRelease: () -> Void
let isTargetModeActive: () -> Bool
}
enum ModifierTrackingResetReason {
case shortcutCapture
case tapDisabled
case reinitialize
case cancel
}
private nonisolated var isKeyPressed: Bool {
get { self.state.withLock { self.state.isKeyPressed } }
set { self.state.withLock { self.state.isKeyPressed = newValue } }
}
private nonisolated var isPromptModeKeyPressed: Bool {
get { self.state.withLock { self.state.isPromptModeKeyPressed } }
set { self.state.withLock { self.state.isPromptModeKeyPressed = newValue } }
}
private nonisolated var isCommandModeKeyPressed: Bool {
get { self.state.withLock { self.state.isCommandModeKeyPressed } }
set { self.state.withLock { self.state.isCommandModeKeyPressed = newValue } }
}
private nonisolated var isRewriteKeyPressed: Bool {
get { self.state.withLock { self.state.isRewriteKeyPressed } }
set { self.state.withLock { self.state.isRewriteKeyPressed = newValue } }
}
private nonisolated var isPromptAssignmentKeyPressed: Bool {
get { self.state.withLock { self.state.isPromptAssignmentKeyPressed } }
set { self.state.withLock { self.state.isPromptAssignmentKeyPressed = newValue } }
}
private nonisolated var activePrimaryShortcutPress: ActivePrimaryShortcutPress? {
get { self.state.withLock { self.state.activePrimaryShortcutPress } }
set { self.state.withLock { self.state.activePrimaryShortcutPress = newValue } }
}
private nonisolated var pressedModifierKeyCodes: Set<UInt16> {
get { self.state.withLock { self.state.pressedModifierKeyCodes } }
set { self.state.withLock { self.state.pressedModifierKeyCodes = newValue } }
}
/// Modifier-only shortcut tracking: detect if another key was pressed during modifier hold
private nonisolated var modifierOnlyKeyDown: Bool {
get { self.state.withLock { self.state.modifierOnlyKeyDown } }
set { self.state.withLock { self.state.modifierOnlyKeyDown = newValue } }
}
private nonisolated var activeModifierOnlyType: HotkeyHoldModeType? {
get { self.state.withLock { self.state.activeModifierOnlyType } }
set { self.state.withLock { self.state.activeModifierOnlyType = newValue } }
}
private nonisolated var activeModifierOnlyShortcut: HotkeyShortcut? {
get { self.state.withLock { self.state.activeModifierOnlyShortcut } }
set { self.state.withLock { self.state.activeModifierOnlyShortcut = newValue } }
}
private nonisolated var otherKeyPressedDuringModifier: Bool {
get { self.state.withLock { self.state.otherKeyPressedDuringModifier } }
set { self.state.withLock { self.state.otherKeyPressedDuringModifier = newValue } }
}
/// Reserved for future tap-vs-hold timing detection (e.g., quick tap to toggle vs long hold)
private nonisolated var modifierPressStartTime: Date? {
get { self.state.withLock { self.state.modifierPressStartTime } }
set { self.state.withLock { self.state.modifierPressStartTime = newValue } }
}
private func cancelPendingReleaseStop(for type: HotkeyHoldModeType) {
let task = self.state.withLock { () -> Task<Void, Never>? in
_ = self.state.pendingReleaseStopTokens.removeValue(forKey: type)
return self.state.pendingReleaseStopTasks.removeValue(forKey: type)
}
task?.cancel()
}
private func cancelPendingReleaseStops() {
let tasks = self.state.withLock { () -> [Task<Void, Never>] in
let tasks = Array(self.state.pendingReleaseStopTasks.values)
self.state.pendingReleaseStopTasks.removeAll()
self.state.pendingReleaseStopTokens.removeAll()
return tasks
}
for task in tasks {
task.cancel()
}
}
private func beginPendingReleaseStop(for type: HotkeyHoldModeType) -> UUID {
let token = UUID()
let task = self.state.withLock { () -> Task<Void, Never>? in
self.state.pendingReleaseStopTokens[type] = token
return self.state.pendingReleaseStopTasks.removeValue(forKey: type)
}
task?.cancel()
return token
}
private func storePendingReleaseStopTask(_ task: Task<Void, Never>, for type: HotkeyHoldModeType, token: UUID) {
let taskToCancel = self.state.withLock { () -> Task<Void, Never>? in
guard self.state.pendingReleaseStopTokens[type] == token else { return task }
let previousTask = self.state.pendingReleaseStopTasks[type]
self.state.pendingReleaseStopTasks[type] = task
return previousTask
}
taskToCancel?.cancel()
}
private func isPendingReleaseStopCurrent(for type: HotkeyHoldModeType, token: UUID) -> Bool {
self.state.withLock {
self.state.pendingReleaseStopTokens[type] == token
}
}
private func clearPendingReleaseStop(for type: HotkeyHoldModeType, token: UUID) {
self.state.withLock {
guard self.state.pendingReleaseStopTokens[type] == token else { return }
_ = self.state.pendingReleaseStopTokens.removeValue(forKey: type)
_ = self.state.pendingReleaseStopTasks.removeValue(forKey: type)
}
}
private func beginAutomaticPress(for type: HotkeyHoldModeType, wasTargetActive: Bool) {
self.cancelPendingReleaseStop(for: type)
self.state.withLock {
self.state.automaticPressStartTimes[type] = Date()
self.state.automaticPressWasTargetActive[type] = wasTargetActive
_ = self.state.automaticPressStartedTypes.remove(type)
}
}
private func markAutomaticPressStarted(for type: HotkeyHoldModeType) {
self.state.withLock {
_ = self.state.automaticPressStartedTypes.insert(type)
}
}
private func clearHoldModeStartTriggered(for type: HotkeyHoldModeType) {
self.state.withLock {
_ = self.state.holdModeStartTriggeredTypes.remove(type)
}
}
private func markHoldModeStartTriggered(for type: HotkeyHoldModeType) {
self.state.withLock {
_ = self.state.holdModeStartTriggeredTypes.insert(type)
}
}
private func finishHoldModeStartTriggered(for type: HotkeyHoldModeType) -> Bool {
self.state.withLock {
self.state.holdModeStartTriggeredTypes.remove(type) != nil
}
}
private func finishAutomaticPress(
for type: HotkeyHoldModeType
) -> (duration: TimeInterval, wasTargetActive: Bool, started: Bool) {
let now = Date()
return self.state.withLock {
let startTime = self.state.automaticPressStartTimes.removeValue(forKey: type) ?? now
let wasTargetActive = self.state.automaticPressWasTargetActive.removeValue(forKey: type) ?? false
let started = self.state.automaticPressStartedTypes.remove(type) != nil
return (now.timeIntervalSince(startTime), wasTargetActive, started)
}
}
private func clearAutomaticPressTracking() {
self.cancelPendingReleaseStops()
self.state.withLock {
self.state.holdModeStartTriggeredTypes.removeAll()
self.state.automaticPressStartTimes.removeAll()
self.state.automaticPressWasTargetActive.removeAll()
self.state.automaticPressStartedTypes.removeAll()
}
}
/// Busy flag to prevent race conditions during stop processing
private var isProcessingStop = false
private var isInitialized = false
private var initializationTask: Task<Void, Never>?
private var healthCheckTask: Task<Void, Never>?
private var maxRetryAttempts = 5
private var retryDelay: TimeInterval = 0.5
private var healthCheckInterval: TimeInterval = 30.0
private var activeShortcutLogScheduled = false
init(
asrService: ASRService,
primaryShortcuts: [HotkeyShortcut],
promptModeShortcut: HotkeyShortcut,
commandModeShortcut: HotkeyShortcut?,
rewriteModeShortcut: HotkeyShortcut,
promptShortcutAssignments: [(selection: SettingsStore.DictationPromptSelection, shortcut: HotkeyShortcut)] = [],
promptModeShortcutEnabled: Bool,
commandModeShortcutEnabled: Bool,
rewriteModeShortcutEnabled: Bool,
startRecordingCallback: (() async -> Void)? = nil,
dictationModeCallback: (() async -> Void)? = nil,
stopAndProcessCallback: ((TimeInterval?) async -> Void)? = nil,
promptModeCallback: (() async -> Void)? = nil,
promptSelectionCallback: ((SettingsStore.DictationPromptSelection) async -> Void)? = nil,
commandModeCallback: (() async -> Void)? = nil,
rewriteModeCallback: (() async -> Void)? = nil,
isDictateRecordingProvider: (() -> Bool)? = nil,
isPromptModeRecordingProvider: (() -> Bool)? = nil,
isCommandRecordingProvider: (() -> Bool)? = nil,
isRewriteRecordingProvider: (() -> Bool)? = nil,
isShortcutCaptureActiveProvider: (() -> Bool)? = nil,
shortcutCaptureHandler: ((NSEvent) -> NSEvent?)? = nil,
isSessionLockedProvider: @escaping () -> Bool = { GlobalHotkeyManager.currentSessionIsLocked() }
) {
self.asrService = asrService
self.primaryShortcuts = primaryShortcuts
self.promptModeShortcut = promptModeShortcut
self.commandModeShortcut = commandModeShortcut
self.rewriteModeShortcut = rewriteModeShortcut
self.promptShortcutAssignments = promptShortcutAssignments
self.promptModeShortcutEnabled = promptModeShortcutEnabled
self.commandModeShortcutEnabled = commandModeShortcutEnabled
self.rewriteModeShortcutEnabled = rewriteModeShortcutEnabled
self.startRecordingCallback = startRecordingCallback
self.dictationModeCallback = dictationModeCallback
self.stopAndProcessCallback = stopAndProcessCallback
self.promptModeCallback = promptModeCallback
self.promptSelectionCallback = promptSelectionCallback
self.commandModeCallback = commandModeCallback
self.rewriteModeCallback = rewriteModeCallback
self.isDictateRecordingProvider = isDictateRecordingProvider
self.isPromptModeRecordingProvider = isPromptModeRecordingProvider
self.isCommandRecordingProvider = isCommandRecordingProvider
self.isRewriteRecordingProvider = isRewriteRecordingProvider
self.isShortcutCaptureActiveProvider = isShortcutCaptureActiveProvider
self.shortcutCaptureHandler = shortcutCaptureHandler
self.isSessionLockedProvider = isSessionLockedProvider
super.init()
NotificationCenter.default.addObserver(
self,
selector: #selector(self.holdSpaceSettingChanged),
name: .init("HoldSpaceToMuteChanged"),
object: nil
)
self.initializeWithDelay()
}
private func initializeWithDelay() {
DebugLogger.shared.debug("Starting delayed initialization...", source: "GlobalHotkeyManager")
self.initializationTask = Task { [weak self] in
do {
try await Task.sleep(nanoseconds: 1_500_000_000) // 1.5 second delay
} catch {
return
}
await MainActor.run { [weak self] in
self?.setupGlobalHotkeyWithRetry()
}
}
}
func setStopAndProcessCallback(_ callback: @escaping (TimeInterval?) async -> Void) {
self.stopAndProcessCallback = callback
}
func setCommandModeCallback(_ callback: @escaping () async -> Void) {
self.commandModeCallback = callback
}
func updatePrimaryShortcuts(_ newShortcuts: [HotkeyShortcut]) {
let ownedShortcut = self.activePrimaryShortcutPress?.shortcut
?? (self.activeModifierOnlyType == .transcription ? self.activeModifierOnlyShortcut : nil)
?? self.activeRecordingActionShortcuts[.transcription]
if newShortcuts != self.primaryShortcuts,
ownedShortcut.map({ !newShortcuts.contains($0) })
?? newShortcuts.isEmpty
{ self.discardShortcutPress(for: .transcription) }
self.primaryShortcuts = newShortcuts
DebugLogger.shared.info("Updated transcription hotkeys", source: "GlobalHotkeyManager")
self.refreshMouseShortcutTapIfNeeded()
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func refreshMouseShortcutTapIfNeeded() {
guard self.eventTap != nil else { return }
let mouseButtons = self.configuredMouseButtons()
guard mouseButtons != self.monitoredMouseButtons else { return }
self.setupMouseShortcutTap(mouseButtons: mouseButtons, preservePrimaryPress: true)
}
func updateCommandModeShortcut(_ newShortcut: HotkeyShortcut?) {
if newShortcut != self.commandModeShortcut { self.discardShortcutPress(for: .commandMode) }
self.commandModeShortcut = newShortcut
DebugLogger.shared.info("Updated command mode hotkey", source: "GlobalHotkeyManager")
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func setRewriteModeCallback(_ callback: @escaping () async -> Void) {
self.rewriteModeCallback = callback
}
func updateRewriteModeShortcut(_ newShortcut: HotkeyShortcut) {
if newShortcut != self.rewriteModeShortcut { self.discardShortcutPress(for: .rewriteMode) }
self.rewriteModeShortcut = newShortcut
DebugLogger.shared.info("Updated rewrite mode hotkey", source: "GlobalHotkeyManager")
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func updateCommandModeShortcutEnabled(_ enabled: Bool) {
self.commandModeShortcutEnabled = enabled
if !enabled { self.discardShortcutPress(for: .commandMode) }
DebugLogger.shared.info(
"Command mode shortcut \(enabled ? "enabled" : "disabled")",
source: "GlobalHotkeyManager"
)
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func updateRewriteModeShortcutEnabled(_ enabled: Bool) {
self.rewriteModeShortcutEnabled = enabled
if !enabled { self.discardShortcutPress(for: .rewriteMode) }
DebugLogger.shared.info(
"Rewrite mode shortcut \(enabled ? "enabled" : "disabled")",
source: "GlobalHotkeyManager"
)
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func setPromptModeCallback(_ callback: @escaping () async -> Void) {
self.promptModeCallback = callback
}
func updatePromptModeShortcut(_ newShortcut: HotkeyShortcut) {
if newShortcut != self.promptModeShortcut { self.discardShortcutPress(for: .promptMode) }
self.promptModeShortcut = newShortcut
DebugLogger.shared.info("Updated prompt mode hotkey", source: "GlobalHotkeyManager")
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func updatePromptModeShortcutEnabled(_ enabled: Bool) {
self.promptModeShortcutEnabled = enabled
if !enabled { self.discardShortcutPress(for: .promptMode) }
DebugLogger.shared.info(
"Prompt mode shortcut \(enabled ? "enabled" : "disabled")",
source: "GlobalHotkeyManager"
)
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func updatePromptShortcutAssignments(_ assignments: [(selection: SettingsStore.DictationPromptSelection, shortcut: HotkeyShortcut)]) {
let previous = self.activePromptAssignmentPress.map { [$0] }
?? self.promptShortcutAssignments.filter { $0.shortcut == self.activeRecordingActionShortcuts[.promptAssignment] }
if !previous.allSatisfy({ old in assignments.contains { $0.selection == old.selection && $0.shortcut == old.shortcut } }) {
self.discardShortcutPress(for: .promptAssignment)
}
self.promptShortcutAssignments = assignments
DebugLogger.shared.info("Updated prompt shortcut assignments", source: "GlobalHotkeyManager")
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
private func setupGlobalHotkeyWithRetry() {
for attempt in 1...self.maxRetryAttempts {
DebugLogger.shared.debug("Setup attempt \(attempt)/\(self.maxRetryAttempts)", source: "GlobalHotkeyManager")
if self.setupGlobalHotkey() {
self.isInitialized = true
DebugLogger.shared.info("Successfully initialized on attempt \(attempt)", source: "GlobalHotkeyManager")
self.startHealthCheckTimer()
return
}
if attempt < self.maxRetryAttempts {
DebugLogger.shared.warning("Attempt \(attempt) failed, retrying in \(self.retryDelay) seconds...", source: "GlobalHotkeyManager")
Task { [weak self] in
try? await Task.sleep(nanoseconds: UInt64((self?.retryDelay ?? 0.5) * 1_000_000_000))
await MainActor.run { [weak self] in
self?.setupGlobalHotkeyWithRetry()
}
}
return
}
}
DebugLogger.shared.error("Failed to initialize after \(self.maxRetryAttempts) attempts", source: "GlobalHotkeyManager")
}
@discardableResult
private func setupGlobalHotkey() -> Bool {
self.finishInterruptedMouseShortcutPress(reason: "hotkey tap reinitialized")
self.cleanupEventTap()
if !AXIsProcessTrusted() {
DebugLogger.shared.debug("Accessibility permissions not granted", source: "GlobalHotkeyManager")
return false
}
self.eventTap = CGEvent.tapCreate(
tap: .cgSessionEventTap,
place: .headInsertEventTap,
options: .defaultTap,
eventsOfInterest: Self.keyboardEventMask(),
callback: { proxy, type, event, refcon -> Unmanaged<CGEvent>? in
guard let refcon = refcon else { return Unmanaged.passUnretained(event) }
ClipboardAudit.recordShortcut(type: type, event: event)
if GlobalHotkeyManager.isSynthesizedTypingEvent(event) {
return Unmanaged.passUnretained(event)
}
let manager = Unmanaged<GlobalHotkeyManager>.fromOpaque(refcon)
.takeUnretainedValue()
if Thread.isMainThread {
return MainActor.assumeIsolated {
manager.handleKeyEvent(type: type, event: event, proxy: proxy)
}
}
return DispatchQueue.main.sync {
MainActor.assumeIsolated {
manager.handleKeyEvent(type: type, event: event, proxy: proxy)
}
}
},
userInfo: Unmanaged.passUnretained(self).toOpaque()
)
guard let tap = eventTap else {
DebugLogger.shared.error("Failed to create CGEvent tap", source: "GlobalHotkeyManager")
return false
}
self.runLoopSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0)
guard let source = runLoopSource else {
DebugLogger.shared.error("Failed to create CFRunLoopSource", source: "GlobalHotkeyManager")
return false
}
CFRunLoopAddSource(self.keyboardTapRunLoopStartingIfNeeded(), source, .commonModes)
CGEvent.tapEnable(tap: tap, enable: true)
if !self.isEventTapEnabled() {
DebugLogger.shared.error("Event tap could not be enabled", source: "GlobalHotkeyManager")
self.cleanupEventTap()
return false
}
DebugLogger.shared.info("Event tap successfully created and enabled", source: "GlobalHotkeyManager")
self.logActiveShortcuts(reason: "event tap ready")
self.setupMouseTaps()
return true
}
private nonisolated func cleanupEventTap() {
Self.tearDown(tap: self.eventTap, source: self.runLoopSource, runLoop: self.keyboardTapRunLoop ?? CFRunLoopGetMain())
self.eventTap = nil
self.runLoopSource = nil
self.clearPrimaryShortcutPressState()
self.cleanupMouseTaps()
}
private nonisolated static func tearDown(
tap: CFMachPort?,
source: CFRunLoopSource?,
runLoop: CFRunLoop = CFRunLoopGetMain()
) {
if let tap {
CGEvent.tapEnable(tap: tap, enable: false)
CFMachPortInvalidate(tap)
}
if let source {
CFRunLoopRemoveSource(runLoop, source, .commonModes)
CFRunLoopSourceInvalidate(source)
}
}
/// Starts (once) a dedicated thread whose run loop services the keyboard tap.
private nonisolated func keyboardTapRunLoopStartingIfNeeded() -> CFRunLoop {
if let runLoop = self.keyboardTapRunLoop { return runLoop }
let ready = DispatchSemaphore(value: 0)
nonisolated(unsafe) var createdRunLoop: CFRunLoop?
let thread = Thread {
createdRunLoop = CFRunLoopGetCurrent()
// A port keeps the loop alive while no tap source is attached.
let keepAlive = NSMachPort()
RunLoop.current.add(keepAlive, forMode: .common)
ready.signal()
CFRunLoopRun()
}
thread.name = "com.fluidvoice.hotkey-event-tap"
thread.qualityOfService = .userInteractive
thread.start()
ready.wait()
let runLoop: CFRunLoop = createdRunLoop ?? CFRunLoopGetMain()
self.keyboardTapRunLoop = runLoop
self.keyboardTapThread = thread
return runLoop
}
nonisolated static func mouseObserverEventMask() -> CGEventMask {
(CGEventMask(1) << CGEventType.leftMouseDown.rawValue)
| (CGEventMask(1) << CGEventType.rightMouseDown.rawValue)
| (CGEventMask(1) << CGEventType.otherMouseDown.rawValue)
}
nonisolated static func mouseShortcutEventMask(mouseButtons: Set<Int>) -> CGEventMask {
var mask: CGEventMask = 0
if mouseButtons.contains(0) {
mask |= (CGEventMask(1) << CGEventType.leftMouseDown.rawValue)
| (CGEventMask(1) << CGEventType.leftMouseUp.rawValue)
}
if mouseButtons.contains(1) {
mask |= (CGEventMask(1) << CGEventType.rightMouseDown.rawValue)
| (CGEventMask(1) << CGEventType.rightMouseUp.rawValue)
}
if mouseButtons.contains(where: { $0 >= 2 }) {
mask |= (CGEventMask(1) << CGEventType.otherMouseDown.rawValue)
| (CGEventMask(1) << CGEventType.otherMouseUp.rawValue)
}
return mask
}
struct ActiveShortcutSummaryInput {
let primary: [HotkeyShortcut]
let promptAssignments: [(key: String, shortcut: HotkeyShortcut)]
let secondaryPromptMode: HotkeyShortcut
let secondaryPromptModeEnabled: Bool
let command: HotkeyShortcut?
let commandEnabled: Bool
let edit: HotkeyShortcut
let editEnabled: Bool
let cancel: HotkeyShortcut?
let pasteLast: HotkeyShortcut?
let pasteLastEnabled: Bool
let mode: HotkeyActivationMode
}
/// One line listing every shortcut the manager will act on and where it came from.
static func activeShortcutSummary(_ input: ActiveShortcutSummaryInput) -> String {
func describe(_ shortcut: HotkeyShortcut?) -> String {
guard let shortcut else { return "none" }
if shortcut.isMouseShortcut {
return "\(shortcut.displayString) [button=\(shortcut.mouseButton ?? -1) flags=\(shortcut.relevantModifierFlags.rawValue)]"
}
return "\(shortcut.displayString) [keyCode=\(shortcut.keyCode) flags=\(shortcut.relevantModifierFlags.rawValue)]"
}
var parts = ["mode=\(input.mode.rawValue)"]
parts += input.primary.enumerated().map { "primary[\($0.offset)]=\(describe($0.element))" }
parts += input.promptAssignments.map { "prompt[\($0.key)]=\(describe($0.shortcut))" }
parts.append("secondaryPromptMode=\(describe(input.secondaryPromptMode)) enabled=\(input.secondaryPromptModeEnabled)")
parts.append("command=\(describe(input.command)) enabled=\(input.commandEnabled)")
parts.append("edit=\(describe(input.edit)) enabled=\(input.editEnabled)")
parts.append("cancel=\(describe(input.cancel))")
parts.append("pasteLast=\(describe(input.pasteLast)) enabled=\(input.pasteLastEnabled)")
return parts.joined(separator: " | ")
}
/// Coalesces the burst of shortcut updates into one log line.
private func scheduleActiveShortcutLog(reason: String) {
guard !self.activeShortcutLogScheduled else { return }
self.activeShortcutLogScheduled = true
Task { @MainActor [weak self] in
guard let self else { return }
self.activeShortcutLogScheduled = false
self.logActiveShortcuts(reason: reason)
}
}
private func logActiveShortcuts(reason: String) {
let settings = SettingsStore.shared
let promptAssignments = self.promptShortcutAssignments.map { assignment in
(
key: settings.dictationPromptConfigurationKey(for: assignment.selection) ?? "?",
shortcut: assignment.shortcut
)
}
let summary = Self.activeShortcutSummary(.init(
primary: self.primaryShortcuts,
promptAssignments: promptAssignments,
secondaryPromptMode: self.promptModeShortcut,
secondaryPromptModeEnabled: self.promptModeShortcutEnabled,
command: self.commandModeShortcut,
commandEnabled: self.commandModeShortcutEnabled,
edit: self.rewriteModeShortcut,
editEnabled: self.rewriteModeShortcutEnabled,
cancel: settings.cancelRecordingHotkeyShortcut,
pasteLast: settings.pasteLastTranscriptionHotkeyShortcut,
pasteLastEnabled: settings.pasteLastTranscriptionShortcutEnabled,
mode: self.hotkeyMode
))
DebugLogger.shared.info("Active shortcuts (\(reason)) | \(summary)", source: "GlobalHotkeyManager")
}
nonisolated static func modifierFlags(from flags: CGEventFlags) -> NSEvent.ModifierFlags {
NSEvent.ModifierFlags(rawValue: UInt(flags.rawValue)).intersection(HotkeyShortcut.shortcutModifierMask)
}
private nonisolated static func isTapEnabled(_ tap: CFMachPort?) -> Bool {
guard let tap else { return false }
return CGEvent.tapIsEnabled(tap: tap)
}
private func configuredMouseButtons() -> Set<Int> {
var buttons = Set(self.primaryShortcuts.compactMap { shortcut in
shortcut.isMouseShortcut ? shortcut.mouseButton : nil
})
if SettingsStore.shared.pasteLastTranscriptionShortcutEnabled,
let shortcut = SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut,
shortcut.isMouseShortcut,
let mouseButton = shortcut.mouseButton
{
buttons.insert(mouseButton)
}
return buttons
}
private func setupMouseTaps() {
self.setupMouseObserverTap()
self.setupMouseShortcutTap(mouseButtons: self.configuredMouseButtons())
}
// Listen-only: macOS delivers clicks to apps whether or not this callback runs.
private func setupMouseObserverTap() {
self.cleanupMouseObserverTap()
guard let tap = CGEvent.tapCreate(
tap: .cgSessionEventTap,
place: .headInsertEventTap,
options: .listenOnly,
eventsOfInterest: Self.mouseObserverEventMask(),
callback: { _, type, event, refcon -> Unmanaged<CGEvent>? in
guard let refcon else { return Unmanaged.passUnretained(event) }
let manager = Unmanaged<GlobalHotkeyManager>.fromOpaque(refcon).takeUnretainedValue()
return manager.handleMouseObserverEvent(type: type, event: event)
},
userInfo: Unmanaged.passUnretained(self).toOpaque()
) else {
DebugLogger.shared.error("Failed to create mouse observer tap", source: "GlobalHotkeyManager")
return
}
guard let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0) else {
CFMachPortInvalidate(tap)
DebugLogger.shared.error("Failed to create mouse observer run loop source", source: "GlobalHotkeyManager")
return
}
self.mouseObserverTap = tap
self.mouseObserverSource = source
CFRunLoopAddSource(CFRunLoopGetMain(), source, .commonModes)
CGEvent.tapEnable(tap: tap, enable: true)
DebugLogger.shared.info("Mouse observer tap enabled (listen-only)", source: "GlobalHotkeyManager")
}
// Filter tap, created only for the button families that have a shortcut.
private func setupMouseShortcutTap(mouseButtons: Set<Int>, preservePrimaryPress: Bool = false) {
let preservesHeldPress = preservePrimaryPress && self.activePrimaryShortcutPress?.mouseButton != nil
if !preservesHeldPress { self.finishInterruptedMouseShortcutPress(reason: "mouse shortcut tap rebuilt") }
self.cleanupMouseShortcutTap(preservePrimaryPress: preservesHeldPress)
var installedTap = false
defer {
if preservesHeldPress, !installedTap {
self.finishInterruptedMouseShortcutPress(reason: "mouse shortcut tap rebuild failed")
}
}
let mask = Self.mouseShortcutEventMask(mouseButtons: mouseButtons)
guard mask != 0 else {
DebugLogger.shared.info("Mouse shortcut tap not needed [mouseButtons=none]", source: "GlobalHotkeyManager")
return
}
guard let tap = CGEvent.tapCreate(
tap: .cgSessionEventTap,
place: .headInsertEventTap,
options: .defaultTap,
eventsOfInterest: mask,
callback: { _, type, event, refcon -> Unmanaged<CGEvent>? in
guard let refcon else { return Unmanaged.passUnretained(event) }
let manager = Unmanaged<GlobalHotkeyManager>.fromOpaque(refcon).takeUnretainedValue()
return manager.handleMouseShortcutEvent(type: type, event: event)
},
userInfo: Unmanaged.passUnretained(self).toOpaque()
) else {
DebugLogger.shared.error("Failed to create mouse shortcut tap", source: "GlobalHotkeyManager")
return
}
guard let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0) else {
CFMachPortInvalidate(tap)
DebugLogger.shared.error("Failed to create mouse shortcut run loop source", source: "GlobalHotkeyManager")
return
}
self.mouseShortcutTap = tap
self.mouseShortcutSource = source
self.monitoredMouseButtons = mouseButtons
CFRunLoopAddSource(CFRunLoopGetMain(), source, .commonModes)
CGEvent.tapEnable(tap: tap, enable: true)
installedTap = Self.isTapEnabled(tap)
let summary = mouseButtons.sorted().map(String.init).joined(separator: ",")
DebugLogger.shared.info("Mouse shortcut tap enabled [mouseButtons=\(summary)]", source: "GlobalHotkeyManager")
}
private func recoverMouseTapsIfNeeded() {
if !Self.isTapEnabled(self.mouseObserverTap) {
DebugLogger.shared.warning("Mouse observer tap not enabled, rebuilding", source: "GlobalHotkeyManager")
self.setupMouseObserverTap()
}
let mouseButtons = self.configuredMouseButtons()
let shortcutTapMissing = !mouseButtons.isEmpty && !Self.isTapEnabled(self.mouseShortcutTap)
if mouseButtons != self.monitoredMouseButtons || shortcutTapMissing {
DebugLogger.shared.warning("Mouse shortcut tap out of date, rebuilding", source: "GlobalHotkeyManager")
self.setupMouseShortcutTap(mouseButtons: mouseButtons)
}
}
private nonisolated func cleanupMouseTaps() {
self.cleanupMouseObserverTap()
self.cleanupMouseShortcutTap()
}
private nonisolated func cleanupMouseObserverTap() {
Self.tearDown(tap: self.mouseObserverTap, source: self.mouseObserverSource)
self.mouseObserverTap = nil
self.mouseObserverSource = nil
}
private nonisolated func cleanupMouseShortcutTap(preservePrimaryPress: Bool = false) {
Self.tearDown(tap: self.mouseShortcutTap, source: self.mouseShortcutSource)
self.mouseShortcutTap = nil
self.mouseShortcutSource = nil
self.monitoredMouseButtons = []
if !preservePrimaryPress { self.clearPrimaryShortcutPressState(mouseOnly: true) }
}
private func handleMouseObserverEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
self.reenableMouseTap(self.mouseObserverTap, label: "Mouse observer") { self.setupMouseObserverTap() }
return Unmanaged.passUnretained(event)
}
if self.isShortcutCaptureActiveProvider?() ?? false {
return Unmanaged.passUnretained(event)
}
self.markOtherInputDuringModifierOnly()
return Unmanaged.passUnretained(event)
}
func handleMouseShortcutEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
let previousInput = self.currentInputTiming
self.currentInputTiming = HotkeyInputTiming(
receivedAt: ProcessInfo.processInfo.systemUptime,
eventTimestamp: event.timestamp,
eventType: type.rawValue,
receivedTimestamp: DispatchTime.now().uptimeNanoseconds
)
defer { self.currentInputTiming = previousInput }
if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
self.finishInterruptedMouseShortcutPress(reason: "mouse shortcut tap disabled")
self.reenableMouseTap(self.mouseShortcutTap, label: "Mouse shortcut") {
self.setupMouseShortcutTap(mouseButtons: self.configuredMouseButtons())
}
return Unmanaged.passUnretained(event)
}
if self.isShortcutCaptureActiveProvider?() ?? false {
return Unmanaged.passUnretained(event)
}
switch type {
case .leftMouseDown, .rightMouseDown, .otherMouseDown:
self.markOtherInputDuringModifierOnly()
if self.handleMouseShortcutDown(event, modifiers: Self.modifierFlags(from: event.flags)) {
return nil
}
case .leftMouseUp, .rightMouseUp, .otherMouseUp:
if self.handleMouseShortcutUp(event) {
return nil
}
default:
break
}
return Unmanaged.passUnretained(event)
}
private func reenableMouseTap(_ tap: CFMachPort?, label: String, rebuild: @escaping @MainActor () -> Void) {
DebugLogger.shared.warning("\(label) tap disabled by macOS, re-enabling", source: "GlobalHotkeyManager")
if let tap {
CGEvent.tapEnable(tap: tap, enable: true)
}
guard !Self.isTapEnabled(tap) else { return }
DebugLogger.shared.warning("\(label) tap re-enable failed, rebuilding", source: "GlobalHotkeyManager")
Task { @MainActor in
rebuild()
}
}
nonisolated static func sessionIsLocked(sessionInfo: [String: Any]) -> Bool {
sessionInfo["CGSSessionScreenIsLocked"] as? Bool ?? false
}
private nonisolated static func currentSessionIsLocked() -> Bool {
self.sessionIsLocked(sessionInfo: CGSessionCopyCurrentDictionary() as? [String: Any] ?? [:])
}
private nonisolated func clearPrimaryShortcutPressState(mouseOnly: Bool = false) {
let task = self.state.withLock { () -> Task<Void, Never>? in
self.state.consumedPasteMouseButton = nil
if mouseOnly {
guard case .mouse? = self.state.activePrimaryShortcutPress else { return nil }
} else {
guard self.state.activePrimaryShortcutPress != nil || self.state.isKeyPressed else { return nil }
}
self.state.activePrimaryShortcutPress = nil
self.state.isKeyPressed = false
self.state.holdModeStartTriggeredTypes.remove(.transcription)
self.state.automaticPressStartTimes.removeValue(forKey: .transcription)
self.state.automaticPressWasTargetActive.removeValue(forKey: .transcription)
self.state.automaticPressStartedTypes.remove(.transcription)
_ = self.state.pendingReleaseStopTokens.removeValue(forKey: .transcription)
return self.state.pendingReleaseStopTasks.removeValue(forKey: .transcription)
}
task?.cancel()
}
private func markOtherInputDuringModifierOnly() {
guard self.modifierOnlyKeyDown else { return }
self.otherKeyPressedDuringModifier = true
}
private func mouseButton(from event: CGEvent) -> Int {
Int(event.getIntegerValueField(.mouseEventButtonNumber))
}
private func finishInterruptedMouseShortcutPress(reason: String) {
guard case .mouse? = self.activePrimaryShortcutPress else { return }
self.clearPrimaryShortcutPressState(mouseOnly: true)
DebugLogger.shared.warning(
"Finishing active mouse shortcut press before \(reason)",
source: "GlobalHotkeyManager"
)
guard Self.shouldForceStopInterruptedPrimaryPress(activationMode: self.hotkeyMode) else { return }
if self.asrService.isRunningOrStarting {
self.stopRecordingIfNeeded()
} else {
self.stopRecordingAfterRelease(
for: .transcription,
label: "Interrupted mouse shortcut",
requireTargetMode: false
)
}
}
nonisolated static func shouldForceStopInterruptedPrimaryPress(activationMode: HotkeyActivationMode) -> Bool {
activationMode != .toggle
}
private func primaryModifierOnlyBehavior(for shortcut: HotkeyShortcut) -> ModifierOnlyShortcutBehavior {
.init(
shortcut: shortcut,
isEnabled: true,
holdModeType: .transcription,
holdStartMessage: "Transcription modifier held (hold mode) - starting",
holdReleaseMessage: "Transcription modifier released (hold mode) - stopping",
toggleIgnoredMessage: "Transcription modifier released but another key was pressed - ignoring",
isModeKeyPressed: { self.isKeyPressed },
setModeKeyPressed: { self.isKeyPressed = $0 },
onHoldStart: { self.startRecordingIfNeeded(shortcut: shortcut) },
onToggleRelease: {
if self.asrService.isRunningOrStarting {
let isSameMode = self.isDictateRecordingProvider?() ?? false
DebugLogger.shared.info(
"Hotkey route | pressed=dictate(mod) | active=\(isSameMode ? "dictate" : "other") | asrRunning=true | action=\(isSameMode ? "stop" : "switch")",
source: "GlobalHotkeyManager"
)
if isSameMode {
self.triggerDictationMode(shortcut: shortcut)
} else {
self.triggerDictationMode(shortcut: shortcut)
}
} else {
DebugLogger.shared.info(
"Hotkey route | pressed=dictate(mod) | active=none | asrRunning=false | action=start",
source: "GlobalHotkeyManager"
)
self.triggerDictationMode(shortcut: shortcut)
}
},
isTargetModeActive: { self.isDictateRecordingProvider?() ?? false }
)
}
func handleKeyEvent(type: CGEventType, event: CGEvent, proxy: CGEventTapProxy? = nil) -> Unmanaged<CGEvent>? {
let previousInput = self.currentInputTiming
self.currentInputTiming = HotkeyInputTiming(
receivedAt: ProcessInfo.processInfo.systemUptime,
eventTimestamp: event.timestamp,
eventType: type.rawValue,
receivedTimestamp: DispatchTime.now().uptimeNanoseconds
)
defer { self.currentInputTiming = previousInput }
if let tapRecoveryResult = self.handleTapDisableEvent(type: type, event: event) {
return tapRecoveryResult
}
if Self.isSynthesizedTypingEvent(event) {
return Unmanaged.passUnretained(event)
}
if self.handleHoldToMute(type: type, event: event, proxy: proxy) {
return nil
}
if self.isShortcutCaptureActiveProvider?() ?? false {
self.resetModifierOnlyShortcutTracking()
if Self.captureKeyboardEvent(type: type, event: event, isAppActive: NSApp.isActive, handler: self.shortcutCaptureHandler) { return nil }
return Unmanaged.passUnretained(event)
}
let keyCode = UInt16(event.getIntegerValueField(.keyboardEventKeycode))
let eventModifiers = Self.modifierFlags(from: event.flags)
let isAutorepeat = event.getIntegerValueField(.keyboardEventAutorepeat) != 0
if self.handleMeetingRecordingShortcut(type: type, keyCode: keyCode, modifiers: eventModifiers, isAutorepeat: isAutorepeat) {
return nil
}
switch type {
case .keyDown:
// A fresh down proves the previous same-key release was missed. Do not let its
// stale ownership turn ordinary typing into a shortcut on the next key-up.
if self.hotkeyMode == .toggle,
!isAutorepeat,
self.activePrimaryShortcutPress?.keyboardKeyCode == keyCode
{ self.activePrimaryShortcutPress = nil }
// The application owns cancellation output; fallback managers only discard capture.
if SettingsStore.shared.cancelRecordingHotkeyShortcut?.matches(keyCode: keyCode, modifiers: eventModifiers) == true {
let result = self.cancelCallback?() ?? .unhandled
// Closing a suggestion must preserve the held shortcut and capture.
if result == .dismissedOverlay {
self.markOtherInputDuringModifierOnly()
return nil
}
var handled = result == .cancelled
if !handled, self.asrService.isRunningOrStarting {
Task { @MainActor in await self.asrService.stopWithoutTranscription() }
handled = true
}
let hasPendingPress = self.state.withLock {
self.state.activePrimaryShortcutPress != nil || self.state.activeModifierOnlyType != nil
}
if handled || hasPendingPress || self.pendingRecordingActionCounts.values.contains(where: { $0 > 0 }) {
self.resetModifierOnlyShortcutTracking(reason: .cancel)
return nil
}
}
self.markOtherInputDuringModifierOnly()
// Check the "paste last transcription" shortcut (a one-shot action, like cancel).
if SettingsStore.shared.pasteLastTranscriptionShortcutEnabled,
let pasteShortcut = SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut,
pasteShortcut.matches(keyCode: keyCode, modifiers: eventModifiers)
{
// Holding the chord emits auto-repeat key-downs; because the paste waits for the
// modifiers to release, every repeat would otherwise queue another insertion and
// paste N times. triggerPasteLastTranscription ignores repeats.
self.triggerPasteLastTranscription(isAutorepeat: event.getIntegerValueField(.keyboardEventAutorepeat) != 0)
return nil
}
if let assignment = self.promptShortcutAssignments.first(where: { $0.shortcut.matchesRecordingShortcut(keyCode: keyCode, modifiers: eventModifiers) }) {
guard !isAutorepeat else { return nil }
switch self.hotkeyMode {
case .hold:
if !self.isPromptAssignmentKeyPressed {
self.cancelPendingReleaseStop(for: .promptAssignment)
self.clearHoldModeStartTriggered(for: .promptAssignment)
self.activePromptAssignmentPress = assignment
self.isPromptAssignmentKeyPressed = true
DebugLogger.shared.info("Prompt shortcut pressed (hold mode) - starting", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
self.markHoldModeStartTriggered(for: .promptAssignment)
}
case .automatic:
if !self.isPromptAssignmentKeyPressed {
self.activePromptAssignmentPress = assignment
self.isPromptAssignmentKeyPressed = true
let isSameMode = self.asrService.isRunning && (self.isPromptModeRecordingProvider?() ?? false)
self.beginAutomaticPress(for: .promptAssignment, wasTargetActive: isSameMode)
if self.asrService.isRunning {
if isSameMode {
DebugLogger.shared.info("Prompt shortcut pressed (automatic, same mode) - waiting for release", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.info("Prompt shortcut pressed (automatic, switch mode)", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
self.markAutomaticPressStarted(for: .promptAssignment)
}
} else {
DebugLogger.shared.info("Prompt shortcut triggered (automatic) - starting", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
self.markAutomaticPressStarted(for: .promptAssignment)
}
}
case .toggle:
if self.asrService.isRunningOrStarting {
if self.isPromptModeRecordingProvider?() ?? false {
DebugLogger.shared.info("Prompt shortcut pressed in Prompt mode - stopping", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
} else {
DebugLogger.shared.info("Prompt shortcut pressed while recording - switching mode", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
}
} else {
DebugLogger.shared.info("Prompt shortcut triggered - starting", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
}
}
return nil
}
// Check prompt mode hotkey
if self.handlePromptModeKeyDown(keyCode: keyCode, modifiers: eventModifiers, isAutorepeat: isAutorepeat) { return nil }
// Check command mode hotkey first
if self.commandModeShortcutEnabled,
let commandModeShortcut = self.commandModeShortcut,
commandModeShortcut.matchesRecordingShortcut(keyCode: keyCode, modifiers: eventModifiers)
{
guard !isAutorepeat else { return nil }
switch self.hotkeyMode {
case .hold:
// Press and hold: start on keyDown, stop on keyUp
if !self.isCommandModeKeyPressed {
self.cancelPendingReleaseStop(for: .commandMode)
self.clearHoldModeStartTriggered(for: .commandMode)
self.isCommandModeKeyPressed = true
DebugLogger.shared.info("Command mode shortcut pressed (hold mode) - starting", source: "GlobalHotkeyManager")
self.triggerCommandMode()
self.markHoldModeStartTriggered(for: .commandMode)
}
case .automatic:
if !self.isCommandModeKeyPressed {
self.isCommandModeKeyPressed = true
let isSameMode = self.asrService.isRunning && (self.isCommandRecordingProvider?() ?? false)
self.beginAutomaticPress(for: .commandMode, wasTargetActive: isSameMode)
if self.asrService.isRunning {
if isSameMode {
DebugLogger.shared.info("Command mode shortcut pressed (automatic, same mode) - waiting for release", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.info("Command mode shortcut pressed (automatic, switch mode)", source: "GlobalHotkeyManager")
self.triggerCommandMode()
self.markAutomaticPressStarted(for: .commandMode)
}
} else {
DebugLogger.shared.info("Command mode shortcut triggered (automatic) - starting", source: "GlobalHotkeyManager")
self.triggerCommandMode()
self.markAutomaticPressStarted(for: .commandMode)
}
}
case .toggle:
// Toggle mode: press to start, press again to stop
if self.asrService.isRunningOrStarting {
if self.isCommandRecordingProvider?() ?? false {
DebugLogger.shared.info("Command mode shortcut pressed in Command mode - stopping", source: "GlobalHotkeyManager")
self.triggerCommandMode()
} else {
DebugLogger.shared.info("Command mode shortcut pressed while recording - switching mode", source: "GlobalHotkeyManager")
self.triggerCommandMode()
}
} else {
DebugLogger.shared.info("Command mode shortcut triggered - starting", source: "GlobalHotkeyManager")
self.triggerCommandMode()
}
}
return nil
}
// Check dedicated rewrite mode hotkey
if self.rewriteModeShortcutEnabled {
if self.rewriteModeShortcut.matchesRecordingShortcut(keyCode: keyCode, modifiers: eventModifiers) {
guard !isAutorepeat else { return nil }
switch self.hotkeyMode {
case .hold:
// Press and hold: start on keyDown, stop on keyUp
if !self.isRewriteKeyPressed {
self.cancelPendingReleaseStop(for: .rewriteMode)
self.clearHoldModeStartTriggered(for: .rewriteMode)
self.isRewriteKeyPressed = true
DebugLogger.shared.info("Rewrite mode shortcut pressed (hold mode) - starting", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
self.markHoldModeStartTriggered(for: .rewriteMode)
}
case .automatic:
if !self.isRewriteKeyPressed {
self.isRewriteKeyPressed = true
let isSameMode = self.asrService.isRunning && (self.isRewriteRecordingProvider?() ?? false)
self.beginAutomaticPress(for: .rewriteMode, wasTargetActive: isSameMode)
if self.asrService.isRunning {
if isSameMode {
DebugLogger.shared.info("Rewrite mode shortcut pressed (automatic, same mode) - waiting for release", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.info("Rewrite mode shortcut pressed (automatic, switch mode)", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
self.markAutomaticPressStarted(for: .rewriteMode)
}
} else {
DebugLogger.shared.info("Rewrite mode shortcut triggered (automatic) - starting", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
self.markAutomaticPressStarted(for: .rewriteMode)
}
}
case .toggle:
// Toggle mode: press to start, press again to stop
if self.asrService.isRunningOrStarting {
if self.isRewriteRecordingProvider?() ?? false {
DebugLogger.shared.info("Rewrite mode shortcut pressed in Edit mode - stopping", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
} else {
DebugLogger.shared.info("Rewrite mode shortcut pressed while recording - switching mode", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
}
} else {
DebugLogger.shared.info("Rewrite mode shortcut triggered - starting", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
}
}
return nil
}
}
// Then check transcription hotkeys
if let shortcut = self.primaryShortcuts.first(where: { $0.matchesRecordingShortcut(keyCode: keyCode, modifiers: eventModifiers) }) {
guard !isAutorepeat else { return nil }
guard self.beginPrimaryShortcutPress(.keyboard(shortcut)) else { return nil }
self.handlePrimaryDictationTriggerDown()
return nil
}
case .keyUp:
// Prompt mode key up (press and hold mode)
if self.handlePromptModeKeyUp(keyCode: keyCode) { return nil }
// Command mode key up
// Note: Only check keyCode, not modifiers - user may release modifier before/with main key
if self.commandModeShortcutEnabled,
self.isCommandModeKeyPressed,
let commandModeShortcut = self.commandModeShortcut,
keyCode == commandModeShortcut.keyCode
{
switch self.hotkeyMode {
case .hold:
self.isCommandModeKeyPressed = false
_ = self.finishHoldModeStartTriggered(for: .commandMode)
DebugLogger.shared.info("Command mode shortcut released (hold mode) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: .commandMode, label: "Command mode")
case .automatic:
self.isCommandModeKeyPressed = false
self.handleAutomaticKeyRelease(for: .commandMode, label: "Command mode")
case .toggle:
break
}
return nil
}
// Rewrite mode key up
// Note: Only check keyCode, not modifiers - user may release modifier before/with main key
if self.rewriteModeShortcutEnabled, self.isRewriteKeyPressed, keyCode == self.rewriteModeShortcut.keyCode {
switch self.hotkeyMode {
case .hold:
self.isRewriteKeyPressed = false
_ = self.finishHoldModeStartTriggered(for: .rewriteMode)
DebugLogger.shared.info("Rewrite mode shortcut released (hold mode) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: .rewriteMode, label: "Rewrite mode")
case .automatic:
self.isRewriteKeyPressed = false
self.handleAutomaticKeyRelease(for: .rewriteMode, label: "Rewrite mode")
case .toggle:
break
}
return nil
}
// Prompt assignment key up
// Note: Only check keyCode, not modifiers - user may release modifier before/with main key
if self.isPromptAssignmentKeyPressed,
self.activePromptAssignmentPress?.shortcut.keyCode == keyCode
{
self.activePromptAssignmentPress = nil
switch self.hotkeyMode {
case .hold:
self.isPromptAssignmentKeyPressed = false
_ = self.finishHoldModeStartTriggered(for: .promptAssignment)
DebugLogger.shared.info("Prompt shortcut released (hold mode) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: .promptAssignment, label: "Prompt shortcut")
case .automatic:
self.isPromptAssignmentKeyPressed = false
self.handleAutomaticKeyRelease(for: .promptAssignment, label: "Prompt shortcut")
case .toggle:
break
}
return nil
}
// Transcription key up
// Note: Only check keyCode, not modifiers - user may release modifier before/with main key
if let shortcut = self.finishPrimaryShortcutPress(matching: { $0.keyboardKeyCode == keyCode }) {
self.handlePrimaryDictationTriggerUp(shortcut: shortcut)
return nil
}
case .flagsChanged:
if HotkeyShortcut.modifierFlag(forKeyCode: keyCode) != nil {
self.pressedModifierKeyCodes = self.synchronizedPressedModifierKeyCodes(
changedKeyCode: keyCode,
modifiers: eventModifiers
)
}
for shortcut in self.primaryShortcuts where shortcut.isModifierOnlyShortcut {
if self.handleModifierOnlyShortcutFlagsChanged(
behavior: self.primaryModifierOnlyBehavior(for: shortcut),
keyCode: keyCode,
modifiers: eventModifiers
) { return nil }
}
if self.handlePromptAssignmentFlagsChanged(keyCode: keyCode, modifiers: eventModifiers) { return nil }
if self.handlePromptModeFlagsChanged(keyCode: keyCode, modifiers: eventModifiers) { return nil }
if let commandModeShortcut = self.commandModeShortcut,
self.handleModifierOnlyShortcutFlagsChanged(
behavior: .init(
shortcut: commandModeShortcut,
isEnabled: self.commandModeShortcutEnabled,
holdModeType: .commandMode,
holdStartMessage: "Command mode modifier held (hold mode) - starting",
holdReleaseMessage: "Command mode modifier released (hold mode) - stopping",
toggleIgnoredMessage: "Command mode modifier released but another key was pressed - ignoring",
isModeKeyPressed: { self.isCommandModeKeyPressed },
setModeKeyPressed: { self.isCommandModeKeyPressed = $0 },
onHoldStart: { self.triggerCommandMode() },
onToggleRelease: {
if self.asrService.isRunningOrStarting {
if self.isCommandRecordingProvider?() ?? false {
DebugLogger.shared.info("Command mode modifier released (toggle, same mode) - stopping", source: "GlobalHotkeyManager")
self.triggerCommandMode()
} else {
DebugLogger.shared.info("Command mode modifier released (toggle, switch mode) - switching", source: "GlobalHotkeyManager")
self.triggerCommandMode()
}
} else {
DebugLogger.shared.info("Command mode modifier released (toggle) - starting", source: "GlobalHotkeyManager")
self.triggerCommandMode()
}
},
isTargetModeActive: { self.isCommandRecordingProvider?() ?? false }
),
keyCode: keyCode,
modifiers: eventModifiers
)
{ return nil }
if self.handleModifierOnlyShortcutFlagsChanged(
behavior: .init(
shortcut: self.rewriteModeShortcut,
isEnabled: self.rewriteModeShortcutEnabled,
holdModeType: .rewriteMode,
holdStartMessage: "Rewrite mode modifier held (hold mode) - starting",
holdReleaseMessage: "Rewrite mode modifier released (hold mode) - stopping",
toggleIgnoredMessage: "Rewrite mode modifier released but another key was pressed - ignoring",
isModeKeyPressed: { self.isRewriteKeyPressed },
setModeKeyPressed: { self.isRewriteKeyPressed = $0 },
onHoldStart: { self.triggerRewriteMode() },
onToggleRelease: {
if self.asrService.isRunningOrStarting {
if self.isRewriteRecordingProvider?() ?? false {
DebugLogger.shared.info("Rewrite mode modifier released (toggle, same mode) - stopping", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
} else {
DebugLogger.shared.info("Rewrite mode modifier released (toggle, switch mode) - switching", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
}
} else {
DebugLogger.shared.info("Rewrite mode modifier released (toggle) - starting", source: "GlobalHotkeyManager")
self.triggerRewriteMode()
}
},
isTargetModeActive: { self.isRewriteRecordingProvider?() ?? false }
),
keyCode: keyCode,
modifiers: eventModifiers
) { return nil }
default:
break
}
return Unmanaged.passUnretained(event)
}
private func synchronizedPressedModifierKeyCodes(
changedKeyCode: UInt16,
modifiers: NSEvent.ModifierFlags
) -> Set<UInt16> {
guard let changedFlag = HotkeyShortcut.modifierFlag(forKeyCode: changedKeyCode) else {
return self.pressedModifierKeyCodes
}
let activeModifiers = modifiers.intersection(HotkeyShortcut.relevantModifierMask)
let activeModifierGroups: [(NSEvent.ModifierFlags, [UInt16])] = [
(.function, [63]),
(.command, [55, 54]),
(.option, [58, 61]),
(.control, [59, 62]),
(.shift, [56, 60]),
]
// Flags tell us a modifier family is active, not which physical side. Preserve the
// side-specific keys we already observed instead of rediscovering them from keyState.
var synchronizedKeyCodes = self.pressedModifierKeyCodes.filter { keyCode in
guard let flag = HotkeyShortcut.modifierFlag(forKeyCode: keyCode) else { return false }
return activeModifiers.contains(flag)
}
guard let changedGroup = activeModifierGroups.first(where: { $0.0 == changedFlag }) else {
return synchronizedKeyCodes
}
if activeModifiers.contains(changedFlag) {
if synchronizedKeyCodes.contains(changedKeyCode) {
let siblingKeyCodes = changedGroup.1.filter { $0 != changedKeyCode }
let siblingIsTracked = siblingKeyCodes.contains { synchronizedKeyCodes.contains($0) }
if siblingIsTracked,
!CGEventSource.keyState(.combinedSessionState, key: CGKeyCode(changedKeyCode))
{
synchronizedKeyCodes.remove(changedKeyCode)
}
} else {
synchronizedKeyCodes.insert(changedKeyCode)
}
} else {
synchronizedKeyCodes.subtract(changedGroup.1)
}
return synchronizedKeyCodes
}
private func markModifierOnlyPressInterrupted(message: String) {
self.otherKeyPressedDuringModifier = true
DebugLogger.shared.info(message, source: "GlobalHotkeyManager")
}
private func handleAutomaticKeyRelease(
for type: HotkeyHoldModeType,
label: String,
onUnstartedTap: (() -> Void)? = nil
) {
let press = self.finishAutomaticPress(for: type)
let duration = String(format: "%.2f", press.duration)
if press.duration < self.automaticTapThresholdSeconds {
if press.wasTargetActive {
DebugLogger.shared.info("\(label) tap (\(duration)s) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingIfNeeded()
} else if press.started {
DebugLogger.shared.info("\(label) tap (\(duration)s) - continuing", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.info("\(label) tap (\(duration)s) - toggling", source: "GlobalHotkeyManager")
onUnstartedTap?()
}
return
}
if press.wasTargetActive || press.started {
DebugLogger.shared.info("\(label) hold (\(duration)s) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: type, label: label)
} else {
DebugLogger.shared.debug("\(label) hold (\(duration)s) ignored - no automatic start", source: "GlobalHotkeyManager")
}
}
private func handlePrimaryDictationTriggerDown() {
switch self.hotkeyMode {
case .hold:
if !self.isKeyPressed {
self.cancelPendingReleaseStop(for: .transcription)
self.clearHoldModeStartTriggered(for: .transcription)
self.isKeyPressed = true
if self.asrService.isRunning {
let isSameMode = self.isDictateRecordingProvider?() ?? false
DebugLogger.shared.debug(
"GlobalHotkeyManager: dictation hold-press path",
source: "GlobalHotkeyManager"
)
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=\(isSameMode ? "dictate" : "other") | asrRunning=true | action=\(isSameMode ? "stop" : "switch")",
source: "GlobalHotkeyManager"
)
if !isSameMode {
self.triggerDictationMode()
}
} else {
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=none | asrRunning=false | action=start",
source: "GlobalHotkeyManager"
)
self.startRecordingIfNeeded()
}
self.markHoldModeStartTriggered(for: .transcription)
}
case .automatic:
if !self.isKeyPressed {
self.isKeyPressed = true
let isSameMode = self.asrService.isRunning && (self.isDictateRecordingProvider?() ?? false)
self.beginAutomaticPress(for: .transcription, wasTargetActive: isSameMode)
if self.asrService.isRunning {
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=\(isSameMode ? "dictate" : "other") | asrRunning=true | action=\(isSameMode ? "release-stop" : "switch")",
source: "GlobalHotkeyManager"
)
if !isSameMode {
self.triggerDictationMode()
self.markAutomaticPressStarted(for: .transcription)
}
} else {
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=none | asrRunning=false | action=start",
source: "GlobalHotkeyManager"
)
self.triggerDictationMode()
self.markAutomaticPressStarted(for: .transcription)
}
}
case .toggle:
break // The owning keyboard/mouse release toggles; repeats do not.
}
}
private func handlePrimaryDictationTriggerUp(shortcut: HotkeyShortcut) {
switch self.hotkeyMode {
case .hold:
self.isKeyPressed = false
_ = self.finishHoldModeStartTriggered(for: .transcription)
self.stopRecordingAfterRelease(for: .transcription, label: "Transcription")
case .automatic:
self.isKeyPressed = false
self.handleAutomaticKeyRelease(for: .transcription, label: "Transcription")
case .toggle:
if self.asrService.isRunningOrStarting {
let isSameMode = self.isDictateRecordingProvider?() ?? false
DebugLogger.shared.debug(
"GlobalHotkeyManager: dictation tap path while already running",
source: "GlobalHotkeyManager"
)
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=\(isSameMode ? "dictate" : "other") | asrRunning=true | action=\(isSameMode ? "stop" : "switch")",
source: "GlobalHotkeyManager"
)
if isSameMode {
self.triggerDictationMode(shortcut: shortcut)
} else {
self.triggerDictationMode(shortcut: shortcut)
}
} else {
DebugLogger.shared.info(
"Hotkey route | pressed=dictate | active=none | asrRunning=false | action=start",
source: "GlobalHotkeyManager"
)
self.triggerDictationMode(shortcut: shortcut)
}
}
}
private func stopRecordingAfterRelease(
for type: HotkeyHoldModeType,
label: String,
requireTargetMode: Bool = true
) {
let toggleStopRequestedAt = ProcessInfo.processInfo.systemUptime
self.logStopInput(requestedAt: toggleStopRequestedAt, route: "deferred_release")
let token = self.beginPendingReleaseStop(for: type)
DebugLogger.shared.debug("\(label) release stop deferred until recording starts", source: "GlobalHotkeyManager")
let task = Task { @MainActor [weak self] in
let maxAttempts = 60
let retryDelayNanoseconds: UInt64 = 50_000_000
for _ in 0..<maxAttempts {
guard !Task.isCancelled else { return }
guard let self = self else { return }
guard self.isPendingReleaseStopCurrent(for: type, token: token) else { return }
if self.asrService.isRunning {
guard !requireTargetMode || self.isRecordingTargetActive(for: type) else {
DebugLogger.shared.debug("\(label) deferred stop skipped - active mode changed", source: "GlobalHotkeyManager")
self.clearPendingReleaseStop(for: type, token: token)
return
}
DebugLogger.shared.info("\(label) deferred stop after recording start", source: "GlobalHotkeyManager")
self.clearPendingReleaseStop(for: type, token: token)
await self.stopRecordingInternal(toggleStopRequestedAt: toggleStopRequestedAt)
return
}
try? await Task.sleep(nanoseconds: retryDelayNanoseconds)
}
guard !Task.isCancelled else { return }
guard let self = self else { return }
guard self.isPendingReleaseStopCurrent(for: type, token: token) else { return }
DebugLogger.shared.warning("\(label) deferred stop expired before recording started", source: "GlobalHotkeyManager")
self.clearPendingReleaseStop(for: type, token: token)
}
self.storePendingReleaseStopTask(task, for: type, token: token)
}
private func label(for type: HotkeyHoldModeType) -> String {
switch type {
case .transcription:
return "Transcription"
case .promptMode:
return "Prompt mode"
case .commandMode:
return "Command mode"
case .rewriteMode:
return "Rewrite mode"
case .promptAssignment:
return "Prompt shortcut"
}
}
private func scheduleModifierOnlyStart(for behavior: ModifierOnlyShortcutBehavior) {
guard self.hotkeyMode != .toggle, !behavior.isModeKeyPressed() else { return }
self.cancelPendingReleaseStop(for: behavior.holdModeType)
self.clearHoldModeStartTriggered(for: behavior.holdModeType)
behavior.setModeKeyPressed(true)
let wasTargetActive = self.asrService.isRunning && behavior.isTargetModeActive()
if self.hotkeyMode == .automatic {
self.beginAutomaticPress(for: behavior.holdModeType, wasTargetActive: wasTargetActive)
}
guard self.hotkeyMode != .automatic || !wasTargetActive else { return }
DebugLogger.shared.info(behavior.holdStartMessage, source: "GlobalHotkeyManager")
if self.hotkeyMode == .hold {
self.markHoldModeStartTriggered(for: behavior.holdModeType)
}
behavior.onHoldStart()
if self.hotkeyMode == .automatic {
self.markAutomaticPressStarted(for: behavior.holdModeType)
}
}
private func finishModifierOnlyPress(
for behavior: ModifierOnlyShortcutBehavior,
wasCleanPress: Bool
) {
switch self.hotkeyMode {
case .hold:
if behavior.isModeKeyPressed() {
behavior.setModeKeyPressed(false)
let didStart = self.finishHoldModeStartTriggered(for: behavior.holdModeType)
if self.asrService.isRunning || didStart {
DebugLogger.shared.info(behavior.holdReleaseMessage, source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: behavior.holdModeType, label: self.label(for: behavior.holdModeType))
}
}
case .automatic:
if behavior.isModeKeyPressed() {
behavior.setModeKeyPressed(false)
}
if wasCleanPress {
self.handleAutomaticKeyRelease(
for: behavior.holdModeType,
label: self.label(for: behavior.holdModeType),
onUnstartedTap: behavior.onToggleRelease
)
} else {
let press = self.finishAutomaticPress(for: behavior.holdModeType)
if press.started {
DebugLogger.shared.info("\(self.label(for: behavior.holdModeType)) modifier released after combo - stopping automatic start", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: behavior.holdModeType, label: self.label(for: behavior.holdModeType))
} else {
DebugLogger.shared.debug(behavior.toggleIgnoredMessage, source: "GlobalHotkeyManager")
}
}
case .toggle:
if wasCleanPress {
behavior.onToggleRelease()
} else {
DebugLogger.shared.debug(behavior.toggleIgnoredMessage, source: "GlobalHotkeyManager")
}
}
}
func resetModifierOnlyShortcutTracking(reason: ModifierTrackingResetReason = .shortcutCapture) {
self.meetingShortcutPressedKey = nil
self.invalidateAllRecordingActions()
self.modifierPressReceivedAt = nil
self.currentStopPressReceivedAt = nil
let shouldStopActiveHold = reason != .cancel && self.hotkeyMode != .toggle
&& self.asrService.isRunningOrStarting
&& (self.isKeyPressed || self.isPromptModeKeyPressed || self.isCommandModeKeyPressed || self.isRewriteKeyPressed || self.isPromptAssignmentKeyPressed)
self.pressedModifierKeyCodes = []
self.modifierOnlyKeyDown = false
self.activeModifierOnlyType = nil
self.otherKeyPressedDuringModifier = false
self.modifierPressStartTime = nil
self.clearAutomaticPressTracking()
self.isKeyPressed = false
self.isPromptModeKeyPressed = false
self.isCommandModeKeyPressed = false
self.isRewriteKeyPressed = false
self.isPromptAssignmentKeyPressed = false
self.activePromptAssignmentPress = nil
self.activeModifierOnlyShortcut = nil
self.activePrimaryShortcutPress = nil
if shouldStopActiveHold {
switch reason {
case .shortcutCapture:
DebugLogger.shared.debug("Shortcut capture active - stopping active hold recording before reset", source: "GlobalHotkeyManager")
case .tapDisabled:
DebugLogger.shared.warning("Event tap disabled during active hold - stopping recording before reset", source: "GlobalHotkeyManager")
case .cancel:
break
case .reinitialize:
DebugLogger.shared.info("Hotkey manager reinitializing - stopping active hold recording before reset", source: "GlobalHotkeyManager")
}
self.stopRecordingIfNeeded()
}
}
private func handlePromptModeKeyDown(keyCode: UInt16, modifiers: NSEvent.ModifierFlags, isAutorepeat: Bool) -> Bool {
guard self.promptModeShortcutEnabled, self.promptModeShortcut.matchesRecordingShortcut(keyCode: keyCode, modifiers: modifiers) else { return false }
guard !isAutorepeat else { return true }
switch self.hotkeyMode {
case .hold:
if !self.isPromptModeKeyPressed {
self.cancelPendingReleaseStop(for: .promptMode)
self.clearHoldModeStartTriggered(for: .promptMode)
self.isPromptModeKeyPressed = true
DebugLogger.shared.info("Prompt mode shortcut pressed (hold mode) - starting", source: "GlobalHotkeyManager")
self.triggerPromptMode()
self.markHoldModeStartTriggered(for: .promptMode)
}
case .automatic:
if !self.isPromptModeKeyPressed {
self.isPromptModeKeyPressed = true
let isSameMode = self.asrService.isRunning && (self.isPromptModeRecordingProvider?() ?? false)
self.beginAutomaticPress(for: .promptMode, wasTargetActive: isSameMode)
if self.asrService.isRunning {
if isSameMode {
DebugLogger.shared.info("Prompt mode shortcut pressed (automatic, same mode) - waiting for release", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.info("Prompt mode shortcut pressed (automatic, switch mode)", source: "GlobalHotkeyManager")
self.triggerPromptMode()
self.markAutomaticPressStarted(for: .promptMode)
}
} else {
DebugLogger.shared.info("Prompt mode shortcut triggered (automatic) - starting", source: "GlobalHotkeyManager")
self.triggerPromptMode()
self.markAutomaticPressStarted(for: .promptMode)
}
}
case .toggle:
if self.asrService.isRunningOrStarting {
if self.isPromptModeRecordingProvider?() ?? false {
DebugLogger.shared.info("Prompt mode shortcut pressed in Prompt mode - stopping", source: "GlobalHotkeyManager")
self.triggerPromptMode()
} else {
DebugLogger.shared.info("Prompt mode shortcut pressed while recording - switching mode", source: "GlobalHotkeyManager")
self.triggerPromptMode()
}
} else {
DebugLogger.shared.info("Prompt mode shortcut triggered - starting", source: "GlobalHotkeyManager")
self.triggerPromptMode()
}
}
return true
}
private func handlePromptModeKeyUp(keyCode: UInt16) -> Bool {
guard self.promptModeShortcutEnabled,
self.isPromptModeKeyPressed, keyCode == self.promptModeShortcut.keyCode else { return false }
switch self.hotkeyMode {
case .hold:
self.isPromptModeKeyPressed = false
_ = self.finishHoldModeStartTriggered(for: .promptMode)
DebugLogger.shared.info("Prompt mode shortcut released (hold mode) - stopping", source: "GlobalHotkeyManager")
self.stopRecordingAfterRelease(for: .promptMode, label: "Prompt mode")
case .automatic:
self.isPromptModeKeyPressed = false
self.handleAutomaticKeyRelease(for: .promptMode, label: "Prompt mode")
case .toggle:
break
}
return true
}
private func handlePromptModeFlagsChanged(keyCode: UInt16, modifiers: NSEvent.ModifierFlags) -> Bool {
self.handleModifierOnlyShortcutFlagsChanged(
behavior: .init(
shortcut: self.promptModeShortcut,
isEnabled: self.promptModeShortcutEnabled,
holdModeType: .promptMode,
holdStartMessage: "Prompt mode modifier held (hold mode) - starting",
holdReleaseMessage: "Prompt mode modifier released (hold mode) - stopping",
toggleIgnoredMessage: "Prompt mode modifier released but another key was pressed - ignoring",
isModeKeyPressed: { self.isPromptModeKeyPressed },
setModeKeyPressed: { self.isPromptModeKeyPressed = $0 },
onHoldStart: { self.triggerPromptMode() },
onToggleRelease: {
if self.asrService.isRunningOrStarting {
if self.isPromptModeRecordingProvider?() ?? false {
DebugLogger.shared.info("Prompt mode modifier released (toggle, same mode) - stopping", source: "GlobalHotkeyManager")
self.triggerPromptMode()
} else {
DebugLogger.shared.info("Prompt mode modifier released (toggle, switch mode) - switching", source: "GlobalHotkeyManager")
self.triggerPromptMode()
}
} else {
DebugLogger.shared.info("Prompt mode modifier released (toggle) - starting", source: "GlobalHotkeyManager")
self.triggerPromptMode()
}
},
isTargetModeActive: { self.isPromptModeRecordingProvider?() ?? false }
),
keyCode: keyCode,
modifiers: modifiers
)
}
private func handlePromptAssignmentFlagsChanged(keyCode: UInt16, modifiers: NSEvent.ModifierFlags) -> Bool {
for assignment in self.promptShortcutAssignments where assignment.shortcut.isModifierOnlyShortcut {
let handled = self.handleModifierOnlyShortcutFlagsChanged(
behavior: .init(
shortcut: assignment.shortcut,
isEnabled: true,
holdModeType: .promptAssignment,
holdStartMessage: "Prompt shortcut modifier held (hold mode) - starting",
holdReleaseMessage: "Prompt shortcut modifier released (hold mode) - stopping",
toggleIgnoredMessage: "Prompt shortcut modifier released but another key was pressed - ignoring",
isModeKeyPressed: { self.isPromptAssignmentKeyPressed },
setModeKeyPressed: { self.isPromptAssignmentKeyPressed = $0 },
onHoldStart: { self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut) },
onToggleRelease: {
if self.asrService.isRunningOrStarting {
if self.isPromptModeRecordingProvider?() ?? false {
DebugLogger.shared.info("Prompt shortcut modifier released (toggle, same mode) - stopping", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
} else {
DebugLogger.shared.info("Prompt shortcut modifier released (toggle, switch mode) - switching", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
}
} else {
DebugLogger.shared.info("Prompt shortcut modifier released (toggle) - starting", source: "GlobalHotkeyManager")
self.triggerPromptSelection(assignment.selection, shortcut: assignment.shortcut)
}
},
isTargetModeActive: { self.isPromptModeRecordingProvider?() ?? false }
),
keyCode: keyCode,
modifiers: modifiers
)
if handled {
self.activePromptAssignmentPress = self.activeModifierOnlyType == .promptAssignment ? assignment : nil
return true
}
}
return false
}
private func handleModifierOnlyShortcutFlagsChanged(
behavior: ModifierOnlyShortcutBehavior,
keyCode: UInt16,
modifiers: NSEvent.ModifierFlags
) -> Bool {
// A held keyboard/mouse shortcut already owns this route.
guard behavior.holdModeType != .transcription || self.activePrimaryShortcutPress == nil else { return false }
guard !behavior.isModeKeyPressed() || self.activeModifierOnlyType == behavior.holdModeType else { return false }
let decision = ModifierOnlyShortcutFlagsDecision.evaluate(
shortcut: behavior.shortcut,
holdModeType: behavior.holdModeType,
isEnabled: behavior.isEnabled,
keyCode: keyCode,
modifiers: modifiers,
state: ModifierOnlyShortcutTrackingState(
pressedModifierKeyCodes: self.pressedModifierKeyCodes,
activeModifierOnlyType: self.activeModifierOnlyType,
activeModifierOnlyShortcut: self.activeModifierOnlyShortcut,
otherKeyPressedDuringModifier: self.otherKeyPressedDuringModifier,
isModeKeyPressed: behavior.isModeKeyPressed()
)
)
self.activeModifierOnlyType = decision.activeModifierOnlyType
self.activeModifierOnlyShortcut = decision.activeModifierOnlyShortcut
if decision.markInterrupted {
self.markModifierOnlyPressInterrupted(
message: "\(self.label(for: behavior.holdModeType)) modifier-only press interrupted - extra modifier pressed"
)
}
self.otherKeyPressedDuringModifier = decision.otherKeyPressedDuringModifier
switch decision.outcome {
case .ignore:
return false
case .start:
self.modifierPressReceivedAt = self.currentInputTiming?.receivedAt
self.modifierOnlyKeyDown = true
self.modifierPressStartTime = Date()
self.scheduleModifierOnlyStart(for: behavior)
return true
case let .finish(wasCleanPress):
let previousPress = self.currentStopPressReceivedAt
self.currentStopPressReceivedAt = self.modifierPressReceivedAt
self.modifierPressReceivedAt = nil
defer { self.currentStopPressReceivedAt = previousPress }
self.modifierOnlyKeyDown = false
self.modifierPressStartTime = nil
self.finishModifierOnlyPress(for: behavior, wasCleanPress: wasCleanPress)
return true
}
}
private func triggerPromptMode() {
self.queueRecordingAction(for: .promptMode, shortcut: self.promptModeShortcut) { [weak self] in
guard let self = self else { return }
guard self.canTriggerRecordingAction("Prompt mode hotkey") else { return }
DebugLogger.shared.info("Prompt mode hotkey triggered", source: "GlobalHotkeyManager")
await self.promptModeCallback?()
}
}
private func triggerPromptSelection(_ selection: SettingsStore.DictationPromptSelection, shortcut: HotkeyShortcut) {
self.queueRecordingAction(for: .promptAssignment, shortcut: shortcut, selection: selection) { [weak self] in
guard let self = self else { return }
guard self.canTriggerRecordingAction("Prompt selection hotkey") else { return }
DebugLogger.shared.info("Prompt selection hotkey triggered", source: "GlobalHotkeyManager")
await self.promptSelectionCallback?(selection)
}
}
private func triggerCommandMode() {
self.queueRecordingAction(for: .commandMode, shortcut: self.commandModeShortcut) { [weak self] in
guard let self = self else { return }
guard self.canTriggerRecordingAction("Command mode hotkey") else { return }
DebugLogger.shared.info("Command mode hotkey triggered", source: "GlobalHotkeyManager")
DebugLogger.shared.debug(
"GlobalHotkeyManager: command callback path, isRunning=\(self.asrService.isRunning), isReady=\(self.asrService.isAsrReady)",
source: "GlobalHotkeyManager"
)
await self.commandModeCallback?()
}
}
private func triggerRewriteMode() {
self.queueRecordingAction(for: .rewriteMode, shortcut: self.rewriteModeShortcut) { [weak self] in
guard let self = self else { return }
guard self.canTriggerRecordingAction("Rewrite mode hotkey") else { return }
DebugLogger.shared.info("Rewrite mode hotkey triggered", source: "GlobalHotkeyManager")
DebugLogger.shared.debug(
"GlobalHotkeyManager: rewrite callback path, isRunning=\(self.asrService.isRunning), isReady=\(self.asrService.isAsrReady)",
source: "GlobalHotkeyManager"
)
await self.rewriteModeCallback?()
}
}
/// Handles a mouse-button down event against the configured mouse shortcuts. Returns true when
/// the event was consumed. "Paste Last Transcription" is a one-shot trigger (mirrors the keyboard
/// path); primary dictation begins a press here and ends it on mouse-up.
private func handleMouseShortcutDown(_ event: CGEvent, modifiers eventModifiers: NSEvent.ModifierFlags) -> Bool {
let mouseButton = self.mouseButton(from: event)
if self.hotkeyMode == .toggle, self.activePrimaryShortcutPress?.mouseButton == mouseButton {
self.activePrimaryShortcutPress = nil
}
if SettingsStore.shared.pasteLastTranscriptionShortcutEnabled,
let pasteShortcut = SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut,
pasteShortcut.matchesMouse(button: mouseButton, modifiers: eventModifiers)
{
self.state.withLock { self.state.consumedPasteMouseButton = mouseButton }
self.triggerPasteLastTranscription(isAutorepeat: false)
return true
}
if let shortcut = self.primaryShortcuts.first(where: { $0.matchesMouse(button: mouseButton, modifiers: eventModifiers) }) {
guard self.beginPrimaryShortcutPress(.mouse(shortcut)) else { return false }
self.handlePrimaryDictationTriggerDown()
return true
}
return false
}
/// Swallows only the mouse-up that pairs with a mouse-down this tap consumed.
private func handleMouseShortcutUp(_ event: CGEvent) -> Bool {
let mouseButton = self.mouseButton(from: event)
let consumedPasteDown = self.state.withLock { () -> Bool in
guard self.state.consumedPasteMouseButton == mouseButton else { return false }
self.state.consumedPasteMouseButton = nil
return true
}
if consumedPasteDown {
return true
}
guard let shortcut = self.finishPrimaryShortcutPress(matching: { $0.mouseButton == mouseButton }) else { return false }
self.handlePrimaryDictationTriggerUp(shortcut: shortcut)
return true
}
func triggerPasteLastTranscription(isAutorepeat: Bool) {
Task { @MainActor [weak self] in
guard let self = self else { return }
// Holding the chord auto-repeats the key-down; act only on the initial press.
guard !isAutorepeat else { return }
guard self.canTriggerRecordingAction("Paste last transcription hotkey") else { return }
// Re-pasting mid-recording would be surprising; ignore while capture is active.
guard !self.asrService.isRunning else {
DebugLogger.shared.info(
"Paste last transcription hotkey ignored - recording in progress",
source: "GlobalHotkeyManager"
)
return
}
DebugLogger.shared.info("Paste last transcription hotkey triggered", source: "GlobalHotkeyManager")
self.pasteLastTranscriptionCallback?()
}
}
private func triggerDictationMode(shortcut: HotkeyShortcut? = nil) {
let shortcut = shortcut ?? self.activePrimaryShortcutPress?.shortcut ?? (self.activeModifierOnlyType == .transcription ? self.activeModifierOnlyShortcut : nil)
self.queueRecordingAction(for: .transcription, shortcut: shortcut) { [weak self] in
guard let self = self else { return }
guard self.canTriggerRecordingAction("Dictate mode hotkey") else { return }
let model = SettingsStore.shared.selectedSpeechModel
DebugLogger.shared.info("Dictate mode hotkey triggered", source: "GlobalHotkeyManager")
DebugLogger.shared.debug(
"GlobalHotkeyManager: dictate callback path, isRunning=\(self.asrService.isRunning), isReady=\(self.asrService.isAsrReady), model=\(model.displayName)",
source: "GlobalHotkeyManager"
)
if let callback = self.dictationModeCallback {
DebugLogger.shared.debug("GlobalHotkeyManager: invoking dictationModeCallback", source: "GlobalHotkeyManager")
await callback()
} else if let startCallback = self.startRecordingCallback {
DebugLogger.shared.debug(
"GlobalHotkeyManager: dictationModeCallback missing; invoking fallback callback",
source: "GlobalHotkeyManager"
)
await startCallback()
} else {
DebugLogger.shared.warning(
"GlobalHotkeyManager: dictation callbacks missing; invoking ASRService.start directly",
source: "GlobalHotkeyManager"
)
await self.asrService.start()
}
}
}
func setHotkeyMode(_ mode: HotkeyActivationMode) {
guard mode != self.hotkeyMode else { return }
for type in [HotkeyHoldModeType.transcription, .promptMode, .commandMode, .rewriteMode, .promptAssignment] {
self.discardShortcutPress(for: type)
}
self.hotkeyMode = mode
DebugLogger.shared.info("Hotkey activation mode set to \(mode.displayName)", source: "GlobalHotkeyManager")
self.scheduleActiveShortcutLog(reason: "shortcuts updated")
}
func enablePressAndHoldMode(_ enable: Bool) {
self.setHotkeyMode(enable ? .hold : .toggle)
}
private func canTriggerRecordingAction(_ label: String) -> Bool {
guard !self.isSessionLockedProvider() else {
DebugLogger.shared.info("Ignoring \(label) - screen is locked", source: "GlobalHotkeyManager")
return false
}
guard !self.isProcessingStop else {
DebugLogger.shared.debug("CLOSE_DETAIL shortcutRejected stopLocked=true uptime=\(ProcessInfo.processInfo.systemUptime)", source: "StopTiming")
return false
}
guard !self.asrService.isDictionaryTrainingCaptureActive else {
DebugLogger.shared.debug("Ignoring \(label) - dictionary training capture is active", source: "GlobalHotkeyManager")
return false
}
return true
}
func toggleRecording() {
let toggleStopRequestedAt = ProcessInfo.processInfo.systemUptime
if self.asrService.isRunningOrStarting {
self.logStopInput(requestedAt: toggleStopRequestedAt, route: "toggle")
}
Task { @MainActor [weak self] in
guard let self = self else { return }
// Prevent new operations while stop is processing
guard self.canTriggerRecordingAction("toggle") else { return }
if self.asrService.isRunningOrStarting {
await self.stopRecordingInternal(toggleStopRequestedAt: toggleStopRequestedAt)
} else {
// Use callback if available, otherwise fallback to direct start
if let callback = self.startRecordingCallback {
await callback()
} else {
await self.asrService.start()
}
}
}
}
private func startRecordingIfNeeded(shortcut: HotkeyShortcut? = nil) {
let shortcut = shortcut ?? self.activePrimaryShortcutPress?.shortcut ?? (self.activeModifierOnlyType == .transcription ? self.activeModifierOnlyShortcut : nil)
self.queueRecordingAction(for: .transcription, shortcut: shortcut) { [weak self] in
guard let self = self else { return }
// Prevent starting while stop is processing
guard self.canTriggerRecordingAction("start") else { return }
if !self.asrService.isRunning {
// Use callback if available, otherwise fallback to direct start
if let callback = self.startRecordingCallback {
await callback()
} else {
await self.asrService.start()
}
}
}
}
private func logStopInput(requestedAt: TimeInterval, route: String) {
guard DebugLogger.diagnosticsEnabled else { return }
var fields = "stop_request stopRequestedAt=\(requestedAt) route=\(route)"
if let input = self.currentInputTiming {
fields += " inputReceivedAt=\(input.receivedAt) eventType=\(input.eventType)"
if let age = input.deliveryAgeMs {
fields += " inputAgeMs=\(age)"
}
if let press = self.currentStopPressReceivedAt, press <= input.receivedAt {
fields += " pressReceivedAt=\(press)"
}
}
DebugLogger.shared.benchmark("HOTKEY_BENCH", message: fields, source: "HotkeyBenchmark")
}
private func stopRecordingIfNeeded(toggleStopRequestedAt: TimeInterval? = nil) {
let toggleStopRequestedAt = toggleStopRequestedAt ?? ProcessInfo.processInfo.systemUptime
self.logStopInput(requestedAt: toggleStopRequestedAt, route: "stop_if_needed")
Task { @MainActor [weak self] in
guard let self = self else { return }
if self.isProcessingStop {
DebugLogger.shared.debug("Ignoring stop - already processing", source: "GlobalHotkeyManager")
return
}
guard !self.asrService.isDictionaryTrainingCaptureActive else {
DebugLogger.shared.debug("Ignoring stop - dictionary training capture is active", source: "GlobalHotkeyManager")
return
}
guard self.asrService.isRunningOrStarting else {
return
}
await self.stopRecordingInternal(toggleStopRequestedAt: toggleStopRequestedAt)
}
}
@MainActor
private func stopRecordingInternal(toggleStopRequestedAt: TimeInterval? = nil) async {
if self.asrService.isStarting, self.asrService.isRunning == false {
DebugLogger.shared.debug("Cancelling pending audio capture start", source: "GlobalHotkeyManager")
await self.asrService.cancelPendingAudioCaptureStart(reason: "hotkey_released")
}
guard self.asrService.isRunning else { return }
guard !self.asrService.isDictionaryTrainingCaptureActive else {
DebugLogger.shared.debug("Stop ignored - dictionary training capture is active", source: "GlobalHotkeyManager")
return
}
guard !self.isProcessingStop else {
DebugLogger.shared.debug("Stop already in progress, ignoring", source: "GlobalHotkeyManager")
return
}
let closeStartedAt = self.traceStopLocked()
defer { self.traceStopUnlocked(since: closeStartedAt) }
if let callback = stopAndProcessCallback {
await callback(toggleStopRequestedAt)
} else {
await self.asrService.stopWithoutTranscription()
}
}
func isEventTapEnabled() -> Bool {
guard let tap = eventTap else { return false }
return CGEvent.tapIsEnabled(tap: tap)
}
func validateEventTapHealth() -> Bool {
// Treat an enabled event tap as "healthy", even if our internal `isInitialized` flag drifted.
// This prevents false "initializing" UI while hotkeys are already working.
let enabled = self.isEventTapEnabled()
if enabled && !self.isInitialized {
self.isInitialized = true
}
return enabled
}
func reinitialize() {
DebugLogger.shared.info("Manual reinitialization requested", source: "GlobalHotkeyManager")
self.initializationTask?.cancel()
self.healthCheckTask?.cancel()
self.resetModifierOnlyShortcutTracking(reason: .reinitialize)
self.isInitialized = false
self.initializeWithDelay()
}
private func startHealthCheckTimer() {
self.healthCheckTask?.cancel()
self.healthCheckTask = Task { [weak self] in
while !Task.isCancelled {
guard let healthCheckInterval = self?.healthCheckInterval else { break }
do {
try await Task.sleep(nanoseconds: UInt64(healthCheckInterval * 1_000_000_000))
} catch {
break
}
guard !Task.isCancelled else { break }
await MainActor.run { [weak self] in
guard let self else { return }
if !self.validateEventTapHealth() {
DebugLogger.shared.warning("Health check failed, attempting to recover", source: "GlobalHotkeyManager")
if self.setupGlobalHotkey() {
self.isInitialized = true
DebugLogger.shared.info("Health check recovery successful", source: "GlobalHotkeyManager")
} else {
DebugLogger.shared.error("Health check recovery failed", source: "GlobalHotkeyManager")
self.isInitialized = false
}
} else {
self.recoverMouseTapsIfNeeded()
}
}
}
}
}
deinit {
initializationTask?.cancel()
healthCheckTask?.cancel()
muteReleaseRecoveryTask?.cancel()
NotificationCenter.default.removeObserver(self)
cleanupEventTap()
}
}
private extension GlobalHotkeyManager {
func invalidateRecordingActions(for type: HotkeyHoldModeType) {
self.recordingActionRevisions[type, default: 0] &+= 1
self.pendingRecordingActionCounts[type] = 0
self.activeRecordingActionShortcuts.removeValue(forKey: type)
self.pendingRecordingActions.removeValue(forKey: type)?.cancel()
}
func invalidateAllRecordingActions() {
for type in [HotkeyHoldModeType.transcription, .promptMode, .commandMode, .rewriteMode, .promptAssignment] {
self.invalidateRecordingActions(for: type)
}
}
/// Keep rapid taps in order through the actual asynchronous capture start/stop.
func queueRecordingAction(for type: HotkeyHoldModeType, shortcut: HotkeyShortcut?, selection: SettingsStore.DictationPromptSelection? = nil, action: @escaping @MainActor () async -> Void) {
guard self.canTriggerRecordingAction(self.label(for: type)) else { return }
let revision = self.recordingActionRevisions[type, default: 0]
let previous = self.pendingRecordingActions[type]
self.pendingRecordingActionCounts[type, default: 0] += 1
self.pendingRecordingActions[type] = Task { @MainActor [weak self] in
await withTaskCancellationHandler {
await previous?.value
} onCancel: {
previous?.cancel()
}
guard !Task.isCancelled else { return }
guard let self, self.recordingActionRevisions[type, default: 0] == revision else { return }
defer {
if self.recordingActionRevisions[type, default: 0] == revision {
self.pendingRecordingActionCounts[type, default: 0] -= 1
if self.pendingRecordingActionCounts[type] == 0 {
self.pendingRecordingActions.removeValue(forKey: type)
}
}
}
guard self.canTriggerRecordingAction(self.label(for: type)) else { return }
if let shortcut, !self.isRecordingShortcutConfigured(shortcut, for: type, selection: selection) { return }
self.activeRecordingActionShortcuts[type] = shortcut
defer {
if self.recordingActionRevisions[type, default: 0] == revision {
self.activeRecordingActionShortcuts.removeValue(forKey: type)
}
}
if self.hotkeyMode == .toggle, self.asrService.isRunningOrStarting, self.isRecordingTargetActive(for: type) {
// Changing an input binding must not cancel transcription already processing.
await Task { @MainActor in
await self.stopRecordingInternal(toggleStopRequestedAt: ProcessInfo.processInfo.systemUptime)
}.value
return
}
await action()
}
}
private func isRecordingShortcutConfigured(_ shortcut: HotkeyShortcut, for type: HotkeyHoldModeType, selection: SettingsStore.DictationPromptSelection?) -> Bool {
switch type {
case .transcription: self.primaryShortcuts.contains(shortcut)
case .promptMode: self.promptModeShortcutEnabled && self.promptModeShortcut == shortcut
case .commandMode: self.commandModeShortcutEnabled && self.commandModeShortcut == shortcut
case .rewriteMode: self.rewriteModeShortcutEnabled && self.rewriteModeShortcut == shortcut
case .promptAssignment: self.promptShortcutAssignments.contains { $0.shortcut == shortcut && $0.selection == selection }
}
}
private func isRecordingTargetActive(for type: HotkeyHoldModeType) -> Bool {
switch type {
case .transcription:
guard let provider = self.isDictateRecordingProvider else { return true }
return provider()
case .promptMode:
guard let provider = self.isPromptModeRecordingProvider else { return true }
return provider()
case .commandMode:
guard let provider = self.isCommandRecordingProvider else { return true }
return provider()
case .rewriteMode:
guard let provider = self.isRewriteRecordingProvider else { return true }
return provider()
case .promptAssignment:
guard let provider = self.isPromptModeRecordingProvider else { return true }
return provider()
}
}
func discardShortcutPress(for type: HotkeyHoldModeType) {
self.invalidateRecordingActions(for: type)
if type == .promptAssignment { self.activePromptAssignmentPress = nil }
let hadPress = self.state.withLock {
let ownsModifier = self.state.activeModifierOnlyType == type
var pressed: Bool
switch type {
case .transcription:
pressed = self.state.isKeyPressed || self.state.activePrimaryShortcutPress != nil
self.state.isKeyPressed = false
self.state.activePrimaryShortcutPress = nil
case .promptMode:
pressed = self.state.isPromptModeKeyPressed
self.state.isPromptModeKeyPressed = false
case .commandMode:
pressed = self.state.isCommandModeKeyPressed
self.state.isCommandModeKeyPressed = false
case .rewriteMode:
pressed = self.state.isRewriteKeyPressed
self.state.isRewriteKeyPressed = false
case .promptAssignment:
pressed = self.state.isPromptAssignmentKeyPressed
self.state.isPromptAssignmentKeyPressed = false
}
if ownsModifier {
self.state.activeModifierOnlyType = nil
self.state.activeModifierOnlyShortcut = nil
self.state.modifierOnlyKeyDown = false
self.state.otherKeyPressedDuringModifier = false
self.state.modifierPressStartTime = nil
}
return pressed || ownsModifier
}
guard hadPress else { return }
self.cancelPendingReleaseStop(for: type)
self.clearHoldModeStartTriggered(for: type)
_ = self.finishAutomaticPress(for: type)
if self.hotkeyMode != .toggle, self.asrService.isRunningOrStarting, self.isRecordingTargetActive(for: type) {
self.stopRecordingAfterRelease(for: type, label: self.label(for: type))
}
}
private func beginPrimaryShortcutPress(_ press: ActivePrimaryShortcutPress) -> Bool {
self.state.withLock {
guard self.state.activePrimaryShortcutPress == nil, !self.state.isKeyPressed else {
return false
}
self.state.activePrimaryShortcutPress = press
return true
}
}
private func finishPrimaryShortcutPress(matching matches: (ActivePrimaryShortcutPress) -> Bool) -> HotkeyShortcut? {
self.state.withLock {
guard let press = self.state.activePrimaryShortcutPress, matches(press) else {
return nil
}
self.state.activePrimaryShortcutPress = nil
return press.shortcut
}
}
}
extension GlobalHotkeyManager {
func traceStopLocked() -> TimeInterval {
OverlayCloseRunLoopProbe.begin()
self.isProcessingStop = true
return ProcessInfo.processInfo.systemUptime
}
func traceStopUnlocked(since startedAt: TimeInterval) {
self.isProcessingStop = false
DebugLogger.shared.debug(
"CLOSE_DETAIL shortcutUnlocked uptime=\(ProcessInfo.processInfo.systemUptime) heldMs=\((ProcessInfo.processInfo.systemUptime - startedAt) * 1000)",
source: "StopTiming"
)
}
nonisolated static func isSynthesizedTypingEvent(_ event: CGEvent) -> Bool {
event.getIntegerValueField(.eventSourceUserData) == TypingService.synthesizedEventUserData
}
nonisolated static func keyboardEventMask() -> CGEventMask {
(CGEventMask(1) << CGEventType.keyDown.rawValue)
| (CGEventMask(1) << CGEventType.keyUp.rawValue)
| (CGEventMask(1) << CGEventType.flagsChanged.rawValue)
}
/// Capture before system shortcuts (such as Control-Command-D lookup) can consume the key.
/// The local monitor remains a fallback for app-directed events that bypass the session tap.
static func captureKeyboardEvent(
type: CGEventType,
event: CGEvent,
isAppActive: Bool,
handler: ((NSEvent) -> NSEvent?)?
) -> Bool {
guard isAppActive, type == .keyDown || type == .flagsChanged,
let handler, let appEvent = NSEvent(cgEvent: event)
else { return false }
return handler(appEvent) == nil
}
}
extension GlobalHotkeyManager {
private func handleTapDisableEvent(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
// macOS can temporarily disable event taps (e.g. timeouts, user input protection).
// If we don't immediately re-enable here, hotkeys will silently stop working until our
// periodic health check kicks in, and the OS may handle the key (e.g. system dictation).
guard type == .tapDisabledByTimeout || type == .tapDisabledByUserInput else {
return nil
}
self.holdToMuteSpaceTap.cancel()
let reason = (type == .tapDisabledByTimeout) ? "timeout" : "user input"
DebugLogger.shared.warning("Event tap disabled by \(reason) — attempting immediate re-enable", source: "GlobalHotkeyManager")
self.resetModifierOnlyShortcutTracking(reason: .tapDisabled)
if self.holdToMuteChecksPhysicalKeyState {
self.reconcileHoldToMute(isPhysicallyDown: CGEventSource.keyState(.hidSystemState, key: 49))
}
if let tap = self.eventTap {
CGEvent.tapEnable(tap: tap, enable: true)
}
if !self.isEventTapEnabled() {
DebugLogger.shared.warning("Event tap re-enable failed — recreating tap", source: "GlobalHotkeyManager")
self.setupGlobalHotkeyWithRetry()
}
return Unmanaged.passUnretained(event)
}
@objc private func holdSpaceSettingChanged() {
if !SettingsStore.shared.holdSpaceToMute {
self.holdToMuteSpaceTap.cancel()
self.muteRecordingGeneration = nil
self.asrService.setDictationMuted(false)
}
}
private func hasConfiguredShortcut(keyCode: UInt16, modifiers: NSEvent.ModifierFlags) -> Bool {
var shortcuts = self.primaryShortcuts + self.promptShortcutAssignments.map(\.shortcut)
if self.promptModeShortcutEnabled {
shortcuts.append(self.promptModeShortcut)
}
if self.rewriteModeShortcutEnabled {
shortcuts.append(self.rewriteModeShortcut)
}
if self.commandModeShortcutEnabled, let shortcut = self.commandModeShortcut {
shortcuts.append(shortcut)
}
if SettingsStore.shared.fluidMeetEnabled, let shortcut = SettingsStore.shared.meetingRecordingHotkeyShortcut {
shortcuts.append(shortcut)
}
if let shortcut = SettingsStore.shared.cancelRecordingHotkeyShortcut {
shortcuts.append(shortcut)
}
if SettingsStore.shared.pasteLastTranscriptionShortcutEnabled,
let shortcut = SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut
{
shortcuts.append(shortcut)
}
return shortcuts.contains { $0.matches(keyCode: keyCode, modifiers: modifiers) }
}
private var canTypeMuteTap: Bool {
self.muteRecordingGeneration == self.asrService.dictationMuteGeneration &&
SettingsStore.shared.holdSpaceToMute && self.asrService.isRunningOrStarting &&
!self.asrService.isDictionaryTrainingCaptureActive &&
(self.isDictateRecordingProvider?() ?? false) &&
!(self.isShortcutCaptureActiveProvider?() ?? false)
}
private func handleHoldToMute(type: CGEventType, event: CGEvent, proxy: CGEventTapProxy?) -> Bool {
let keyCode = UInt16(event.getIntegerValueField(.keyboardEventKeycode))
let modifiers = Self.modifierFlags(from: event.flags)
guard keyCode == 49, type == .keyDown || type == .keyUp else {
if self.holdToMuteKeyState.ownsSpace, type != .keyUp {
// Fast typing can overlap Space and the next letter. Flush before the
// letter, but never before navigation, shortcuts, or modifier changes.
let typing = type == .keyDown && HoldToMuteSpaceTap.isPlainTextKey(event) &&
!self.hasConfiguredShortcut(keyCode: keyCode, modifiers: modifiers)
self.holdToMuteSpaceTap.finish(at: event.timestamp, proxy: proxy, allowed: typing && self.canTypeMuteTap)
}
return false
}
let wasOwned = self.holdToMuteKeyState.ownsSpace
let consumed: Bool
var beginTap = false
var finishTap = false
switch type {
case .keyDown:
let isRepeat = event.getIntegerValueField(.keyboardEventAutorepeat) != 0
let canBegin = SettingsStore.shared.holdSpaceToMute && self.asrService.isRunningOrStarting &&
!self.asrService.isDictionaryTrainingCaptureActive &&
(self.isDictateRecordingProvider?() ?? false) &&
!(self.isShortcutCaptureActiveProvider?() ?? false) &&
modifiers.isDisjoint(with: HotkeyShortcut.relevantModifierMask) &&
!self.hasConfiguredShortcut(keyCode: 49, modifiers: [])
consumed = self.holdToMuteKeyState.keyDown(isRepeat: isRepeat, canBegin: canBegin)
self.holdToMuteSpaceTap.cancel()
if consumed, !isRepeat {
self.muteRecordingGeneration = self.asrService.dictationMuteGeneration
self.startMuteReleaseRecovery()
beginTap = true
}
case .keyUp:
consumed = self.holdToMuteKeyState.keyUp()
finishTap = consumed && self.canTypeMuteTap && modifiers.isDisjoint(with: HotkeyShortcut.relevantModifierMask)
self.muteRecordingGeneration = nil
self.muteReleaseRecoveryTask?.cancel()
self.muteReleaseRecoveryTask = nil
default:
return false
}
if consumed || wasOwned {
let muted = self.holdToMuteKeyState.ownsSpace &&
self.muteRecordingGeneration == self.asrService.dictationMuteGeneration &&
SettingsStore.shared.holdSpaceToMute
self.asrService.setDictationMuted(muted)
}
// Muting and unmuting always precede any destination/event bookkeeping.
if beginTap {
self.holdToMuteSpaceTap.begin(event)
} else if type == .keyUp {
self.holdToMuteSpaceTap.finish(at: event.timestamp, proxy: proxy, allowed: finishTap)
}
return consumed
}
/// Recover a missed key-up without unmuting while Space is physically held.
func reconcileHoldToMute(isPhysicallyDown: Bool) {
guard self.holdToMuteKeyState.ownsSpace else { return }
self.holdToMuteKeyState.reconcile(isPhysicallyDown: isPhysicallyDown)
if !self.holdToMuteKeyState.ownsSpace {
self.holdToMuteSpaceTap.cancel()
self.muteRecordingGeneration = nil
self.asrService.setDictationMuted(false)
}
}
private func startMuteReleaseRecovery() {
self.muteReleaseRecoveryTask?.cancel()
guard self.holdToMuteChecksPhysicalKeyState else { return }
self.muteReleaseRecoveryTask = Task { [weak self] in
// Give a normal short tap its key-up before recovering a lost release.
do { try await Task.sleep(nanoseconds: HoldToMuteSpaceTap.maximumDuration) } catch { return }
while !Task.isCancelled {
do { try await Task.sleep(nanoseconds: 100_000_000) } catch { return }
guard let self, self.holdToMuteKeyState.ownsSpace else { return }
self.reconcileHoldToMute(isPhysicallyDown: CGEventSource.keyState(.hidSystemState, key: 49))
}
}
}
}
extension GlobalHotkeyManager {
func setCancelCallback(_ callback: @escaping () -> CancelHandlingResult) {
self.cancelCallback = callback
}
func setPasteLastTranscriptionCallback(_ callback: @escaping () -> Void) {
self.pasteLastTranscriptionCallback = callback
}
func setMeetingRecordingCallback(_ callback: @escaping () -> Void) {
self.meetingRecordingCallback = callback
}
private func handleMeetingRecordingShortcut(type: CGEventType, keyCode: UInt16, modifiers: NSEvent.ModifierFlags, isAutorepeat: Bool) -> Bool {
if type == .keyUp, self.meetingShortcutPressedKey == keyCode {
self.meetingShortcutPressedKey = nil
return true
}
guard type == .keyDown, SettingsStore.shared.fluidMeetEnabled,
let shortcut = SettingsStore.shared.meetingRecordingHotkeyShortcut,
shortcut.matches(keyCode: keyCode, modifiers: modifiers),
!self.isSessionLockedProvider() else { return false }
self.markOtherInputDuringModifierOnly()
if !isAutorepeat {
self.meetingShortcutPressedKey = keyCode
self.meetingRecordingCallback?()
}
return true
}
}