talk-rs

⚠️ Disclaimer: this project is entirely "vibe coded".

Every line of code, test, and documentation in this repository was produced by an AI coding agent under human direction. No part of it has been written, line-by-line audited, or formally reviewed by a human engineer. It works on the author's machine and ships with tests, but treat it accordingly: read the source before trusting it with anything important, and expect rough edges, dead code paths, and the occasional architectural oddity that a human would have caught.

Voice dictation for Linux. Record, transcribe, and paste text into any application – all from a single keyboard shortcut.

talk-rs captures audio from your microphone, sends it to a transcription API (Mistral Voxtral or OpenAI Whisper), and types the result into the focused window. A small X11 overlay badge shows the current state (recording / transcribing) so you always know what is happening.

Features

• Dictation workflow – press a key to start recording, press again to stop; transcribed text is pasted automatically.
• Multiple providers – Mistral (Voxtral), OpenAI (Whisper / GPT-4o), and local on-device Parakeet for batch transcription; Mistral and OpenAI realtime streaming via WebSocket.
• Text-to-speech – the speak command synthesizes text and plays it (or saves a WAV). Two providers mirror the transcription side: kokoro (local, offline, multi-language via sherpa-onnx) and mistral (remote Voxtral TTS). Language handling is config-driven and agnostic.
• Speaker diarization – identify who is speaking (--diarize); output is tagged with speaker labels. Currently supported with Mistral V2 models in batch mode.
• Multi-candidate picker – with --pick, run several providers in parallel and choose the best transcription from a GTK picker window. A waterfall spectrogram of the recording is shown above the candidate list; it loads asynchronously and adapts to window width. Non-default models are transcribed on demand via a per-candidate button to avoid unnecessary API calls.
• Visual overlay – non-intrusive X11 badge at the top of the screen (works without a compositor).
• Live transcription overlay – a dynamic phase-coloured waterfall replaces the static "transcribing" badge; three independent throughput tracks (upload bytes, download bytes, paste characters) show progress through the pipeline, with a time-grid layer over the spectrogram.
• Dead audio detection – overlay badge shows a red prohibit icon and "NO SOUND" warning when no real microphone is detected (e.g. headset unplugged); a centered full-screen overlay and repeating alert tone reinforce the signal, and a notification also appears on the text panel.
• Auto-pause – automatically pauses audio forwarding during silence, trimming dead air from transcription input. Resumes instantly with a 300 ms lookback buffer to preserve speech onset. The badge shows yellow pause bars and "LISTENING" during pauses. Disable with --no-auto-pause.
• Audio visualizers – optional in-badge visualization during recording (--viz waterfall, --viz amplitude, --viz spectrum); monochrome mode with --mono.
• Audio feedback – start/stop tones plus a periodic boop while the badge shows LISTENING (i.e. during auto-pause silence); the boop is silent while you are actively speaking, and is never heard when --no-auto-pause is used. Fully configurable or disabled.
• Bluetooth headset auto-switch – when a Bluetooth headset is connected in A2DP mode (high-quality stereo, no microphone), talk-rs automatically switches it to its Hands-Free Profile (HFP) for the duration of the recording so the headset microphone is available, then restores the original profile on stop. Survives unclean termination: a state file at $XDG_RUNTIME_DIR/talk-rs/card-profile.json is written before the switch, and the next invocation restores the original profile from that file before starting a new recording. Works with any HFP-capable headset (uses PulseAudio's standard device.form_factor property, not vendor-specific identifiers). Disable per-invocation with --no-bt-auto-switch or globally via the audio.bt_auto_switch config key.
• Context bias – supply domain-specific vocabulary to improve transcription accuracy.
• Daemon toggle mode – first invocation spawns a short-lived daemon that records; second invocation signals it to stop, transcribe, paste, and exit. Ideal for global shortcuts.
• No idle daemon – between dictations, zero talk-rs processes stay resident. The toggle daemon spawns on press, records, and exits after pasting. No memory footprint when idle.
• Retry last – re-transcribe the last cached recording without speaking again (--retry-last).
• Recordings browser – record --ui opens a GTK4 window listing all recordings (OGG from output_dir) and dictation cache (OGG). Imported audio dropped into output_dir – .m4a, .mp4, or .aac (e.g. iPhone voice memos) – is listed and playable alongside native OGG recordings, with the same waterfall and transcription workflow. Play, delete, open in the file manager, or transcribe on demand. A waterfall spectrogram is shown for every recording, even those without transcripts; sections auto-refresh via inotify when files change externally.
• Per-segment timing export – --output-yaml includes per-segment start/end timestamps in the metadata sidecar, suitable for subtitles and post-processing.
• Standalone commands – record and transcribe can be used independently for scripting.
• Environment overrides – every config value can be set via TALK_RS_* environment variables.

Prerequisites

Build dependencies

# Debian / Ubuntu
sudo apt install build-essential pkg-config libasound2-dev libopus-dev \
  libgtk-4-dev libpipewire-0.3-dev libspa-0.2-dev libclang-dev \
  libpulse-dev

# Fedora
sudo dnf install alsa-lib-devel opus-devel pkg-config \
  gtk4-devel pipewire-devel spa-devel clang-devel \
  pulseaudio-libs-devel

libpulse-dev / pulseaudio-libs-devel provides the PulseAudio client library used to switch a Bluetooth headset's PulseAudio card profile between A2DP (high-quality stereo) and HFP (microphone-enabled) when recording. On PipeWire systems, pipewire-pulse supplies the libpulse.so shared object at runtime, so no PulseAudio daemon is needed – only the development headers for compilation.

A working Rust toolchain is required (1.87+). Install via rustup if needed.

Runtime dependencies

PipeWire must be running (used for audio capture). Most modern Linux desktops ship with PipeWire by default.

Cloud transcription providers require an API key:

• Mistral (default)
• OpenAI

Parakeet is a local, on-device ASR backend using sherpa-onnx on the CPU and needs no API key. After a consent prompt, its model is downloaded on first use into ~/.local/share/talk-rs/models/.

Installation

If building from a git clone, run ./autogen.sh first to resolve version placeholders in Cargo.toml:

./autogen.sh
cargo build --release

The binary is at target/release/talk-rs. Copy it somewhere in your $PATH:

cp target/release/talk-rs ~/.local/bin/

Configuration

talk-rs reads $XDG_CONFIG_HOME/talk-rs/config.yaml (typically ~/.config/talk-rs/config.yaml).

Copy the example and fill in your values:

mkdir -p ~/.config/talk-rs
cp config.example.yaml ~/.config/talk-rs/config.yaml

Minimal working configuration:

output_dir: ~/talk-rs-output

providers:
  mistral:
    api_key: YOUR_MISTRAL_API_KEY

Required fields

Optional fields

The recording.* settings control the quality of recordings meant for a human to listen to or share. They are independent of transcription: audio sent to the providers is always downsampled to 16 kHz mono internally (both Voxtral and Whisper operate at 16 kHz), so these knobs do not affect transcription accuracy or upload size.

OpenAI model migration

The OpenAI batch default is exactly gpt-transcribe, and the realtime default is exactly gpt-live-transcribe. Existing configuration files remain valid: prompt, keywords, languages, and realtime_delay are optional, and omitting them sends no hint fields.

• gpt-transcribe sends prompt, repeated keywords[], repeated languages[], and response_format=json to the batch endpoint.
• gpt-live-transcribe nests model, prompt, keywords, languages, and delay under session.audio.input.transcription in the realtime session.update.
• whisper-1 remains available for segment/word timestamps, subtitles, and translation workflows. It retains response_format=verbose_json, accepts prompt and one unambiguous singular language, and does not accept keywords or multiple languages.
• gpt-4o-transcribe and gpt-4o-mini-transcribe remain available as legacy batch choices. gpt-realtime-whisper remains available as a legacy realtime choice, using singular language for one expected language and rejecting keywords, multiple languages, and realtime_delay.

Configured hints that the selected model cannot represent fail locally before HTTP or WebSocket traffic; talk-rs never silently drops them. There is no structured previous-turn configuration field in the official schema. Earlier-turn context is service-managed where supported.

Direct-OpenAI prices checked 2026-07-31: gpt-transcribe costs $0.0045/min ($0.27/hr), while whisper-1 costs $0.006/min ($0.36/hr). The new batch default is 25% lower, a $0.09 per hour savings.

Environment overrides

Every config value can be overridden via environment variables:

export TALK_RS_PROVIDERS_MISTRAL_API_KEY="sk-..."
export TALK_RS_PROVIDERS_OPENAI_API_KEY="sk-..."
export TALK_RS_PROVIDERS_OPENAI_PROMPT="Preserve punctuation and casing."
export TALK_RS_PROVIDERS_OPENAI_KEYWORDS="Kalysto, talk-rs"
export TALK_RS_PROVIDERS_OPENAI_LANGUAGES="fr, en"
export TALK_RS_PROVIDERS_OPENAI_REALTIME_DELAY="low"

TALK_RS_PROVIDERS_OPENAI_KEYWORDS and TALK_RS_PROVIDERS_OPENAI_LANGUAGES are comma-separated lists. talk-rs trims whitespace and ignores empty entries deterministically; environment values override YAML in both existing and environment-created OpenAI sections.

See config.example.yaml for the full list.

Usage

Global options

Dictate (main workflow)

Record, transcribe, and paste into the focused application:

talk-rs dictate

Toggle mode (ideal for keyboard shortcuts):

talk-rs dictate --toggle

First call starts a background daemon that records. Second call stops recording, transcribes, and pastes the result.

Options:

Record

Capture audio to an OGG/Opus file:

talk-rs record                       # auto-named <output_dir>/YYYY/MM/YYYY-MM-DDTHH-MM-SS±ZZZZ.ogg
talk-rs record meeting-notes.ogg     # custom filename
talk-rs record --toggle              # first call starts, second call stops
talk-rs record --toggle meeting.ogg  # toggle with an explicit output path

Toggle mode starts a background recorder on the first call. The second call sends SIGINT; the recorder stops capture, finalizes and syncs the audio file, then exits. Its PID remains published during finalization, so repeated stop calls cannot start a second writer for the same toggle slot. Toggle mode conflicts with --ui.

Foreground and toggle recording use the same feedback as dictation: the start tone finishes before capture begins, an optional X11 badge visualizes the captured PCM, and the periodic boop sounds only while the badge detects silence. On stop, the boop and badge are torn down before capture closes. The stop tone sounds only after the encoder has finalized the file and sync_all() has made it durable. If X11 is unavailable, recording and sound feedback continue without the badge.

Options:

Toggle state is stored under $XDG_CACHE_HOME/talk-rs/ (normally ~/.cache/talk-rs/). Dictation keeps its existing daemon.pid, daemon.lock, and daemon.log files. Standalone recording uses the separate record.pid, record.lock, and record.log files, so the two commands cannot stop or overwrite each other's toggle state.

Transcribe

Transcribe an existing audio file:

talk-rs transcribe recording.ogg                # print to stdout
talk-rs transcribe recording.ogg output.txt     # write to file
talk-rs transcribe recording.ogg --provider openai
talk-rs transcribe voice-memo.m4a               # imported m4a also works

Options:

1. Provider overload

   Cloud providers periodically answer 503 high load or 429 backend_out_of_capacity, especially on long recordings. talk-rs treats every 5xx and 429 as "busy, try again later" and waits between attempts: 5 s, 15 s, 30 s, 60 s, 120 s, 120 s (about 5.5 minutes in total, seven attempts). A Retry-After header from the provider overrides the schedule slot (capped at 120 s). Each wait is logged at -v as server retry N/6. Other 4xx answers are permanent and fail immediately.

   Connection failures (DNS, unreachable host, TLS timeout) use a separate, shorter schedule and never consume the server-retry budget. Large uploads are given the whole request time budget on every attempt, so an 80-minute recording is not cut off by the early connection slots.

   If all seven attempts fail the recording is kept in the cache; re-run transcribe on the .ogg (or dictate --retry-last) once the provider has recovered.

Speak (text-to-speech)

The architectural mirror of transcribe: text in, speech out. Synthesize text and play it through the speakers, or save it to a WAV file. Two providers – kokoro (local, offline, on-device via sherpa-onnx) and mistral (remote Voxtral TTS).

talk-rs speak "hello world"                        # synthesize + play
talk-rs speak --provider mistral --voice <id> "hi" # remote Voxtral TTS
talk-rs speak -o out.wav "save me to a file"       # write WAV, don't play
echo "from a pipe" | talk-rs speak                 # read text from stdin
talk-rs speak -f message.txt                       # read text from a file
talk-rs speak --lang fr --voice ff_siwis "Bonjour" # French (Kokoro)

Text is resolved in priority order: the positional argument, then --file, then stdin (when stdin is not a TTY).

The default provider is resolved as --provider > speak.default_provider (config) > the local kokoro backend when a providers.kokoro section exists, else mistral. On first use the Kokoro model (~350 MB) is downloaded after an interactive consent prompt (or a non-interactive proceed-with-log, exactly like the Parakeet ASR model) into ~/.local/share/talk-rs/models/kokoro-multi-lang-v1_0/.

Options:

Language handling is config-driven and agnostic: the requested language selects the phonemizer. The stock Kokoro model ships one baked language; other languages are derived on demand by patching the model's ONNX voice metadata, cached as model-<lang>.onnx next to the stock model.

Supported input audio formats

Commands that read audio from disk – transcribe, dictate --input-audio-file, dictate --retry-last, and the record --ui recordings browser – accept the following formats:

Imported files keep their original extension on upload, so the transcribe command sends .m4a to the provider as-is – both Mistral Voxtral and OpenAI Whisper accept these natively. Playback and waterfall spectrograms in the records browser work for every listed format.

GNOME keyboard shortcut

Bind talk-rs dictate --toggle to a key (e.g. Super+/):

BASE="org.gnome.settings-daemon.plugins.media-keys"
BPATH="/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings"

CURRENT=$(gsettings get "$BASE" custom-keybindings)
N=0
while echo "$CURRENT" | grep -q "custom${N}/"; do
  N=$((N + 1))
done
SLOT="${BPATH}/custom${N}/"
SCHEMA="${BASE}.custom-keybinding:${SLOT}"

if [ "$CURRENT" = "@as []" ]; then
  gsettings set "$BASE" custom-keybindings "['${SLOT}']"
else
  gsettings set "$BASE" custom-keybindings "$(echo "$CURRENT" | sed "s|]$|, '${SLOT}']|")"
fi

gsettings set "$SCHEMA" name    'talk-rs dictate'
gsettings set "$SCHEMA" command 'talk-rs dictate --toggle --viz waterfall'
gsettings set "$SCHEMA" binding '<Super>slash'

First press starts recording, second press stops, transcribes, and pastes into the focused application.

To change the key, replace <Super>slash with the desired binding (e.g. <Super>semicolon, <Super>d). Add --realtime to use streaming transcription instead of batch mode.

Development

cargo fmt                     # format
cargo clippy --all-targets    # lint
cargo test                    # test
cargo build                   # build

Cargo feature flags

The default build enables everything (full dictation CLI). Library consumers can opt out of the desktop stack with default-features = false:

Example headless consumer (cloud transcription only):

talk-rs = { path = "../talk-rs", default-features = false }

License

MIT – see LICENSE.

Changelog

0.7.1 (2026-09-17)

Fix

• [dictate] reject a bad API key or model up front in --realtime mode. [Valentin Lab]

  Batch dictation runs a pre-flight check (API key, model) and fails immediately on a misconfiguration. Realtime dictation skipped it: RealtimeTranscriber::validate was fully implemented for Mistral and OpenAI but never called, hidden behind three #[allow(dead_code)], so a bad key or model only surfaced from inside the streaming loop after the user had started talking.

  dictate_realtime now calls validate right after creating the transcriber and before opening the streaming session, so the error is immediate and enriched with the available models; reconnects keep skipping it. Capture itself has already started at that point and buffers meanwhile: the check gates the provider session, not the microphone. The three pragmas are gone, so the compiler would flag any future regression. A unit test drives validate against a mock that rejects the WebSocket upgrade with 401 and checks that exactly one handshake happens.

0.7.0 (2026-09-17)

New

• [overlay, picker] show a draining countdown while the provider is busy. [Valentin Lab]

  During a server backoff the badge used to sit on a static dim-blue stripe with TRANSCRIBING for up to two minutes — indistinguishable from a hang, which is exactly how users reported it.

  The badge now enters an amber "waiting on the provider" state: the phase-line row becomes a solid amber band that drains right-to-left across the wait (refilling when the next retry fires), and the centre text reads BUSY · RETRY N/M so the user knows it is the provider, not their setup, and how far through the retry budget they are. The scrolling phase history records the wait as dim amber so the timeline still shows how long the provider stayed busy after the retry succeeds. Connection retries keep their previous rendering.

  The picker row label gains the wait as well: server retry 1/6 in 30s….

  TranscriptionEvent::RetryScheduled carries a new delay field (zero for connection retries) so UI consumers can render the countdown from the event's own timestamp.

• [record] add feedback parity with dictate [Valentin Lab]

  Make standalone recordings provide the same start and stop tones, silence-gated boop, and optional X11 badge as dictation.

  Share one feedback lifecycle so --no-sounds, --no-boop, --no-overlay, --viz, and --mono behave consistently in foreground and --toggle modes.

• [record] support record --toggle lifecycle. [Valentin Lab]

  Give standalone recording the same toggle workflow as dictation while keeping each command's daemon state isolated.

  Register SIGINT before startup work and retain ownership through encoder finalization and sync_all() so rapid stop requests cannot race a second recorder.

Fix

• [transcription] cache model suggestions per API key, not only per endpoint. [Valentin Lab]

  Two credentials pointing at the same api_base shared one cached model list, so a second key could be served the entitlements of the first for up to an hour. The in-process cache is now keyed by (api_base, api_key).

  This also isolates the model_suggestions unit tests, which previously failed under --test-threads=1 because consecutive MockServer instances reuse the same port and therefore the same cache entry.

