fix(stt): chunked transcription with progress, retry, and no 300s cliff

[EtienneLescot]

The bug

Transcribing a 30-minute import fails. Reproduced on the reporter's file (podcast project, 32 min):

wav 62430920 bytes
FETCH THREW after 311s: TypeError fetch failed — Headers Timeout Error

whisperServer.runMultipartInfer uses Node's global fetch, i.e. undici, whose headersTimeout defaults to 300 s. whisper.cpp sends no response header until it has transcribed the whole upload. Measured on this file: whisper needed 574 s, undici cut the connection at 300 s, and the renderer surfaced an unactionable "Transcription failed / fetch failed". The helper process kept burning CPU on a transcription nobody was listening for — the reporter's machine still had one alive a day later.

Audio extraction was never the problem: replayed as-is in Chromium it completes in 75 s and yields 31 215 421 samples @16 kHz with real signal (peak 0.85).

The fix

Split the audio into ~90 s chunks and run them one at a time.

• electron/stt/chunking.ts nudges each boundary to the quietest 20 ms frame within ±3 s of the ideal cut, so a break lands in a pause instead of mid-word. Energy minimum, not a VAD: whisper.cpp's Silero VAD runs per request, so it cannot tell us where to cut before we upload.
• SttManager.transcribe shifts each chunk's timestamps to absolute time, emits completedSec/totalSec per chunk, and retries a chunk up to 3 times — re-running server.start() between attempts (idempotent when the helper is alive, a respawn when it isn't), because the usual cause of a mid-run failure is a dead helper, not a bad chunk.
• Language is pinned to whatever the first chunk detected. Left to auto-detect, whisper can flip mid-recording on a chunk that opens with a proper noun and "transcribe" the remainder as another language.
• whisperServer bounds each request at 280 s and names the failure with the helper's stderr, instead of letting undici's 300 s ceiling surface as a bare "fetch failed".

Progress reaches the UI

The renderer's status callback forwarded only a phase string and never subscribed to the main process's events, so the toast showed one static "transcribing" for the entire run. Progress now travels the road the phase already had — status.ts owns the vocabulary, the store owns the queue, TranscriptionStatus.tsx owns how a job reads on screen. The store's onStatus also loses its as TranscriptionPhase cast: the two vocabularies are now genuinely the same type, "loading-model" included.

Both the bar and the percentage render nothing until the run reports measurable progress — queued, extracting audio and downloading the model have no fraction, and a bar pinned at 0 % reads as "stuck" where a spinner reads as "working".

Why chunks run sequentially

Measured, not assumed. whisper-stt-server holds a single model context:

	wall time
two 120 s chunks, one after the other	76.9 s
the same two, fired together	144.1 s

0.53× — concurrency is ~1.9× slower. A client-side worker pool would be a pessimisation. Real parallelism needs several server processes, each with its own copy of the model resident on the GPU; worth revisiting only if a much smaller model ever becomes the default. This is recorded in the code so nobody "optimises" it later.

Verification

End to end on the 32-minute source, real planChunks driving the real server:

audio 1951.0s → 22 chunks (91,88,92,89,91,92,93,89,88,90,89,90,92,91,93,87,87,89,88,88,92,61s)
segments=485
coverage: last segment ends at 1950.7s / 1951.0s
slowest chunk 76.8s vs the 280s per-request ceiling
timestamps monotonic across chunk seams: true

Boundaries land at 87–93 s rather than on a 90 s grid — the pause search is doing its job.

• vitest run electron/stt src/lib/captioning src/lib/ai-edition/transcription — 85/85 pass (10 new: 5 on chunk planning, 5 on orchestration — absolute offsets across seams, monotonic progress ending at 100 %, language pinning, retry, terminal failure; plus 2 on progress propagation).
• tsc --noEmit clean.

Known gaps

• src/lib/ai-edition/store/transcriptionStore.test.ts was not executed locally. It fails to load because i18next is missing from this machine's node_modules and no package manager is available here to install it — a pre-existing environment gap that also breaks 7 untouched component test files on this branch. The store change is covered by tsc and by the pure status.ts tests; CI should be the judge.
• The 280 s per-request bound leaves one real ceiling: a machine so slow that a 90 s chunk needs more than 280 s (~0.3× realtime). Removing it for good means a direct undici dependency and new Agent({ headersTimeout: 0, bodyTimeout: 0 }) as the fetch dispatcher (verified working). Deliberately not done here to avoid adding a dependency for a hypothetical machine — flagged in a ponytail: comment.
• Audio extraction still blocks the renderer for ~70 s on a 32-minute file (decodeAudioData 44 s + mixToMono 26 s, both synchronous). Out of scope here, worth its own pass.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 686152ad-aac1-4a1a-9e62-e2791b4faa1a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}