Skip to content

Hotkeys and Dictation Flow

What This Feature Does

Hotkeys are the primary control surface for starting and stopping dictation. They connect keyboard events to profile-aware dictation sessions, then run the output pipeline (ASR -> transforms -> actions -> paste/save).

The Essential Mental Model

Hotkey → mapped Profile → Capture → Processing → Delivery

A hotkey does two jobs: it defines how dictation starts and stops, and it selects the profile for that session. The mapped profile then controls replacements, LLM processing, tags, routing, paste behavior, history, saved outputs, and Notes.

Selecting a profile in the profile editor does not remap existing hotkeys. Check the Profile value in Manage Hotkeys... whenever the active behavior is not what you expected.

Design Rationale

OpenScreech supports both Push and Hold and Toggle because users have different motor patterns and contexts:

  • Hold mode gives deliberate, bounded capture windows.
  • Toggle mode reduces key strain during longer utterances.

Both models map to the same downstream processing pipeline, so users can choose ergonomics without changing transcript quality behavior.

Two hotkeys can deliberately select different profiles. For example, a push-and-hold hotkey could use Quick Paste, while a toggle hotkey uses Structured Notes.

Activation Modes

Mode How It Works Best For Tradeoff
Push and Hold Dictation starts on key-down, ends on key-up Short commands, quick edits Requires continuous key hold
Toggle First press starts, next press stops Longer dictation bursts Easier to forget active state

Default seeded hotkeys include Right Command (hold) and Right Option (toggle).

End-to-End Session Lifecycle

  1. Hotkey event activates dictation.
  2. If the profile and an enabled LLM stage request selected text, the app captures it once from the frontmost application.
  3. Overlay appears with profile styling and hints.
  4. App checks microphone permission and input availability, then begins capture immediately.
  5. If the dictation speech model is still being prepared, the overlay shows Preparing speech model… while the captured 16 kHz audio continues accumulating. Live preview begins when the model is ready.
  6. Stop event triggers final transcription.
  7. The Processing Run advances according to dependencies:
  8. Word replacement completes before dependent LLM stages begin.
  9. Independent LLM branches run concurrently; only the selected final-output chain gates the primary transcript.
  10. Auto Tag and Trigger Routing match detection run on the selected final output.
  11. Once the primary transcript and route matches are known:
  12. Auto paste and temporary history can complete without waiting for background actions.
  13. Skip auto paste when trigger routing fires uses the presence of a match, not the eventual action result.
  14. Matched Trigger Routing actions execute in configured order inside their own background block.
  15. Saved Outputs, Notes, and Screechback continue as independent branches and do not delay primary delivery.

Raw audio, original text, and word-replaced text can begin saving before LLM processing finishes. A selected final LLM result and computed tags are added when they become available. A failure in one save does not cancel successful sibling saves.

Selected-text capture runs only at hotkey activation. OpenScreech first reads the focused control through macOS Accessibility. If needed, it presses the application's enabled Copy menu item through Accessibility without simulating keyboard input, briefly using the clipboard and restoring it when doing so will not overwrite a concurrent change. There is no ongoing selection or clipboard monitoring. If no usable selection is available, LLM prompts receive an empty {{SELECTED_TEXT}} value.

During Active Dictation

Behavior Notes
Preparing speech model… Microphone capture is active, but the local dictation model is not ready to produce preview text yet
Esc key Cancels active dictation and clears capture buffers
Left Arrow Enters recall and moves backward through paste-ready temporary history
Right Arrow Moves forward through recalled items; after the newest item, returns to fresh live listening
Profile quick-switch keys Can switch processing/styling profile mid-session
Overlay drag Position persistence is profile-configurable
Audio meter Uses profile-level smoothing and optional peak marker

Managing Hotkeys

In Manage Hotkeys..., you can:

  • Add hotkeys
  • Delete hotkeys
  • Assign/change activation key
  • Set activation type (Push and Hold or Toggle)
  • Enable/disable hotkeys
  • Map hotkeys to profiles
  • Import/export hotkeys as JSON

Plain-English tip:

  • Keep one very reliable default hotkey plus one fallback mode.

Temporary History

Property Value
Capacity Up to 10 items
Scope In-memory menu history
Inclusion rule Controlled per profile (Add transcriptions to temporary history)
Menu retrieval Click a history item to copy its full text
Overlay recall During dictation, use Left/Right Arrow to browse paste-ready results

Recalling From the Dictation Overlay

  1. While the overlay is listening, press Left Arrow to recall the newest temporary-history result.
  2. Continue pressing Left Arrow to move farther back, or press Right Arrow to move forward.
  3. The overlay displays the selected text with a status such as Recalling · 1 back. The active profile styling remains in place.
  4. Left and Right Arrow only change the selection. Releasing either arrow does not paste.
  5. Complete the session normally to paste the displayed result: release the activation key in Push and Hold mode, or press the activation key again in Toggle mode.

Recalled results are already finalized and are pasted with their stored formatting without running ASR, word replacement, LLM processing, or trigger routing again. Entering recall discards the unfinished live capture. Pressing Right Arrow after the newest recalled item returns to Listening and begins a fresh capture. Esc cancels without pasting.

Setting Recommendation Why
Primary daily hotkey Push-and-hold Fewer accidental long captures
Secondary hotkey Toggle Useful fallback for longer dictation
Temporary history On for most profiles Quick recovery of recent snippets
Keep Microphone Open Enable only if startup lag is noticeable Reduces warm-start latency at the cost of idle capture session overhead

Common Failure Modes

Symptom Likely Cause What To Check
Hotkey does nothing Permission/blocking issue Accessibility/Input Monitoring and Preflight status
Starts but no transcript Mic routing/model issue Microphone selection, model download, captured speech duration
Meter moves while Preparing speech model… remains visible The microphone is capturing while the local model finishes loading Wait for Listening; if it never appears, reopen Preflight and confirm Parakeet v3 is installed
Unexpected paste target Focus changed before paste Active app focus timing
Route fired but no paste Auto-paste suppression on trigger routing Profile trigger routing setting
Processing or paste behavior is unexpected Hotkey is mapped to a different profile The hotkey's Profile value in Manage Hotkeys...

Validation Checklist

  • Start/stop behavior is consistent for both hold and toggle paths.
  • Esc reliably cancels without stale text insertion.
  • Profile quick-switch changes behavior during active dictation.
  • History entries appear only for profiles with history enabled.
  • Left/Right Arrow navigates history without pasting on arrow release.
  • Completing from recall pastes the displayed finalized result without reprocessing it.

In-App Help Cues For This Feature

In Manage Hotkeys..., look for:

  • ? buttons explaining activation key/type/profile mapping
  • hover text on controls for quick reminders

Quick Tips

  • A profile quick-switch made while listening changes the final processing and delivery. It does not restart capture-time work such as overlay placement or selected-text capture.
  • Escape cancels both live dictation and a history-recall session. Nothing is pasted, and the unfinished capture is discarded.
  • At app startup, OpenScreech prepares dictation ASR first, then warms the independent Meeting Recording and Transcribe Files ASR services.

See Also

Visual Notes

  • TODO: add screenshot of Manage Hotkeys... window.
  • TODO: add GIF of push-and-hold usage.
  • TODO: add GIF of toggle usage.
  • TODO: add GIF of Esc cancel behavior.
  • TODO: add GIF of Left/Right Arrow history recall and return to live listening.