• [transport] wait out provider overload instead of failing within two minutes. [Valentin Lab]

  Long recordings sent to Mistral regularly failed with 503 high load, please retry or 429 backend_out_of_capacity: the transport retried a 5xx at most twice with no delay, never retried a 429 at all, and capped every attempt at the connection-phase budget (2, 5, 8, 11, 15, 30, 120 s), so a 26 MB upload was structurally doomed on the first six slots. An 83-minute call thus needed seven uploads to succeed when the API was healthy, and gave up in about two minutes when it was not.

  Data-phase (server busy) retries now form their own loop, independent of the connection-phase budget: every 5xx and 429 is retried after a wait of 5, 15, 30, 60, 120, 120 s (seven attempts, about 5.5 minutes), a server-supplied Retry-After overrides the schedule slot (capped at 120 s), and the wait is cancellable. The per-attempt cap is lifted to the request's own wall_clock when that is larger, so large uploads get their full proportional budget on every attempt. Each backoff is logged at info as server retry N/6.

  PipelineFailure annotates an exhausted 429 as "server-retry budget exhausted" rather than "4xx permanent, no retry".

0.6.0 (2026-08-02)

New

• [transcription] expose OrderedItemTranscript to downstream consumers. [Valentin Lab]

  Item-aware realtime providers report transcript text as ordered conversation items rather than as the generic TextDelta / SegmentDelta pair, and reconciling those items requires conversation ordering, provisional-to-authoritative replacement, and a terminal drain.

  OrderedItemTranscript already implements exactly that, but it was crate-private, so an external consumer of TranscriptionEvent had no way to handle the item-aware variants without reimplementing the same ordering algorithm.

  Publish the type and the six methods such a consumer needs, and keep the internal ordering state and the replay helpers restricted.

• [openai] add gpt-transcribe and item-aware realtime support. [Valentin Lab]

  Integrate the new batch and live models with configurable context, keyword, language, and delay hints while retaining legacy model compatibility.

  Reconcile provisional realtime deltas by item so authoritative completions replace rather than duplicate picker and dictation text.

• [speak, synthesis] add TTS speak command with Kokoro and Mistral providers. [Valentin Lab]

  Architectural mirror of the transcription surface on the synthesis side: a OneShotSynthesizer trait with a cfg-gated factory, a local Kokoro backend (kokoro feature, same sherpa-onnx static lib as parakeet, consent-gated ~350 MB model download via the shared model_fetch helper) and a remote Mistral Voxtral backend (POST /v1/audio/speech, sharing the existing providers.mistral API key via new tts_model and tts_voice fields).

  talk-rs speak reads text from the positional argument, --file or stdin, then plays through the AudioPlayer or saves a WAV with -o.

  Language handling is automatic by default: whichlang detects the text language, selecting the phonemizer for Kokoro (non-default languages derive a metadata-patched model-<lang>.onnx, cached next to the stock model) and the per-language voice for Mistral (tts_voices config map or built-in presets). --lang overrides detection. An explicitly pinned voice whose language contradicts the resolved language is a hard error naming the voice, both languages and the remedies; --force bypasses the guard. Voices with unknowable language (custom Mistral UUIDs) skip the guard.

  Config surface: providers.kokoro (voice, num_threads, lang, model_dir), providers.mistral.tts_voices, speak.default_provider, with matching TALK_RS_* env overrides.

• [paste] composable paste-node tree configurable per target window. [Valentin Lab]

  Refactor the paste subsystem into a tree of composable nodes (router / decorator / leaf), each implementing a common paste() interface, selectable via a recursive paste: tree in the config.

  Node families:

  • routers: detect-display-server and match-wm-class (first-match glob routing on WM_CLASS);
  • decorator: chunk;
  • leaves: clipboard and xtest-type.

  This lets the user pick chunking, paste shortcut (ctrl_v vs ctrl_shift_v), or XTest typing on a per-target-window basis.

  Fully backward compatible: absent paste: reproduces the previous behaviour; the old flat paste keys are still accepted and mapped to an equivalent tree; --no-chunk-paste strips the chunk nodes.

  Runtime paste behaviour is unchanged in this commit (the existing clipboard sync is moved verbatim into the clipboard node).

  Also add an x11_get_wm_class helper to drive the match-wm-class router.

• [transcription, config] add local Parakeet backend with consent-gated download. [Valentin Lab]

  Add NVIDIA Parakeet TDT 0.6b v3 as a local, on-device, CPU transcription provider selectable via provider: parakeet (config transcription.default_provider or the --provider flag), running fully offline through a statically-linked sherpa-onnx.

  The ~640 MB model is NEVER downloaded silently. The transcribe pipeline only checks for the model (model::ensure_present) and errors if it is absent; the actual fetch (model::download_model) is an explicit, consented step driven per entry surface:

  • transcribe CLI: [y/N] prompt on a TTY; a clear stderr message then proceed when piped (selecting parakeet is the consent).
  • dictate --toggle: a "DOWNLOADING MODEL" overlay badge while it fetches, before recording starts.
  • --pick picker: a GTK AlertDialog on click; Cancel is a clean no-op. Parakeet is only listed when providers.parakeet is configured, and an absent default model is demoted to a click-to- download row rather than auto-erroring.

  The download is atomic (extract + verify into a staging dir, then a single rename into the cache) with an fs2 lock for concurrent invocations, so an interrupted run never leaves a half-populated model dir. Inference runs in spawn_blocking and reuses the existing 16 kHz mono decode pipeline. The backend sits behind a parakeet cargo feature (on by default; --no-default-features drops the C++ dependency for a lean cloud-only build).

• [record, config] add human-quality recording profile for .ogg output. [Valentin Lab]

  The record command reused AudioConfig::new() — the 16 kHz mono 32 kbps profile required by the transcription providers — to write recordings meant for a human to listen to. At 16 kHz the Opus encoder is capped to an 8 kHz audio bandwidth (Nyquist), so shared recordings sounded muffled and dull.

  Separate the two concerns: the transcription profile stays hardcoded and hidden (an API requirement, not a user preference), while a new user-facing recording: config section controls the record output quality. It exposes sample_rate (default 48000), channels (default 1 mono) and bitrate (default 128000), each also settable via TALK_RS_RECORDING_* env vars.

  The record path now:

  • resolves its AudioConfig from the recording: section;
  • captures via PipeWireCapture (negotiates the requested rate / channels with the device, robust on mono-only mics) instead of the exact-match CpalCapture;
  • encodes with OggOpusWriter::new_for_recording (Opus Application::Audio for fuller fidelity vs the speech-optimised Voip mode kept by the transcription path).

  Verified empirically: a fresh recording now carries energy up to ~20 kHz (was a hard wall at 8 kHz). Documents the new section in config.example.yaml and README.org; adds config tests for defaults, YAML parsing, partial overrides and env overrides.

• [config] expand a leading ~ in output_dir to $HOME [Valentin Lab]

  The README minimal example and many users naturally write output_dir: ~/talk-rs-output, but there was no tilde expansion: the value was taken literally as a relative directory named ~. Combined with the new absolute-path requirement, the documented example would now fail outright.

  Expand a leading ~ (bare) or ~/… to the user's home directory (via directories::UserDirs) at load time, after the TALK_RS_OUTPUT_DIR override and before validation, so both the file value and the env override benefit. A tilde that is not the first path component (e.g. /tmp/~/x) and the ~user form are left untouched. Document the behavior in config.example.yaml and README.org; add tests for the bare-~, ~/…, env-override, and non-leading-tilde cases.

• Add --timestamp flag for diarized transcription output. [Boris Gallet]

  Adds a CLI flag --timestamp (also -t) that prefixes each speaker-attributed line with [HH:MM:SS] in the transcript output.

  • CLI: --timestamp added to both transcribe and dictate commands
  • Config: env var TALK_RS_TIMESTAMP also supported
  • Output format: [HH:00:00] speaker_1 text...
  • Tests: 5 new tests covering timestamp formatting, edge cases, and integration with diarization

  Motivation: when transcribing long meetings (>30min), knowing when each speaker talked is essential for navigation and summary.

• [paste, config] configurable paste shortcut (Ctrl+V vs Ctrl+Shift+V) [Boris Gallet]

  Add PasteShortcut enum to PasteConfig with two variants:

  • ctrl_shift_v (default) — primary selection paste
  • ctrl_v — regular clipboard paste for terminals/Emacs

  Refactor simulate_paste() to take PasteShortcut and resolve the correct X11 keysyms via a pure paste_keysyms() function. Propagate the shortcut through paste_text_to_target(), the realtime per-segment paste task, and the picker path.

• [picker, realtime] surface WS session phases as picker row status. [Valentin Lab]

• [picker, transcription] picker Stop button via SIGUSR1 cross-process cancel. [Valentin Lab]

• [transcription] cross-process job registry via lock-file YAML + SIGUSR1. [Valentin Lab]

  Step 11 of the transport-consolidation plan at .sisyphus/plans/transport-consolidation.md.

  New module transcription::jobs extends the existing per-model lock files in recording_cache with a YAML payload describing the owner process and adds SIGUSR1-based cross-process cancellation.

• [transcription, picker] wire telemetry sink into realtime path. [Valentin Lab]

  Step 10 of the transport-consolidation plan. Realtime transcribers now accept a telemetry sink so WS upgrade phase and retry events reach the picker UI, fixing the silent-blocking symptom.

• [transcription, transport] introduce unified http_request / ws_upgrade API. [Valentin Lab]

  Adds the public transport-consolidation API surface (talk_rs::transcription::transport::{http_request, ws_upgrade}) plus the truthful-counter, growing-budget, cancellable http_request implementation.

  This is Steps 0-2 of the consolidation plan at .sisyphus/plans/transport-consolidation.md. The plan resolves three long-standing bugs surfaced by the user: (a) send_once hardcodes attempts=1, max_attempts=1 in every PipelineFailure, (b) the connect budget never grows across attempts, (c) requests cannot be cancelled. After this commit:

  • http_request reports truthful attempts/max_attempts in PipelineFailure (was 1/1 everywhere).
  • Connection-phase retries run on the growing budget [2, 5, 8, 11, 15] seconds, wrapped in an outer tokio::time::timeout so blackhole destinations don't hang for the OS-default ~125s TCP SYN timeout.
  • Data-phase retries (5xx responses) run up to 3 attempts.
  • CancellationToken aborts an in-flight request via tokio::select! within ms of the trigger.

  The legacy with_retry / send_once paths are untouched — they will be migrated in Steps 3-5 of the plan. Multipart bodies are intentionally rejected by http_request for now; Step 4 adds a body-factory shape so retries can rebuild a fresh reqwest::multipart::Form per attempt.

  Tests: tests/transport_integration.rs pins the spec for the unified transport. Five of the ten tests pass after this commit (connection budget, data retries, both attempts-counter tests, cancellation). The remaining five remain unimplemented!() / panic! placeholders for Step 6 (ws_upgrade) and Step 11 (jobs cross-process registry); they ship RED on purpose and will flip green as those steps land.

  The transcription::transport module changes from pub(crate) to pub so integration tests can pin the public surface.

