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¶
- Hotkey event activates dictation.
- If the profile and an enabled LLM stage request selected text, the app captures it once from the frontmost application.
- Overlay appears with profile styling and hints.
- App checks microphone permission and input availability, then begins capture immediately.
- 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. - Stop event triggers final transcription.
- The Processing Run advances according to dependencies:
- Word replacement completes before dependent LLM stages begin.
- Independent LLM branches run concurrently; only the selected final-output chain gates the primary transcript.
- Auto Tag and Trigger Routing match detection run on the selected final output.
- Once the primary transcript and route matches are known:
- Auto paste and temporary history can complete without waiting for background actions.
Skip auto paste when trigger routing firesuses the presence of a match, not the eventual action result.- Matched Trigger Routing actions execute in configured order inside their own background block.
- 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 HoldorToggle) - 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¶
- While the overlay is listening, press
Left Arrowto recall the newest temporary-history result. - Continue pressing
Left Arrowto move farther back, or pressRight Arrowto move forward. - The overlay displays the selected text with a status such as
Recalling · 1 back. The active profile styling remains in place. - Left and Right Arrow only change the selection. Releasing either arrow does not paste.
- Complete the session normally to paste the displayed result: release the activation key in
Push and Holdmode, or press the activation key again inTogglemode.
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.
Recommended Defaults¶
| 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.
Escreliably 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.
Escapecancels 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¶
- Profiles
- Dictate into Documents
- Run Tools with Voice Commands
- Dictate Prompts for AI Tools
- Menu and Window Map
- In-App Help Cues (? Buttons and Hover Tooltips)
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
Esccancel behavior. - TODO: add GIF of Left/Right Arrow history recall and return to live listening.