Dictation
Dictation is the core TypeWhisper workflow: press your hotkey, talk, and have transcribed text land in whatever application you are using. This page covers the activation modes and the dictation settings exposed in the Linux UI.
You choose how the main global dictation hotkey behaves:
| Mode | Behavior |
|---|---|
| Toggle | Press to start recording, press again to stop. |
| Push to talk | Hold the key to record; release to stop. |
| Hybrid | Starts on press. A short tap keeps recording (toggle-style); holding past ~600 ms stops on release (push-to-talk-style). |
See Global hotkeys for assigning and registering the dictation hotkey.
Press Escape during recording, transcription, or post-processing to cancel the dictation in flight. This is only active while a dictation is running, so it does not shadow modal dialogs or editors when you are not dictating.
Turn on auto-paste to have transcribed text inserted automatically after transcription completes. How that text is delivered depends on your per-app strategy — see Text insertion.
While you dictate, TypeWhisper shows a live microphone preview and a recording overlay. When a streaming-capable transcription engine is active, live partial-transcript text appears in the overlay as you speak. LLM responses stream into the overlay and the prompt palette token by token.
You can configure which overlay widgets show (Indicator, Waveform, Text) on the Appearance page. Streaming behavior depends on the engine — see Transcription engines.
The Linux UI exposes these dictation settings:
| Setting | What it does |
|---|---|
| Whisper mode | Optimizes for quiet/whispered speech. |
| Silence auto-stop | Automatically stops recording after detected silence. |
| Sound feedback | Plays a cue when recording starts/stops. |
| Audio ducking | Lowers other audio while you record. |
| Media pause | Pauses media playback during recording. |
| Aggressive short-clip transcription | Transcribes short, quiet utterances that would otherwise be discarded as silence. |
| Normalize spoken numbers to digits | Converts spoken numbers into digits before insertion and export — "twenty three" → 23, "dreiundzwanzig" → 23, "veintitrés" → 23. On by default; English, German, and Spanish only. See [[Text cleanup |
| Auto-learn approved history corrections | Saves clear phrase-level corrections from your History edits into the Dictionary. Off by default — turn it on if you want history edits to build dictionary corrections. |
| Learn corrections from other apps | Silently learns a correction when you type over a dictated word in the app you dictated into. Off by default — see Learning corrections from other apps below. |
The Input device picker selects the microphone used for dictation. Alongside your specific devices it offers Automatic (follow system default), which uses whatever your desktop's current default input device is and migrates live when that default changes — plugging in a headset or switching devices in your sound settings moves dictation over without restarting TypeWhisper.
The migration is in-flight-safe: it never tears down an active capture stream, so a switch that happens mid-recording is deferred until the current recording finishes. Default-device changes are detected through a debounced pactl subscribe watcher; without pactl installed, Automatic still resolves the default at the start of each recording, it just can't migrate a stream already in flight.
A short-speech policy uses peak-level and duration thresholds so that accidental taps and silent clips are dropped before they reach the transcription engine. The aggressive short-clip transcription option works in the opposite direction, keeping short quiet utterances that would otherwise be discarded.
Turn on Learn corrections from other apps and TypeWhisper watches for the edits you make to fix a dictation. Dictate a word, then type over it in the target app to correct it, and the correction is learned silently and applied to every dictation that follows — no dialog, no approval step.
This is off by default, because it reads the text of the focused field in other applications. Turn it on only if you want that.
After a dictation is inserted, TypeWhisper anchors a baseline read of the focused text field and opens a bounded tracking window. When the edit commits — you move focus out of the app, or stop typing for a moment — it compares the baseline against the final text and saves high-confidence recognition fixes to the Dictionary.
The observation is event-driven over AT-SPI: TypeWhisper subscribes to focus and text-changed signals on one persistent connection. There is no polling, no keyboard hook, and no keylogging — it only ever reads the field it just dictated into, during a short window after that dictation.
| Guard | Behavior |
|---|---|
| Password fields | Excluded, and fails closed — if the field's AT-SPI role is PASSWORD_TEXT or can't be determined, nothing is learned. |
| Similarity gate | Rejects change-of-intent rewrites ("call mom" → "email dad") while keeping single-word spelling fixes. |
| Widening guard | Stops an idle commit from growing a learned replacement as you keep typing past the correction. |
| Line breaks | An edit that would introduce a newline is rejected outright. |
Learning logs are redacted, so your dictated and corrected text never reaches the trace log.
Each time something is learned you get a brief toast — Learned "teh" → "the", or Learned 3 corrections for a batch — with an Undo action that removes that whole batch from the dictionary again. On tiling window managers, where a positioned toast doesn't fit the session, it falls back to a desktop notification.
Learned entries land in the Dictionary as ordinary corrections, so you can review, disable, or delete them there at any time.
GTK apps expose their text regardless, but Chromium/Electron apps (VS Code, browsers) and Qt apps only build an accessibility tree when the session flag org.a11y.Status.IsEnabled is on — and most desktops, GNOME included, leave it off by default. Without it, correction learning silently reads nothing from those apps.
When correction learning is on and that flag reads as off, the Dictation page shows an Enable accessibility bridge button. After enabling:
- Restart any Chromium/Electron app you want to learn from — they only pick the flag up at launch. Qt apps apply it immediately.
- A Remove accessibility bridge button appears so you can turn it back off if you stop using correction learning. Enabling the bridge activates accessibility for all apps in the session, which carries a small overhead.
Removal is only ever offered for a flag TypeWhisper itself set, and is refused while a screen reader appears to be active.
Terminals, TUIs, and anything else that doesn't implement the AT-SPI text interface are skipped silently. Dictation into them works normally — there is simply nothing to observe. These skips are expected and are not recorded in the Error Log.
Several dictation features depend on external desktop tools. When a tool is missing, the Linux UI disables the relevant control and explains why (including session-aware install hints).
| Feature | Tool required |
|---|---|
| Sound feedback | canberra-gtk-play |
| Audio ducking | pactl |
| Media pause | playerctl |
Clipboard-backed auto-paste and text delivery rely on additional tools — see Text insertion and Wayland notes.
- Global hotkeys — assign and register the dictation hotkey.
- Text insertion — how transcribed text reaches the target app.
- Text cleanup — post-processing applied to dictation.
- Appearance — overlay widgets (Indicator, Waveform, Text).
- Transcription engines — which engines support live streaming.
| Date | Change |
|---|---|
| 2026-06-17 | Initial version. |
| 2026-06-17 | Added Engine, settings, and System audio screenshots. |
| 2026-06-17 | Added recording-overlay screenshot. |
| 2026-06-17 | Documented the Auto-learn approved history corrections setting. |
| 2026-06-17 | Removed unused screenshot placeholders. |
| 2026-07-27 | v0.12.1: documented the Automatic (follow system default) input device and the Normalize spoken numbers to digits setting. |
| 2026-07-27 | v0.13.0: documented Learn corrections from other apps — how it observes edits, its password/similarity/widening guards, the learned-correction toast with Undo, and the accessibility-bridge setup. |