From d5d6e59bfa941adcdbcc7b1f3418706a95f21e39 Mon Sep 17 00:00:00 2001 From: Abir Deol Date: Thu, 17 Sep 2026 22:47:04 -0700 Subject: [PATCH] docs : clarify VAD mode timestamps and CWD model path errors (#4019) * docs(stream): clarify VAD mode timestamps and CWD model path errors AI use: I found this while building against the library and used an AI assistant to help verify the relevant source (file/line refs above). The report and the documentation wording are mine, and I've checked every claim against the source myself. * Update examples/stream/README.md Co-authored-by: Daniel Bevenius --------- Co-authored-by: Daniel Bevenius --- examples/stream/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/examples/stream/README.md b/examples/stream/README.md index f10645e7e..5eac6f1c5 100644 --- a/examples/stream/README.md +++ b/examples/stream/README.md @@ -25,6 +25,36 @@ It's best to tune it to the specific use case, but a value around `0.6` should b When silence is detected, it will transcribe the last `--length` milliseconds of audio and output a transcription block that is suitable for parsing. +## Output format + +The output format depends on --step, and there is no flag to override it. + +Default (--step > 0): one rolling segment, no timestamps, rewritten in +place with ANSI erase-line escapes. Fine for a terminal, wrong for a pipe. + +VAD mode (--step 0): timestamped blocks meant for parsing. + + ### Transcription 0 START | t0 = 0 ms | t1 = 4000 ms + + [00:00:00.000 --> 00:00:03.480] Hello there. + + ### Transcription 0 END + +- timestamps are enabled implicitly by --step 0; there is no -nt here +- strip the [t0 --> t1] prefix; don't discard those lines as log noise +- -tdrz appends [SPEAKER_TURN] on a speaker change +- the ### markers and [Start speaking] are on stdout + +## Model path + +-m is relative to the process CWD and defaults to models/ggml-base.en.bin. +Spawning whisper-stream from a parent with a different CWD needs an +absolute path, or you get: + + error: failed to initialize whisper context + +which is also what a corrupt model prints, so check the path first. + ## Building The `whisper-stream` tool depends on SDL2 library to capture audio from the microphone. You can build it like this: