Dictation & analytics#

Dictation turns speech into text entirely on your machine: audio is captured with CPAL, transcribed by a local Whisper model, and delivered to whatever text field you were looking at. Nothing is sent to a cloud speech service, and every transcript is stored in a local SQLite database that also feeds a fairly detailed speaking-analytics tab.

Dictation is a module — it can be switched off entirely in Settings → Integrations & Data → Modules, which removes its view from the sidebar.

Getting set up#

1. Download a Whisper model. Settings → Integrations & Data → Dictation lists five: tiny, base, small, medium, large-v3. Download is streamed from the official whisper.cpp Hugging Face repository at a pinned revision, with live progress.
2. Pick a microphone. The picker lists every CPAL input device with its sample rate and channel count. Leave it on Default to follow the system default.
3. Test it. The stethoscope button opens the device for about 1.5 seconds and reports what it actually delivered — sample rate, channels, format, peak level, frame count.
4. Optionally enable global shortcuts in Settings → General → Preferences → Keyboard Shortcuts. They are off by default.

Model verification#

A model counts as Ready only when its SHA-256 marker matches and the file is still the byte length it was when hashed. A model truncated after verification — a disk-full copy, an interrupted sync, a half-restored backup — is reported as unverified rather than loaded, so you get "download it again" instead of an opaque whisper.cpp failure.

Models live in ~/.packetbench/models/ggml-<size>.bin, each beside a .sha256 marker. If your configured model has gone missing, PacketBench silently falls back to any other verified model on disk and rewrites the setting — the log records the substitution.

Recording#

The Dictation view. The left column is capture; the right is analytics and history.

Three ways to start:

• Click the round record button in the Dictation view.
• Toggle shortcut — Ctrl+Alt+R by default.
• Push-to-talk — hold Ctrl+Alt+Space by default; release to transcribe.

Escape cancels and discards. Ctrl+Shift+D opens the Dictation view. All three global bindings only exist while global shortcuts are enabled; the idle hint under the record button says so rather than advertising a chord that is not bound.

While recording, a 25-bar exponential-frequency waveform is emitted from the capture thread. Audio is resampled to the 16 kHz Whisper expects, from whatever your device delivers (48 kHz, 44.1 kHz, 8 kHz — all handled).

Recording stops automatically at the maximum recording length (default 5 minutes, clamped by the backend to 10 seconds – 30 minutes) and transcribes what it has. That ceiling bounds retained PCM even if a key release is missed or the frontend is temporarily unresponsive.

When capture goes wrong#

Dictation has a lot of machinery for the case where the microphone stops answering, because a Bluetooth headset that walks out of range can block inside CPAL indefinitely.

Every capture carries a monotonic id. A response that arrives after its capture was cancelled or superseded is discarded rather than resurrecting a dead recording or delivering a stale transcript — which also means dictating the same word twice in a row delivers twice, instead of the second being mistaken for a duplicate.

Cancel always reaches the backend and always resets locally, so Escape can clear a wedged "Transcribing…" spinner. A cancel with nothing in flight is a state reset: it will not wipe a transcript you are still reading.

Where the text goes#

Delivery is a chain, and the destination is frozen when the capture starts, not when the transcript comes back. Transcription takes seconds and people click elsewhere while it runs; delivering into whatever happens to be focused at that moment would type your words into an unrelated field.

1. A PacketBench text field you had focused. The text is inserted directly.
2. A terminal pane you had focused. The text is written to the PTY with all line breaks collapsed to spaces — a newline would submit a command, and Whisper emits multi-line output for multi-segment audio. Dictation must never execute a command on its own.
3. The clipboard, always.
4. A synthetic Ctrl+V into the foreground application, only if you enabled "Paste into other Windows apps".

Two settings gate all of this:

• Auto-paste after transcription (default off). With it off, nothing is delivered automatically — the transcript sits in the Dictation view for you to copy.
• Paste into other Windows apps (default off, and disabled until auto-paste is on). This is the system-wide paste opt-in.

Fields dictation refuses#

A field is refused as a delivery target when it is a password input, when its autocomplete is current-password, new-password, or one-time-code, or when it sits inside a region marked data-dictation="off", data-dictation="secure", or data-sensitive="true". The Dictation view itself is marked data-dictation="off", as is the Trust & Provenance settings card.

