From dcda11a9248e1d24a67bdd9f6fd34fe112fb4a4b Mon Sep 17 00:00:00 2001
From: codeonym <bouarourayoub0@gmail.com>
Date: Tue, 10 Nov 2026 17:37:00 +0000
Subject: [PATCH 1/2] feat: generate offline Qwen narration clips (#4)

---
 .github/workflows/ci.yml                      |   2 +-
 README.md                                     |  28 +++-
 docker/Dockerfile                             |   9 +-
 docker/tts/assets.json                        |  72 +++++++++
 docker/tts/download.py                        |  28 ++++
 docker/tts/requirements.in                    |   5 +
 docker/tts/requirements.txt                   |  92 +++++++++++
 docker/tts/worker.py                          |  67 ++++++++
 package.json                                  |   2 +-
 .../004-pluggable-tts-local-default.md        |   2 +
 .../decisions/011-transcript-json-schema.md   |   2 +
 ...26-11-10_1716_odd-viewport-encoder-hang.md |  17 ++
 .../history/CHANGES.md                        |   1 +
 .../001-clips-and-metadata-in-gh4.md          |  16 ++
 .../002-qwen3-tts-06b-local-default.md        |  21 +++
 .../decisions/003-customvoice-ryan-english.md |  14 ++
 .../decisions/004-local-adapter-only.md       |  14 ++
 .../005-official-python-cpu-runtime.md        |  23 +++
 .../006-skip-blank-narration-audio.md         |  14 ++
 ...007-demo-specific-portable-audio-folder.md |  13 ++
 .../GH-4-tts-adapter-local-voice/draft.md     |  48 ++++--
 .../history/2026-11-10_1353_draft.md          |  27 ++++
 .../history/2026-11-10_1353_meta.md           |  12 ++
 .../history/2026-11-10_1358_meta.md           |  12 ++
 .../history/2026-11-10_1423_impl.md           | 110 +++++++++++++
 .../history/2026-11-10_1735_impl.md           | 126 +++++++++++++++
 .../history/CHANGES.md                        |  13 ++
 .../GH-4-tts-adapter-local-voice/impl.md      | 146 ++++++++++++++++++
 .../GH-4-tts-adapter-local-voice/meta.md      |   6 +-
 src/runner/run.ts                             |  32 ++--
 src/runner/tts.ts                             |  79 ++++++++++
 test/e2e/record.test.ts                       |  67 ++++++--
 test/e2e/tts.test.ts                          |  55 +++++++
 test/unit/tts.test.ts                         |  97 ++++++++++++
 34 files changed, 1223 insertions(+), 49 deletions(-)
 create mode 100644 docker/tts/assets.json
 create mode 100644 docker/tts/download.py
 create mode 100644 docker/tts/requirements.in
 create mode 100644 docker/tts/requirements.txt
 create mode 100644 docker/tts/worker.py
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/follow-ups/2026-11-10_1716_odd-viewport-encoder-hang.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/001-clips-and-metadata-in-gh4.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/002-qwen3-tts-06b-local-default.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/003-customvoice-ryan-english.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/004-local-adapter-only.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/005-official-python-cpu-runtime.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/006-skip-blank-narration-audio.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/007-demo-specific-portable-audio-folder.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_draft.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_meta.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1358_meta.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1423_impl.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1735_impl.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/impl.md
 create mode 100644 src/runner/tts.ts
 create mode 100644 test/e2e/tts.test.ts
 create mode 100644 test/unit/tts.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b272516..e395f4b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,7 +8,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 45
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
diff --git a/README.md b/README.md
index eb93935..116cefc 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@ Record reproducible feature demos from a short Playwright script. A coding agent
 writes the script, and `flow-reel` replays it in a sandbox on a virtual display while recording the screen. The same
 script gives the same video, step for step.
 
-This release records **silent** video with narration text, captions and step timings. Voice, cursor and zoom polish,
-and sound effects come in later releases.
+This release records **silent** video with narration text, captions, step timings and separate speech clips.
+Fitting and mixing the speech into the MP4, cursor and zoom polish, and sound effects come in later releases.
 
 ## Requirements
 
@@ -14,6 +14,8 @@ and sound effects come in later releases.
   pulled, `flow-reel` builds it locally once (a few minutes).
 - About 2.5 free CPU cores while recording. On an overloaded machine the recording stops with an error rather than
   save a video whose timing is off.
+- The image is about 7 GB unpacked; its build downloads about 2.5 GB of model weights. Local speech synthesis uses
+  four CPU threads after capture and can require more than 5 GiB of process memory, in addition to your app and OS.
 
 ## Install
 
@@ -62,12 +64,30 @@ Next to the script:
 | `settings.events.json` | Every move, click, keystroke run and scroll the runner made, timed the same way (schema version 1). |
 | `settings.srt` | Captions for a subtitle-capable video player. |
 | `settings.vtt` | WebVTT captions for a browser's `<video>` / `<track>`. |
+| `settings.audio/000.wav` | Local speech clips, named by zero-based step index. |
 
 Each caption shows one step's narration from its `startMs` to its `endMs`. Caption whitespace is normalized and the
 player wraps the text; the transcript keeps the original narration. Blank narration and steps lasting zero
 milliseconds stay in the transcript but produce no caption. Short actions can be too brief to read: step holds for
 voice clips come in a later release.
 
+Narration uses Qwen3-TTS 0.6B CustomVoice, Ryan in English, through the official Python runtime on CPU. Model and
+tokenizer assets are pinned and downloaded when the image is built; synthesis runs offline without a key. Speech
+is generated after capture finishes. The transcript records the voice, seed, and each clip's relative file path,
+duration in milliseconds and complete-file SHA-256 hash. Copy the audio folder with its transcript when sharing it.
+
+Synthesis normalizes whitespace without interpreting caption escapes; the transcript preserves the original text.
+Blank narration produces no clip. Clip numbers retain step indexes, so skipped steps leave gaps. Rerunning replaces
+the generated numeric WAVs in this demo's audio folder; keep personal audio under other filenames or folders.
+Nonblank narration on a zero-duration action still produces speech. Clips can outlast their action windows until
+the next release adds holds and muxing; the MP4 has no audio track yet. A synthesis failure fails the command.
+
+The local generator resets seed 0 for each clip and uses pinned settings. Matching hashes are checked in fresh
+processes on the tested CPU/container platform; byte equality across hardware or architectures is not guaranteed.
+On the tested Ryzen 5 3500U, one fresh process generated three short clips (6.4 seconds of speech) in 147 seconds,
+with about 5.4 GiB peak process memory. Runtime varies with host load. A synthesis job has a 15-minute timeout;
+individual steps also fail if generation reaches its limit, rather than returning truncated speech.
+
 Captions escape `&`, `<` and `>` so narration is emitted without raw tags. WebVTT displays the literal text; some
 SRT players display escape sequences such as `&lt;` instead. Use WebVTT in a browser when literal symbols matter.
 
@@ -86,7 +106,7 @@ a script have the same steps, each starting within ±150 ms.
 
 ## Known gaps
 
-- No synthesized voice or audio yet; narration is text only.
+- Speech clips are separate; the MP4 remains silent until step holds and audio muxing are added.
 - No cursor drawn in the video yet: the runner logs the motion in `events.json` for the polish step.
 - Playwright calls the runner doesn't cover run without any mouse motion (the warning names them).
 
@@ -96,7 +116,7 @@ a script have the same steps, each starting within ±150 ms.
 npm ci
 npm run typecheck
 npm test            # unit tests
-npm run test:e2e    # builds the image and records a fixture app twice (needs Docker and ffmpeg)
+npm run test:e2e    # builds the image, tests offline synthesis, and records twice (needs Docker and ffmpeg)
 ```
 
 Planning lives in `planning/` (see `groundwork.md`).
diff --git a/docker/Dockerfile b/docker/Dockerfile
index c3944a4..f156e42 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -2,14 +2,19 @@
 FROM mcr.microsoft.com/playwright:v1.64.1-noble
 
 RUN apt-get update \
- && apt-get install -y --no-install-recommends xvfb x11-utils ffmpeg \
+ && apt-get install -y --no-install-recommends xvfb x11-utils ffmpeg python3-venv sox libsndfile1 time \
  && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /opt/flow-reel
+COPY docker/tts/requirements.txt docker/tts/requirements.txt
+RUN python3 -m venv /opt/flow-reel/tts-venv \
+ && /opt/flow-reel/tts-venv/bin/pip install --no-cache-dir -r docker/tts/requirements.txt
+COPY docker/tts ./docker/tts
+RUN /opt/flow-reel/tts-venv/bin/python docker/tts/download.py
 COPY package.json ./
 RUN npm install --omit=dev --no-fund --no-audit
 COPY dist ./dist
 
-ENV FLOW_REEL_IN_CONTAINER=1 HOME=/tmp
+ENV FLOW_REEL_IN_CONTAINER=1 HOME=/tmp HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 TOKENIZERS_PARALLELISM=false
 USER pwuser
 ENTRYPOINT ["node", "/opt/flow-reel/dist/cli.js"]
diff --git a/docker/tts/assets.json b/docker/tts/assets.json
new file mode 100644
index 0000000..777439a
--- /dev/null
+++ b/docker/tts/assets.json
@@ -0,0 +1,72 @@
+{
+  "repository": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
+  "revision": "85e237c12c027371202489a0ec509ded67b5e4b5",
+  "files": [
+    {
+      "file": "config.json",
+      "size": 4908,
+      "hash": "5e8d5fc100536984e3a89bd87ef08e59e322b29b",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "generation_config.json",
+      "size": 245,
+      "hash": "1872b16d4535564abf2db5d6debe6cddd82b7f2e",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "merges.txt",
+      "size": 1671839,
+      "hash": "20024bfe7c83998e9aeaf98a0cd6a2ce6306c2f0",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "model.safetensors",
+      "size": 1811626576,
+      "hash": "bc3c7e785eb961179c25450d1acff03f839e0002f2f3a5aeb67b5735c0fa2adb",
+      "algorithm": "sha256"
+    },
+    {
+      "file": "preprocessor_config.json",
+      "size": 127,
+      "hash": "0525dd953bb9241912f7147666f0d535165d5d4f",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "speech_tokenizer/config.json",
+      "size": 2336,
+      "hash": "06cc8dc4c5ec8a1929086b71b98c313020d9268b",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "speech_tokenizer/configuration.json",
+      "size": 76,
+      "hash": "ab58e2eaf53cd14a1a2a7527d9261ceea93a24cd",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "speech_tokenizer/model.safetensors",
+      "size": 682293092,
+      "hash": "836b7b357f5ea43e889936a3709af68dfe3751881acefe4ecf0dbd30ba571258",
+      "algorithm": "sha256"
+    },
+    {
+      "file": "speech_tokenizer/preprocessor_config.json",
+      "size": 234,
+      "hash": "ba40914f4f49ab98a8ca545d4892ef7291a39592",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "tokenizer_config.json",
+      "size": 7344,
+      "hash": "6ff9fd60cc623bb54bbd603cbd418c97a11528d7",
+      "algorithm": "git-blob-sha1"
+    },
+    {
+      "file": "vocab.json",
+      "size": 2776833,
+      "hash": "4783fe10ac3adce15ac8f358ef5462739852c569",
+      "algorithm": "git-blob-sha1"
+    }
+  ]
+}
diff --git a/docker/tts/download.py b/docker/tts/download.py
new file mode 100644
index 0000000..ad8b3cc
--- /dev/null
+++ b/docker/tts/download.py
@@ -0,0 +1,28 @@
+"""Build-time only: fetch immutable model assets and verify their published hashes."""
+import hashlib
+import json
+from pathlib import Path
+from urllib.request import urlopen
+
+from huggingface_hub import hf_hub_download
+
+ROOT = Path("/opt/flow-reel/tts-model")
+manifest = json.loads(Path(__file__).with_name("assets.json").read_text())
+for asset in manifest["files"]:
+    path = Path(hf_hub_download(manifest["repository"], asset["file"], revision=manifest["revision"], local_dir=ROOT))
+    digest = hashlib.sha256() if asset["algorithm"] == "sha256" else hashlib.sha1()
+    if asset["algorithm"] == "git-blob-sha1":
+        digest.update(f"blob {asset['size']}\0".encode())
+    with path.open("rb") as stream:
+        while chunk := stream.read(1024 * 1024):
+            digest.update(chunk)
+    if path.stat().st_size != asset["size"] or digest.hexdigest() != asset["hash"]:
+        raise RuntimeError(f"model asset verification failed: {asset['file']}")
+
+# The checkpoint is Apache-2.0; retain its model card and the upstream runtime licence.
+for filename, url in {
+    "MODEL_CARD.md": f"https://huggingface.co/{manifest['repository']}/resolve/{manifest['revision']}/README.md",
+    "LICENSE": "https://raw.githubusercontent.com/QwenLM/Qwen3-TTS/022e286b98fbec7e1e916cb940cdf532cd9f488e/LICENSE",
+}.items():
+    with urlopen(url) as response:
+        (ROOT / filename).write_bytes(response.read())
diff --git a/docker/tts/requirements.in b/docker/tts/requirements.in
new file mode 100644
index 0000000..38aef8e
--- /dev/null
+++ b/docker/tts/requirements.in
@@ -0,0 +1,5 @@
+qwen-tts==0.1.1
+torch @ https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=ee40b8a4b4b2cf0670c6fd4f35a7ef23871af956fecb238fbf5da15a72650b1d ; platform_machine == "x86_64"
+torch @ https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl#sha256=179451716487f8cb09b56459667fa1f5c4c0946c1e75fbeae77cfc40a5768d87 ; platform_machine == "aarch64"
+torchaudio @ https://download-r2.pytorch.org/whl/cpu/torchaudio-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=502b19a5bd0ef8fc97adf06c24146c5e2b94bc3c43b768174407c031cd21c3a5 ; platform_machine == "x86_64"
+torchaudio @ https://download-r2.pytorch.org/whl/cpu/torchaudio-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl#sha256=2ef1f8d0f0feba5a9364620925c864890b90abc98a65f35895256dd6aa1710be ; platform_machine == "aarch64"
diff --git a/docker/tts/requirements.txt b/docker/tts/requirements.txt
new file mode 100644
index 0000000..f63ee8b
--- /dev/null
+++ b/docker/tts/requirements.txt
@@ -0,0 +1,92 @@
+--index-url https://pypi.org/simple
+
+accelerate==1.12.0
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.16.0
+brotli==1.2.1
+certifi==2026.10.23
+cffi==2.1.1
+charset-normalizer==3.5.2
+click==8.5.1
+cloudpickle==3.1.2
+decorator==5.3.1
+einops==0.8.2
+fastapi==0.162.2
+filelock==4.2.10
+flatbuffers==25.12.19
+fsspec==2026.9.0
+gradio==6.17.3
+gradio-client==2.5.0
+groovy==0.1.2
+h11==0.16.0
+hf-gradio==0.4.1
+hf-xet==1.8.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface-hub==0.36.2
+idna==3.20
+jinja2==3.1.6
+joblib==1.6.0
+lazy-loader==0.6
+librosa==1.0.0
+llvmlite==0.50.0
+markdown-it-py==4.2.0
+markupsafe==3.0.4
+mdurl==0.1.2
+mpmath==1.3.0
+msgpack==1.2.4
+narwhals==2.28.0
+networkx==3.7
+numba==0.68.1
+numpy==2.5.4
+onnxruntime==1.31.1
+opentelemetry-api==1.45.2
+orjson==3.13.0
+packaging==26.3
+pandas==3.1.1
+pillow==12.3.0
+platformdirs==4.14.5
+pooch==1.9.0
+protobuf==7.36.2
+psutil==7.2.2
+pycparser==3.12
+pydantic==2.14.3
+pydantic-core==2.50.4
+pydub==0.25.1
+pygments==2.21.0
+python-dateutil==4.0.0
+python-multipart==0.0.33
+pytz==2026.6
+pyyaml==6.0.3
+qwen-tts==0.1.1
+regex==2026.11.9
+requests==2.34.2
+rich==15.0.0
+safehttpx==0.1.7
+safetensors==0.8.0
+scikit-learn==1.9.1
+scipy==1.18.1
+semantic-version==2.10.0
+setuptools==84.2.1
+shellingham==1.5.4
+soundfile==0.14.0
+sox==1.5.0
+soxr==1.1.0
+starlette==1.10.0
+sympy==1.14.0
+threadpoolctl==3.8.0
+tokenizers==0.22.2
+tomlkit==0.14.0
+torch @ https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=ee40b8a4b4b2cf0670c6fd4f35a7ef23871af956fecb238fbf5da15a72650b1d ; platform_machine == "x86_64"
+torch @ https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl#sha256=179451716487f8cb09b56459667fa1f5c4c0946c1e75fbeae77cfc40a5768d87 ; platform_machine == "aarch64"
+torchaudio @ https://download-r2.pytorch.org/whl/cpu/torchaudio-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=502b19a5bd0ef8fc97adf06c24146c5e2b94bc3c43b768174407c031cd21c3a5 ; platform_machine == "x86_64"
+torchaudio @ https://download-r2.pytorch.org/whl/cpu/torchaudio-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl#sha256=2ef1f8d0f0feba5a9364620925c864890b90abc98a65f35895256dd6aa1710be ; platform_machine == "aarch64"
+tqdm==4.70.1
+transformers==4.57.3
+typer==0.29.0
+typing-extensions==4.16.0
+typing-inspection==0.4.5
+tzdata==2026.6
+urllib3==2.8.0
+uvicorn==0.54.0
diff --git a/docker/tts/worker.py b/docker/tts/worker.py
new file mode 100644
index 0000000..62466da
--- /dev/null
+++ b/docker/tts/worker.py
@@ -0,0 +1,67 @@
+"""One model load, serial clips, fixed CPU generation; JSON stdin/stdout for the TS adapter."""
+import contextlib
+import json
+import random
+import resource
+import sys
+import time
+
+START = time.monotonic()
+MAX_TOKENS = 1024
+
+
+def synthesize(jobs):
+    # Upstream prints optional-dependency notices to stdout; keep our JSON channel clean.
+    with contextlib.redirect_stdout(sys.stderr):
+        import numpy as np
+        import soundfile as sf
+        import torch
+        from qwen_tts import Qwen3TTSModel
+
+        torch.set_num_threads(4)
+        torch.set_num_interop_threads(1)
+        torch.use_deterministic_algorithms(True)
+        model = Qwen3TTSModel.from_pretrained(
+            "/opt/flow-reel/tts-model", device_map="cpu", dtype=torch.float32,
+            attn_implementation="eager", local_files_only=True,
+        )
+        model.model.eval()
+        # The pinned official wrapper discards codec counts before returning WAVs.
+        # Check those counts at its generation boundary to reject token-limit truncation.
+        generate = model.model.generate
+
+        def checked_generate(**kwargs):
+            codes, hidden = generate(**kwargs)
+            if any(len(code) >= MAX_TOKENS - 1 for code in codes):
+                raise RuntimeError("speech reached its generation limit; shorten this step's narration")
+            return codes, hidden
+
+        model.model.generate = checked_generate
+        for job in jobs:
+            try:
+                random.seed(0)
+                np.random.seed(0)
+                torch.manual_seed(0)
+                wavs, rate = model.generate_custom_voice(
+                    text=job["text"], speaker="Ryan", language="English", non_streaming_mode=True,
+                    do_sample=True, top_k=50, top_p=1.0, temperature=0.9, repetition_penalty=1.05,
+                    subtalker_dosample=True, subtalker_top_k=50, subtalker_top_p=1.0,
+                    subtalker_temperature=0.9, max_new_tokens=MAX_TOKENS,
+                )
+                if not len(wavs[0]) or not np.isfinite(wavs[0]).all():
+                    raise RuntimeError("speech was empty or invalid")
+                sf.write(job["file"], wavs[0], rate, subtype="PCM_16")
+            except Exception as error:
+                raise RuntimeError(f"step {job['index']}: {error}") from error
+
+
+if __name__ == "__main__":
+    try:
+        jobs = json.load(sys.stdin)
+        synthesize(jobs)
+        print(json.dumps({"clips": len(jobs)}))
+        print(json.dumps({"ttsSeconds": round(time.monotonic() - START, 3),
+                          "peakMemoryKiB": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss}), file=sys.stderr)
+    except Exception as error:
+        print(f"Qwen TTS: {error}", file=sys.stderr)
+        sys.exit(1)
diff --git a/package.json b/package.json
index 40519c9..2be8740 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run test/unit",
-    "test:e2e": "npm run build && vitest run test/e2e --testTimeout=900000 --hookTimeout=900000"
+    "test:e2e": "npm run build && vitest run test/e2e --no-file-parallelism --testTimeout=900000 --hookTimeout=900000"
   },
   "dependencies": {
     "playwright": "1.64.1"
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/decisions/004-pluggable-tts-local-default.md b/planning/GH-1-narrated-reproducible-feature-demos/decisions/004-pluggable-tts-local-default.md
index 71cc64a..b9bc7f3 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/decisions/004-pluggable-tts-local-default.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/decisions/004-pluggable-tts-local-default.md
@@ -1,5 +1,7 @@
 # 004: TTS sits behind an adapter, with a local open voice by default
 
+**Partly superseded by GH-4 decision 002** (the starting local model is Qwen3-TTS 0.6B instead of Kokoro/Piper).
+
 **Date:** 2026-11-02 (shaping, Q4; agreed: "yes!")
 
 **Question:** local TTS, cloud TTS, or pluggable?
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/decisions/011-transcript-json-schema.md b/planning/GH-1-narrated-reproducible-feature-demos/decisions/011-transcript-json-schema.md
index cd74dc1..19af3fc 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/decisions/011-transcript-json-schema.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/decisions/011-transcript-json-schema.md
@@ -1,5 +1,7 @@
 # 011: `transcript.json` has one versioned schema; each ticket fills its own fields
 
+**Partly superseded by GH-4 decision 001** (GH-4 writes `voice` and step `audio`; GH-5 still owns held `endMs`).
+
 **Date:** 2026-11-02 (global pass, Q9; agreed: "ok")
 
 **Question:** what does `transcript.json` hold, given four tickets read or write it?
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/follow-ups/2026-11-10_1716_odd-viewport-encoder-hang.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/follow-ups/2026-11-10_1716_odd-viewport-encoder-hang.md
new file mode 100644
index 0000000..1358532
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/follow-ups/2026-11-10_1716_odd-viewport-encoder-hang.md
@@ -0,0 +1,17 @@
+---
+status: open
+from: agent
+found-while: GH-4
+resolved-by:
+---
+
+# Odd scaled viewports can hang recording after encoder failure
+
+In src/runner/display.ts, a 640×360 viewport scales to 853×480.
+libx264 rejects the odd width. In src/runner/recorder.ts, the
+recorder can then wait after the encoder has exited. The test
+timed out after 120 seconds; its container kept Xvfb alive and
+interfered with the next recording.
+
+Investigate even capture dimensions and reliable encoder-exit
+handling, with regression coverage. This is separate from GH-4.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/history/CHANGES.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/history/CHANGES.md
index 2023afe..8d450cf 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/history/CHANGES.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-2-silent-replay-recording-sandbox/history/CHANGES.md
@@ -6,3 +6,4 @@
 - 2026-11-09: review fixes (page-level actions, network-idle wait, act budget) and corrections noted in impl.md.
 - 2026-11-09: in review: https://github.com/codeonym-oss/flow-reel/pull/10.
 - 2026-11-10: done: PR #10 squash-merged as 1fa4e5d; GH-2 closed and board status set to Done.
+- 2026-11-10: with approval, saved 2026-11-10_1716_odd-viewport-encoder-hang.md after GH-4 validation exposed an existing odd-viewport encoder-exit hang.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/001-clips-and-metadata-in-gh4.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/001-clips-and-metadata-in-gh4.md
new file mode 100644
index 0000000..ca2f570
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/001-clips-and-metadata-in-gh4.md
@@ -0,0 +1,16 @@
+# 001: GH-4 generates clips and writes their metadata during recording
+
+**Date:** 2026-11-10 (ticket pass, Q1; agreed: "ok")
+
+**Question:** does GH-4 integrate synthesis and metadata into `flow-reel record`, or leave integration to GH-5?
+
+**Decision:** **GH-4 generates WAV clips and writes `voice` and each narrated step's `audio` metadata during
+`flow-reel record`.** Synthesis happens after capture so it does not compete with the real-time recorder. The MP4
+stays silent and step timing is unchanged. GH-5 owns holds and muxing, and may move synthesis earlier as needed.
+
+This supersedes story decision 011 only in assigning the `voice` and `audio` fields to GH-4 rather than GH-5.
+The version 1 schema stays the same.
+
+- **Why:** an end-to-end recording produces usable clips and their durations and hashes for GH-5.
+- **Not chosen:** shipping only an adapter with a separate synthesis test, leaving recording integration and
+  metadata to GH-5.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/002-qwen3-tts-06b-local-default.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/002-qwen3-tts-06b-local-default.md
new file mode 100644
index 0000000..954c6bf
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/002-qwen3-tts-06b-local-default.md
@@ -0,0 +1,21 @@
+# 002: Start with Qwen3-TTS 0.6B as the local engine
+
+**Date:** 2026-11-10 (ticket pass, Q2; agreed: "lets choose qwen i guess? right wqen 0.6 as starter !")
+
+**Question:** which local TTS engine ships first?
+
+**Decision:** **Qwen3-TTS 0.6B** is the starting local engine, replacing the Kokoro/Piper candidates in story
+decision 004. Local, offline, CPU execution remains required. The exact variant, default speaker and runtime are
+settled separately. No Kokoro or Piper fallback is added in this ticket.
+
+- **Why:** the person chose Qwen 0.6B as the starting engine.
+- **Not chosen:** Kokoro or Piper as the initial bundled engine.
+- **Verification required:** pin runtime and model assets; prove network-disabled synthesis and matching WAV
+  SHA-256 hashes across fresh runs. Measure CPU time and peak memory rather than assuming the GPU-oriented
+  upstream examples establish CPU performance. A failed requirement must be surfaced before changing the engine
+  or the reproducibility contract.
+
+Sources checked on 2026-11-10:
+- [Official model list and Python runtime](https://github.com/QwenLM/Qwen3-TTS): 0.6B CustomVoice and Base variants.
+- [CustomVoice model card](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice): Apache-2.0 weights,
+  built-in speakers and supported languages; examples use CUDA.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/003-customvoice-ryan-english.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/003-customvoice-ryan-english.md
new file mode 100644
index 0000000..5de2e76
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/003-customvoice-ryan-english.md
@@ -0,0 +1,14 @@
+# 003: Use CustomVoice with Ryan in English
+
+**Date:** 2026-11-10 (ticket pass, Q3; agreed: "ok")
+
+**Question:** start with a built-in voice or the Base model's voice cloning?
+
+**Decision:** **bundle `Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice`, with Ryan and English as the initial voice and
+language.** Voice cloning, reference-audio configuration and voice design are outside GH-4.
+
+- **Why:** a built-in English speaker gives narration without another user-supplied asset.
+- **Not chosen:** Base with voice cloning, which adds reference-audio configuration and testing.
+
+Source: [official CustomVoice model card](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice), checked
+2026-11-10; Ryan is listed as a native English speaker.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/004-local-adapter-only.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/004-local-adapter-only.md
new file mode 100644
index 0000000..21a5701
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/004-local-adapter-only.md
@@ -0,0 +1,14 @@
+# 004: Ship only the local adapter in GH-4
+
+**Date:** 2026-11-10 (ticket pass, Q4; agreed: "local for now! for cloud, its next ticket right? or thi one? idk !!")
+
+**Question:** does GH-4 ship a cloud provider as well as the local engine?
+
+**Decision:** **local Qwen only for now**, behind a small TTS adapter interface. Cloud provider implementations,
+credentials and container secret forwarding are outside GH-4. This narrows the existing draft's cloud-adapter
+promise; it preserves story decision 004's adapter boundary.
+
+- **Why:** focus the first implementation on offline, repeatable local synthesis.
+- **Not chosen:** adding a cloud adapter and its credentials and provider-specific tests now.
+- **Sequencing:** the next existing ticket is GH-5 (holds and muxing), not cloud. A cloud provider would be separately
+  planned work; this decision does not create a tracker issue or expand GH-5.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/005-official-python-cpu-runtime.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/005-official-python-cpu-runtime.md
new file mode 100644
index 0000000..bc9cfee
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/005-official-python-cpu-runtime.md
@@ -0,0 +1,23 @@
+# 005: Use the official Python runtime on CPU
+
+**Date:** 2026-11-10 (ticket pass, Q5; agreed: "ok")
+
+**Question:** use the official Python runtime or an optimized community runtime?
+
+**Decision:** **use the official `qwen-tts` Python runtime on CPU**, called through the inherited subprocess
+boundary. Pin its dependencies and the model/tokenizer asset revisions; bundle the required assets in the image,
+with no runtime downloads. No GPU requirement or alternative community runtime is introduced.
+
+- **Why:** fewer compatibility assumptions while integrating the selected Qwen checkpoint.
+- **Not chosen:** a community runtime with extra compatibility and conversion work.
+- **Build checks:** synthesize representative narration twice in fresh processes with networking disabled; compare
+  complete WAV SHA-256 hashes. Pin generation settings and reset seed 0 per clip. Check the talker and sub-talker
+  settings explicitly rather than relying on upstream sampling defaults. Record wall time and peak memory. If
+  repeatability or practical CPU operation fails, report the evidence and revisit the choice before proceeding.
+- **Limit:** equal hashes must be demonstrated on the tested CPU/container platform; cross-architecture equality
+  is not established by that test and must not be claimed.
+
+Sources checked 2026-11-10:
+- [Official runtime and setup](https://github.com/QwenLM/Qwen3-TTS).
+- [Generation wrapper](https://github.com/QwenLM/Qwen3-TTS/blob/main/qwen_tts/inference/qwen3_tts_model.py):
+  generation parameters include both talker and sub-talker sampling settings.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/006-skip-blank-narration-audio.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/006-skip-blank-narration-audio.md
new file mode 100644
index 0000000..e3a973a
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/006-skip-blank-narration-audio.md
@@ -0,0 +1,14 @@
+# 006: Skip blank narration and retain step indexes in clip names
+
+**Date:** 2026-11-10 (ticket pass, Q6; agreed: "ok")
+
+**Question:** skip audio for blank narration or create a silent WAV?
+
+**Decision:** **blank or missing narration produces no audio file and no step `audio` field.** Preserve the step
+and original transcript text. Normalize whitespace in synthesis input by replacing whitespace runs with one space
+and trimming; use plain text, without caption entity escaping. Nonblank narration is voiced even when its action
+has zero duration. Clip names use the original zero-based step index, padded to at least three digits, so skipped
+steps leave gaps (`000.wav`, `002.wav`).
+
+- **Why:** matches blank-caption behavior without inventing a silence duration; step identities remain clear.
+- **Not chosen:** silent WAVs for blank steps, or compacting filenames around skipped steps.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/007-demo-specific-portable-audio-folder.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/007-demo-specific-portable-audio-folder.md
new file mode 100644
index 0000000..f181abf
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/decisions/007-demo-specific-portable-audio-folder.md
@@ -0,0 +1,13 @@
+# 007: Store clips beside the transcript in a demo-specific audio folder
+
+**Date:** 2026-11-10 (ticket pass, Q7; agreed: "ok")
+
+**Question:** keep audio beside the transcript or inside the ignored work folder?
+
+**Decision:** **`demo.ts` produces `demo.audio/000.wav` beside `demo.transcript.json`.** Each step's `audio.file`
+is relative to the transcript directory, for example `demo.audio/000.wav`. Demo-specific folders prevent different
+scripts in one directory from sharing a generic `audio/` namespace.
+
+- **Why:** the transcript and referenced clips can be copied together for GH-5 and reproducibility checks.
+- **Not chosen:** `.flow-reel/demo/audio/`, which makes referenced output depend on an ignored intermediate folder;
+  or a shared `audio/` folder, which collides between demos.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/draft.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/draft.md
index 2a36fc5..d772500 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/draft.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/draft.md
@@ -2,26 +2,46 @@
 
 ## Problem
 
-Captions alone are not a narrated demo; the voice must work offline, in CI, with no key (decision 004).
+GH-3 preserves narration and writes captions, but produces no speech. Narration needs a local, keyless voice that
+works offline in the recording image, with repeatable audio for later sync and comparison work.
 
 ## Change
 
-- A TTS adapter interface in `flow-reel`: text in, an audio clip and its duration out.
-- A local default voice in the image, called as a subprocess (decision 008).
-- Each step's narration is synthesised to `audio/NNN.wav`; `transcript.json` gets `voice` and each step's `audio`
-  with `durationMs` and `sha256` (decision 011).
-- A cloud adapter can be selected with a key; the local one stays the default.
+- Add a small internal TTS adapter boundary: text in, WAV clips and measured durations and SHA-256 hashes out.
+- Bundle `Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice`, using Ryan in English, with the official Python `qwen-tts`
+  runtime on CPU. Pin dependencies and model/tokenizer assets; no runtime downloads (ticket decisions 002-005).
+- `flow-reel record demo.ts` synthesizes narration after capture, writes `demo.audio/NNN.wav`, and adds `voice`
+  and step `audio` metadata to schema version 1. Paths are relative to the transcript directory; filenames use
+  zero-based step indexes padded to at least three digits (ticket decisions 001, 006, 007).
+- Preserve original narration. Normalize whitespace only for synthesis, without caption entity escaping.
+  Missing or blank narration has no clip or `audio` field; nonblank narration is voiced even for a zero-duration
+  action (ticket decision 006).
+- Record the adapter, voice and seed; reset seed 0 per clip and pin generation settings. Verify complete WAV
+  hashes across fresh processes on the tested CPU/container platform.
+- Synthesis failure fails the command with context. The MP4 stays silent and step/caption timing stays as
+  recorded; GH-5 adds holds and muxing.
+
+Ticket decision 001 supersedes story decision 011 only in assigning voice/audio metadata to GH-4 rather than
+GH-5. The schema itself is unchanged. Decisions 002-003 select Qwen instead of the story's Kokoro/Piper candidates.
 
 ## Out of scope
 
-Holding steps for their clip and muxing audio into the video (ticket 4).
+- Step holds, audio muxing, sync checks and a transcript-comparison command (GH-5).
+- Cloud providers, credentials and secret forwarding; those would be separately planned work (decision 004).
+- Voice cloning, reference recordings, voice design, voice/language configuration flags.
+- GPU execution, community inference runtimes, cross-architecture byte-equality claims, cursor/zoom polish and SFX.
 
 ## Done when
 
-- Synthesising the sample demo's narration twice with the local voice gives identical `sha256` per clip.
-- It runs with the network off.
-
-## For the ticket pass
-
-- Kokoro or Piper: quality, image size, CPU speed, licence.
-- The adapter's interface, and which cloud adapter (if any) ships first.
+- Recording produces valid voice/audio metadata and playable nonempty WAVs for nonblank narration. Referenced
+  files exist; durations and complete-file SHA-256 hashes match the actual WAVs.
+- Fresh synthesis processes with networking disabled produce matching hashes for the same normalized text and
+  settings on the tested CPU/container platform. The test regenerates clips rather than reusing cached audio.
+- Blank narration is skipped, step indexes remain stable, and original transcript text stays intact. Rerunning
+  with fewer voiced steps leaves no stale generated clips, while preserving unrelated files and other demos.
+- Missing assets or a worker failure produce a nonzero command result, with no new transcript claiming successful
+  synthesis. The MP4 stays silent; caption/step timing and existing schema compatibility remain intact.
+- CPU wall time, peak memory, image size and tested platform are reported; sample narration is inspected for
+  intelligibility. If CPU operation or repeatability fails, surface evidence before changing engine or contract.
+- Type checking, unit tests, build and Docker E2E pass, including existing resolution, frame-alignment, caption
+  playback and ±150 ms step-start checks. README describes clips and the still-silent MP4 accurately.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_draft.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_draft.md
new file mode 100644
index 0000000..2a36fc5
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_draft.md
@@ -0,0 +1,27 @@
+# Voice narration through a TTS adapter with a local default voice
+
+## Problem
+
+Captions alone are not a narrated demo; the voice must work offline, in CI, with no key (decision 004).
+
+## Change
+
+- A TTS adapter interface in `flow-reel`: text in, an audio clip and its duration out.
+- A local default voice in the image, called as a subprocess (decision 008).
+- Each step's narration is synthesised to `audio/NNN.wav`; `transcript.json` gets `voice` and each step's `audio`
+  with `durationMs` and `sha256` (decision 011).
+- A cloud adapter can be selected with a key; the local one stays the default.
+
+## Out of scope
+
+Holding steps for their clip and muxing audio into the video (ticket 4).
+
+## Done when
+
+- Synthesising the sample demo's narration twice with the local voice gives identical `sha256` per clip.
+- It runs with the network off.
+
+## For the ticket pass
+
+- Kokoro or Piper: quality, image size, CPU speed, licence.
+- The adapter's interface, and which cloud adapter (if any) ships first.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_meta.md
new file mode 100644
index 0000000..e8f8a3d
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1353_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Voice narration through a TTS adapter with a local default voice
+key: GH-4
+parent: GH-1
+status: tracked
+branch:
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/4
+mr:
+created: 2026-11-02
+updated: 2026-11-02
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1358_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1358_meta.md
new file mode 100644
index 0000000..6eca799
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1358_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Voice narration through a TTS adapter with a local default voice
+key: GH-4
+parent: GH-1
+status: planned
+branch:
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/4
+mr:
+created: 2026-11-02
+updated: 2026-11-10
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1423_impl.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1423_impl.md
new file mode 100644
index 0000000..32fe3a2
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1423_impl.md
@@ -0,0 +1,110 @@
+# Implementation: Local Qwen narration clips
+
+Planned 2026-11-10 against `main` at `487d62b`, after GH-3 merged in PR #11. Follow story decisions 004, 008-011
+and ticket decisions 001-007. No existing follow-ups are taken up. GH-5 owns holds and muxing.
+
+## Current code and baseline
+
+- `src/runner/run.ts` preserves narration, calibrates step/event times, writes a silent MP4, validates the
+  transcript and writes SRT/VTT. No TTS code or Python environment exists in the image.
+- `src/schema/transcript.ts` already defines optional `voice: { adapter, voice, seed }` and step
+  `audio: { file, durationMs, sha256 }`. Keep version 1 and acceptance of old transcripts.
+- `src/index.ts` exposes URL/viewport options and `step(narration, action)`. No public TTS configuration is needed
+  for this ticket's fixed default. The host launcher mounts the script folder and runs the versioned image.
+- `docker/Dockerfile` extends Playwright Noble, installs Xvfb/ffmpeg and copies `dist`. npm publishes `dist` and
+  `docker`; put Python helpers and their pinned build specifications under `docker/` so fallback builds include them.
+- Baseline: type checking and all 45 unit tests passed. The sandbox loader subprocess failed with empty stderr;
+  all tests passed outside the sandbox. Docker E2E was not rerun for planning; PR #11 CI passed.
+
+## Read first
+
+- This ticket's decisions 001-007 and inherited story decisions 004, 008, 009, 010 and 011.
+- `src/runner/run.ts`, `src/schema/transcript.ts`, `src/schema/check.ts`, `src/runner/captions.ts`.
+- `src/index.ts`, `src/cli.ts`, `src/host/launch.ts`, `src/runner/recorder.ts` (`durationMs`).
+- `docker/Dockerfile`, `package.json`, `tsconfig.build.json`, `.github/workflows/ci.yml`, `README.md`.
+- `test/unit/schema.test.ts`, `test/unit/captions.test.ts`, `test/e2e/record.test.ts`, `test/e2e/player.ts`.
+- [Official runtime](https://github.com/QwenLM/Qwen3-TTS), especially its inference generation wrapper, and
+  [selected checkpoint](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice). Read pinned-revision code;
+  GPU-oriented upstream examples do not establish CPU performance.
+
+## Steps
+
+1. **Prove the real CPU/offline path first.** Add a small Python worker under `docker/tts/`. Install the official
+   package in an isolated environment, pin compatible CPU PyTorch/dependency versions, and pin immutable model
+   and tokenizer revisions with verified asset hashes. Fetch all required assets at image build time, keeping
+   applicable licences/notices. Load explicit local paths with runtime networking disabled. Use CPU float32 and
+   a CPU-compatible attention implementation; no CUDA or FlashAttention installation.
+   Load the model once per worker invocation, process clips serially and write mono PCM16 WAVs at its returned
+   sample rate. Reset Python/NumPy/PyTorch seeds to 0 per clip, enable deterministic execution, and explicitly pin
+   talker and sub-talker generation settings. Start with upstream sampling settings plus the reset seed and prove
+   equality. Bound generation; detect empty output or token-limit truncation rather than claiming success.
+   Pass indexed texts and destinations as structured JSON over stdin; stdout carries machine-readable results
+   and stderr carries diagnostics. Never interpolate narration into shell commands.
+   → check: add a real Docker synthesis test running the worker in two fresh `--network none` containers with
+   separate empty output folders and no audio reuse. Assert playable, nonempty WAVs and equal complete-file hashes
+   for representative lines, including repeated text at different indexes to test seed reset. Measure wall time,
+   peak memory and image size. Inspect/listen to a generated sample. If CPU operation, quality or repeatability
+   fails, report evidence before substituting the runtime/model or weakening requirements.
+
+2. **Add the narrow TypeScript adapter and clip orchestration.** Create `src/runner/tts.ts` with an internal
+   adapter interface holding fixed `{ adapter, voice, seed }` identity and an asynchronous synthesis operation
+   for indexed text requests and destinations. Implement only Qwen via `spawn` with argument arrays. Keep one
+   multi-clip worker call so the model loads once; no registry, public plugin API, cloud secrets or CLI flags.
+   Normalize whitespace runs to one space and trim synthesis input, skip missing/blank text and preserve original
+   steps. Use original indexes with `padStart(3, "0")`. Compute SHA-256 from complete WAVs in Node; measure duration
+   from actual sample data or checked ffprobe output, rejecting missing/invalid/empty audio. Return metadata only
+   after successful validation. Keep worker invocation behind the adapter seam so orchestration tests can use a
+   small fake without presenting fake output as proof of real Qwen reproducibility.
+   → check: write failing `test/unit/tts.test.ts` tests, then implement. Cover blank/missing narration, whitespace,
+   Unicode, literal markup/entity-looking text without caption escaping, nonblank zero-duration steps, gaps,
+   indexes above 999, duration/hash correctness, paths with spaces, nonmutation and contextual worker failures.
+
+3. **Integrate after capture and before publishing the transcript.** Call synthesis from `src/runner/run.ts`
+   after capture stops and final times are calibrated. Close browser/display before expensive synthesis where
+   practical without altering capture timing. Write `<name>.audio/NNN.wav` beside the transcript and attach
+   relative paths such as `demo.audio/000.wav` and measured metadata. Write the fixed voice identity in version 1.
+   Keep timing, `endMs`, captions and the silent video unchanged. For an all-blank demo, skip launching the worker,
+   retain configured voice identity and omit step audio.
+   Replace this demo's generated numeric WAV set on success so fewer voiced steps leave no stale generated clips.
+   Scope replacement to flow-reel's numeric WAVs in this demo-specific folder; preserve unrelated files and other
+   demos. Stage outputs if needed to avoid publishing a partial clip set. Failure must fail the command and must
+   not publish a new transcript claiming complete successful synthesis.
+   → check: test reruns with fewer voiced steps and all-blank narration at the orchestration seam; preserve other
+   files and demos. Exercise worker failure/missing assets and useful nonzero errors. Extend E2E to verify every
+   referenced WAV, PCM encoding, positive duration, actual duration/hash and transcript-relative resolution.
+   Existing old-schema acceptance must stay green.
+
+4. **Verify recordings and document output.** Extend the existing two fixture recordings in
+   `test/e2e/record.test.ts`: compare voice identity, clip hashes and durations across runs, while retaining original
+   narration and all resolution, frame-alignment, caption playback and ±150 ms checks. The separate synthesis
+   test disables networking; browser recording still needs the host fixture server. Exercise the shipped worker,
+   not a test-only replacement.
+   Update README with Qwen/Ryan/English, measured CPU/disk needs, build-time downloads versus offline synthesis,
+   `demo.audio/` paths, skipped blanks, reproducibility limits and the still-silent MP4. Audio may exceed action
+   windows until GH-5 adds holds and muxing. Change CI only if measured resource/time requirements require it;
+   keep actual CPU/offline synthesis in CI rather than replacing it with fakes.
+   → check: run `npm run typecheck`, `npm test`, `npm run build`, `npm run test:e2e`. Check output references against
+   README. Run `npm pack --dry-run` to verify helper and build specifications ship, without model weights in npm.
+   Record results and measurements as build notes in this plan.
+
+## Tests
+
+- Unit: normalization/eligibility, stable indexes, relative paths, metadata, nonmutation, scoped replacement and
+  failures at the adapter seam; existing schema compatibility.
+- Real Docker synthesis: two fresh offline processes, regenerated WAVs, complete-file equality, seed reset,
+  actual audio validity and CPU resource measurements. No speed or memory claims before measurement.
+- Existing recording E2E: both runs acquire audio clips and metadata while all GH-2/GH-3 guarantees remain.
+- Sample listening: intelligibility and obvious truncation/repetition. If listening is unavailable, report that
+  limitation and request human review of a concrete generated sample; parsing WAVs is not a listening check.
+
+## Risks
+
+- Qwen's model and Python dependencies increase image size and may exceed current CI CPU/memory/time budgets.
+  Measure first; surface failures before changing engine, requiring a GPU or dropping checks.
+- Seed alone is not proof of determinism. Pin settings/assets, reset per clip and test fresh processes. Equality
+  across CPU architectures is unproven; GH-9 must validate its release architectures separately.
+- Empty, truncated or runaway speech must fail with step context rather than be accepted as a valid clip.
+- TTS during real-time capture could break timing: synthesize only after capture stops.
+- Relative paths must work with spaces and adjacent demos. Cleanup must preserve unrelated files. Original
+  narration and caption escaping stay intact.
+- Clip durations intentionally do not fit step windows yet. GH-5 owns that work; do not move timestamps to hide it.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1735_impl.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1735_impl.md
new file mode 100644
index 0000000..bf3b903
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1735_impl.md
@@ -0,0 +1,126 @@
+# Implementation: Local Qwen narration clips
+
+Planned 2026-11-10 against `main` at `487d62b`, after GH-3 merged in PR #11. Follow story decisions 004, 008-011
+and ticket decisions 001-007. No existing follow-ups are taken up. GH-5 owns holds and muxing.
+
+## Build notes (in progress, 2026-11-10)
+
+- The first real offline test failed because the image had no Python TTS environment. Adapter tests then exposed
+  missing synthesis, unnecessary worker calls for blank input, stale clips after reruns and acceptance of invalid
+  audio; those slices now pass (50 unit tests overall). Type checking and build pass.
+- CPU-wheel index resolution failed in the first build. Requirements now pin official CPU wheel URLs/checksums
+  for Python 3.12 on x86_64/aarch64; only x86_64 is being tested here. Remaining runtime dependencies are version
+  pinned. The selected model revision and published weight/configuration hashes are recorded in assets.json.
+- The completed image measured 6,999,289,865 bytes (about 7.0 GB). The asset download/verification step took
+  377.9 seconds on this connection. Real offline generation and resource measurements are still pending.
+- The worker loads once per job, processes clips serially and resets seed 0 per clip. Generation is bounded to
+  1,024 codec tokens; the official wrapper discards codec counts, so its underlying generation boundary is checked
+  for limit exhaustion before accepting WAV output. The Node subprocess has a 15-minute job timeout.
+- E2E files run serially to avoid competing recording/TTS workloads. Their output subfolders are separate under
+  test/e2e/out. npm pack dry-run includes the worker, pinned requirements and model build specifications.
+
+## Current code and baseline
+
+- `src/runner/run.ts` preserves narration, calibrates step/event times, writes a silent MP4, validates the
+  transcript and writes SRT/VTT. No TTS code or Python environment exists in the image.
+- `src/schema/transcript.ts` already defines optional `voice: { adapter, voice, seed }` and step
+  `audio: { file, durationMs, sha256 }`. Keep version 1 and acceptance of old transcripts.
+- `src/index.ts` exposes URL/viewport options and `step(narration, action)`. No public TTS configuration is needed
+  for this ticket's fixed default. The host launcher mounts the script folder and runs the versioned image.
+- `docker/Dockerfile` extends Playwright Noble, installs Xvfb/ffmpeg and copies `dist`. npm publishes `dist` and
+  `docker`; put Python helpers and their pinned build specifications under `docker/` so fallback builds include them.
+- Baseline: type checking and all 45 unit tests passed. The sandbox loader subprocess failed with empty stderr;
+  all tests passed outside the sandbox. Docker E2E was not rerun for planning; PR #11 CI passed.
+
+## Read first
+
+- This ticket's decisions 001-007 and inherited story decisions 004, 008, 009, 010 and 011.
+- `src/runner/run.ts`, `src/schema/transcript.ts`, `src/schema/check.ts`, `src/runner/captions.ts`.
+- `src/index.ts`, `src/cli.ts`, `src/host/launch.ts`, `src/runner/recorder.ts` (`durationMs`).
+- `docker/Dockerfile`, `package.json`, `tsconfig.build.json`, `.github/workflows/ci.yml`, `README.md`.
+- `test/unit/schema.test.ts`, `test/unit/captions.test.ts`, `test/e2e/record.test.ts`, `test/e2e/player.ts`.
+- [Official runtime](https://github.com/QwenLM/Qwen3-TTS), especially its inference generation wrapper, and
+  [selected checkpoint](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice). Read pinned-revision code;
+  GPU-oriented upstream examples do not establish CPU performance.
+
+## Steps
+
+1. **Prove the real CPU/offline path first.** Add a small Python worker under `docker/tts/`. Install the official
+   package in an isolated environment, pin compatible CPU PyTorch/dependency versions, and pin immutable model
+   and tokenizer revisions with verified asset hashes. Fetch all required assets at image build time, keeping
+   applicable licences/notices. Load explicit local paths with runtime networking disabled. Use CPU float32 and
+   a CPU-compatible attention implementation; no CUDA or FlashAttention installation.
+   Load the model once per worker invocation, process clips serially and write mono PCM16 WAVs at its returned
+   sample rate. Reset Python/NumPy/PyTorch seeds to 0 per clip, enable deterministic execution, and explicitly pin
+   talker and sub-talker generation settings. Start with upstream sampling settings plus the reset seed and prove
+   equality. Bound generation; detect empty output or token-limit truncation rather than claiming success.
+   Pass indexed texts and destinations as structured JSON over stdin; stdout carries machine-readable results
+   and stderr carries diagnostics. Never interpolate narration into shell commands.
+   → check: add a real Docker synthesis test running the worker in two fresh `--network none` containers with
+   separate empty output folders and no audio reuse. Assert playable, nonempty WAVs and equal complete-file hashes
+   for representative lines, including repeated text at different indexes to test seed reset. Measure wall time,
+   peak memory and image size. Inspect/listen to a generated sample. If CPU operation, quality or repeatability
+   fails, report evidence before substituting the runtime/model or weakening requirements.
+
+2. **Add the narrow TypeScript adapter and clip orchestration.** Create `src/runner/tts.ts` with an internal
+   adapter interface holding fixed `{ adapter, voice, seed }` identity and an asynchronous synthesis operation
+   for indexed text requests and destinations. Implement only Qwen via `spawn` with argument arrays. Keep one
+   multi-clip worker call so the model loads once; no registry, public plugin API, cloud secrets or CLI flags.
+   Normalize whitespace runs to one space and trim synthesis input, skip missing/blank text and preserve original
+   steps. Use original indexes with `padStart(3, "0")`. Compute SHA-256 from complete WAVs in Node; measure duration
+   from actual sample data or checked ffprobe output, rejecting missing/invalid/empty audio. Return metadata only
+   after successful validation. Keep worker invocation behind the adapter seam so orchestration tests can use a
+   small fake without presenting fake output as proof of real Qwen reproducibility.
+   → check: write failing `test/unit/tts.test.ts` tests, then implement. Cover blank/missing narration, whitespace,
+   Unicode, literal markup/entity-looking text without caption escaping, nonblank zero-duration steps, gaps,
+   indexes above 999, duration/hash correctness, paths with spaces, nonmutation and contextual worker failures.
+
+3. **Integrate after capture and before publishing the transcript.** Call synthesis from `src/runner/run.ts`
+   after capture stops and final times are calibrated. Close browser/display before expensive synthesis where
+   practical without altering capture timing. Write `<name>.audio/NNN.wav` beside the transcript and attach
+   relative paths such as `demo.audio/000.wav` and measured metadata. Write the fixed voice identity in version 1.
+   Keep timing, `endMs`, captions and the silent video unchanged. For an all-blank demo, skip launching the worker,
+   retain configured voice identity and omit step audio.
+   Replace this demo's generated numeric WAV set on success so fewer voiced steps leave no stale generated clips.
+   Scope replacement to flow-reel's numeric WAVs in this demo-specific folder; preserve unrelated files and other
+   demos. Stage outputs if needed to avoid publishing a partial clip set. Failure must fail the command and must
+   not publish a new transcript claiming complete successful synthesis.
+   → check: test reruns with fewer voiced steps and all-blank narration at the orchestration seam; preserve other
+   files and demos. Exercise worker failure/missing assets and useful nonzero errors. Extend E2E to verify every
+   referenced WAV, PCM encoding, positive duration, actual duration/hash and transcript-relative resolution.
+   Existing old-schema acceptance must stay green.
+
+4. **Verify recordings and document output.** Extend the existing two fixture recordings in
+   `test/e2e/record.test.ts`: compare voice identity, clip hashes and durations across runs, while retaining original
+   narration and all resolution, frame-alignment, caption playback and ±150 ms checks. The separate synthesis
+   test disables networking; browser recording still needs the host fixture server. Exercise the shipped worker,
+   not a test-only replacement.
+   Update README with Qwen/Ryan/English, measured CPU/disk needs, build-time downloads versus offline synthesis,
+   `demo.audio/` paths, skipped blanks, reproducibility limits and the still-silent MP4. Audio may exceed action
+   windows until GH-5 adds holds and muxing. Change CI only if measured resource/time requirements require it;
+   keep actual CPU/offline synthesis in CI rather than replacing it with fakes.
+   → check: run `npm run typecheck`, `npm test`, `npm run build`, `npm run test:e2e`. Check output references against
+   README. Run `npm pack --dry-run` to verify helper and build specifications ship, without model weights in npm.
+   Record results and measurements as build notes in this plan.
+
+## Tests
+
+- Unit: normalization/eligibility, stable indexes, relative paths, metadata, nonmutation, scoped replacement and
+  failures at the adapter seam; existing schema compatibility.
+- Real Docker synthesis: two fresh offline processes, regenerated WAVs, complete-file equality, seed reset,
+  actual audio validity and CPU resource measurements. No speed or memory claims before measurement.
+- Existing recording E2E: both runs acquire audio clips and metadata while all GH-2/GH-3 guarantees remain.
+- Sample listening: intelligibility and obvious truncation/repetition. If listening is unavailable, report that
+  limitation and request human review of a concrete generated sample; parsing WAVs is not a listening check.
+
+## Risks
+
+- Qwen's model and Python dependencies increase image size and may exceed current CI CPU/memory/time budgets.
+  Measure first; surface failures before changing engine, requiring a GPU or dropping checks.
+- Seed alone is not proof of determinism. Pin settings/assets, reset per clip and test fresh processes. Equality
+  across CPU architectures is unproven; GH-9 must validate its release architectures separately.
+- Empty, truncated or runaway speech must fail with step context rather than be accepted as a valid clip.
+- TTS during real-time capture could break timing: synthesize only after capture stops.
+- Relative paths must work with spaces and adjacent demos. Cleanup must preserve unrelated files. Original
+  narration and caption escaping stay intact.
+- Clip durations intentionally do not fit step windows yet. GH-5 owns that work; do not move timestamps to hide it.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
index 59e9ec7..a396b10 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
@@ -1 +1,14 @@
 - 2026-11-02: tracked as GH-4 (https://github.com/codeonym-oss/flow-reel/issues/4).
+- 2026-11-10: began the ticket pass against main at 487d62b; 45 unit tests and type checking pass. Agreed that GH-4 generates clips and writes voice/audio metadata, with holds and muxing left to GH-5 (decision 001).
+- 2026-11-10: chose Qwen3-TTS 0.6B as the starting local engine, retaining CPU/offline and audio reproducibility requirements (decision 002).
+- 2026-11-10: selected the CustomVoice variant with Ryan in English; cloning and voice design stay outside GH-4 (decision 003).
+- 2026-11-10: limited GH-4 to the local adapter; cloud support would be separately planned work, while GH-5 remains holds and muxing (decision 004).
+- 2026-11-10: selected the official Python CPU runtime with pinned offline assets, fresh-process reproducibility checks and measured resource use (decision 005).
+- 2026-11-10: agreed to skip blank narration audio, preserve transcript text, normalize synthesis whitespace and keep original step indexes in clip filenames (decision 006).
+- 2026-11-10: chose a portable demo-specific audio folder beside the transcript, with transcript-relative clip paths (decision 007).
+- 2026-11-10: confirmed shared understanding ("ok go ahead"), archived previous draft/meta, wrote impl.md against 487d62b, revised the draft to local Qwen scope and marked planned. Tracker update awaits approval; no implementation or git mutation performed.
+- 2026-11-10: after approval ("ok go ahead"), replaced GH-4's GitHub description from draft.md and read it back to verify the agreed scope. Ticket pass complete; ready for groundwork:implement GH-4.
+- 2026-11-10: after approval ("ok"), fetched origin, created feat/4-tts-adapter-local-voice preserving planning changes, and moved GH-4 to In Progress on board 6; implementation started.
+- 2026-11-10: added implementation build notes covering red/green slices, pinned CPU wheel resolution, model asset verification, image size, generation bounds and serial E2E execution; real-model checks still running.
+- 2026-11-10: finished GH-4 implementation and reviewed both axes with zero findings. Type checking, 50 unit tests, build and a clean 10-test Docker E2E run pass (968.05s); audio hashes match and final step deltas are 2/2/3ms. Documented CPU/image costs and set CI timeout45min. Saved the approved odd-viewport issue under GH-2; no capture safeguard was weakened. Awaiting commit approval.
+- 2026-11-10: commit approved ("ok go"); committing the verified implementation and approved planning/follow-up files as feat: generate offline Qwen narration clips (#4).
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/impl.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/impl.md
new file mode 100644
index 0000000..62cd1d6
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/impl.md
@@ -0,0 +1,146 @@
+# Implementation: Local Qwen narration clips
+
+Planned 2026-11-10 against `main` at `487d62b`, after GH-3 merged in PR #11. Follow story decisions 004, 008-011
+and ticket decisions 001-007. No existing follow-ups are taken up. GH-5 owns holds and muxing.
+
+## Build notes (2026-11-10)
+
+- Implemented the official Qwen 0.6B CustomVoice CPU worker (Ryan/English) and internal TypeScript adapter.
+  Synthesis starts after capture, browser and display shutdown. WAVs are staged, validated and published to
+  the demo-specific audio folder before the transcript is written. No step timing, holds or muxing were added.
+- Observed red/green slices for missing synthesis, blank-input worker avoidance, stale clips and invalid audio.
+  The recording integration test failed on absent voice metadata before integration. All 50 unit tests pass.
+- Verified final `npm run typecheck`, `npm test` (50 passed), `npm run build`, and a clean
+  `npm run test:e2e` (10 passed across 2 files, 968.05 seconds). `git diff --check` passes.
+  The full E2E command's build and real Docker runs completed successfully; no tests were skipped in that run.
+- The final recording pair has identical audio metadata and complete WAV hashes; step start deltas are
+  2, 2 and 3 ms. Existing frame alignment, resolution and native caption playback assertions pass. Both direct
+  worker and command-level missing-asset failures are checked, including absence of a success transcript.
+- Real network-disabled workers regenerate the same WAV bytes in fresh processes. Repeated text at different
+  indexes also matches, proving per-clip seed reset. The person listened to the sample and answered "Sounds good".
+- Image size is about 7.0 GB unpacked. The model asset download/verification step took 377.9 seconds locally.
+  CPU-wheel index resolution initially failed; requirements now pin official CPU wheel URLs/checksums, plus
+  version-pinned runtime dependencies. Model/tokenizer revisions and published asset hashes are in assets.json.
+  Only x86_64 is tested; aarch64 wheel URLs are specified, without claiming cross-architecture equality.
+- Final recording synthesis batches took 195.525 and 206.414 seconds; final offline batches took 261.525 and
+  185.745 seconds. Peak process memory across measured runs reached about 5.6 GiB. README reports a representative
+  earlier 147-second run and explicitly notes host-load variation. CI timeout is 45 minutes to accommodate
+  cold image building and CPU synthesis; all checks remain enabled.
+- Generation is bounded to 1,024 codec tokens. The pinned wrapper discards codec counts, so its generation
+  boundary is checked for limit exhaustion before WAV acceptance. The Node worker job timeout is 15 minutes.
+- Initial capture attempts hit the existing overload guard; it was not weakened. The CLI error-path test uses a
+  960×540 viewport (1280×720 master), with full-resolution success fixtures preserved. A temporary 640×360 fixture
+  exposed the pre-existing odd-width/early-encoder-exit hang. The approved GH-2 follow-up records it separately.
+  A timed-out test container was removed, and the error-path test now names and force-cleans its own container
+  in a finally block with a child deadline shorter than the test deadline. No test containers remain running.
+- E2E files run serially and use separate output folders under test/e2e/out. Per-test cleanup preserves other
+  artifacts on focused reruns. npm pack dry-run includes the compiled adapter, worker, requirements and asset
+  specifications, without model weights (about 23 KB packed).
+- Parallel Standards and Spec reviews against 487d62b, including all new files and final incremental changes,
+  found zero issues on both axes. No agreed feature was changed or left unimplemented. Awaiting commit approval.
+
+## Current code and baseline
+
+- `src/runner/run.ts` preserves narration, calibrates step/event times, writes a silent MP4, validates the
+  transcript and writes SRT/VTT. No TTS code or Python environment exists in the image.
+- `src/schema/transcript.ts` already defines optional `voice: { adapter, voice, seed }` and step
+  `audio: { file, durationMs, sha256 }`. Keep version 1 and acceptance of old transcripts.
+- `src/index.ts` exposes URL/viewport options and `step(narration, action)`. No public TTS configuration is needed
+  for this ticket's fixed default. The host launcher mounts the script folder and runs the versioned image.
+- `docker/Dockerfile` extends Playwright Noble, installs Xvfb/ffmpeg and copies `dist`. npm publishes `dist` and
+  `docker`; put Python helpers and their pinned build specifications under `docker/` so fallback builds include them.
+- Baseline: type checking and all 45 unit tests passed. The sandbox loader subprocess failed with empty stderr;
+  all tests passed outside the sandbox. Docker E2E was not rerun for planning; PR #11 CI passed.
+
+## Read first
+
+- This ticket's decisions 001-007 and inherited story decisions 004, 008, 009, 010 and 011.
+- `src/runner/run.ts`, `src/schema/transcript.ts`, `src/schema/check.ts`, `src/runner/captions.ts`.
+- `src/index.ts`, `src/cli.ts`, `src/host/launch.ts`, `src/runner/recorder.ts` (`durationMs`).
+- `docker/Dockerfile`, `package.json`, `tsconfig.build.json`, `.github/workflows/ci.yml`, `README.md`.
+- `test/unit/schema.test.ts`, `test/unit/captions.test.ts`, `test/e2e/record.test.ts`, `test/e2e/player.ts`.
+- [Official runtime](https://github.com/QwenLM/Qwen3-TTS), especially its inference generation wrapper, and
+  [selected checkpoint](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice). Read pinned-revision code;
+  GPU-oriented upstream examples do not establish CPU performance.
+
+## Steps
+
+1. **Prove the real CPU/offline path first.** Add a small Python worker under `docker/tts/`. Install the official
+   package in an isolated environment, pin compatible CPU PyTorch/dependency versions, and pin immutable model
+   and tokenizer revisions with verified asset hashes. Fetch all required assets at image build time, keeping
+   applicable licences/notices. Load explicit local paths with runtime networking disabled. Use CPU float32 and
+   a CPU-compatible attention implementation; no CUDA or FlashAttention installation.
+   Load the model once per worker invocation, process clips serially and write mono PCM16 WAVs at its returned
+   sample rate. Reset Python/NumPy/PyTorch seeds to 0 per clip, enable deterministic execution, and explicitly pin
+   talker and sub-talker generation settings. Start with upstream sampling settings plus the reset seed and prove
+   equality. Bound generation; detect empty output or token-limit truncation rather than claiming success.
+   Pass indexed texts and destinations as structured JSON over stdin; stdout carries machine-readable results
+   and stderr carries diagnostics. Never interpolate narration into shell commands.
+   → check: add a real Docker synthesis test running the worker in two fresh `--network none` containers with
+   separate empty output folders and no audio reuse. Assert playable, nonempty WAVs and equal complete-file hashes
+   for representative lines, including repeated text at different indexes to test seed reset. Measure wall time,
+   peak memory and image size. Inspect/listen to a generated sample. If CPU operation, quality or repeatability
+   fails, report evidence before substituting the runtime/model or weakening requirements.
+
+2. **Add the narrow TypeScript adapter and clip orchestration.** Create `src/runner/tts.ts` with an internal
+   adapter interface holding fixed `{ adapter, voice, seed }` identity and an asynchronous synthesis operation
+   for indexed text requests and destinations. Implement only Qwen via `spawn` with argument arrays. Keep one
+   multi-clip worker call so the model loads once; no registry, public plugin API, cloud secrets or CLI flags.
+   Normalize whitespace runs to one space and trim synthesis input, skip missing/blank text and preserve original
+   steps. Use original indexes with `padStart(3, "0")`. Compute SHA-256 from complete WAVs in Node; measure duration
+   from actual sample data or checked ffprobe output, rejecting missing/invalid/empty audio. Return metadata only
+   after successful validation. Keep worker invocation behind the adapter seam so orchestration tests can use a
+   small fake without presenting fake output as proof of real Qwen reproducibility.
+   → check: write failing `test/unit/tts.test.ts` tests, then implement. Cover blank/missing narration, whitespace,
+   Unicode, literal markup/entity-looking text without caption escaping, nonblank zero-duration steps, gaps,
+   indexes above 999, duration/hash correctness, paths with spaces, nonmutation and contextual worker failures.
+
+3. **Integrate after capture and before publishing the transcript.** Call synthesis from `src/runner/run.ts`
+   after capture stops and final times are calibrated. Close browser/display before expensive synthesis where
+   practical without altering capture timing. Write `<name>.audio/NNN.wav` beside the transcript and attach
+   relative paths such as `demo.audio/000.wav` and measured metadata. Write the fixed voice identity in version 1.
+   Keep timing, `endMs`, captions and the silent video unchanged. For an all-blank demo, skip launching the worker,
+   retain configured voice identity and omit step audio.
+   Replace this demo's generated numeric WAV set on success so fewer voiced steps leave no stale generated clips.
+   Scope replacement to flow-reel's numeric WAVs in this demo-specific folder; preserve unrelated files and other
+   demos. Stage outputs if needed to avoid publishing a partial clip set. Failure must fail the command and must
+   not publish a new transcript claiming complete successful synthesis.
+   → check: test reruns with fewer voiced steps and all-blank narration at the orchestration seam; preserve other
+   files and demos. Exercise worker failure/missing assets and useful nonzero errors. Extend E2E to verify every
+   referenced WAV, PCM encoding, positive duration, actual duration/hash and transcript-relative resolution.
+   Existing old-schema acceptance must stay green.
+
+4. **Verify recordings and document output.** Extend the existing two fixture recordings in
+   `test/e2e/record.test.ts`: compare voice identity, clip hashes and durations across runs, while retaining original
+   narration and all resolution, frame-alignment, caption playback and ±150 ms checks. The separate synthesis
+   test disables networking; browser recording still needs the host fixture server. Exercise the shipped worker,
+   not a test-only replacement.
+   Update README with Qwen/Ryan/English, measured CPU/disk needs, build-time downloads versus offline synthesis,
+   `demo.audio/` paths, skipped blanks, reproducibility limits and the still-silent MP4. Audio may exceed action
+   windows until GH-5 adds holds and muxing. Change CI only if measured resource/time requirements require it;
+   keep actual CPU/offline synthesis in CI rather than replacing it with fakes.
+   → check: run `npm run typecheck`, `npm test`, `npm run build`, `npm run test:e2e`. Check output references against
+   README. Run `npm pack --dry-run` to verify helper and build specifications ship, without model weights in npm.
+   Record results and measurements as build notes in this plan.
+
+## Tests
+
+- Unit: normalization/eligibility, stable indexes, relative paths, metadata, nonmutation, scoped replacement and
+  failures at the adapter seam; existing schema compatibility.
+- Real Docker synthesis: two fresh offline processes, regenerated WAVs, complete-file equality, seed reset,
+  actual audio validity and CPU resource measurements. No speed or memory claims before measurement.
+- Existing recording E2E: both runs acquire audio clips and metadata while all GH-2/GH-3 guarantees remain.
+- Sample listening: intelligibility and obvious truncation/repetition. If listening is unavailable, report that
+  limitation and request human review of a concrete generated sample; parsing WAVs is not a listening check.
+
+## Risks
+
+- Qwen's model and Python dependencies increase image size and may exceed current CI CPU/memory/time budgets.
+  Measure first; surface failures before changing engine, requiring a GPU or dropping checks.
+- Seed alone is not proof of determinism. Pin settings/assets, reset per clip and test fresh processes. Equality
+  across CPU architectures is unproven; GH-9 must validate its release architectures separately.
+- Empty, truncated or runaway speech must fail with step context rather than be accepted as a valid clip.
+- TTS during real-time capture could break timing: synthesize only after capture stops.
+- Relative paths must work with spaces and adjacent demos. Cleanup must preserve unrelated files. Original
+  narration and caption escaping stay intact.
+- Clip durations intentionally do not fit step windows yet. GH-5 owns that work; do not move timestamps to hide it.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
index e8f8a3d..ed3bdfb 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
@@ -3,10 +3,10 @@ kind: ticket
 title: Voice narration through a TTS adapter with a local default voice
 key: GH-4
 parent: GH-1
-status: tracked
-branch:
+status: building
+branch: feat/4-tts-adapter-local-voice
 tracker-url: https://github.com/codeonym-oss/flow-reel/issues/4
 mr:
 created: 2026-11-02
-updated: 2026-11-02
+updated: 2026-11-10
 ---
diff --git a/src/runner/run.ts b/src/runner/run.ts
index de8f958..be51030 100644
--- a/src/runner/run.ts
+++ b/src/runner/run.ts
@@ -12,6 +12,7 @@ import { screenFor, startDisplay } from "./display.ts";
 import { loadDemo } from "./load.ts";
 import { trackNetwork } from "./network.ts";
 import { FPS, downscale, durationMs, firstFrameOfColour, startRecording } from "./recorder.ts";
+import { voiceSteps } from "./tts.ts";
 import { wrapPage } from "./wrap.ts";
 
 // A still moment before the first step and after the last; a short settle before each step, so its start doesn't
@@ -46,6 +47,8 @@ export async function record(scriptPath: string): Promise<void> {
     vtt: join(dir, `${name}.vtt`),
   };
   const { viewport, url } = demo.options;
+  const steps: TranscriptStep[] = [];
+  const events: RunnerEvent[] = [];
 
   const display = await startDisplay(viewport);
   try {
@@ -57,8 +60,6 @@ export async function record(scriptPath: string): Promise<void> {
       await page.locator("body").boundingBox(); // warms up the round-trip the first step would otherwise pay for
 
       const recording = await startRecording(out.master, screenFor(viewport));
-      const steps: TranscriptStep[] = [];
-      const events: RunnerEvent[] = [];
       const until = (ms: number) => sleep(Math.max(0, ms - recording.now()));
       await until(MARK_AT_MS);
       const markMs = recording.now();
@@ -115,24 +116,27 @@ export async function record(scriptPath: string): Promise<void> {
       writeFileSync(join(work, name, "master.json"), `${JSON.stringify({ startMs })}\n`);
 
       downscale(out.master, out.video, viewport, startMs);
-      const transcript: Transcript = {
-        version: 1,
-        script: basename(scriptPath),
-        video: { file: basename(out.video), width: viewport[0], height: viewport[1], fps: FPS, durationMs: durationMs(out.video) },
-        steps,
-      };
-      writeChecked(out.transcript, transcript, validateTranscript(transcript));
-      const captions = renderCaptions(transcript.steps);
-      writeFileSync(out.srt, captions.srt, "utf8");
-      writeFileSync(out.vtt, captions.vtt, "utf8");
-      const log = { version: 1 as const, events };
-      writeChecked(out.events, log, validateEvents(log));
     } finally {
       await context.close();
     }
   } finally {
     display.kill();
   }
+
+  // CPU synthesis starts only after capture, browser and display have finished.
+  const narration = await voiceSteps(steps, join(dir, `${name}.audio`));
+  const transcript: Transcript = {
+    version: 1,
+    script: basename(scriptPath),
+    video: { file: basename(out.video), width: viewport[0], height: viewport[1], fps: FPS, durationMs: durationMs(out.video) },
+    ...narration,
+  };
+  writeChecked(out.transcript, transcript, validateTranscript(transcript));
+  const captions = renderCaptions(transcript.steps);
+  writeFileSync(out.srt, captions.srt, "utf8");
+  writeFileSync(out.vtt, captions.vtt, "utf8");
+  const log = { version: 1 as const, events };
+  writeChecked(out.events, log, validateEvents(log));
 }
 
 function writeChecked(file: string, value: unknown, errors: string[]) {
diff --git a/src/runner/tts.ts b/src/runner/tts.ts
new file mode 100644
index 0000000..f9b8f1f
--- /dev/null
+++ b/src/runner/tts.ts
@@ -0,0 +1,79 @@
+import { execFileSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Transcript, TranscriptStep } from "../schema/transcript.ts";
+
+export interface ClipRequest { index: number; text: string; file: string }
+export interface TtsAdapter {
+  voice: NonNullable<Transcript["voice"]>;
+  synthesize(jobs: readonly ClipRequest[]): Promise<void>;
+}
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const qwen: TtsAdapter = {
+  voice: { adapter: "qwen3-tts-0.6b", voice: "Ryan", seed: 0 },
+  synthesize(jobs) {
+    return new Promise<void>((resolve, reject) => {
+      const child = spawn(join(root, "tts-venv/bin/python"), [join(root, "docker/tts/worker.py")], {
+        env: { ...process.env, HF_HUB_OFFLINE: "1", TRANSFORMERS_OFFLINE: "1" },
+        stdio: ["pipe", "ignore", "pipe"], timeout: 900_000, killSignal: "SIGKILL",
+      });
+      let diagnostics = "";
+      child.stderr.on("data", (chunk: Buffer) => { diagnostics = (diagnostics + chunk).slice(-65536); });
+      child.once("error", (error) => reject(new Error(`Qwen TTS could not start: ${error.message}`, { cause: error })));
+      child.stdin.on("error", () => {}); // startup/exit errors are reported with the worker diagnostics
+      child.once("close", (code, signal) => {
+        if (code !== 0) reject(new Error(`Qwen TTS failed (${signal ?? code}): ${diagnostics.trim()}`));
+        else {
+          if (diagnostics) process.stderr.write(diagnostics);
+          resolve();
+        }
+      });
+      child.stdin.end(JSON.stringify(jobs));
+    });
+  },
+};
+
+function clipMetadata(job: ClipRequest, audioDir: string) {
+  try {
+    const { streams: [audio], format } = JSON.parse(execFileSync("ffprobe", ["-v", "error",
+      "-select_streams", "a:0", "-show_entries", "stream=codec_name,channels,duration:format=format_name",
+      "-of", "json", job.file], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }));
+    const durationMs = Math.round(Number(audio?.duration) * 1000);
+    if (format.format_name !== "wav" || audio?.codec_name !== "pcm_s16le" || audio.channels !== 1
+      || !Number.isFinite(durationMs) || durationMs <= 0) throw new Error("expected nonempty mono PCM16 WAV");
+    return {
+      file: `${basename(audioDir)}/${basename(job.file)}`, durationMs,
+      sha256: createHash("sha256").update(readFileSync(job.file)).digest("hex"),
+    };
+  } catch (error) {
+    throw new Error(`step ${job.index} audio is invalid: ${(error as Error).message}`, { cause: error });
+  }
+}
+
+export async function voiceSteps(
+  steps: readonly TranscriptStep[], audioDir: string, adapter: TtsAdapter = qwen,
+): Promise<{ voice: TtsAdapter["voice"]; steps: TranscriptStep[] }> {
+  mkdirSync(audioDir, { recursive: true });
+  const staging = mkdtempSync(join(audioDir, ".pending-"));
+  try {
+    const jobs = steps.flatMap((step) => {
+      const text = (step.narration ?? "").replace(/\s+/g, " ").trim();
+      return text ? [{ index: step.index, text, file: join(staging, `${String(step.index).padStart(3, "0")}.wav`) }] : [];
+    });
+    if (jobs.length) await adapter.synthesize(jobs);
+    const audio = new Map(jobs.map((job) => [job.index, clipMetadata(job, audioDir)]));
+    for (const entry of readdirSync(audioDir, { withFileTypes: true })) {
+      if (entry.isFile() && /^\d{3,}\.wav$/.test(entry.name)) rmSync(join(audioDir, entry.name));
+    }
+    for (const job of jobs) renameSync(job.file, join(audioDir, basename(job.file)));
+    return { voice: adapter.voice, steps: steps.map(({ audio: _, ...step }) => {
+      const clip = audio.get(step.index);
+      return clip ? { ...step, audio: clip } : step;
+    }) };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
diff --git a/test/e2e/record.test.ts b/test/e2e/record.test.ts
index dfc1d7d..a659685 100644
--- a/test/e2e/record.test.ts
+++ b/test/e2e/record.test.ts
@@ -1,5 +1,6 @@
-import { execFile, execFileSync } from "node:child_process";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { type Server, createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 import { join, resolve } from "node:path";
@@ -9,16 +10,16 @@ import { type EventLog, validateEvents } from "../../src/schema/events.ts";
 import { type Transcript, validateTranscript } from "../../src/schema/transcript.ts";
 
 // The whole recorder, in Docker, against a fixture app served from the host's 127.0.0.1 (GH-2 impl.md step 12).
-const OUT = resolve("test/e2e/out");
+const OUT = resolve("test/e2e/out/record");
 const html = readFileSync(resolve("test/e2e/app/index.html"));
 let server: Server;
 let port: number;
 let image: string;
 const NARRATIONS = ["  Type <b>Ada</b> & &lt; --> 保存.\r\n  ", "Scroll down and save.", "Open the settings."];
 
-const script = (p: number) => `import { demo } from "flow-reel";
+const script = (p: number, viewport?: [number, number]) => `import { demo } from "flow-reel";
 
-export default demo({ url: "http://localhost:${p}/" }, async ({ page, step }) => {
+export default demo(${JSON.stringify({ url: `http://localhost:${p}/`, viewport })}, async ({ page, step }) => {
   await step(${JSON.stringify(NARRATIONS[0])}, () => page.getByRole("textbox", { name: "Name" }).fill("Ada"));
   await step(${JSON.stringify(NARRATIONS[1])}, () => page.getByRole("button", { name: "Save" }).click());
   await step(${JSON.stringify(NARRATIONS[2])}, () => page.getByRole("link", { name: "Settings" }).click());
@@ -30,10 +31,16 @@ interface Run { dir: string; transcript: Transcript; events: EventLog }
 // Async: the fixture server lives in this process, so the event loop must stay free while the recording runs.
 async function recordOnce(name: string): Promise<Run> {
   const dir = join(OUT, name);
+  rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, "demo.ts"), script(port));
-  const { stderr } = await promisify(execFile)(process.execPath, ["dist/cli.js", "record", join(dir, "demo.ts")]);
-  if (stderr) console.error(stderr);
+  try {
+    const { stderr } = await promisify(execFile)(process.execPath, ["dist/cli.js", "record", join(dir, "demo.ts")]);
+    if (stderr) writeFileSync(join(dir, "record.log"), stderr);
+  } catch (error) {
+    writeFileSync(join(dir, "record.log"), (error as { stderr?: string }).stderr ?? String(error));
+    throw error;
+  }
   return {
     dir,
     transcript: JSON.parse(readFileSync(join(dir, "demo.transcript.json"), "utf8")),
@@ -62,20 +69,60 @@ let a: Run;
 let b: Run;
 
 beforeAll(async () => {
-  rmSync(OUT, { recursive: true, force: true });
+  mkdirSync(OUT, { recursive: true });
   const { version } = JSON.parse(readFileSync("package.json", "utf8"));
   image = `ghcr.io/codeonym-oss/flow-reel:${version}`;
   execFileSync("docker", ["build", "-q", "-t", image, "-f", "docker/Dockerfile", "."], { stdio: "inherit" });
   server = createServer((_req, res) => res.writeHead(200, { "content-type": "text/html" }).end(html));
   await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
   port = (server.address() as AddressInfo).port;
-  a = await recordOnce("a");
-  b = await recordOnce("b");
 }, 900_000);
 
 afterAll(() => server?.close());
 
+it("fails the command without publishing a successful transcript when TTS assets are missing", async () => {
+  const dir = join(OUT, "missing-assets");
+  rmSync(dir, { recursive: true, force: true });
+  const assets = join(dir, "empty-model");
+  mkdirSync(assets, { recursive: true });
+  writeFileSync(join(dir, "demo.ts"), script(port, [960, 540]));
+  const container = `flow-reel-missing-tts-${randomUUID()}`;
+  try {
+    await expect(promisify(execFile)("docker", ["run", "--name", container, "--rm", "--init", "--shm-size=1g", "--network", "host",
+      "--user", `${process.getuid!()}:${process.getgid!()}`, "-v", `${dir}:/work`,
+      "-v", `${assets}:/opt/flow-reel/tts-model:ro`, image, "record", "/work/demo.ts"], { timeout: 90_000 }))
+      .rejects.toMatchObject({ code: 1, stderr: expect.stringContaining("Qwen TTS failed") });
+  } finally {
+    // A killed Docker client can leave its container alive, holding the host-network X11 socket.
+    spawnSync("docker", ["rm", "--force", container], { stdio: "ignore", timeout: 10_000 });
+  }
+  expect(existsSync(join(dir, "demo.transcript.json"))).toBe(false);
+}, 120_000);
+
 describe("flow-reel record", () => {
+  beforeAll(async () => {
+    a = await recordOnce("a");
+    b = await recordOnce("b");
+  }, 900_000);
+
+  it("writes portable Qwen clips with measured metadata and the same audio on both runs", () => {
+    for (const run of [a, b]) {
+      expect(run.transcript.voice).toEqual({ adapter: "qwen3-tts-0.6b", voice: "Ryan", seed: 0 });
+      run.transcript.steps.forEach((step, index) => {
+        expect(step.audio?.file).toBe(`demo.audio/${String(index).padStart(3, "0")}.wav`);
+        const file = join(run.dir, step.audio!.file);
+        const { streams: [audio] } = JSON.parse(execFileSync("ffprobe", ["-v", "error", "-show_streams", "-of", "json", file], { encoding: "utf8" }));
+        expect(audio).toMatchObject({ codec_name: "pcm_s16le", channels: 1 });
+        expect(step.audio!.durationMs).toBe(Math.round(Number(audio.duration) * 1000));
+        expect(step.audio!.durationMs).toBeGreaterThan(0);
+        expect(step.audio!.sha256).toBe(createHash("sha256").update(readFileSync(file)).digest("hex"));
+      });
+      const { streams } = JSON.parse(execFileSync("ffprobe", ["-v", "error", "-show_entries", "stream=codec_type", "-of", "json", join(run.dir, "demo.mp4")], { encoding: "utf8" }));
+      expect(streams.map((s: { codec_type: string }) => s.codec_type)).toEqual(["video"]);
+    }
+    expect(a.transcript.steps.map((s) => s.audio)).toEqual(b.transcript.steps.map((s) => s.audio));
+  });
+
   it("loads WebVTT in Chromium with literal text and displays the active caption during playback", async () => {
     for (const run of [a, b]) {
       const { stdout } = await promisify(execFile)("docker", ["run", "--rm", "--init", "--shm-size=1g",
diff --git a/test/e2e/tts.test.ts b/test/e2e/tts.test.ts
new file mode 100644
index 0000000..ca5c1aa
--- /dev/null
+++ b/test/e2e/tts.test.ts
@@ -0,0 +1,55 @@
+import { execFile, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { beforeAll, expect, it } from "vitest";
+
+const OUT = resolve("test/e2e/out/tts");
+const { version } = JSON.parse(readFileSync("package.json", "utf8"));
+const image = `ghcr.io/codeonym-oss/flow-reel:${version}`;
+
+beforeAll(() => {
+  mkdirSync(OUT, { recursive: true });
+  execFileSync("docker", ["build", "-q", "-t", image, "-f", "docker/Dockerfile", "."], { stdio: "inherit" });
+}, 900_000);
+
+it("synthesizes identical playable WAVs in fresh offline processes with a reset seed per clip", async () => {
+  const hashes: string[][] = [];
+  for (const run of ["a", "b"]) {
+    const dir = join(OUT, run);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const worker = promisify(execFile)("docker", ["run", "--rm", "--init", "--network", "none", "-i",
+      "--user", `${process.getuid!()}:${process.getgid!()}`, "-v", `${dir}:/work`,
+      "--entrypoint", "/opt/flow-reel/tts-venv/bin/python", image, "/opt/flow-reel/docker/tts/worker.py"],
+    { timeout: 600_000, maxBuffer: 1 << 20 });
+    worker.child.stdin!.end(JSON.stringify([
+      { index: 0, text: "Open the settings.", file: "/work/000.wav" },
+      { index: 1, text: "Scroll down and save.", file: "/work/001.wav" },
+      { index: 2, text: "Open the settings.", file: "/work/002.wav" },
+    ]));
+    const { stdout, stderr } = await worker;
+    writeFileSync(join(dir, "synthesis.log"), stderr);
+    expect(JSON.parse(stdout)).toEqual({ clips: 3 });
+    hashes.push([0, 1, 2].map((index) => {
+      const file = join(dir, `${index.toString().padStart(3, "0")}.wav`);
+      const { streams: [audio] } = JSON.parse(execFileSync("ffprobe", ["-v", "error", "-show_streams", "-of", "json", file], { encoding: "utf8" }));
+      expect(audio).toMatchObject({ codec_name: "pcm_s16le", channels: 1 });
+      expect(Number(audio.duration)).toBeGreaterThan(0);
+      return createHash("sha256").update(readFileSync(file)).digest("hex");
+    }));
+  }
+  expect(hashes[0]).toEqual(hashes[1]);
+  expect(hashes[0][0]).toBe(hashes[0][2]);
+}, 1_200_000);
+
+it("fails clearly when bundled assets are missing, with no network fallback or successful output", async () => {
+  const empty = join(OUT, "missing-assets");
+  mkdirSync(empty, { recursive: true });
+  const worker = promisify(execFile)("docker", ["run", "--rm", "--init", "--network", "none", "-i",
+    "-v", `${empty}:/opt/flow-reel/tts-model:ro`, "--entrypoint", "/opt/flow-reel/tts-venv/bin/python",
+    image, "/opt/flow-reel/docker/tts/worker.py"], { timeout: 60_000 });
+  worker.child.stdin!.end(JSON.stringify([{ index: 0, text: "Speak.", file: "/tmp/never.wav" }]));
+  await expect(worker).rejects.toMatchObject({ code: 1, stdout: "", stderr: expect.stringContaining("Qwen TTS:") });
+}, 60_000);
diff --git a/test/unit/tts.test.ts b/test/unit/tts.test.ts
new file mode 100644
index 0000000..b18fc8f
--- /dev/null
+++ b/test/unit/tts.test.ts
@@ -0,0 +1,97 @@
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { voiceSteps, type TtsAdapter } from "../../src/runner/tts.ts";
+
+// Python wave: mono PCM16, 8 kHz, sixteen silent samples (2 ms).
+const WAV = Buffer.from("UklGRkQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", "base64");
+const dirs: string[] = [];
+const directory = () => {
+  const dir = mkdtempSync(join(tmpdir(), "flow reel tts "));
+  dirs.push(dir);
+  return dir;
+};
+afterEach(() => dirs.forEach((dir) => rmSync(dir, { recursive: true, force: true })));
+const voice = { adapter: "fixture", voice: "test", seed: 0 };
+const adapter: TtsAdapter = { voice, async synthesize(jobs) {
+  jobs.forEach((job) => writeFileSync(job.file, WAV));
+} };
+
+it("writes normalized narration as a clip with measured metadata, preserving the original step", async () => {
+  const texts: string[] = [];
+  const adapter: TtsAdapter = {
+    voice,
+    async synthesize(jobs) {
+      for (const job of jobs) {
+        texts.push(job.text);
+        writeFileSync(job.file, WAV);
+      }
+    },
+  };
+  const steps = [{ index: 0, narration: "  Open\r\n <b>保存</b> & &lt;.\t ", startMs: 5, actionEndMs: 5, endMs: 5 }];
+  const original = structuredClone(steps);
+  const dir = join(directory(), "demo.audio");
+  const result = await voiceSteps(steps, dir, adapter);
+  expect(texts).toEqual(["Open <b>保存</b> & &lt;."]);
+  expect(result).toEqual({ voice, steps: [{ ...steps[0], audio: {
+    file: "demo.audio/000.wav", durationMs: 2,
+    sha256: "faf90dde7fd7a168c57cb3a4724584c233c2b297754169d85a5d7b4165ef82fd",
+  } }] });
+  expect(readFileSync(join(dir, "000.wav"))).toEqual(WAV);
+  expect(steps).toEqual(original);
+});
+
+it("keeps blank and old steps without audio and does not need a worker for an all-blank demo", async () => {
+  const steps = [
+    { index: 0, narration: " \r\n\t", startMs: 0, actionEndMs: 2, endMs: 2 },
+    { index: 1, startMs: 3, actionEndMs: 4, endMs: 4 },
+  ];
+  const result = await voiceSteps(steps, join(directory(), "blank.audio"), {
+    voice, async synthesize() { throw new Error("worker should not be needed"); },
+  });
+  expect(result.voice).toEqual(voice);
+  expect(result.steps).toEqual(steps);
+  expect(result.steps.every((step) => step.audio === undefined)).toBe(true);
+});
+
+it("replaces only this demo's generated clips, retaining gaps, large indexes and unrelated files", async () => {
+  const root = directory();
+  const dir = join(root, "demo.audio");
+  const other = join(root, "other.audio");
+  mkdirSync(dir);
+  mkdirSync(other);
+  writeFileSync(join(dir, "notes.txt"), "keep");
+  writeFileSync(join(other, "000.wav"), WAV);
+  const step = (index: number, narration: string) => ({ index, narration, startMs: 0, actionEndMs: 1, endMs: 1 });
+  await voiceSteps([step(0, "First."), step(1, "Second.")], dir, adapter);
+  const result = await voiceSteps([step(0, ""), step(2, "Third."), step(1000, "Last.")], dir, adapter);
+  expect(result.steps.map((s) => s.audio?.file)).toEqual([undefined, "demo.audio/002.wav", "demo.audio/1000.wav"]);
+  expect(readdirSync(dir).sort()).toEqual(["002.wav", "1000.wav", "notes.txt"]);
+  expect(readFileSync(join(other, "000.wav"))).toEqual(WAV);
+  await voiceSteps([], dir, adapter);
+  expect(readdirSync(dir)).toEqual(["notes.txt"]);
+});
+
+it("rejects invalid audio before replacing a previous successful clip set", async () => {
+  const dir = join(directory(), "demo.audio");
+  const steps = [{ index: 0, narration: "Speak.", startMs: 0, actionEndMs: 1, endMs: 1 }];
+  await voiceSteps(steps, dir, adapter);
+  await expect(voiceSteps(steps, dir, { voice, async synthesize(jobs) {
+    jobs.forEach((job) => writeFileSync(job.file, "not a WAV"));
+  } })).rejects.toThrow(/step 0.*audio/i);
+  expect(readFileSync(join(dir, "000.wav"))).toEqual(WAV);
+  expect(readdirSync(dir)).toEqual(["000.wav"]);
+});
+
+it("keeps prior clips and removes partial work when synthesis fails", async () => {
+  const dir = join(directory(), "demo.audio");
+  const steps = [{ index: 0, narration: "Speak.", startMs: 0, actionEndMs: 1, endMs: 1 }];
+  await voiceSteps(steps, dir, adapter);
+  await expect(voiceSteps(steps, dir, { voice, async synthesize(jobs) {
+    writeFileSync(jobs[0].file, "partial");
+    throw new Error("step 0: worker failed");
+  } })).rejects.toThrow("step 0: worker failed");
+  expect(readFileSync(join(dir, "000.wav"))).toEqual(WAV);
+  expect(readdirSync(dir)).toEqual(["000.wav"]);
+});

From 6cf5ecb680366ae6ca2551361296437b6293426a Mon Sep 17 00:00:00 2001
From: codeonym <bouarourayoub0@gmail.com>
Date: Tue, 10 Nov 2026 17:41:42 +0000
Subject: [PATCH 2/2] chore: mark GH-4 in review (#4)

---
 .../history/2026-11-10_1741_meta.md                  | 12 ++++++++++++
 .../GH-4-tts-adapter-local-voice/history/CHANGES.md  |  1 +
 .../tickets/GH-4-tts-adapter-local-voice/meta.md     |  4 ++--
 3 files changed, 15 insertions(+), 2 deletions(-)
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1741_meta.md

diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1741_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1741_meta.md
new file mode 100644
index 0000000..ed3bdfb
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/2026-11-10_1741_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Voice narration through a TTS adapter with a local default voice
+key: GH-4
+parent: GH-1
+status: building
+branch: feat/4-tts-adapter-local-voice
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/4
+mr:
+created: 2026-11-02
+updated: 2026-11-10
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
index a396b10..3c4a979 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/history/CHANGES.md
@@ -12,3 +12,4 @@
 - 2026-11-10: added implementation build notes covering red/green slices, pinned CPU wheel resolution, model asset verification, image size, generation bounds and serial E2E execution; real-model checks still running.
 - 2026-11-10: finished GH-4 implementation and reviewed both axes with zero findings. Type checking, 50 unit tests, build and a clean 10-test Docker E2E run pass (968.05s); audio hashes match and final step deltas are 2/2/3ms. Documented CPU/image costs and set CI timeout45min. Saved the approved odd-viewport issue under GH-2; no capture safeguard was weakened. Awaiting commit approval.
 - 2026-11-10: commit approved ("ok go"); committing the verified implementation and approved planning/follow-up files as feat: generate offline Qwen narration clips (#4).
+- 2026-11-10: pushed dcda11a and opened PR #12 after approval ("yes, push and merge !"); marked in-review and recorded its link. Board 6 has no In Review option, so its item stays In Progress until merge. Waiting for final-head CI before the approved squash merge.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
index ed3bdfb..37a423e 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-4-tts-adapter-local-voice/meta.md
@@ -3,10 +3,10 @@ kind: ticket
 title: Voice narration through a TTS adapter with a local default voice
 key: GH-4
 parent: GH-1
-status: building
+status: in-review
 branch: feat/4-tts-adapter-local-voice
 tracker-url: https://github.com/codeonym-oss/flow-reel/issues/4
-mr:
+mr: https://github.com/codeonym-oss/flow-reel/pull/12
 created: 2026-11-02
 updated: 2026-11-10
 ---