• [record] m4a / mp4 / aac read support across the recordings browser. [Valentin Lab]

  The recordings browser (record --ui) silently ignored any file that was not .ogg: the directory walker filtered on a hardcoded extension, the waterfall decoder errored on unknown formats, the playback path fell through to the WAV parser (producing either an error or garbage), and the inotify live-refresh filter listed only .wav / .ogg events. Imported audio — typically .m4a voice memos copied into output_dir — was therefore invisible in the UI even though every downstream consumer (the transcription providers, the GTK list, the file manager) handles those files natively.

  Add full read support for .m4a, .mp4, and raw .aac across every audio-consuming path of the browser:

  • New read_m4a_as_f32 in src/record/audio.rs uses [[https://github.com/pdeljanov/Symphonia][symphonia]] for ISO/MP4 demuxing and AAC-LC decoding. Multichannel input is averaged to mono and resampled with the existing resample_linear helper to match the calling site's rate, mirroring the read_ogg_as_f32 / read_wav_as_f32 contract. The authoritative sample rate and channel count are read from the first decoded AudioBuffer's SignalSpec, never from codec_params: symphonia's ISO/MP4 demuxer is known to underreport channels for AAC tracks (a stereo AAC-LC track surfaces as codec_params.channels = 1 even though the decoder produces a 2-channel buffer), which would otherwise make the stereo-to-mono mixdown walk the interleaved buffer with the wrong stride, doubling the output sample count and halving playback speed / pitch. Only the aac + isomp4 symphonia feature flags are enabled, so the release binary picks up an AAC decoder

    • MP4 demuxer (~200 KB) and no other codecs.

  • New m4a_duration_secs walks the MP4 box hierarchy to read mvhd.duration / mvhd.timescale directly — O(box-count), no full decode required. Mirrors the O(1) ogg_duration_secs probe so the listing stays snappy on large files. Supports both v0 and v1 mvhd layouts and tolerates size = 0 ("to end of file") and size = 1 (64-bit extended) box headers.

  • The central dispatcher read_audio_as_i16 gains the "m4a" | "mp4" | "aac" arm — this automatically extends m4a support to every caller, including the picker waterfall (src/dictate/picker/ui.rs) and the shared audio_player_bar widget.

  • src/record/entries.rs is generalised: collect_oggs_recursive → collect_audio_recursive, with a shared AUDIO_EXTENSIONS constant and a case-insensitive has_audio_extension helper so .M4A files from a camera are picked up alongside lowercased ones. Listing-time duration is dispatched through a new audio_duration_secs that routes to the per-format probe. Both list_ogg_recordings (now lists all audio under output_dir) and list_cache_recordings (dictation cache) use the new collector.

  • WavPlayer::play in src/record/player.rs learns the same m4a | mp4 | aac arm. The fallthrough to read_wav_as_f32 is preserved — backwards-compatible with the legacy .wav cache entries — but is no longer hit for AAC content, which previously produced corrupted playback.

  • The GTK4 FileMonitor filter in src/record/ui.rs:908 treats every listable extension as audio. The comparison is lowercased so case-mixed imports trigger the live-refresh.

  • delete_recording extends the YAML companion + .wf waterfall cache cleanup so deleting an .m4a row sweeps the same sidecars an .ogg row would.

  Test coverage:

  • Two shipped fixtures under tests/fixtures/: the original sine_440_0.5s_mono.m4a (5 345 B, 440 Hz sine, AAC-LC, mono, 0.5 s) and the new sine_440_0.5s_stereo.m4a (5 026 B, same signal, stereo) that mirrors the format produced by the AudioRecorder app the user imports voice memos from — both are documented in tests/fixtures/README.md with the ffmpeg regeneration command.
  • 5 new record::audio::tests cover m4a_duration_secs against the mono fixture (±0.1 s tolerance to absorb encoder rounding), read_m4a_as_f32 for mono (sample-count window + non-silent peak), read_m4a_as_f32 for stereo at both 16 kHz and 48 kHz (the regression test that locks in the SignalSpec-vs- codec_params correctness — empirically verified to fail with a 2× sample count when the bug is reintroduced), read_audio_as_i16 dispatch through to the AAC arm, and the unsupported-format error path.
  • 4 new record::entries::tests cover the broadened collector (.m4a / .MP4 / .aac mixed with .ogg, case-insensitive extension matching, mixed flat + nested layouts) and the audio_duration_secs dispatcher's None-on-unknown semantics.
  • Full cargo fmt, cargo clippy --all-targets --all-features, cargo test (438 unit tests pass, 0 fail), and cargo build --release clean.

  README.org gains a "Supported input audio formats" subsection under Usage and updates the recordings-browser feature bullet to mention .m4a imports; README.md is regenerated by autogen.sh.

• [overlay] surface validate phase + retry counter on the spectrogram. [Valentin Lab]

  Add a dedicated Phase::Validating state to the overlay's HTTP state machine, driven by the PreflightStarted / PreflightCompleted telemetry events emitted by the validate-cache miss path. The phase reuses the same green as Phase::Done but at half opacity so the user can tell at a glance that the network roundtrip in flight is the cheap /v1/models validation rather than the actual transcription upload. Phase::color now returns ([u8; 4], f32) so each phase carries its own opacity; throughput tracks drop the opacity component since they always render at full strength.

  Also draws a small attempt counter at the top-left of the SPEC area whenever a RetryScheduled event fires (validate retries or transcription retries), dimmed to follow the current phase's opacity so a validate retry shows a half-opacity "2" while a transcription retry shows a full-opacity "2". The counter is cleared at the start of every fresh recording cycle and at every fresh PreflightStarted / RequestStarted so a stale digit never bleeds into the next attempt.

  To support the dimmed stripe and counter, PixelBuffer gains a blend_pixel(x, y, color, opacity) helper that linear-blends BGRA over the existing background and leaves the alpha channel untouched (the X11 overlay window owns transparency, we never want a hole punched through the badge layer).

  Tests cover:

  • the new phase transitions (PreflightStarted → Validating, success → Idle, failure → Error, RetryScheduled inside vs. outside Validating);
  • Phase::color returning green at 0.5 for Validating and green at 1.0 for Done, plus a regression check that every non-validating phase renders at full opacity;
  • render_retry_counter painting nothing for attempt 0, visible pixels for attempt >= 1, and being measurably dimmer at half opacity (skip-clean if no system font is installed);
  • PixelBuffer::blend_pixel at 0.0 / 0.5 / 1.0 / clamp / OOB.

• [picker, transcription] reliable picker transcription with live status, validation cache, and timeout attribution. [Valentin Lab]

  Three coupled changes that together make the picker UI usable on flaky networks (notably VPNs that drop connection attempts mid-flight):

  1. RequestTimeoutPolicy enum + TranscribeOptions struct. Picker rows run under UserAttended: no per-request wall-clock cap, only the client-wide connect_timeout plus TCP-level defences (tcp_user_timeout, TCP keepalive). Slow servers no longer trip a 3-second wall-clock that fires after a successful connect. Autonomous callers (dictate end-of-recording, transcribe CLI, produce_transcript) keep the previous Proportional policy so an unattended pipeline cannot hang. Threaded through transcribe_audio, create_batch_transcriber, and the with_policy constructors on MistralBatchTranscriber / OpenAIBatchTranscriber.

  2. Disk-backed validation cache for /v1/models (\$XDG_CACHE_HOME/talk-rs/validate-cache.yaml, 24-hour TTL, atomic tempfile + rename). Successful preflights memoize, so subsequent transcriptions for the same (provider, model, api_base) skip the network entirely within the TTL. Writes are atomic and last-writer-wins; corrupt cache files fall through to network rather than panicking. On cache miss the preflight runs a growing-budget retry of [2, 5, 8, 11, 15] seconds across 5 attempts so a transient connect blip cannot doom the whole transcription on the first attempt; permanent errors (HTTP 4xx, model-not-found) bail without retry. The user-facing error now leads with "<Provider> model validation failed (preflight to /v1/models)" so the failed concern is unambiguous (the prior lead phrase "Failed to connect to <Provider> API" falsely implied the transcription itself failed).

  3. Live status display in picker candidate rows. New PickerStatusSink translates HTTP-pipeline telemetry into short italic strings rendered at 0.55 opacity in place of the transcript area: pre-validating model… (cache-miss only), connecting…, uploading…, waiting for server…, transcribing…, retry N/M…. Final candidate (success or error) replaces the status with the actual transcript or error. Action button tooltip mirrors the status while in-flight and clears on terminal events. Realtime rows are left alone — their partial transcript already serves as status. New TranscriptionEvent::PreflightStarted / PreflightCompleted variants surface the validate phase to any sink (only emitted on cache miss); PreflightCompleted is silent on the picker so the next event replaces the line without flicker.

  Also includes the diagnostic logging that enabled this fix: TimerSpec slice + format_reqwest_error_with_timers make reqwest error messages name which timer fired (connect_timeout, request_wall_clock, validate_request, or kernel_tcp_unspecified) and quote its budget, so log readers no longer have to correlate elapsed time against client state to identify a timeout source.

  New module: src/transcription/transport/validate_cache.rs. New tests: 8 cache tests, 4 validate_model tests covering schedule + cache-hit + retry semantics, 7 PickerStatusSink tests covering phase transitions / dedup / cache-hit / preflight silence, plus the user_attended_policy_omits_request_wall_clock_attribution regression detector. 389 → 404 lib tests passing, 0 failures.

  The stale comment at picker/backend.rs:152-155 claiming "no artificial outer timeout is needed" is updated to describe the actual UserAttended semantics.

• [audio, dictate, record] Bluetooth headset HFP auto-switch. [Valentin Lab]

  When a Bluetooth headset is connected in A2DP mode (high-quality stereo output, no microphone), talk-rs now automatically switches it to its Hands-Free Profile (HFP) for the duration of a recording so the headset microphone is enabled, then restores the original profile on stop. This replaces the equivalent feature of the legacy memo shell script and removes the need to manually toggle profiles when dictating with a Bluetooth headset.

  Detection uses PulseAudio's standard device.form_factor = "headset" property (not vendor-specific identifiers), with a fallback for stacks that omit form_factor (matches bluez_card.* cards exposing a headset-head-unit* profile). Profile selection prefers headset-head-unit-msbc (16 kHz wideband) → headset-head-unit-cvsd (8 kHz narrowband) → headset-head-unit (generic), all of which are PulseAudio-standard names.

  Crash resilience: the saved profile is persisted to $XDG_RUNTIME_DIR/talk-rs/card-profile.json BEFORE the switch, so an unclean termination (SIGKILL, power loss) leaves a recoverable state file behind. A new recover_stale_profile() runs at the start of every live-capture command and restores the profile from that file before activating HFP for the new recording — so even after a crash mid-recording the user gets A2DP back on next launch. This is a real improvement over memo, which overwrote its state file on start and could permanently lose the original profile after a crash.

  Implementation uses libpulse-binding v2.30 — pure Rust, no pactl subprocess and no D-Bus. On PipeWire systems, pipewire-pulse provides libpulse.so as a compatibility shim, so pa_context_set_card_profile_by_name reaches the right device through WirePlumber. This avoids stdout parsing and keeps error handling fully typed. Build dependency added: libpulse-dev (Debian/Ubuntu) / pulseaudio-libs-devel (Fedora).

  A new HeadsetGuard RAII type holds the saved profile and restores it on Drop, so the original profile is restored on normal return, ?-propagated errors, panics, and SIGINT-driven daemon exits — no need to thread explicit restore calls through every exit path.

  Configurable via:

  • --no-bt-auto-switch CLI flag on both dictate and record (also forwarded to the spawned daemon by --toggle).
  • audio.bt_auto_switch config key (default true).
  • TALK_RS_AUDIO_BT_AUTO_SWITCH env var (true/false/yes/no/1/0/on/off).
  • File-input dictation paths (--input-audio-file, --retry-last) skip the switch since they don't touch the mic.

  All bt_profile failures are non-fatal: they log a warning and let the recording proceed on whatever input device is currently active.

  Verified end-to-end:

  • 14 new unit tests in src/audio/bt_profile.rs (profile picker, headset detection, JSON round-trip, state-file path resolution, guard drop semantics).
  • tests/bt_profile_smoke.rs integration test (gated #[ignore]
    • TALK_RS_BT_INTEGRATION=1) runs a real A2DP→HFP→A2DP round-trip against the running PulseAudio/pipewire-pulse server.
  • Full cargo fmt, cargo clippy --all-targets, cargo test, cargo build, cargo build --release clean.

• [transcription, record] surface cached transcripts in the recordings browser. [Valentin Lab]

  Adds read_cached_transcript() in src/transcription/mod.rs -- a synchronous, network-free waterfall that returns a transcript for an audio file by walking, in priority order:

  1. The pick file (<stem>.pick.yml) -- the authoritative, possibly user-edited transcript.
  2. The default-provider / default-model batch sidecar.
  3. None -- nothing cached.

  The recordings browser (record --ui) in src/record/entries.rs now uses this waterfall in both list_ogg_recordings and list_cache_recordings so an entry shows its transcript whenever one is cheaply available -- not only when it has been pick-finalised. The InProgress state from the pick lock still wins so the UI can keep displaying "transcription ongoing" for in-flight runs.

• [transcription] persist per-segment timing in YAML sidecar. [Valentin Lab]

  Providers already return timed transcript segments (Voxtral batch, Whisper verbose_json, Voxtral realtime), but talk-rs was discarding everything except a segment_count integer. This commit preserves the (start, end, text) tuples all the way from the API response to the YAML sidecar so downstream consumers such as activity-memo can reconstruct sub-minute timelines without re-transcribing.

  Data model (src/transcription/mod.rs):

  New TranscriptSegment struct and an optional segments field on TranscriptionResult. A shared parse_transcript_segments helper extracts start/end/text from raw serde_json::Value slices, used by both Mistral and OpenAI parsers.

  Mistral batch (src/transcription/mistral.rs):

  Both transcribe_file and transcribe_stream now call parse_transcript_segments on the response segments array. Voxtral returns segments by default with speaker_id: null when diarization is not requested — those were previously skipped by parse_diarization_segments (which requires a non-null speaker_id). Both extractions now coexist: diarization segments for --diarize users, transcript segments for everyone.

  OpenAI batch (src/transcription/openai.rs):

  response_format is now verbose_json for whisper models (which support it) and stays json for GPT-4o transcribe models (which do not). verbose_json causes Whisper to return a segments array with start/end/text — parsed the same way as Voxtral.

  Realtime (src/dictate/realtime.rs, src/dictate/picker/backend.rs):

  SegmentDelta events are now destructured as { text, start, end } instead of { text, .. }. A parallel Vec<TranscriptSegment> accumulator captures timed segments alongside the existing text accumulator. The picker UI state (picker/ui.rs) carries segments through candidate selection.

  YAML sidecar (src/recording_cache.rs):

  New CommonSegment struct with #[derive(Serialize)]. RecordingMetadata gains an optional segments field (skip_serializing_if = Option::is_none). write_metadata accepts an extra segments: Option<&[TranscriptSegment]> parameter; call sites in dictate/mod.rs and dictate/picker/mod.rs pass result.segments.as_deref().

  Resulting YAML when segments are present:

  segments:
  - start: 0.0
    end: 1.5
    text: Hello world.
  - start: 2.0
    end: 3.8
    text: This is a test.
  

  Absent when the provider returned no segments (old files, GPT-4o, realtime sessions where the server omits timing).

  Backward compatibility: existing YAML files without segments: continue to work. The field is purely additive.

  Tests: unit tests for parse_transcript_segments (valid, malformed, empty, mixed); YAML serialization with/without segments; wiremock integration tests in both mistral.rs and openai.rs using a new tests/fixtures/voxtral-response.json fixture.

• [overlay, indicator] add centered no-sound overlay and alert tones. [Valentin Lab]

  When the overlay detects a dead audio device (no-sound), a large semi-transparent overlay now appears at the centre of the screen with a prohibit icon, "NO SOUND" title, and "No audio detected" subtitle. The overlay uses per-pixel ARGB alpha (80% opacity) when a compositor is available, falling back to solid black otherwise.

  A periodic alert tone (triple-pulse at 550 Hz) plays every 2 seconds while no-sound is active, and the regular boop heartbeat is suppressed to avoid colliding sounds. An AlertPlayer handle allows the silence-notifier thread to play sounds without owning the full SoundPlayer.

  Also fixes the badge prohibit icon regression introduced in commit 31d99f0: that commit enlarged DOT_RADIUS_MAX from 10 to 21 for the volume-reactive dot, but the prohibit icon shared that constant, making its stroke look disproportionately thin. A dedicated PROHIBIT_ICON_RADIUS (10.0) now restores the original proportions. The rendering logic is factored into draw_prohibit_icon_with_stroke (parameterised stroke) with draw_prohibit_icon as a thin wrapper.

• [overlay] add time-grid layer over the waterfall spectrogram. [Valentin Lab]

  Draw vertical dotted yellow marks every wall-clock second, alpha-blended at 60% over the existing waterfall pixels. Each mark is a column of alternating 1 px dot / 1 px gap in pure yellow (BGR [0, 255, 255]). Destination alpha is left untouched to preserve window opacity.

  Grid alignment uses columns_pushed_total, an absolute column counter that resets together with spectrogram_history. Marks are placed where abs_idx % COLUMNS_PER_GRID_MARK == 0 and right-aligned the same way the waterfall itself is. The counter increments even during auto-pause empty-column pushes so the grid reflects true elapsed time including silent gaps.

  render_time_grid is called in both the normal recording path and the auto-pause path, after the waterfall and badges but before the pulsing dot / LISTENING indicator.

  Alpha was initially set to 0.3 but proved too subtle on real spectrograms; bumped to 0.6 after visual testing.

  This establishes the rendering pattern — absolute-index layer drawn over the scrolling waterfall — that future event overlays (network phase colors, byte-count bars) will follow.

• [transcription] add ProgressBody stream wrapper for upload telemetry. [Valentin Lab]

  Add a futures::Stream wrapper that sits between a Vec<u8> audio payload and reqwest::Body::wrap_stream, emitting telemetry events as bytes flow through:

  • ConnectionEstablished on the first poll_next (proxy for TCP+TLS handshake completion)
  • UploadProgress { bytes_sent, total, t } on every yielded chunk
  • UploadComplete { total, t } exactly once at stream exhaustion

  Boolean guards (emitted_connection, emitted_complete) prevent duplicate events if the runtime re-polls a terminal position.

  Chunk size is controlled by PROGRESS_BODY_CHUNK_BYTES (8 KiB). A len() accessor exposes the total byte count so callers can set Content-Length on multipart parts.

  Six unit tests cover empty buffers, single-chunk and multi-chunk bodies, cumulative byte accounting, and the exactly-once guarantees for connection and completion events.

  #[allow(dead_code)] annotations carry inline justification comments; the struct is wired into mistral.rs / openai.rs in sub-phase 1C and the pragmas will be removed at that point.

• [telemetry] add display-agnostic transcription event module. [Valentin Lab]

  Introduce src/telemetry/mod.rs with the foundational types for observing the HTTP transcription lifecycle without coupling to any display or pipeline module.

  Contents:

  • TranscriptionEvent enum (13 variants covering request start through paste completion, each carrying a monotonic Instant timestamp).
  • TelemetrySink trait (Send + Sync, single emit method) so producers can hold Arc<dyn TelemetrySink> without locking at the API boundary.
  • NoOpSink — zero-cost default that drops every event; useful for tests and headless code paths.
  • BroadcastSink — wraps tokio::sync::broadcast to fan events to any number of subscribers, dropping silently on lag or when no receivers are attached.
  • 7 unit tests covering sink behaviors, Arc<dyn> usage, receiver lifecycle, and a Clone smoke test over all event variants.

  The module enforces a strict dependency rule: it imports nothing from crate::x11, crate::audio, crate::dictate, or any other display/pipeline module. Display adapters will depend on telemetry, never the reverse.

  This is sub-phase 1A of the telemetry system — pure skeleton with no consumers or producers wired yet. Later sub-phases will integrate event emission into the HTTP transcription path (1B/1C) and connect the X11 overlay as a consumer (1D).

• [record] show waterfall spectrogram for recordings without transcripts. [Valentin Lab]

  Recordings without a transcript preview now display an inline waterfall spectrogram instead of blank space. A single background worker thread computes the FFT data sequentially with yields between items to keep CPU usage low. Both WAV and OGG files are supported via a new read_audio_as_i16 helper.

• [dictate] add OGG format support with cache optimization. [Valentin Lab]

  Add --upload-format <wav|ogg> CLI flag to enable OGG Opus encoding during dictation. When OGG is selected, the encoder tees bytes to a cache file, allowing retries to use the smaller OGG file (164 KB vs 1.2 MB WAV).

  Also extend --input-audio-file to accept OGG Opus files, auto-detected by extension and decoded via ogg + opus crates into PCM i16 chunks through the AudioCapture trait.

  Changes:

  • src/transcription/mod.rs: add UploadFormat enum (shared, clap::ValueEnum)
  • src/cli/def.rs: add --upload-format argument
  • src/cli/action/mod.rs: plumb upload_format through action dispatch
  • src/dictate/mod.rs: compute OGG cache path, pass to streaming, use in retry
  • src/dictate/streaming.rs: spawn encode pipeline that tees OGG to cache
  • src/dictate/toggle.rs: forward --upload-format to daemon
  • src/audio/file_source.rs: add OggFileSource for OGG Opus decoding

• [dictate] add --no-paste flag and pipeline timing instrumentation. [Valentin Lab]

  --no-paste skips pasting the transcription into the focused application (useful for benchmarking or headless use).

  Add t_stop timing from recording stop through capture, WAV flush, transcription, and first paste, logged at info level for end-to-end latency analysis.

• [picker] write companion recording metadata YAML on text changes. [Valentin Lab]

  Save a metadata YAML alongside the WAV so the record UI can display transcript previews via its inotify watcher. Keyboard edits are debounced (1 s); programmatic changes (row selection, API result arrival) and window close are immediate. Also updates the copy-to-clipboard icon from U+2398 to U+29C9 for consistency with the record UI.

• [record] add dictate button and update copy icon in recordings UI. [Valentin Lab]

  Add a "Transcribe recording" button on WAV files that have no transcription yet — launches dictate --pick with the audio file. Change the copy-to-clipboard icon from U+2398 to U+29C9. Wire up .dictate-btn CSS class for consistent button sizing.

• [record] add copy-to-clipboard button for dictation transcripts. [Valentin Lab]

• [transcription] add configurable base URL for Mistral and OpenAI providers. [Valentin Lab]

  Allow overriding the API base URL for both Mistral and OpenAI via the url config field or TALK_RS_PROVIDERS_MISTRAL_URL / TALK_RS_PROVIDERS_OPENAI_URL environment variables. This lets users point at self-hosted or API-compatible endpoints.

  Batch transcription endpoints append /v1/audio/transcriptions to the base URL; realtime WebSocket endpoints convert the HTTP(S) scheme to WS(S). Trailing slashes are trimmed automatically.

• [record] add resizable window, close button, and edge resize to record --ui [Valentin Lab]

  Factorize undecorated-window helpers (build_title_bar, install_edge_resize, close-btn CSS) into gtk_theme so both the picker and the recordings browser share a single implementation. The picker is refactored to call the shared helpers; the recordings browser gains the same resize + close-button UX.

• [picker] add character-level diff highlighting, editable text area, and copy button. [Valentin Lab]

  Integrate dissimilar crate for live character-level diff between the original transcription and each candidate label: red strikethrough for deletions, green background for insertions (both at 50% opacity). Add escape_pango() and diff_markup() helpers for safe Pango markup generation. Include an editable text area pre-populated on row selection and a copy-to-clipboard button in the picker popup; edited text is used on confirm.

• [picker] add waterfall spectrogram with playback controls and drag-to-seek. [Valentin Lab]

  Render a frequency-vs-time waterfall strip above the candidate list using generate_waterfall_columns() computed on a background thread. A translucent cursor overlay tracks playback position with sub-buffer interpolation for smooth movement.

  Player gains pause()/resume()/seek()/progress() methods. The play button switches to Adwaita media icons and a shared playing_flag replaces fragile label-text checks. A rewind button and GestureDrag on the waterfall provide drag-to-seek (auto-pauses during drag, resumes on release).

  README.org updated to mention the waterfall in the picker feature list.

Changes

• [transcription] always normalize file uploads to 16 kHz mono OGG [Valentin Lab]

  Batch File uploads were sent to the providers verbatim. With the new high-quality record output (48 kHz, up to 128 kbps), that meant uploading far more data than either provider can use: Mistral Voxtral and OpenAI Whisper / gpt-4o-transcribe both downsample to 16 kHz mono internally and ignore everything above 8 kHz. Sending richer audio only wastes bandwidth, adds latency, and risks OpenAI's 25 MB cap — for zero accuracy gain.

  Add normalize_file_for_upload (a single chokepoint shared by both the Mistral and OpenAI batch transcribers): it decodes any supported file via read_audio_as_i16 (resampling to 16 kHz and downmixing to mono) and re-encodes to OGG/Opus before upload, advertising an .ogg file name. Decode failures fall back to the original bytes so an upload that worked before keeps working. The live streaming path is untouched — it already emits 16 kHz mono.

  Adds tests covering stereo-44.1kHz to mono downmix, mono passthrough, the missing-file error, and the undecodable-file raw-bytes fallback.

• [transcription] route realtime WS through unified transport. [Valentin Lab]

  Steps 6-9 of the transport-consolidation plan at .sisyphus/plans/transport-consolidation.md.

  Step 6 (transport ws_upgrade): the WS upgrade handshake now shares the same growing-budget connection-retry schedule (CONNECTION_BUDGETS_SECS = [2, 5, 8, 11, 15]) as http_request, wrapping each tokio_tungstenite::connect_async attempt in a tokio::time::timeout so blackholes don't hang for the OS-default ~125s TCP SYN timeout. Cancellation is wired through the same tokio::select pattern. Tungstenite errors classify into connect-retryable (Io, Tls, ConnectionClosed, AlreadyClosed) vs permanent (Http, protocol violations).

  Step 7 (realtime migration): MistralRealtimeTranscriber::transcribe_realtime and OpenAIRealtimeTranscriber::transcribe_realtime swap their with_retry + connect_async blocks for a single ws_upgrade call each. Same for the validate_realtime_session helpers. Provider-specific headers (OpenAI-Beta: realtime=v1) are passed verbatim to the transport.

  The picker's "click T on realtime, nothing happens" symptom diagnosed in plan section 1 dot 12 and Step 8 is structurally fixed by this commit: the upgrade now uses the growing-budget schedule (2+5+8+11+15 = 41s total instead of 5x15 = 75s) and emits ConnectionEvent::RetryScheduled events. Step 10 wires those events to the picker's UI sink to make the retries visible to the user.

  Step 9 (delete legacy primitives): delete transcription/transport/retry.rs entirely (with_retry, MAX_RETRIES, and 5 unit tests). Delete CONNECT_TIMEOUT and build_client from transport/http.rs. Delete WS_CONNECT_TIMEOUT from both realtime modules.

  Outside the transport module, the words "retry" and "attempt" do not appear anywhere related to network calls; paste.rs::FOCUS_MAX_RETRIES is the only remaining MAX_RETRIES and it governs X11 window focus, an unrelated concern.

  Test status: 433 lib tests green (down from 438 -- the 5 retry tests are gone with the file). 6/10 transport_integration tests green; the remaining 4 are jobs-registry placeholders explicitly deferred to Step 11.

  Net diff: -521 / +419 (transport surface keeps growing while realtime and http.rs shrink).

• [transcription] migrate batch + validate + model-suggestions to http_request [Valentin Lab]

  Steps 3-5 of the transport-consolidation plan at .sisyphus/plans/transport-consolidation.md.

  After this commit, every batch HTTP call to a transcription provider funnels through transport::http_request:

  • transport::http::validate_model (validate preflight) — its in-line growing-budget loop is deleted; the new transport's CONNECTION_BUDGETS_SECS covers the same [2, 5, 8, 11, 15] schedule.
  • MistralBatchTranscriber::send_request — send_once is gone, the multipart form is built by a factory closure that the transport invokes per retry (RequestBody::Multipart accepts a Box<dyn Fn() -> reqwest::multipart::Form + Send + Sync> because reqwest::multipart::Form is not Clone).
  • OpenAIBatchTranscriber::send_request — same treatment as Mistral.
  • model_suggestions::fetch_transcription_models — its 5-attempt in-line retry loop is deleted; the transport handles retries. Stale-cache fallback preserved.

  The notorious attempts=1, max_attempts=1 lie at mistral.rs:359 and openai.rs:316 is removed: the providers no longer build PipelineFailure themselves, so the http_request truthful counter (already in place from Step 2) now surfaces correctly to every batch call site.

  transport/http.rs::build_client and CONNECT_TIMEOUT are marked #[allow(dead_code)] with a TODO pointing at Step 9 (which deletes them entirely along with the legacy with_retry path). They're retained transiently because the realtime modules (realtime.rs / openai_realtime.rs) still use the legacy with_retry upgrade path — Steps 6-7 migrate those to ws_upgrade.

  RequestBody::Bytes now wraps Arc<Vec<u8>> so the transport can .clone() the audio buffer cheaply across retries.

  Test changes:

  • validate_model_emits_one_retry_event_per_retry becomes validate_model_does_not_retry_on_malformed_response_body. Behaviour change rationale documented in the test: decode is a content failure, not a transport failure; mid-body truncation was already covered by the connection-retry layer. The pin on the schedule [2, 5, 8, 11, 15] moves to transport_connection_phase_retries_with_growing_budget in tests/transport_integration.rs.

  Test status: 438/438 lib tests green, 21/22 integration suites green; transport_integration keeps the 5 still-RED tests for Step 6 (ws_upgrade) and Step 11 (jobs registry).

  Net diff: -284 lines (697 → 413) with strictly better correctness.

• [transcription, error] consolidate HTTP pipeline failures into structured TalkError::Pipeline [Valentin Lab]

  Replaces the older pattern of stuffing reqwest failures into TalkError::Config(String) / TalkError::Transcription(String) with a single structured variant TalkError::Pipeline(Box<PipelineFailure>) that carries the provider, phase, attempts/max counts, URL, and a typed PipelineFailureKind (Network / HttpStatus / ModelRejected / Decode).

  Motivation: the prior string-format helper format_reqwest_error_with_timers produced messages like:

  Configuration error: OpenAI model validation failed
  (preflight to /v1/models): error sending request for url
  (https://...) [kind=timeout, name=connect_timeout, budget=2s,
  url=https://...] -> client error (Connect) -> operation timed out
  

  Three problems with that output:

  1. Configuration error: prefix was misleading — a network timeout against the preflight endpoint is not a config issue.
  2. The URL was printed twice (once in the reqwest::Error preamble, once in the [url=...] tag).
  3. The trailing chain layers client error (Connect) and operation timed out just restated what name=connect_timeout already conveyed; the verbosity drowned out useful layers like DNS lookup failures or ECONNREFUSED (os error 111).

  The new PipelineFailure::Display impl produces a clean one-liner with structural source-chain dedup:

  Mistral model validation failed [name=connect_timeout,
  budget=2s, url=https://mistral.vps-03.0k.io/v1/models]
  (after 5/5 attempts)
  

  DNS / ECONNREFUSED / TLS layers are kept (they add information not in the structured fields); client error (Connect), operation timed out, etc. are dropped.

  Architectural consolidation (per architectural-consolidation.md):

  • Outcome A on TalkError — extended the existing error vocabulary with one new variant rather than introducing a parallel PreflightError / RequestError type. Boxed to keep Result<T, TalkError> stack size sane.
  • Outcome B on the formatter — the responsibility "render a reqwest failure as text" moved out of format_reqwest_error_with_timers and into PipelineFailure::Display. The transport layer keeps the reqwest-classification mechanics (classify_reqwest_error, build_pipeline_failure_kind, TimerSpec → TimerLabel conversion); the error layer knows how to display the structured value. No reqwest types leak into error.rs.
  • Outcome A on TranscriptionEvent — no new events invented; the existing RetryScheduled is now emitted between attempts of the validate-cache-miss retry loop, with attempt = 1..=4 / max = 4 for the 5-attempt budget. Same vocabulary as the existing with_retry for the transcription request, so the picker UI's retry N/M… rendering covers both phases without picker code changes.
  • Structural-first model-error detection — the bail-on-permanent logic in with_retry now matches PipelineFailureKind::ModelRejected structurally before falling back to the legacy string match. Pre-migration call sites that still produce string-stuffed errors continue to work; structural producers always win.

  Scope: in scope for this change is the HTTP preflight (validate) and batch HTTP transcription request paths. Realtime/WebSocket transport (MistralRealtimeTranscriber, OpenAIRealtimeTranscriber) stays on the legacy TalkError::Transcription(String) shape — it has different transport semantics (WS upgrade, session events) and is a separate consolidation when the user wants it.

  User-visible effect: picker rows now show pre-validating model… followed by retry 1/4…, retry 2/4…, retry 3/4…, retry 4/4… during the validate-phase retries (this was the missing-progress complaint). When validation or transcription ultimately fails, the error message lacks the Configuration error: prefix, prints the URL once, and dedups restatement layers so only novel information remains in the chain.

  Files touched:

  • src/error.rs: new Pipeline variant, PipelineFailure struct, PipelinePhase / PipelineFailureKind / NetworkKind / TimerLabel types, Display impl with source-chain dedup heuristic. 7 unit tests for Display variants, dedup, and From<PipelineFailure> transparency.
  • src/transcription/transport/http.rs: removed format_reqwest_error_with_timers and attribute_timer; added build_pipeline_failure_kind and inner classify_reqwest_error helper. Reworked validate_model_uncached to take a sink, emit RetryScheduled between attempts, and return structured Pipeline errors. Replaced 5 legacy string-format tests with 5 structural classifier tests; added 3 new tests covering retry-event emission and structural is_model_error.
  • src/transcription/mistral.rs, src/transcription/openai.rs: send_once produces PipelineFailure { phase: Request, .. } instead of string-stuffed Transcription(String). Updated the user_attended_policy_omits_request_wall_clock_attribution regression test to assert on the structured shape.
  • src/transcription/mod.rs: is_model_error structural fast path on PipelineFailureKind::ModelRejected; legacy string match preserved as fallback.

  Verification: cargo fmt clean, cargo clippy --all-targets clean, cargo test 428 passed / 0 failed, cargo build and cargo build --release both succeed. No new unwrap()/expect() outside #[cfg(test)]; no trailing whitespace; no dead-code pragmas.

• [audio, dictate] gate periodic boop on auto-pause LISTENING state. [Valentin Lab]

  The periodic boop heartbeat used to play unconditionally for the entire recording, including while the user was actively speaking. The user's mental model is that boops belong to the yellow LISTENING badge — i.e. the auto-pause state where audio forwarding is held back during silence. Make the implementation match that model.

  • Extend SoundPlayer::start_boop_loop with a positive play_when gate (in addition to the existing negative suppress gate). Boops fire iff play_when_ok && !suppressed.
  • Wire the overlay's existing pause_flag atomic into play_when at the call site in dictate. No new shared state — the same flag the audio tee already consumes for sample gating.
  • Anchor the interval clock to the rising edge of play_when, not to loop creation. The first boop after entering LISTENING always lands a full interval later — never sooner — and brief silences shorter than interval produce zero boops. A falling edge mid-period cancels the in-flight wait so the next listening period starts a fresh clock.
  • Extract the loop body into a free run_boop_loop async function so the state machine is unit-testable without an audio device.

  Side effects: with --no-auto-pause the boop is silent for the entire recording (the gate never opens), which is consistent with the user's mental model. The dead-signal alert path still suppresses boops in-place via suppress and does NOT reset the phase, so the alert tone continues to stand alone.

  Tests cover: ungated periodic firing, gated-off silence, suppress-overrides-play-when, the phase-reset invariant on the rising edge, and the no-emit guarantee for sub-interval listening bursts.

• [picker] unify row order, add T/↻ action button, preserve text area. [Valentin Lab]

  Three connected picker UX fixes that all live in src/dictate/picker/ui.rs:

  1. Deterministic row order. Previously rows were appended in four buckets (cached, batch-pending, realtime-pending, deferred), so a given (provider, model, streaming) triple's screen position depended on whether it had a cached transcription -- the order shifted as results arrived. Now all rows go through one unified sort on (provider_rank, model, streaming) where the config's default provider gets rank 0 and others rank 1 (alphabetical among them), and a single loop renders them.

  2. Unified T/↻ action button. Replaces the previous ▶ deferred-transcribe button (only on never-run rows) and ↻ retry button (only on errored rows) with a single action button present on every row in the leftmost column. Icon is T when the row has no transcription (first run / spinner / deferred / error / "no speech detected") and ↻ once a non-empty transcript exists -- so the user can always re-run a model, including successful ones. Button is sized 28x28 with padding: 0 to match the play/copy icon footprint.

  3. Preserve text area on non-transcribed rows. A new per-row has_transcription: Rc<RefCell<Vec<bool>>> tracks whether the row currently holds a non-empty transcript. In connect_row_selected the buf_sel.set_text(text) call is now guarded by this flag, so selecting a spinner / deferred / error / empty-result row no longer wipes whatever the user is viewing or editing. The flag flips true on first non-empty Candidate/StreamUpdate arrival, false on user retry-click, error, and InitialBatchDone "no response".

  Verified locally with ./autogen.sh, cargo fmt, cargo clippy --all-targets, cargo test, cargo build, cargo build --release, plus a live UI smoke test confirming row order is content-independent, the action button is leftmost and square, and selecting a non-transcribed row leaves the text area intact.

• [transcription, dictate, record] pick-file waterfall + shared retry. [Valentin Lab]

  Introduce a layered cache architecture for transcription:

  • Layer 1 (recording_cache): <stem>.pick.yml is the authoritative transcript for a recording. get_transcript returns Available(text) / InProgress / NotAvailable. Locks (<stem>.pick-lock.yml) coordinate producers.
  • Layer 2 (produce_transcript): check pick, acquire lock, delegate to Layer 3, write pick, release lock. Used by transcribe command (default options) and by dictate Mode C (file input, default options).
  • Layer 3 (transcribe_audio): per-model sidecar cache (<stem>_<provider>_<model>_<mode>.yml) + per-model lock. New allow_api: bool parameter lets the picker probe the cache without triggering API calls; returns CacheOnly on miss.
  • Layer 4 (src/transcription/transport/): single retry primitive with_retry used by both batch HTTP POST and realtime WebSocket upgrade. The 85-line retry loop in src/dictate/mod.rs is removed.

  Concept consolidation:

  • BatchTranscriber::transcribe_file and transcribe_stream collapse into one fetch_transcription(body: TranscriptionBody) method. The trait is now pub(crate) — outside callers go through transcribe_audio or produce_transcript.
  • RealtimeTranscriber is also pub(crate). Its WebSocket upgrade handshake is now wrapped in the shared with_retry.
  • src/transcription/http.rs moves to src/transcription/transport/http.rs.

  Consumer changes:

  • dictate writes a pick on every successful transcription unless a specific provider/model/diarize option is given. Mode C (--retry-last / --input-audio-file with default options) short-circuits: if a pick exists, paste it directly.
  • transcribe command's default branch now polls get_transcript on TranscriptInProgress.
  • Record UI reads the pick file only — no sidecar fallback. Displays (no text) for empty picks, (transcription ongoing) for in-progress, audio player when no pick exists.
  • Picker probes the sidecar cache via transcribe_audio(allow_api=false) instead of enumerating sidecar files directly; only the default model auto-transcribes, other models show a transcribe button.
  • Old picker JSON cache (~/.cache/talk-rs/picker-results/) is deleted — src/dictate/picker/cache.rs removed.

  Error variants added: TranscriptInProgress, CacheOnly, ModelInProgress.

  Telemetry: Arc<dyn TelemetrySink> threaded from CLI through produce_transcript / transcribe_audio / BatchTranscriber::fetch_transcription / with_retry / ProgressBody — retry events observable by the UI visualizer without any new propagation mechanism.

  Tests: 350 pass, up from 330. New unit tests cover the retry primitive (initial-success, transient-then-success, model-error bail, exhaustion), get_transcript state machine, pick-lock acquire/release idempotence, per-model lock independence, and pick round-trip.

• [transcription] unify all batch transcription behind one function and one cache. [Valentin Lab]

  Every batch-from-file transcription now goes through a single entry point transcription::transcribe_audio which checks a sidecar cache before calling the provider and stores the result after. Callers never see the cache.

  recording_cache::TranscriptionCache provides the abstract cache API (get / store). Storage is currently YAML files next to the source audio; the implementation detail is hidden. All sidecar types gain Deserialize so cached results can be read back into a TranscriptionResult.

  src/transcribe.rs (CLI talk-rs transcribe) collapses to config resolution + one transcribe_audio call + output. The manual transcriber creation, sidecar writing, and model-name resolution are gone.

  src/dictate/picker/backend.rs now takes Arc<Config> instead of pre-built Box<dyn BatchTranscriber> and calls transcribe_audio. The picker no longer creates transcribers itself (picker/mod.rs, picker/ui.rs); re-opening the picker on the same audio file hits the cache and returns instantly.

  src/dictate/mod.rs retry loop uses transcribe_audio (cache may short-circuit repeated retries on the same OGG). The streaming and realtime paths — which cannot use transcribe_audio because the audio file does not exist at transcription start — now call TranscriptionCache::store after completion, followed by a separate write_last_pointers for dictate-specific symlinks.

  write_recording_metadata (picker/mod.rs) is deleted. The picker no longer overwrites provider sidecars on text-edit or selection — that is a future <stem>.yml user-selection sidecar concern.

  timestamp_granularities is now sent unconditionally on all Mistral API requests (not just --diarize), restoring per-segment timing from voxtral-mini-2602+ which requires the explicit parameter.

• [telemetry, transcription, overlay, paste] add three independent-scale throughput tracks with download byte streaming and paste character tracking. [Valentin Lab]

  Transcription backends (mistral, openai) now stream the HTTP response body via bytes_stream() instead of buffering the whole JSON payload, emitting per-chunk DownloadProgress events as bytes arrive.

  paste_text_to_target accepts a TelemetrySink and emits PasteProgress after each chunk so the overlay can visualise paste throughput alongside upload and download.

  The overlay replaces the single upload throughput bar with three independent tracks (upload, download, paste), each owning its own 16 px budget, peak tracking, and history ring buffer. Independent scales ensure a ~1 KB JSON download is visually comparable to a ~100 KB audio upload — shared-budget scaling made the smaller track invisible at a 500:1 byte ratio.

• [dictate] keep overlay visible during paste and emit paste telemetry events. [Valentin Lab]

  Move o.hide() after paste_text_to_target() so the overlay (dimmed waterfall, phase colours, throughput bars) stays on screen throughout the paste phase.

  Emit TranscriptionEvent::PasteStarted before paste and TranscriptionEvent::PasteCompleted after it, so the overlay phase state machine shows a green band during paste (PasteStarted → Done, PasteCompleted → Idle).

• [overlay, transcription] add upload throughput bars and fix dead-signal gate during transcription. [Valentin Lab]

  Layer 3b throughput bars: each waterfall column now draws a phase-coloured vertical bar growing downward from the phase line, proportional to the upload bytes transferred in that time slice (peak-normalised, max 48 px). New state tracks current_upload_bytes, prev_upload_bytes, upload_peak_delta, and a parallel throughput_history vec. Bars render in all three display branches (transcribing, auto-paused, normal).

  Dead-signal gate fix: column-push was gated on !no_sound_active, which blocked all pushes during transcription because capture.stop() makes the ring buffer go stale and the dead-signal detector fires. Changed to (!no_sound_active || is_transcribing) so columns keep advancing. Also reordered render branches so is_transcribing takes priority over no_sound_active, preventing the "NO SOUND" icon from hiding the transcribing waterfall.

  ProgressBody wrapping for retries: transcribe_file in both mistral.rs and openai.rs now reads the audio into a Vec<u8> and wraps it with ProgressBody + Body::wrap_stream, so retry attempts emit upload telemetry and throughput bars are visible during file-based retries.

• [overlay, dictate] replace static transcribing badge with dynamic phase-colour waterfall. [Valentin Lab]

  The static "transcribing" PNG badge is replaced by a live render that keeps the 60 fps waterfall loop running through the transcription phase:

  • Waterfall continues scrolling with empty columns at 30 % brightness, making elapsed transcription time visible at a glance.
  • A 2-pixel phase-colour line at the top of the spectrogram area shows the HTTP lifecycle in real time: connecting (dim blue), uploading (bright blue), waiting for server response (amber), receiving (teal), done (green), error (red).
  • "TRANSCRIBING" text is rendered in light blue, following the same pattern as the auto-pause "LISTENING" overlay.
  • The telemetry broadcast::Receiver is wired from the BroadcastSink broker (created in dictate) into the overlay thread; events are drained non-blockingly each frame via try_recv().
  • Broker creation in src/dictate/mod.rs is moved before the overlay so the receiver is available at construction time.

  The static PNG path is kept as a fallback for the edge case where Transcribing is received outside an active recording session. Layer 3b (byte-throughput bars) is deferred to a later commit.

• [transcription, dictate] wire telemetry events into batch transcription paths. [Valentin Lab]

  Add set_sink method to the BatchTranscriber trait with a default no-op implementation so concrete backends can accept a TelemetrySink.

  In MistralBatchTranscriber::transcribe_stream, wrap the audio buffer with ProgressBody so ConnectionEstablished / UploadProgress / UploadComplete events flow as bytes are sent. Both transcribe_stream and transcribe_file now emit RequestStarted / ResponseHeaders / RequestCompleted boundary events on every exit path.

  Apply the same boundary-event pattern to OpenAIBatchTranscriber::transcribe_file.

  In dictate::mod, create an Arc<BroadcastSink> before the transcriber and inject it via set_sink. The retry loop emits RetryScheduled and re-injects the sink into each freshly-created retry transcriber. No consumer subscribes yet — display wiring follows in sub-phase 1D.

  Remove the three #[allow(dead_code)] annotations from http.rs now that ProgressBody is used by mistral.rs.

• [overlay] keep waterfall scrolling during auto-pause and dim history. [Valentin Lab]

  Three visual improvements to the X11 recording/listening badge:

  1. Waterfall continues scrolling during auto-pause by pushing empty columns (vec![0.0; SPEC_H]) instead of freezing. The x-axis now represents wall-clock time: silence appears as a growing empty hole beside the dimmed audio history, which is useful for diagnosing pause behavior.

  2. During auto-pause the spectrogram/amplitude/spectrum renderers accept a dim parameter. Normal mode passes 1.0; auto-pause passes DIM_FACTOR_PAUSED (0.3) before overlaying the LISTENING text and pause bars at full opacity.

  3. Column advance rate decoupled from render frame rate via COLUMN_PERIOD_FRAMES = 2: the waterfall advances at 30 cols/sec while FPS stays at 60 so the red-dot pulse remains smooth. The visible time window roughly doubles from ~4.4 s to ~8.8 s. Peak tracking still runs every frame for stable normalization.

  New unit tests cover the dim path and the zero-column ("hole") rendering.

• [record] match memo audio filename scheme. [Valentin Lab]

  Audio filenames produced by talk-rs now follow the exact scheme used by the memo tool: YYYY-MM-DDTHH-MM-SS+ZZZZ.ogg -- an ISO 8601 local timestamp with a numeric timezone offset, colons in the time portion replaced by dashes to stay filesystem-safe. Recordings from both tools can now coexist in the same directory and sort chronologically.

  src/record/mod.rs -- default_filename() drops the legacy memo- prefix and switches the chrono format to %Y-%m-%dT%H-%M-%S%z.ogg. The user-facing record command therefore writes <output_dir>/YYYY/MM/2026-04-11T13-15-52+0200.ogg for auto-named recordings. src/cli/def.rs help text is updated to reflect the new default path.

  src/recording_cache.rs -- generate_recording_path() now includes %z in the timestamp used for the dictate cache at ~/.cache/talk-rs/recordings/. The paired metadata YAML sidecar inherits the new stem automatically, so dictate now writes e.g. 2026-04-11T13-15-52+0200_mistral_voxtral-mini-2507_batch.yml. write_last_paste_state() picks up the same format for the timestamp field in last_paste.yml for internal consistency.

  The existing unit test test_resolve_output_path_no_args_... and the integration test test_record_default_filename_format are rewritten to parse the generated filename through chrono::DateTime::parse_from_str and assert a round-trip instead of string-matching a prefix, because the real specification is "the stem must parse back as a local datetime with timezone offset".

  Backward compatibility: existing cached recordings and legacy memo-* record files still list, play, delete, and rotate correctly because the entries reader and cache rotation sort by basename rather than by format. Old files gradually age out of the dictate cache via rotate_cache().

• [record] namespace auto-generated recordings by YYYY/MM [Valentin Lab]

  Auto-generated recording filenames are now placed under YYYY/MM subdirectories of the configured output_dir, mirroring the layout used by the memo tool so long-running users do not end up with thousands of files in a single directory.

  src/record/entries.rs now walks nested YYYY/MM directories when listing recordings for the record --ui browser. Mixed flat plus nested layouts are supported by sorting entries on basename so existing and newly created recordings interleave chronologically.

  src/record/ui.rs now installs its inotify watch recursively so newly created YYYY/MM subdirectories are tracked as soon as they appear. The GTK browser refreshes rows under the correct subtree when files land in freshly created month directories, fixing a regression where the UI stopped auto-updating after the first recording of a new month.

• Harden HTTP timeouts and add --log-file support. [Valentin Lab]

  Replace per-request wall-clock timeouts with TCP-level dead-connection detection so that legitimate long uploads and slow server processing are no longer killed prematurely:

  • Upgrade reqwest 0.11 → 0.13 (hyper-rustls TLS backend).
  • Configure tcp_user_timeout (Linux), tcp_keepalive, keepalive interval/retries in the shared build_client().
  • Remove BATCH_FILE_TIMEOUT, RETRY_TIMEOUT, and all tokio::time::timeout / tokio::select! wrappers around transcription calls — stalls are now caught at the TCP layer within a few seconds.
  • Centralise model_suggestions to use the shared HTTP client.
  • Switch error formatting to {:#} for reqwest error chains.

  Add persistent file logging behind --log-file / $TALK_RS_LOG_FILE:

  • log::setup() accepts an optional file path; a second fern dispatch appends plain-text Info+ logs with timestamps.
  • Auto-truncate at 2 MiB to prevent unbounded growth.
  • Propagate the flag via environment so child processes inherit it.
  • Add chrono timestamps to stderr output as well.
  • Enable clap env feature for $TALK_RS_LOG_FILE support.

• [picker] defer non-default model transcription with on-demand button. [Valentin Lab]

  Only the default transcription model is transcribed immediately when opening a recording in picker mode. Other configured models are deferred and presented with a transcribe button (▶) for on-demand transcription, reducing unnecessary API calls.

• [record] show transcribe button on all recordings. [Valentin Lab]

  Allow users to re-transcribe recordings that already have a transcript. Previously the button was only shown for recordings without transcripts.

• [dictate] migrate dictation cache from WAV to OGG/Opus format. [Valentin Lab]

  Unified cache format across realtime and batch dictation paths. Both now write .ogg cache files using OggOpusWriter. Removed redundant batch-mode OGG tee. Updated cache management (rotation, last-recording pointer, listing, retry) to use .ogg paths. Recordings browser UI now shows OGG cache entries. Delete operation is backward-compatible for legacy .wav files. Removed prune_ogg_cache() since rotate_cache() handles all cache maintenance.

  Files changed:

  • src/dictate/realtime.rs — ogg_recording_task replaces wav_recording_task
  • src/dictate/streaming.rs — uses ogg_recording_task, removed OGG tee
  • src/dictate/mod.rs — unified cache path, removed redundant prune call
  • src/recording_cache.rs — .ogg paths, pointers, rotation
  • src/record/entries.rs — list_cache_recordings() scanning .ogg
  • src/record/ui.rs — updated imports/references
  • src/record/audio.rs — minor update
  • README.org, sample-metadata*.yml, src/cli/def.rs — doc updates

• [record] extract audio_player_bar widget and improve recordings UI. [Valentin Lab]

  Move waterfall spectrogram, playback cursor, and play/pause/rewind controls into a shared audio_player_bar widget under src/widgets/. Replace the inline waterfall worker pool in record --ui with the new widget. Restore a simple play button for entries with transcripts, read OGG transcript previews from companion YAML metadata, and add incremental FileMonitor row updates to avoid full section rebuilds.

• [dictate] always cache OGG format and prune old files. [Valentin Lab]

  OGG cache files are now saved alongside WAV during dictation, regardless of --upload-format setting. Old OGG files are automatically pruned to keep only the 10 most recent, preventing unbounded cache growth.

• [record] defer recording list loading to after window paint. [Valentin Lab]

  Show the recording browser window immediately with a "Loading recordings…" indicator; populate data and set up file watchers in an idle callback triggered on the first map signal so the user never stares at a blank wait.

  Also add log::debug! timing traces to list_ogg_recordings, list_wav_recordings, and the window lifecycle.

• [overlay] make badge background opaque black. [Valentin Lab]

  • Change BG_COLOR alpha from 0x00 to 0xFF for solid black background
  • Force spectrogram pixels to full opacity (color[3] = 0xFF) so they don't create transparent holes over the black background
  • Apply rounded shape mask in ARGB visual path so corners stay rounded with opaque background
  • Update two tests to assert against BG_COLOR instead of alpha=0

• [record] optimize OGG duration to O(1) seek-from-end. [Valentin Lab]

  Replace sequential packet iteration with a tail-read approach: seek to the last ~64 KB, scan backward for the final OggS page header, and read the granule position directly. Constant time regardless of file size.

  Add tests for valid, too-small, and non-OGG files.

Fix

• [audio] consume PCM buffer with a cursor in write_pcm to avoid quadratic drain. [Valentin Lab]

  OggOpusWriter::write_pcm drained samples_per_frame from the front of pcm_buffer inside the encode loop. Vec::drain from the front memmoves the whole remaining tail down on every iteration, making the function quadratic in the number of buffered samples.

  This was harmless for the streaming call sites (src/dictate and src/record), which feed small chunks as they arrive so the buffer never holds more than about one frame. It was severe for encode_16k_mono_ogg in src/transcription/mod.rs, reached via normalize_file_for_upload: that path decodes a whole file to PCM and passes it in a single call, so the buffer starts at full file length and is drained 320 samples at a time. A long recording could spend hours spinning on memmove before contacting the provider at all.

  Consume the buffer with an index cursor and drain once at the end of the call. Behaviour-preserving by construction: the leftover tail after the single drain(..pos) is exactly the samples after the last full frame, which is what finalize() pads and flushes.

  Measured, release build, one call with 20 minutes of 16 kHz mono audio: 455.6 s before, 15.6 s after. The residual is the Opus encode itself, which is linear and unchanged.

  Tests keep a reference copy of the old draining implementation and assert the new one is byte-identical to it, for both the bulk and the irregularly-chunked call shapes. The regression guard asserts on a test-only counter of samples relocated by front-drains rather than on wall-clock time: at test-affordable sizes the linear Opus encode dominates and the measured ratio between the two was only 1.2x, too close to noise to discriminate, whereas the counter separates them by three orders of magnitude deterministically.

• [paste, clipboard] gate chunk advance on target client re-fetch with retry. [Valentin Lab]

  Chunked clipboard paste split long text and advanced to the next chunk as soon as the served_count signal went positive. That counter is incremented by ANY X11 client fetching the CLIPBOARD selection — including clipboard managers — so the selection was routinely overwritten before the target application had actually pasted a chunk, dropping that chunk and (via a lingering serve thread) duplicating the last one.

  Gate each chunk on the TARGET window's X11 client re-fetching it, identified by client-base (requestor & !resource_id_mask) rather than the ephemeral requestor window id:

  • The serve thread now records UTF8_STRING fetches per client-base (our own read-back client is excluded), and the clipboard node waits for the target client specifically. Chunk 1 LEARNS the target's per-paste fetch count through a quiescence window; later chunks CONFIRM the same count before the selection is overwritten.
  • Transient focus failures (the paste keystroke sent before keyboard focus was effective) are recovered by re-focusing the target window and re-sending the keystroke up to target_fetch_retries times (default 2) before giving up.
  • When the target never fetches within chunk_fetch_timeout_ms (default raised 300 -> 500, now a per-attempt deadline) after all retries, the paste ABORTS rather than silently corrupting the document, surfacing a red overlay and an alert sound; the user's original clipboard is still restored.
  • settle_before_restore is removed — the target-confirmation makes the restore race impossible by construction.

  Blind pastes with no known target window (the realtime per-segment path) fall back to the previous served_count gate unchanged.

  New knobs on the clipboard node: target_fetch_retries and target_quiescence_ms; restore_settle_ms is now a no-op kept for backward compatibility.

• [paste, clipboard] wait for paste target to fetch before overwriting clipboard. [Valentin Lab]

  Long pastes split text into chunks and, after pasting, restore the user's original clipboard. Both the inter-chunk overwrite and the final restore happened after a FIXED sleep rather than waiting for the target window to actually fetch the offered content. A slow target could then pull the WRONG clipboard generation — typically grabbing the restored value instead of the last chunk — leaking the old clipboard into the document and dropping the final chunk.

  Block on the existing served_count signal instead of guessing with a sleep:

  • X11Clipboard::wait_until_served polls until the offered content is fetched (or a timeout), so paste_one no longer overwrites a chunk the target has not pulled yet.
  • settle_before_restore waits for the last chunk's fetch activity to stay stable for restore_settle_ms before restoring, closing the restore race. Same treatment for the realtime per-segment path.
  • On timeout a WARN is emitted so the corruption-prone case is no longer silent.

  Requestor-identity matching is intentionally avoided: the target window id never appears as the SelectionRequest requestor, so the served-count signal is the reliable discriminator.

  The two timings are config-tunable via paste.restore_settle_ms (default 200) and paste.chunk_fetch_timeout_ms (default 400).

• [log] let --log-file honor -vvv so trace reaches the file. [Valentin Lab]

  Previously the --log-file sink was pinned to Info, so the paste-diagnostic traces (emitted at Trace) never reached the file even with -vvv — they only went to stderr. In daemon mode that made them effectively unreachable from the user-chosen log file.

  Move the per-sink level filters onto the child dispatches and leave the root dispatch at its pass-all default. In fern a parent Dispatch::level() is a hard gate children cannot exceed in verbosity, so the old structure (root pinned to the stderr level, file child nominally at Info) silently dropped everything below the root level before the file child ever saw it — the "file always captures at least Info" promise was in fact never kept at the default Warn verbosity.

  The file now captures max(base_level, Info): at least Info so it stays useful at the default verbosity, and as deep as Trace under -vvv so the paste diagnostics land in the file. Extract base_level_for and file_level_for as pure helpers with unit tests covering the floor and the -vvv case.

• [config] reject relative output_dir with a clear error. [Valentin Lab]

  The generated config.example.yaml and the README state that output_dir "Must be an absolute path", but validate_config only checked that it was non-empty. A relative value was silently accepted and then resolved against the process working directory at runtime, which is unpredictable — the toggle daemon spawns with an inherited, effectively arbitrary CWD, so recordings could land anywhere.

  Enforce the documented contract: validate_config now returns a output_dir must be an absolute path error for any non-absolute value (whether from the file or the TALK_RS_OUTPUT_DIR env override). Document the requirement on the struct field, and add regression tests covering both the YAML and env paths.

  Fixes #7

• [transport] extend connection retry budget for large uploads. [Boris Gallet]

  The connect_budget timeout wraps the entire HTTP send request (TCP + TLS + body upload) via tokio::time::timeout, not just the connection establishment. For large audio files (>10 MB), the upload to the Mistral API takes ~36s at ~530 KB/s, exceeding even the 15s maximum budget on the 5th attempt.

  Add two generous retry slots (30s, 120s) at the end of the growing-budget schedule [2, 5, 8, 11, 15, 30, 120] so realistic upload latencies (500-2000 KB/s) are accommodated.

  Tested: 19.5 MB / 1h audio file transcribed successfully (~71s total, succeeds on the 30s or 120s attempt depending on network conditions).

• [recording_cache, dictate] persist diarization segments in YAML sidecar. [Boris Gallet]

  TranscriptionCache::store() was silently discarding diarization segments when writing the YAML metadata sidecar. The RecordingMetadata struct had no diarization field, and dictate/mod.rs explicitly set diarization: None when building the cache entry.

  This meant that talk-rs dictate --diarize --timestamp --no-paste would print the correct timestamped speaker output to stdout, but the YAML sidecar next to the OGG file would lose all speaker attribution — making it impossible to reconstruct who spoke when from the cache alone.

  Changes:

  • Add CommonDiarizationSegment with speaker, start, end, text
  • Add diarization field to RecordingMetadata
  • Add common_diarization_from_result() converter
  • Wire diarization through write_metadata_to_dir, write_metadata, TranscriptionCache::store, and into_transcription_result
  • Fix dictate/mod.rs to preserve result.diarization instead of overwriting with None
  • Update transcribe.rs test to pass diarization
  • Add diarization: None to all existing test RecordingMetadata initializers

  TDD: test_transcription_cache_round_trip_with_diarization verifies that SPEAKER_00 / SPEAKER_01 survive store → YAML → read.

• [dictate, toggle] forward all missing flags to daemon. [Boris Gallet]

  `toggle_spawn() was silently dropping several dictate flags when spawning the daemon process:

  • --timestamp (new in PR)
  • --no-paste
  • --pick
  • --retry-last
  • --replace-last-paste
  • --input-audio-file
  • --output-yaml

  This caused talk-rs dictate --toggle --no-paste to paste anyway, and talk-rs dictate --toggle --timestamp to produce untimestamped output.

  Refactor: extract build_daemon_args() as a pure function, pass &DictateOpts instead of individual parameters, add 10 unit tests covering every forwarded flag.

• [overlay] flag NO SOUND only on stuck-at-rail, not on silence. [Valentin Lab]

  Replace the variance-based dead-signal heuristic with a stuck-at-rail detector. A disconnected device pins every sample at the i16 rail (constant ~-1.0); only that flat-and-near-rail signature now triggers the NO SOUND warning.

  The old variance ceiling mis-flagged the exact-zero digital silence that Bluetooth HFP mics emit between speech (variance == 0) as a dead device, producing spurious NO SOUND warnings whenever the user paused talking.

  Add is_stuck_at_rail() helper with 7 unit tests covering a disconnected device (both rails), zero silence, a quiet noise floor, loud speech, a constant mid-level DC offset, and empty input.

• [openai] migrate realtime to GA API. [Valentin Lab]

  short body.

• [picker, error, telemetry] retry labels, row off-by-one, 4xx-permanent annotation. [Valentin Lab]

  Three user-reported bugs from the post-Step-12 review.

  1. Picker T button triggers wrong row when a primary cached entry shares the same (provider, model) with a deferred candidate.

     The button click handler searched local_candidates for the first row matching (provider, model, streaming). Because the primary entry (the cached pre-selected row) is inserted first and shares those fields with a deferred candidate for the same model, Vec::position returned the primary row's index — the spinner appeared on the row ABOVE the one the user clicked.

     Fix: include the is_primary flag in the button's captured identity tuple and match on all four fields in the click handler.

  2. Retry counter ambiguity (retry N/4 vs N/5, unlabeled which phase).

     TranscriptionEvent::RetryScheduled now carries a kind: RetryKind field (Connection or Data). The picker renders connect retry N/M… for connection-phase retries and server retry N/M… for data-phase retries.

  3. HTTP 4xx errors show (after 1/5 attempts) with no indication that retrying was deliberately skipped.

     PipelineFailureKind::HttpStatus rendering now annotates 4xx as — 4xx permanent, no retry and 5xx with exhausted budget as — server-retry budget exhausted, so users understand the counter is correct rather than premature.

  The known-flaky SIGUSR1 lib test cancel_remote_via_sigusr1_triggers_owner_token is marked #[ignore] to match its integration-test cousin (SIGUSR1 is process-wide; the test passes in isolation but races against other registered jobs in the parallel test runner).

  Tests: 440 lib green (1 ignored), 9 transport_integration green (1 ignored), 11 other integration suites green. Clippy clean. Release build green.

• [error] dedup reqwest URL restatement from rendered failure chain. [Valentin Lab]

• [transcription] guard validate-cache writes with POSIX flock. [Valentin Lab]

  The validate-cache write path was a read-modify-write race: a process recorded its first entry, serialised only its own in-process map, and atomically renamed onto the shared file — clobbering any sibling-process entries it had never read. Observed in production as the real cache being repeatedly truncated to a single entry whenever a fresh talk-rs process (picker spawn, dictate daemon, record --ui) recorded a validation.

  persist_to_disk() now:

  1. Acquires an exclusive fs2::FileExt::lock_exclusive on a sibling validate-cache.yaml.lock file.
  2. Re-reads the on-disk YAML unconditionally and merges entries into the in-process map (newer validated_at wins).
  3. Writes the merged set via the existing tempfile + atomic rename.
  4. Releases the lock via an RAII LockGuard.

  Readers stay lock-free; the atomic rename gives them either the previous-complete or new-complete file.

  Also adds the TALK_RS_VALIDATE_CACHE_PATH env override so tests can redirect the cache at a tempfile, plus a process-wide __TEST_LOCK and __test_reset() exposed to sibling test modules so cache-touching tests in http::tests don't race with the ones here on the shared OnceLock statics.

  Coverage:

  • record_merges_with_sibling_disk_entries reproduces the production failure (sibling entry on disk, fresh process records a different key, both must survive).
  • The four validate_model_* tests in http::tests now hold a CacheTestGuard so they cannot pollute the dev's real cache.

  Refs: production cache truncation observed after recent picker / dictate parallelisation work.

• [audio, dictate] restore BT headset profile immediately on stop. [Valentin Lab]

  Previously the HeadsetGuard was dropped at the end of dictate(), which meant the Bluetooth headset stayed in HFP (lower-quality voice profile) for the entire transcription + paste pipeline — sometimes tens of seconds — before flipping back to A2DP. The user-visible effect was that music / system audio came back in degraded HFP quality for a noticeable window after they pressed the toggle to stop recording.

  The fix: drop the guard the moment the microphone capture stops, in parallel with the rest of the dictation pipeline.

  A new HeadsetGuard::restore_now_async() method takes the saved profile out of the guard and dispatches the restore on tokio::task::spawn_blocking. This off-loads the libpulse mainloop driver (which can block on BlueZ profile renegotiation for ~1 s) from the async runtime, so transcription and paste continue in parallel without waiting.

  The guard is now moved by value into dictate_streaming and dictate_realtime and restore_now_async() is called the moment capture.stop() returns — right next to the stop sound and the "Transcribing" overlay swap. After the restore is dispatched the guard is empty so its eventual Drop at function exit is a no-op.

  The guard's RAII Drop remains the safety net for code paths between activation and dispatch (panic, early ?-return, etc.): those will still trigger a synchronous restore.

  The standalone record command was already correct — its capture.stop() is on the last line of record() so the guard drop already happened immediately. Untouched here.

  Two new unit tests in bt_profile.rs cover the new method:

  • restore_now_async on a guard with no saved profile is a cheap no-op (does not spawn any blocking task).
  • restore_now_async takes the saved profile out of the guard so the eventual Drop does not double-restore.

  Verified end-to-end:

  • cargo fmt, cargo clippy --all-targets, cargo test (370 tests pass), cargo build, cargo build --release clean.
  • Live cargo test --test bt_profile_smoke against the running PulseAudio / pipewire-pulse server still detects the headset correctly.

• [overlay, dictate] pause recording pipeline on dead signal and skip transcription. [Valentin Lab]

  Dead-signal detection (no_sound_active) explicitly excluded auto-pause, so a dead microphone kept recording useless constant-value frames into the OGG cache. After the user stopped, those silent seconds were sent to the transcription API — wasting time, tokens, and showing a misleading "transcribing" badge.

  Now the overlay sets pause_flag = true when dead signal triggers, stopping the audio tee from forwarding frames to the encoder. A new had_live_audio flag on OverlayHandle tracks whether any frame with real variance was ever seen during the recording session. After recording stops, dictate_streaming checks both buffer.is_empty() and had_live_audio() — if no usable audio exists, the transcription pipeline is aborted immediately with an empty result.

• [overlay] enlarge red dot and fix its centering. [Valentin Lab]

  Scale DOT_RADIUS_MAX from 10 to 21 and DOT_RADIUS_MIN from 3 to 6 so the volume indicator fills the spec area and is readable at a glance. Shift DOT_CX from 20 to 26 so the larger dot plus its gap clears the rounded corners.

  Side-effect: the pause icon (derived from DOT_RADIUS_MAX) also grows, and its vertical centering improves because bar_h is now odd (29 px), eliminating the 0.5 px asymmetry of the old even value.

• [transcription] add per-request wall-clock timeout to HTTP calls. [Valentin Lab]

  Mistral transcription was observed hanging for 168s when the server accepted the TCP connection but stalled at the application layer. The existing build_client() defences (tcp_user_timeout, tcp_keepalive, connect_timeout) only cover TCP-level failures and cannot detect a slow-but-alive server.

  Add proportional_timeout(audio_bytes) in http.rs: max(3s, kb / 10) — scales with payload size so large files are not killed prematurely.

  Apply .timeout() at each call site:

  • mistral::transcribe_file — uses file metadata length
  • mistral::transcribe_stream — uses drained audio buffer length
  • openai::transcribe_file — adds a metadata read for file length

  openai::transcribe_stream is deliberately left unchanged: it uses Body::wrap_stream where total size is unknown at request-build time; a wall-clock cap would kill long recordings.

  CONNECT_TIMEOUT (2s) is unchanged — log analysis across 81 sessions showed 100% cumulative success within the existing 5 retries.

• [record] copy full transcript to clipboard instead of truncated preview. [Valentin Lab]

  The copy-to-clipboard button in the recordings browser was cloning the transcript_preview field (200 chars with trailing ellipsis) instead of the full transcript. This caused users to lose data when copying recordings to paste elsewhere.

  The fix adds a transcript_full field to RecordingEntry holding the complete single-line transcript (newlines collapsed to spaces, never truncated). The copy button now clones transcript_full while the display label continues using transcript_preview for brevity.

  Also introduces a TRANSCRIPT_PREVIEW_CHARS constant and a transcript_variants() helper to extract both values from a single YAML read, eliminating duplication between list_ogg_recordings and list_cache_recordings.

  Includes 8 unit tests covering edge cases: empty input, short text, newline collapse, exact-200-char boundary, 201-char truncation, very long text, multibyte CJK characters, and long text with embedded newlines.

• [record] remove waterfall spectrogram cache when deleting recordings. [Valentin Lab]

  The delete_recording() function now also removes the .wf waterfall spectrogram cache file when deleting a recording. Previously only .yml companion files were cleaned up, leaving orphaned .wf files behind.

• [record] make file monitor events incremental instead of rebuilding. [Valentin Lab]

  Previously, any audio file event (Created/Deleted/ChangesDoneHint) triggered a full populate_section() rebuild, which cleared all rows, re-read all entries from disk, and always selected row 0. This caused scroll position reset and visible flashing.

  Now each event type is handled incrementally:

  • Deleted: finds matching row by widget_name, selects adjacent row, removes just that row, updates expander count
  • Created/ChangesDoneHint: builds one new row or refreshes existing one in-place at correct sorted position
  • YAML events: extracted into shared update_row_for_yml helper
  • Unhandled events: logged at debug level for future debugging
  • populate_section() no longer called from inotify path (only at init)

  Fixes scroll reset and flashing on file deletion.

• [transcription] buffer audio before upload to provide explicit Content-Length. [Valentin Lab]

  Mistral's API rejects chunked Transfer-Encoding with 411 Length Required. Collect all audio bytes from the mpsc channel into a buffer first, then send with known length via Part::stream_with_length(). This eliminates the 411 failure + retry overhead, reducing transcription time from ~4.4s to ~2.8s (-36%).

  Also removed now-unused imports: futures::StreamExt and tokio_stream::wrappers::ReceiverStream.

• [overlay] freeze visualization data during auto-pause and no-sound. [Valentin Lab]

  Prevent silence gaps from appearing in the waterfall spectrogram when auto-pause is active or no sound is detected. Wrap all per-viz-mode data updates (spectrogram_history, amp_history, spectrum_peak) in a condition that skips accumulation when !auto_paused && !no_sound_active is false.

• [record] extend FileMonitor lifetime past main_loop.run() [Valentin Lab]

  Move _keep_monitors binding out of the inner block so the inotify file watches remain alive for the entire duration of the GTK main loop. Previously they were dropped before main_loop.run() was called, silently losing notifications.

• [gtk-theme] recompute edge in click handler to fix intermittent resize. [Valentin Lab]

  The install_edge_resize click controller was reading a cached edge from the motion controller's shared RefCell rather than computing it from its own (x, y) coordinates. Hand jitter between the last motion event and the press event caused the cached edge to be stale, producing two failure modes:

  • Window moves instead of resizing (cached edge was None, gesture denied, WindowHandle drag took over).
  • Nothing happens (cached edge was set, gesture claimed, but begin_resize silently failed).

  Extract detect_edge() and edge_cursor() helpers, call detect_edge from the pressed handler with a slightly larger threshold (10 px vs 6 px cursor zone) to forgive press-time jitter.

• [transcription] provide explicit Content-Length in Mistral batch uploads. [Valentin Lab]

  The Mistral API now rejects multipart requests without an explicit Content-Length header (HTTP 411). transcribe_file() was using Part::stream() which sends chunked TE without Content-Length. Switched to Part::stream_with_length() with the file size from metadata.

• [picker] defer WavPlayer initialization to avoid blocking UI on cpal device probing. [Valentin Lab]

  Move WavPlayer::new() from synchronous construction (which blocks ~1-2 s on PipeWire while probing audio devices) to a glib::idle_add_local_once callback fired after the window is presented. The picker and recordings windows now appear instantly; the play button is enabled once the player is ready.

• [picker] cap message loop and reuse labels to prevent cursor stutter. [Valentin Lab]

  The transcription poll timer drained all queued StreamUpdate messages in an unbounded loop, rebuilding the label widget (destroy + create) on every streaming delta. When a burst of results arrived the GTK main loop was blocked, starving the 16 ms cursor timer and causing visible jumps.

  Two fixes:

  • Limit the loop to MAX_MSGS_PER_TICK (5) iterations per 50 ms tick so other main-loop sources stay responsive.
  • Reuse the existing gtk4::Label via set_text() instead of tearing down and recreating the widget on every delta. The full widget swap now only happens once (first update replacing the spinner).

0.5.0 (2026-03-10)

New

• [overlay] auto-pause recording during silence to trim dead air. [Valentin Lab]

  When the user stops speaking, recording pauses after 0.5s of silence (RMS below 0.003). Silent segments are not sent to the transcription API, reducing noise and improving accuracy.

  Recording resumes instantly when speech is detected. A 500ms lookback buffer in the audio tee preserves the speech onset so the beginning of words is not clipped.

  Visual indicator: yellow pause bars replace the red pulsing dot, with "LISTENING" text in the viz area.

  Dead-signal detection (NO SOUND) takes priority over auto-pause. The dead-signal trigger is increased from 1 frame to 0.5s to avoid false flashes from momentary PipeWire glitches.

  The pause mechanism uses a shared Arc<AtomicBool> between the overlay thread and the audio tee task.

• [overlay] detect dead audio device and display NO SOUND warning. [Valentin Lab]

  Unified audio capture: the overlay now reads from the same PipeWire stream as the recording pipeline via a new audio tee task (src/audio/tee.rs), replacing the independent CPAL capture that could pick a different device or miss the dead-device condition.

  Dead-signal detection uses sample variance rather than an RMS threshold. A dead or missing PipeWire device sends constant i16::MIN (-32768) samples, which yields RMS ~1.0 (indistinguishable from quiet speech) but variance = 0. A real microphone in a silent room still produces random quantisation noise with variance > 0, so the check reliably separates "no device" from "quiet room".

  Visual warning: when a dead signal is detected the recording badge switches from the red dot to a prohibit icon (circle + diagonal bar) with "NO SOUND" text, and the text panel shows a descriptive message explaining the likely cause.

  Font and glyph rendering utilities (draw_text, measure_text, glyph helpers) moved from src/x11/visualizer.rs to the shared src/x11/render_util.rs so both the visualizer and the overlay can use them without duplication.

• [x11] add --bw monochrome mode for audio visualizers with theme detection. [Valentin Lab]

  Add a --bw flag that switches the amplitude and spectrum visualizer panels to monochrome rendering. The foreground colour is chosen automatically based on the desktop theme (dark-light crate via freedesktop D-Bus portal, with GTK_THEME env-var fallback): white-on-black for dark themes, black-on-white for light themes.

  Also fixes visualizer panel positioning to use the exported BADGE_W constant instead of a hardcoded 182, which caused overlap after the badge was widened to 273 px.

• [transcription] add 2-second TCP connect timeout to HTTP clients. [Valentin Lab]

  Add a CONNECT_TIMEOUT of 2 seconds to all reqwest::Client builders in Mistral, OpenAI, and model-suggestion modules. This fails fast when the server is unreachable without shortening the overall transcription timeout (reverted to 5 seconds). Constructors for MistralBatchTranscriber and OpenAIBatchTranscriber now return Result to propagate client-build errors.

• [x11] replace static recording badge with live spectrogram waterfall. [Valentin Lab]

  Overlay now renders a real-time FFT spectrogram with a pulsing red rec dot, dynamic frequency scaling, and all-time volume peak tracking. Extract shared PixelBuffer, RingBuffer, FFT, and shape helpers into render_util module from visualizer.

Changes

• [overlay] improve FFT resolution and fix visual gaps in visualizers. [Valentin Lab]

  Double FFT_SIZE from 1024 to 2048, raising frequency resolution from 46.9 Hz/bin to 23.4 Hz/bin.

  Rewrite map_spectrum_to_column() to use midpoint-boundary bin ranges with peak (max) aggregation instead of truncating to a single bin index with 3-neighbor averaging. This eliminates visual holes in the waterfall caused by integer truncation skipping bins.

  In render_spectrum_badge(), remove the hard-coded 1 px gap between bars and distribute bins proportionally across the full badge width so no frequency bins are dropped.

• Rename --bw flag to --mono [Valentin Lab]

• Consolidate audio visualizers into recording badge with --viz flag. [Valentin Lab]

  Replace --amplitude and --spectrum side-panel flags with a single --viz <waterfall|amplitude|spectrum> option that renders the selected visualization inside the recording badge. No visualizer by default.

  • Add VizMode enum to config.rs with config file + env var support
  • Overlay badge switches renderer per viz mode (waterfall/amplitude/spectrum)
  • Strip dead audio panel code from visualizer.rs (text-only now, -756 lines)
  • Audio capture in overlay only when viz mode is active

• [x11] add transparent gap around pulsating red dot on recording badge. [Valentin Lab]

  Clear a circle slightly larger than the red dot to transparent before drawing the dot itself, creating a 2-pixel gap that visually separates the dot from the spectrogram waterfall underneath. The gap scales with the dot radius (which varies from 3 to 10 px based on volume). Edge pixels are anti-aliased by blending towards transparent.

• [x11] widen recording badge and make spectrogram fill full width. [Valentin Lab]

  Badge width increased from 182 to 273 pixels (~50% wider). Spectrogram waterfall now spans the full badge width (margin 4px each side). Red dot moved left (DOT_CX 28→20) and draws on top of the spectrogram instead of beside it.

• [x11] use 32-bit ARGB visual for compositor alpha transparency on recording badge. [Valentin Lab]

  Replace opaque background + Shape extension approach with true ARGB transparency. Add find_argb_visual(), create_argb_overlay_window(), and draw_rounded_border() with SDF-based premultiplied alpha rendering. The badge now shows a visible rounded border and is see-through to the desktop. Falls back to the old opaque+shape approach when no 32-bit visual is available.

• [dictate] reduce transcription timeouts from 5s to 2s. [Valentin Lab]

  Lower TRANSCRIPTION_TIMEOUT and RETRY_TIMEOUT from 5 seconds to 2 seconds to shorten the wait during dictation.

• [dictate, x11] decouple text panel lifecycle from audio visualizer panels. [Valentin Lab]

  The text panel is now created once at visualizer thread start and persists for the entire thread lifetime, independently of the audio panels (amplitude/spectrum). Hide now only hides audio panels; the text panel self-manages its visibility based on pending messages.

  This removes the need for callers to explicitly hide() the visualizer after showing error/status messages — the text panel stays visible until its TTL messages expire, then unmaps itself.

  • Remove HideAudio command; Hide takes its semantics
  • Remove destroy_windows(); only destroy_audio_windows() needed
  • Remove enable_text parameter from new() / visualizer_thread()
  • Remove explicit viz.hide() calls from error paths in dictate
  • Event loop now has three states: audio-active, text-only, and idle

• [dictate, x11] replace set_text with TTL-based push_message for status messages. [Valentin Lab]

  Error and retry messages now stack in the visualizer text panel and fade out after a configurable TTL instead of overwriting the live transcription line. hide_audio dismisses only the amplitude and spectrum panels while keeping status messages visible.

• [paste] reduce inter-paste sleep delays. [Valentin Lab]

  The native x11rb/XTest paste path is synchronous and no longer needs the generous delays that accommodated xdotool process-spawn overhead.

  • Clipboard-set → paste delay: 50 ms → 5 ms
  • Inter-paste settle: 100 ms → 15 ms
  • Final settle before clipboard restore: 100 ms → 50 ms

• [dictate, x11] always create visualizer for error/retry feedback. [Valentin Lab]

  The visualizer is now initialised even when --amplitude and --spectrum are not passed. When neither audio panel is enabled the visualizer thread skips CPAL audio-device initialisation and only manages the text window — very lightweight.

  The text panel is created unconditionally but mapped on demand: it appears when a message is set and hides when cleared. This lets the dictation pipeline display transcription errors, reconnection attempts, and retry status directly below the overlay badge so the user is never left wondering why nothing is happening.

  Realtime mode shows: transcription errors, "reconnecting", and "reconnect failed". Batch (streaming) mode shows: retry count, pipeline failure reason, and "will retry after recording".

• [dictate, audio] decouple WAV recording from transcription pipeline. [Valentin Lab]

  WAV recording now writes to a shared AudioBuffer that is completely independent of the transcription pipeline. If transcription fails mid-recording, the audio is never lost — the buffer_feeder replays all chunks from cursor 0 into a fresh transcriber.

  Key changes:

  • Replace audio_tee_to_wav with wav_recording_task + buffer_feeder: the WAV task writes every chunk to disk and to the shared buffer unconditionally; feeder tasks read from the buffer and can be killed/restarted without affecting the recording.

  • Realtime mode: on TranscriptionEvent::Error or unexpected channel closure, abort the feeder, create a new transcriber, and replay all buffered audio from the beginning.

  • Batch (streaming) mode: same decoupling; retry the encode + transcribe pipeline up to 3 times during live recording. If all retries fail, recording continues and the WAV is intact for post-recording retry.

  • PipeWire capture: flush residual samples after the mainloop exits so the last partial chunk is not silently dropped.

  • Play the start-sound before starting capture so the tone is never recorded in the audio.

Fix

• [overlay] implement color rendering for visualizers. [Valentin Lab]

  Add heat_map_color (blue→cyan→green→yellow→red) for waterfall and level_color (green→yellow→red) for bar/wave. All three visualizers now render in color by default; --bw correctly switches to monochrome instead of being a no-op.

0.4.0 (2026-02-26)

New

• [picker] add play button to preview recorded audio. [Valentin Lab]

  Add a ▶/■ toggle button at the top of the --pick window so users can listen to their recorded audio before selecting a transcription. Reuses the existing WavPlayer from the recordings browser by widening its visibility to pub(crate). Playback stops automatically on window close or escape.

Fix

• [dictate, transcription] stop toggle_validate from killing daemon on network errors. [Valentin Lab]

  Proactive toggle_validate was sending SIGINT to the daemon on unrelated network errors, causing unexpected recording stops. Remove proactive validation entirely from the toggle/recording path. Model suggestions are now lazy: only fetched (with cache + retries) when transcription fails with a model-not-found error.

  Move provider-specific intelligence (error detection patterns, API base URLs, model filters) from model_suggestions.rs into mistral.rs and openai.rs. model_suggestions.rs is now a pure cache utility with no provider knowledge. Factory dispatchers in transcription/mod.rs route calls to the correct provider module.

0.3.0 (2026-02-24)

Changes

• [clipboard, x11] replace xclip with native x11rb clipboard. [Valentin Lab]

  Use x11rb directly for CLIPBOARD selection get/set instead of shelling out to xclip. set_text spawns a background thread that serves SelectionRequest events until the next write or drop.

  No external runtime tools are required for clipboard operations.

• [paste, x11] replace xdotool with native x11rb/XTest calls. [Valentin Lab]

  Remove the xdotool runtime dependency by reimplementing all window-management and key-simulation helpers with x11rb and the XTest extension:

  • get_active_window and focus_window now use x11rb directly
  • simulate_paste and simulate_backspace use XTest key events
  • xdotool removed from README prerequisites

Fix

• [record] save recordings in configured output_dir by default. [Valentin Lab]

  Previously talk-rs record (with no explicit path) wrote memo-<timestamp>.ogg into the current working directory. Now it loads the user config and uses output_dir as the parent directory for default recordings, matching the behavior of dictate.

  Extracts a testable resolve_output_path() helper and updates CLI help text and config docs to reflect the new default.

0.2.0 (2026-02-23)

New

• [dictate] add --no-chunk-paste flag and paste.chunk_chars config. [Valentin Lab]

  Allow users to control the 150-character paste chunking behaviour.

  --no-chunk-paste disables chunking entirely (pastes in one shot). paste.chunk_chars in the config file sets a custom chunk size; 0 also disables chunking. The CLI flag overrides the config value.

• [dictate] add --no-boop flag and honor boop_interval_ms config. [Valentin Lab]

  Adds a --no-boop CLI flag that disables only the periodic boop heartbeat during recording while keeping start/stop sounds. Also wires up the existing indicators.boop_interval_ms config field which was defined but never read — the boop interval was hardcoded to 5 seconds. Setting boop_interval_ms to 0 in config now disables boops permanently.

• [dictate] add 5 s transcription timeout with 5-attempt retry. [Valentin Lab]

  dictate_streaming now aborts the transcription task if it does not complete within 5 seconds — this prevents zombie daemon processes caused by the API hanging indefinitely.

  On failure (timeout, API error, network issue through VPN), the batch branch retries up to 5 times using transcribe_file against the saved WAV. Each retry creates a fresh BatchTranscriber and applies the same 5 s timeout. Progress is shown in the visualizer overlay: "Transcription failed: {reason}. Retrying ({N}/5)..."

  If all retries are exhausted the error is displayed for 3 seconds, then the daemon exits cleanly — YAML metadata is skipped, paste is skipped, and the WAV is preserved for the picker.

• [record-ui] add GTK4 recordings browser with --ui flag. [Valentin Lab]

  talk-rs record --ui opens a two-section window:

  • Dictation cache — WAV files from ~/.cache/talk-rs/recordings/
  • Recordings — OGG files from config.output_dir

  Each row shows date, duration, size, and transcript preview with play (native cpal), open-in-file-manager (FileLauncher), and delete buttons. Sections auto-refresh via gio::FileMonitor (inotify) when files are added or removed externally, and the expander counter updates on deletion.

  Enables gtk4 feature v4_10 for FileLauncher support.

• [transcription] add --diarize speaker diarization. [Valentin Lab]

  Add modular speaker diarization support. Each provider can optionally populate a diarization field on TranscriptionResult with per-segment speaker labels (DiarizationSegment struct).

  Mistral V2 batch mode: sends diarize=true and timestamp_granularities=segment form fields, parses segments[].speaker_id from the API response. OpenAI returns None (interface ready for future implementation).

  CLI: --diarize flag on transcribe and dictate commands. Client-side error when combined with --realtime (Mistral WebSocket has no diarize parameter). Output formatting merges adjacent same-speaker segments into [SPEAKER_XX]-tagged lines via format_transcription_output().

  Also fixes stale docs: default model name in README.org and config.example.yaml, --pick help text (rofi to GTK), and adds missing OpenAI provider section to config example.

Changes

• [dictate] move stop-sound and overlay feedback into dictate_streaming [Valentin Lab]

  Immediate audible + visual feedback (stop sound, "Transcribing" badge) now fires inside dictate_streaming right after capture.stop(), so the user gets feedback the instant they toggle off — before the API call finishes. Batch-mode overlay is kept visible until paste or empty-transcription exit. Also applies cargo fmt.

• [dictate] register early SIGINT handler and add debug tracing. [Valentin Lab]

  Move the CancellationToken + ctrl_c handler above the capture and sound-indicator setup. Without this there is a ~1 s race window where SIGINT has no handler and the daemon becomes an unkillable orphan. Also append [DBG] traces to daemon.log in toggle_dispatch and toggle_stop for signal-flow observability.

0.1.0 (2026-02-21)

New

• [audio] add --monitor flag for mic+system audio mixing. [Valentin Lab]

  Add MonitorCapture that combines microphone input with system audio (PipeWire monitor source) into a single stream. The --monitor flag is available on both record and dictate commands, and is forwarded through toggle-mode daemon spawning.

• [monitor] add GDK4-based monitor geometry module. [Valentin Lab]

  Query the GDK display for the largest monitor (by physical pixel area) and return (x, y, width, height) scaled by the monitor's scale_factor. GDK4 dropped the "primary" flag, so largest-area is used as heuristic.

  This replaces the xrandr subprocess calls previously embedded in overlay.rs and visualizer.rs with a shared, type-safe module that returns physical pixel coordinates suitable for direct X11 window placement.

• [dictate] integrate realtime transcription into picker. [Valentin Lab]

  The --pick flag now accepts realtime (WebSocket) transcribers alongside batch ones. Each realtime candidate streams incremental text updates into the GTK picker via PickerMessage::StreamUpdate and displays a ⚡ indicator in the provider column.

  Key additions:

  • OPENAI_REALTIME_MODELS / MISTRAL_REALTIME_MODELS constants and add_known_realtime_models to populate retry candidates.
  • read_wav_pcm_samples helper to feed recorded WAV data into realtime transcribers as chunked PCM.
  • split_into_word_chunks splits paste text into word-bounded chunks so large transcriptions are pasted incrementally, avoiding overwhelming the target application.
  • Retry button correctly re-spawns either batch or realtime transcription depending on the candidate type.
  • Removes the --pick is currently supported only in batch mode guard.

• [daemon] add ownership-safe signal_daemon and stop_if_owner helpers. [Valentin Lab]

  signal_daemon sends SIGINT to a daemon process group and removes the PID file immediately so the next toggle-on sees NotRunning. The exiting daemon uses remove_pid_file_if_owner to avoid clobbering a PID file written by a newly spawned replacement.

  stop_if_owner re-acquires the lock and only performs a full graceful stop when the PID file still belongs to the expected process.

• [audio] add native PipeWire capture and rubato resampler. [Valentin Lab]

  Add two new audio modules:

  • pipewire_capture: captures audio directly from PipeWire using the Rust pipewire bindings, matching pw-cat --record routing (including Bluetooth devices). Runs on a dedicated thread with fixed-size chunk emission.

  • resample: sinc-interpolated downsampler (48 kHz → 16 kHz) using rubato with Blackman2 windowing and 128-tap anti-aliasing filter. Includes spawn_resample_task() that bridges two mpsc channels, passing through unchanged when rates match.

  Also adds preferred_capture_rate() to CpalCapture for querying the default input device's best mono rate (capped at 48 kHz).

  Dependencies: pipewire, rubato, audioadapter-buffers, gdk4-x11.

• [dictate] add transcription metadata capture and GTK multi-provider picker. [Valentin Lab]

  Enrich transcription responses with structured TranscriptionMetadata capturing latency, token usage, detected language, and provider-specific diagnostics (rate-limit headers, realtime session/event counters).

  The BatchTranscriber trait now returns TranscriptionResult (text + metadata) instead of a bare String, and the recording cache YAML includes the full metadata payload for post-hoc analysis.

  Add a GTK4 picker window (--pick) that fires parallel transcription requests across all known provider/model combinations and displays candidates progressively as they complete. Results are cached per audio file in ~/.cache/talk-rs/picker-results/ so reopening the picker skips API calls entirely.

  Supporting changes:

  • --retry-last: reuse the last cached recording as input audio
  • --replace-last-paste: delete previously pasted text before inserting the new selection (tracked via last_paste.yml)
  • last_recording.wav / last_metadata.yml symlink pointers in the recording cache for quick access to the most recent entry
  • simulate_backspace helper and paste_text_to_target refactoring to share paste logic between batch mode and picker
  • x11_centre_and_raise for single-instance picker detection and monitor-aware centring via RandR
  • New TranscriptionEvent variants (SessionInfo, RateLimitsUpdated, TransportMetadata) for realtime metadata collection
  • Mistral realtime validation now skips the REST /v1/models check (realtime-only models are not listed there)

• [dictate] add --output-yaml flag for metadata export. [Valentin Lab]

  Copy the recording cache metadata YAML to a user-specified path after transcription completes. Reuses the existing cache metadata file written by write_metadata rather than generating a separate one.

• [dictate] add --input-audio-file flag for file-based transcription. [Valentin Lab]

  Feed a pre-recorded WAV file through the transcription pipeline instead of live microphone capture. Works with both batch and realtime modes, enabling reproducible benchmarks across providers and models.

  The WavFileSource implements AudioCapture and validates the file is 16 kHz / mono / 16-bit PCM (with ffmpeg conversion hints on mismatch). Batch mode races Ctrl+C against natural file completion via a oneshot signal from the encode task. Realtime mode handles file exhaustion through the existing channel cascade.

  Also removes the now-redundant save_file parameter from dictate_streaming() since --save copies from the recording cache.

• [dictate] add --save flag and recording cache. [Valentin Lab]

  Replace the positional FILE argument with --save <PATH> on the dictate command. The last 10 recordings are now always cached in ~/.cache/talk-rs/recordings/ as timestamped WAV files with companion YAML metadata (provider, model, realtime flag, transcript).

  Both batch and realtime paths tee raw PCM to the cache. When --save is specified, the cache WAV is copied to the user path after recording. Oldest entries beyond 10 are automatically rotated out.

• [transcription] add multi-provider support with OpenAI backend. [Valentin Lab]

  Add OpenAI as a second transcription provider alongside Mistral, supporting both batch (REST) and realtime (WebSocket) modes.

  Infrastructure:

  • Provider enum (Mistral | OpenAI) with Deserialize/FromStr
  • BatchTranscriber and RealtimeTranscriber traits with factory functions and lazy API-key validation
  • --provider and --model CLI flags on dictate and transcribe
  • TranscriptionConfig with default_provider in config file
  • OpenAIConfig with model (batch) and realtime_model fields
  • Environment variable overrides for all provider settings

  OpenAI batch (openai.rs):

  • OpenAIBatchTranscriber with streaming upload via reqwest::Body::wrap_stream
  • Wiremock-based unit tests for success, error, streaming, and edge cases

  OpenAI realtime (openai_realtime.rs):

  • OpenAIRealtimeTranscriber using WebSocket with session.type: "transcription"
  • 16 kHz → 24 kHz PCM resampling (linear interpolation, 3:2 ratio)
  • server_vad turn detection, input_audio_buffer.append streaming
  • Post-commit timeout for completion detection (no explicit "done" event)
  • Default model: gpt-4o-realtime-preview

  Preflight validation:

  • validate() method on both traits, called before audio capture
  • REST GET /v1/models check: verifies API key and model existence, lists available transcription models on bad model name
  • WebSocket session check (realtime only): catches "model not supported in realtime mode" before daemon spawn in --toggle mode
  • Validation in toggle_start(), dictate(), and transcribe()

• [visualizer] add live transcription text overlay. [Valentin Lab]

  Render live transcription text below the recording badge using fontdue for glyph rasterisation. Features include:

  • Async font loading from system paths (/usr/share/fonts) to avoid blocking the render loop at startup
  • CJK-aware font fallback (Noto Sans CJK)
  • Centered, single-line text with automatic left-clip on overflow
  • Pulsing "..." dots while waiting for speech
  • Rounded-corner text background via XShape
  • dictate_realtime() pushes TextDelta/SegmentDelta text to the overlay in real time

• [cli] add --amplitude and --spectrum flags to dictate [Valentin Lab]

  Integrate the visualizer module into the dictate command lifecycle: init on start, show alongside the recording badge, hide on stop. Both flags are forwarded through --toggle daemon mode.

• [visualizer] add real-time audio visualizer module. [Valentin Lab]

  Amplitude history (RMS-based bar chart) and FFT spectrum panels rendered via X11 put_image at 60 fps. Each panel is independently toggleable, positioned on either side of the recording badge, and runs its own CPAL capture stream decoupled from the recording pipeline.

  Includes ring buffer, radix-2 Cooley-Tukey FFT, pixel buffer helpers, multi-monitor geometry detection, and comprehensive unit tests.

• [cli] add debug WAV capture for realtime transcription. [Valentin Lab]

  Every realtime dictate session now saves a copy of the raw PCM audio to $XDG_CACHE_HOME/talk-rs/debug-capture.wav (or to the user-specified file path). This tees the audio stream so exactly what is sent to Voxtral is also written to disk, allowing the user to verify that:

  • recording starts when expected
  • recording stops when expected
  • the full audio content is captured correctly

  The WAV header is patched with the final data size on completion. The tee task continues writing even if the transcriber channel closes early.

• [cli] add structured logging with -v/-vv/-vvv verbosity. [Valentin Lab]

  Replace unused tracing/tracing-subscriber with log+fern+colored following the fyl project pattern. All eprintln! diagnostic messages are now routed through log:: macros at appropriate levels:

  • log::error! for failures (WebSocket errors, encode errors)
  • log::warn! for degraded operation (missing overlay, stream drops)
  • log::info! for user-visible events (start/stop, transcription result)
  • log::debug! for pipeline steps (connect, session, clipboard, overlay)
  • log::trace! for high-frequency data (audio chunks, WS frames)

  The -v flag is forwarded to daemon subprocesses so --toggle mode inherits verbosity. Refactors dictate() arguments into DictateOpts struct to satisfy clippy::too_many_arguments.

• [overlay] add X11 visual overlay indicator for dictate command. [Valentin Lab]

  Pure Rust X11 overlay using x11rb with Shape extension for binary transparency (works without compositor). Displays embedded PNG badges (recording/transcribing) centered on primary monitor.

  • src/core/overlay.rs: background thread with command channel, OverlayHandle for show/hide/quit, Shape mask from alpha channel, pixel drawing grouped by color via poly_point
  • --no-overlay flag on dictate (passed through --toggle)
  • Overlay shows "Recording" badge on start, hides on stop
  • PNG assets embedded via include_bytes!, decoded with png crate
  • Screen position from xrandr --query with multi-monitor support
  • 8 unit tests covering PNG decode, geometry parsing, type invariants

• [audio] add sound indicators to dictate command. [Valentin Lab]

  Synthesize short tones via cpal output to give audible feedback during recording: ascending major-third on start, periodic soft boop as heartbeat, descending major-third on stop. A single-channel SoundPlayer with preemption ensures sounds never overlap.

  • indicator.rs: tone synthesis, SoundPlayer, boop loop via tokio task with CancellationToken
  • --no-sounds CLI flag to disable indicators
  • Flag forwarded through --toggle daemon spawn

• [cli] add --toggle daemon mode to dictate command. [Valentin Lab]

  First invocation spawns a background daemon (--daemon) that records and transcribes via WebSocket. Second invocation sends SIGINT to stop recording, complete transcription, and paste the result.

  Uses kernel-level flock on a lock file to prevent races between concurrent toggle calls. PID file at $XDG_CACHE_HOME/talk-rs/daemon.pid with stale-PID detection via kill(pid, 0). Graceful shutdown waits up to 10 s before escalating to SIGTERM.

  Active window is captured by the toggle caller and forwarded to the daemon via the hidden --target-window argument so paste targets the correct window.

• [transcription] add realtime WebSocket module for Voxtral Realtime API. [Valentin Lab]

  Implement MistralRealtimeTranscriber that connects to the Voxtral Realtime API via WebSocket, streams base64-encoded PCM audio, and receives incremental TranscriptionEvent variants (text deltas, segment boundaries, language detection, errors).

  The module includes event parsing, sender/receiver loops, and comprehensive unit tests for all event types and PCM encoding.

  Adds dependencies: tokio-tungstenite, base64, url; moves serde_json from dev to main dependencies.

• [config] add model and context_bias to MistralConfig [Valentin Lab]

  Add configurable model name (defaulting to voxtral-mini-latest) and optional context_bias field for improved transcription accuracy of proper nouns and technical terms.

  Both fields support environment variable overrides via TALK_RS_PROVIDERS_MISTRAL_MODEL and TALK_RS_PROVIDERS_MISTRAL_CONTEXT_BIAS.

  The MistralTranscriber now passes these fields through to the Mistral API in both file-based and streaming transcription requests.

• [audio] add AudioWriter trait with OggOpusWriter and WavWriter [Valentin Lab]

  Replace raw OpusEncoder usage with container-aware writers that produce valid OGG/Opus (RFC 7845) and WAV output.

  • OggOpusWriter: encodes PCM → Opus, wraps in OGG pages with proper OpusHead/OpusTags headers and granule positions
  • WavWriter: wraps raw PCM in a 44-byte WAV header, with finalize returning a corrected header for seekable files
  • record command dispatches writer by file extension (.wav vs default .ogg)
  • dictate streaming and chunked modes now produce self-contained OGG payloads per chunk (each with its own header), fixing transcription API compatibility
  • Chunked mode buffers raw PCM instead of pre-encoded Opus, enabling per-chunk OGG encapsulation
  • New dependencies: ogg 0.9, byteorder 1

• [cli] add --chunked mode to dictate command. [Valentin Lab]

  Add --chunked flag and -n / --chunk-seconds option to split recording into time-based chunks, each transcribed separately via MistralTranscriber. Results are accumulated and pasted at the end.

  Chunk duration is resolved from: CLI -n flag > dictate.chunk_seconds in config > error. Adds Clone to MistralConfig for per-chunk transcriber instantiation.

• [cli] add dictate command with streaming transcription and clipboard paste. [Valentin Lab]

  Record audio, stream it to Mistral API for transcription via transcribe_stream(), then paste the result into the focused application using xclip + xdotool:

  • Capture active window before recording (xdotool getactivewindow)
  • Encode PCM → Opus and stream to API during recording
  • On stop: refocus window, save clipboard, set text, paste via xdotool key ctrl+shift+v, restore clipboard
  • Optional --file arg to save audio alongside transcription

• [transcription] add transcribe_stream() for streaming audio upload. [Valentin Lab]

  Extend Transcriber trait with transcribe_stream() method that accepts a tokio::sync::mpsc::Receiver<Vec<u8>> for incremental audio upload. MistralTranscriber converts the receiver to a futures::Stream via tokio-stream and uses reqwest::Body::wrap_stream() for chunked HTTP transfer encoding — audio is uploaded as it's recorded, so transcription completes near-instantly after recording stops.

  Adds tokio-stream dependency for ReceiverStream wrapper.

• [clipboard] add Clipboard trait with X11Clipboard and MockClipboard [Valentin Lab]

  Introduce clipboard module for Phase 2 dictate functionality:

  • Clipboard trait with get_text() and set_text() async methods
  • X11Clipboard implementation using xclip command-line tool (matches 0k-memo reference implementation)
  • MockClipboard with Arc<Mutex<String>> for thread-safe testing
  • TalkError::Clipboard error variant for clipboard operations
  • Unit tests for MockClipboard (4 tests)
  • Integration tests: xclip binary check, X11 roundtrip, save/restore pattern (2 ignored, require X11 display)

• [cli] add transcribe command with MistralTranscriber backend. [Valentin Lab]

  Transcribes audio files via Mistral API (voxtral-mini-latest model). Outputs to stdout or file. Config refactored with providers namespace for future backend extensibility.

  Includes:

  • Transcriber trait with MockTranscriber and MistralTranscriber
  • transcribe CLI command with arg parsing
  • Integration tests: mock pipeline, error handling, real Mistral API call

• [cli] add record command with CpalCapture and OpusEncoder pipeline. [Valentin Lab]

  Captures audio from system microphone, encodes with Opus, writes to file. Supports optional output path (defaults to memo-YYYY-MM-DD-HH-MM-SS.ogg). Graceful shutdown via SIGINT (Ctrl+C) with encoder flush.

  Includes integration tests verifying:

  • Mock capture pipeline creates valid output files
  • Real hardware capture creates non-empty Opus files
  • Default filename format generation

• [audio] add AudioEncoder trait with MockEncoder and OpusEncoder implementations. [Valentin Lab]

  Implement audio encoding trait with two implementations:

  • MockEncoder: Pass-through encoder for testing (converts i16 to little-endian bytes)
  • OpusEncoder: Real Opus codec encoder using the opus crate with configurable bitrate

  Features:

  • AudioEncoder trait with encode() and flush() methods
  • Stateful encoding with internal buffering for frame-based codecs
  • Configuration from AudioConfig (sample_rate, channels, bitrate)
  • Support for mono and stereo channels
  • Comprehensive unit tests including encode/decode roundtrip verification
  • Proper error handling with TalkError::Audio variant

  Changes:

  • Created src/core/audio/encoder.rs with trait and implementations
  • Added Clone derive to AudioConfig for test flexibility
  • Exported AudioEncoder, MockEncoder, OpusEncoder in src/core/audio/mod.rs
  • All tests pass (10 audio tests)

• [audio] add AudioCapture with CpalCapture and full sample format support. [Valentin Lab]

  Includes:

  • AudioCapture trait for swappable backends
  • MockAudioCapture for testing
  • CpalCapture with support for all CPAL sample formats (I8, U8, I16, U16, I32, U32, I64, U64, F32, F64)
  • Integration tests verifying real audio device compatibility

  All unit and integration tests pass on real hardware.

• [error] add TalkError enum with thiserror derives. [Valentin Lab]

  Implements comprehensive error handling with variants for:

  • Config - Configuration errors
  • Audio - Audio capture/encoding errors
  • Transcription - API transcription errors
  • Io - IO operations (with #[from] std::io::Error)
  • Session - Session management errors

  Includes unit tests for error conversions and documentation.

  Refs #1.3

• [config] add Config struct with YAML loading. [Valentin Lab]

  Implements configuration loading with:

  • Config struct with nested MistralConfig, AudioConfig
  • Config::load() with optional custom path parameter
  • XDG directory support via directories crate
  • Environment variable overrides (TALK_RS_* prefix)
  • Fail-fast on missing required fields
  • Unit tests for loading and validation

  Uses patterns from insight-cli for directory handling.

  Refs #1.4

Changes

• [visualizer] render amplitude as symmetrical waveform. [Valentin Lab]

  Replace bottom-anchored vertical bars with a mirror-image waveform centred on the vertical midline. Each column extends equally upward and downward, producing a classic audio waveform look.

  Pre-fill the amplitude history buffer with zeros so the waveform starts at the right edge and scrolls leftward — instead of stretching a few early samples across the whole panel width.

• [visualizer] skip text panel when not in realtime mode. [Valentin Lab]

  The text bar with pulsing dots below the recording badge is only useful in realtime mode where live transcription text streams in. In batch mode it just showed empty dots.

  Add an enable_text flag to VisualizerHandle::new() and create_windows(), gated on opts.realtime. The error overlay path keeps text enabled so validation failures remain visible.

• [dictate] switch paste chunking to character-based and init GTK4 in daemon path. [Valentin Lab]

  Replace word-based split_into_word_chunks with character-based split_into_char_chunks (limit PASTE_CHUNK_CHARS = 150). Splits on word boundaries to avoid cutting words. The 150-char threshold keeps each paste below the point where terminal applications collapse it into an opaque summary block.

  Also call gtk4::init() before creating the overlay and visualizer in the daemon code path. Without this, GDK4 monitor queries silently fail and the overlay/visualizer never appear when talk-rs runs as a toggle-mode daemon.

• [overlay,visualizer] replace xrandr with GDK4 monitor geometry. [Valentin Lab]

  Remove the per-module xrandr --query subprocess calls and their associated parsing helpers (parse_geometry, parse_primary, parse_geom_word) along with their tests.

  Both modules now call monitor::primary_monitor_geometry() from the main thread before spawning their X11 worker threads, passing the MonitorGeometry tuple in. This is required because GDK must be queried from the thread that called gtk4::init().

• [picker-cache] add streaming flag to cache entries. [Valentin Lab]

  SelectedEntry and CachedResult now carry a streaming bool (defaulting to false for backwards compatibility) so the picker cache can distinguish batch from realtime transcription results.

  write_selected takes the flag as a new parameter.

• [dictate] improve picker UX and integrate PipeWire capture. [Valentin Lab]

  Picker improvements:

  • Sort entries by (provider, model) for stable display order.
  • Add retry button (↻) on error rows via PickerMessage enum, allowing re-transcription without reopening the picker.
  • Centre window using gdk4_x11::X11Surface::xid() in the map signal, eliminating the _NET_CLIENT_LIST polling race.
  • Refactor x11_centre_and_raise into x11_centre_and_raise_xid (direct XID) and a title-search wrapper.
  • Record selected (provider, model) via picker_cache::write_selected so the choice persists across picker reopens.

  Focus and paste fixes:

  • Add ensure_focus() with exponential-backoff retries to confirm the target window is active before pasting.
  • Prefer read_last_paste_state() over recording metadata for replacement character count (correct across successive picker selections).
  • Pass --delay 0 to xdotool key in simulate_backspace.

  Audio capture:

  • Replace CpalCapture with PipeWireCapture for live recording at 48 kHz, piped through resample::spawn_resample_task to downsample to 16 kHz before encoding.

• [picker-cache] add selection tracking and legacy format migration. [Valentin Lab]

  Introduce PickerCache struct wrapping results + an optional SelectedEntry so the picker remembers which (provider, model) the user last chose.

  • read() now returns PickerCache and transparently migrates the old flat-array JSON format.
  • Split write() into write_results() (preserves selection) and write_selected() (preserves results).
  • selected field is omitted from JSON when None (skip_serializing_if).
  • Updated tests for new format, legacy migration, and serialisation.

• [config] update default Mistral model to voxtral-mini-2507 [Valentin Lab]

  voxtral-mini-latest now aliases to voxtral-mini-2602; pin to the explicit voxtral-mini-2507 version so users can compare results between model generations.

• [audio] hardcode AudioConfig parameters. [Valentin Lab]

  The audio config section (sample_rate, channels, bitrate) exposed Opus encoder internals as user-facing configuration. The only sensible values for voice dictation are 16 kHz / 1 channel / 32 kbps — any other combination either fails or wastes bandwidth with no transcription quality gain.

  AudioConfig now has a new() constructor returning hardcoded defaults. The audio field is removed from Config, along with TALK_RS_AUDIO_* env var overrides and the env_var_u32 / env_var_u8 helpers that were only used for audio.

• [cli] make batch mode the default for dictate [Valentin Lab]

  Replace --batch flag with --realtime. Streaming upload (batch) is now the default behavior; pass --realtime to get incremental WebSocket transcription instead.

• [cli] paste transcription per segment in dictate realtime mode. [Valentin Lab]

  Instead of accumulating all segments and pasting once after recording stops, each segment is now pasted into the focused application as it arrives. This provides real-time feedback while dictating.

  dictate_realtime() accepts an optional segment channel. A spawned paste consumer reads from it and does clipboard-set + ctrl+shift+v per segment (~150 ms cadence). Clipboard is saved before recording and restored after the paste task drains.

  Batch mode (--batch) retains the previous single-paste behavior.

• [cli] replace chunked mode with realtime default and --batch flag. [Valentin Lab]

  The dictate command now uses WebSocket-based realtime transcription by default, streaming audio to the Voxtral Realtime API for incremental results. The previous --chunked / --chunk-seconds flags and DictateConfig are removed in favor of a simpler --batch flag that falls back to the original upload-after-stop workflow.

  Add client-side flush_sentences() that splits the live transcription buffer on sentence-ending punctuation (. ! ? and CJK equivalents 。 ！ ？), printing completed sentences to stdout as they arrive. Includes unit tests for Latin and CJK punctuation, trailing partials, and no-punctuation edge cases.

Fix

• [picker] switch retry channel to tokio::sync::mpsc [Valentin Lab]

  Replace std::sync::mpsc with tokio::sync::mpsc::unbounded_channel for the picker retry channel. The std channel's blocking .recv() holds a tokio worker thread and prevents the runtime from shutting down cleanly when the picker window closes.

• [picker] use theme foreground color for selected rows. [Valentin Lab]

  Pin color on row:selected to theme_fg_color so text stays readable on light GTK themes. Without this, some themes switch selected text to white which is invisible against our translucent accent selection background.

• [transcription] use transcription_session.update for OpenAI realtime. [Valentin Lab]

  The OpenAI Realtime API requires a different endpoint and event format for transcription-only sessions:

  • URL uses ?intent=transcription instead of ?model=
  • OpenAI-Beta: realtime=v1 header is required
  • Client event is transcription_session.update (not session.update)
  • Session schema uses flat input_audio_format/input_audio_transcription fields instead of nested GA audio.input structure
  • Server responds with transcription_session.created/.updated

  Also fix the default realtime_model from gpt-4o-realtime-preview (a session model) to gpt-4o-mini-transcribe (a transcription model).

• [audio] fire stop sound immediately on toggle. [Valentin Lab]

  Pass SoundPlayer and CancellationToken into dictate_realtime() so the stop sound plays the instant SIGINT is caught — before capture.stop() and before the WebSocket finishes collecting transcription results.

  Previously the stop sound played only after dictate_realtime() returned, adding 100-500ms of perceived delay on toggle.

  Batch mode still plays the stop sound in dictate() after the recording completes.

• [audio] use deterministic flush signal on capture stop. [Valentin Lab]

  Replace the heuristic 50ms sleep in CpalCapture::stop() with a deterministic std::sync::mpsc signal from the callback thread.

  The callback stores its final partial buffer in a shared final_buffer and signals completion via a one-shot channel. stop() waits for this signal (with a 2-second safety timeout for unresponsive hardware), then injects the final samples into the tokio::sync::mpsc channel before closing it.

  This guarantees the last audio chunk is never silently dropped, regardless of callback timing or system load.

• [audio] wait for output device warmup before playing start sound. [Valentin Lab]

  SoundPlayer::new() now blocks until the CPAL output callback has actually fired at least once, proving the audio pipeline is live. A Condvar bridges the callback thread and the caller — no arbitrary sleep.

  Previously, stream.play() returned before the device was ready, so the first few milliseconds of the start sound were lost to device startup latency, making the sound appear clipped.

• [audio] flush partial buffer on capture stop. [Valentin Lab]

  The CPAL callback was discarding all incoming audio once running became false — any samples accumulated in its internal buffer that had not yet reached samples_per_chunk were silently lost. This caused the end of every recording to be chopped off.

  Now the callback flushes its partial buffer exactly once when it detects the stop signal. A 50ms grace period before dropping the stream ensures the callback has time to see the flag and flush.

• [transcription] harden networking against hangs and silent drops. [Valentin Lab]

  The realtime WebSocket and batch HTTP paths had several unhandled failure modes that could hang the app indefinitely:

  • connect_async and wait_for_session_created had no timeout, hanging forever on unreachable servers or unresponsive sessions
  • transcribe_file (batch) had no request timeout at all
  • No WebSocket ping keepalive, making silent network drops undetectable
  • Sender and receiver tasks ran independently with no coordination; one dying left the other hanging
  • Cleanup task silently swallowed panics from spawned tasks
  • Silent WS stream end (TCP RST) was not logged

  Fixes:

  • 15s timeout on WS connect and session.created handshake
  • 300s timeout on batch transcribe_file request
  • 30s periodic Ping frames in sender loop for keepalive
  • Shared CancellationToken between sender/receiver for coordinated shutdown on either side's failure
  • Cleanup task now logs panics from JoinHandle results
  • Unexpected stream end logged and cancellation propagated

Other

• Test: [audio] add closed-loop loopback integration tests. [Valentin Lab]

  5 tests using a PipeWire null sink as a virtual audio loopback:

  • loopback_start_sound_is_captured: start sound produces non-silent audio through the loopback pipeline.
  • loopback_stop_sound_is_captured: same for the stop sound.
  • loopback_start_sound_has_two_notes: RMS energy envelope confirms two distinct tone bursts (sound completeness, not clipped).
  • loopback_preemption_replaces_sound: at most 3 tone onsets when stop preempts start (4 would mean both played fully).
  • loopback_capture_receives_played_audio_i16: f32-to-i16 conversion path verified through loopback.

  Uses the "pulse" ALSA device (not "default") so cpal routes through PulseAudio where $PULSE_SINK / $PULSE_SOURCE are respected — tests are completely silent (no sound on real speakers).

  Infrastructure: shared null sink via OnceLock with stale cleanup, serial lock with poison recovery, SoundPlayer::from_device() targeting.

  Run with: cargo test --test audio_loopback -- --ignored --test-threads=1