Focusing a secure region also clears the remembered field, so a transcript spoken at a password prompt cannot land in the form behind it. Focusing an ordinary button (including the mic button itself) does not clear it — clicking the mic is the normal way to start dictating.

The clipboard deliberately keeps the transcript after a paste. Restoring a previous clipboard value could re-expose a password or one-time code that was sitting there.

Composer mic buttons#

An agent composer's mic button uses the same backend but claims the capture, so the automatic delivery path stands down and the composer inserts the text itself. Without that claim the utterance would land twice. If the composer unmounts mid-capture it releases the claim, and a still-open microphone is cancelled rather than transcribed into nowhere.

Settings reference#

Everything below is in Settings → Integrations & Data → Dictation, except the shortcuts, which are in Settings → General → Preferences.

The three shortcuts must all differ from each other, and PacketBench only ever unregisters accelerators it successfully registered itself — an existing OS or application binding is reported as a conflict, never taken over. The status line under the shortcut rows says which state you are in: off, registering, active, or the conflict message.

History#

The History tab lists past transcriptions, newest first, 100 at a time (server-side page cap 500). Expanding a row shows the full text plus mode, duration, WPM, word count, and sentiment.

Search is a LIKE scan over the transcript text, capped at 200 results, with %, _, and \ escaped so a search for a literal 100% matches only that.

Transcripts are stored in ~/.packetbench/dictation.db (SQLite). One row per transcription, with text, mode, a UTC ISO-8601 timestamp, word_count, duration_seconds, wpm, and sentiment.

Analytics#

The Analytics tab is built from a single backend aggregation (get_dictation_analytics) over the whole entries table, rendered as 21 visualisations from three hand-rolled chart primitives. It fills in progressively: the first entry gives you totals, speed, and time saved; a day or two adds the trend lines and heatmaps; a week adds streaks, goals, and the week-over-week comparison.

Headline#

Total words · entries · average WPM · time spoken · time saved · vocabulary diversity, plus average sentiment when there is any to average.

Time saved is measured against typing at 40 wpm, clamped at zero per day before summing. Vocabulary diversity is distinct words over total words.

Trends#

Six charts over a trailing series of at most 365 day-buckets (days with at least one entry only): words per day, words per minute, vocabulary growth, cumulative talking time, cumulative time saved, and sentiment over time.

The two cumulative charts are seeded from a carry total for the day-buckets that fell outside the window, so they continue your history instead of restarting at zero. A line under the charts says how much was carried in.

Rhythm#

A yearly daily-activity heatmap, a weekday × hour heatmap, and two hour-of-day bar charts (session count, and mean WPM). Hours with no reading show as an empty tick, not a zero bar.

Consistency#

Three streak numbers that are genuinely different and are shown as such:

When you have a lapsed run, a line explains why the current streak reads zero.

Goals are fixed constants, not user settings: 500 words/day and 2,500 words/week. There is no UI to change them. The section also compares this UTC week against last.

Language#

Top words, filler words, distinctive words, word-length distribution, common two- and three-word phrases, new words this week, and a Flesch-Kincaid reading level.

The filler-word list is fixed and reported in declaration order including zeros, so the frontend controls sorting: um, uh, like, basically, actually, literally, honestly, anyway, so, right. "Distinctive" means over three characters, outside a built-in ~300-word common list, and used at least twice. Phrases must appear at least twice and cannot be entirely stopwords. New-words chips are capped at 50 with the real total shown alongside.

Reading level is clamped to 1–18; a value of 0 means "not enough text to score" and renders as an empty state rather than grade zero.

Records#

Fastest WPM, most words in a day, longest entry, longest session.

Sentiment#

Sentiment is a VADER compound score in −1…+1, computed in Rust at the single write point, so every new entry gets one.

The coverage label ("scored 12 of 840 entries") is shown wherever a sentiment number is.

Deliberately absent#

A mode breakdown donut and topic classification were removed on purpose. PacketBench only ever writes the transcribe mode, so modeBreakdown is always a single bucket; the topic rules were tuned to a different product. Do not build anything new on modeBreakdown.

Related#

• Settings reference — the Dictation and Keyboard Shortcuts cards in context.
• Workspaces & terminals — dictating into a terminal pane.
• Agents & conversations — the composer mic button.