macOS app

The macOS runtime has two parts:

Python owns capture, transcription, grammar cleanup, replacements, clipboard and paste output, history, sockets, LaunchAgent lifecycle, and CLI commands.
Swift owns the visible menu bar app, overlay, settings, onboarding, and IPC rendering.

Hotkeys

Shortcut	Action
Double-tap Right Option	Start recording and copy the result by default
Hold Right Option	Record until release and paste the result at the cursor
Tap Right Option or Space	Stop a double-tap recording and transcribe
Esc	Cancel recording or stop speech
Option+T	Read selected text aloud
Ctrl+Shift+G	Proofread selected text
Ctrl+Shift+R	Rewrite selected text
Ctrl+Shift+P	Optimize selected text as an LLM prompt

Double-tap dictation follows ui.auto_paste: clipboard by default, cursor paste when enabled. Hold-to-record always pastes the result at the cursor. Text-transform shortcuts require grammar correction to be enabled with a working backend. The menu bar icon opens a status panel:

Area	Purpose
Status	Connection pill and a live hero — waveform and timer while recording, transcription progress, latched errors, and a Start button when the service is down
Quick toggles	Paste at cursor, replacements, read aloud, and sounds
Engine / Grammar	Switch the transcription engine and grammar backend in place
Recent	Latest transcriptions — click to copy, hover to reveal the audio in Finder
Footer	Settings, retry last transcription, a More menu, and quit

The More menu carries copy-last, the transcripts, audio, and log folders, update check, service restart, and the tutorial replay. Esc closes the panel; controls that need the service disable themselves while it is unreachable instead of failing silently.

Settings panels

Panel	Covers
Recording	Trigger key, double-tap window, audio cleanup, and duration limits
Transcription	Engine cards with verified model cache state, inline download progress, cancel, and per-engine sampling or decoding parameters
Grammar	Backend chooser and per-backend connection and limits
Vocabulary	Searchable replacement editor with import and export
Voice	Text-to-speech voice and shortcut, plus the dictation commands editor and tester
Shortcuts	Proofread, rewrite, prompt-engineer bindings, and cheatsheet
Output	Overlay, sounds, notifications, paste-at-cursor, and history limit
Activity	Sessions, words, 30-day chart, top words, and top replacement triggers
Advanced	Live service status, permission request buttons, storage paths, model idle unload, service log, and doctor
About	Version, credits, and replay tutorial

Settings save to ~/.whisper/config.toml and apply immediately — the trigger key, transform shortcuts, and the TTS shortcut all rebind live. Engine and grammar backend switches happen in place with rollback.

Overlay states

The floating overlay shows recording duration, waveform, processing progress, copied or pasted result, errors, and speaking state. Python publishes state snapshots over IPC. Swift drops stalled IPC consumers instead of blocking the transcription pipeline.

Start

Product

Reference

Hotkeys

Menu bar

Settings panels

Overlay states

​Hotkeys

​Menu bar

​Settings panels

​Overlay states

Hotkeys

Menu bar

Settings panels

Overlay states