From d5135acfb19a228cae343e501b211ca85c2f8122 Mon Sep 17 00:00:00 2001
From: Abir Deol <160072369+apollo-2006@users.noreply.github.com>
Date: Wed, 26 Aug 2026 17:52:55 -0700
Subject: [PATCH 1/2] 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.
---
 examples/stream/README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/examples/stream/README.md b/examples/stream/README.md
index f10645e7e45..6a44550c6cd 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 shape 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:

From 4ff4734218b268452626d9aa5c25cd4c4ffc4e8d Mon Sep 17 00:00:00 2001
From: Abir Deol <160072369+apollo-2006@users.noreply.github.com>
Date: Fri, 11 Sep 2026 10:20:55 -0700
Subject: [PATCH 2/2] Update examples/stream/README.md

Co-authored-by: Daniel Bevenius <daniel.bevenius@gmail.com>
---
 examples/stream/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/stream/README.md b/examples/stream/README.md
index 6a44550c6cd..5eac6f1c54e 100644
--- a/examples/stream/README.md
+++ b/examples/stream/README.md
@@ -27,7 +27,7 @@ a transcription block that is suitable for parsing.
 
 ## Output format
 
-The shape depends on --step, and there is no flag to override it.
+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.