retake-demos 0.14.2 → 0.14.3

package/AGENTS.md

@@ -122,6 +122,12 @@ a person who has heard it. It only fixes the voice and rate of narration that
 already exists, and strips any `viewport`/`scale` pin, which silently beats the
 preset and is the one way two takes of the same app come out different shapes.
 
+Voices are names: `andrew`, `ava`, `brian`, `emma`, `aria`, `ryan` (Edge,
+online) and `heart`, `michael`, `aiden` (local: they run on the person's Mac
+and the first narrated render downloads the model). The voice a person picked
+when they first opened Retake is the routine's voice. If the routine says
+`silent` and they want narration, ask which voice — never guess an id.
+
 Writing the steps, the captions and the story is still entirely your job.
 `demos/style.md` is the taste that needs judgement; the routine is the part
 that only needs to be the same every time.

package/README.md

@@ -324,7 +324,7 @@ On a new workspace, `retake ui` opens the first-demo flow and writes the manifes
 
 **Scenes** are the spine: `{ action: scene, label, caption }` at each beat. They take their timestamps from the actual run, so captions land on the frames they describe even when the app took 3 seconds this time and 11 the last. **Labels must be unique** — `thumbnail`, `until`, the stills and the proof log all address scenes by label, so two scenes called the same thing make every one of those ambiguous. `validate` rejects it.
 
-**Two kinds of take.** `mode: demo` (the default) proves how something works — a client walkthrough, a PR clip, a lesson — and keeps everything but the product out of the frame. `mode: launch` presents the product in public and may carry a title card, music, emphasis and a branded ending. `validate` warns if a demo is carrying launch furniture. **The launch cut.** `compressIdle: true` shows the app's long waits as ~1.5 s each (your own pacing `wait`s are never touched); `voiceover: true` reads the captions aloud (edge-tts, `pipx install edge-tts` once). **Local voices** run on an Apple Silicon Mac and send nothing anywhere: `retake routine set voice heart` (Kokoro, female, ~300 MB), `michael` (Kokoro, male) or `aiden` (Qwen3, ~1.8 GB). They need [uv](https://docs.astral.sh/uv/) (`brew install uv`); the model downloads once, the first time a video is narrated. Kokoro reads demo words the demo way ("press re-CORD", "deh-mohz") and every local voice is levelled to Edge's loudness; `typing: brisk` makes typed text land fast with the pauses carrying the meaning. All render-time except typing. **Music.** `music: track.mp3` (or `{ file, gainDb, fadeOutMs }`) mixes a bed under the video at render time, looped or trimmed to fit and faded out at the end. Bring your own track — it ships inside your video, so it must be one you may use (CC0 or licensed). **Cards and callouts.** `intro:`/`outro:` add a title card in Retake's own look — rendered at render time, so changing a word is a re-render, and the intro's settled frame is written as `cover.png`, the poster. `{ action: callout, selector, label, ms }` draws an animated ring and label around an element while the take holds — recorded coordinates, drawn at render, moving with the camera. Sparingly: the captions carry the story.
+**Two kinds of take.** `mode: demo` (the default) proves how something works — a client walkthrough, a PR clip, a lesson — and keeps everything but the product out of the frame. `mode: launch` presents the product in public and may carry a title card, music, emphasis and a branded ending. `validate` warns if a demo is carrying launch furniture. **The launch cut.** `compressIdle: true` shows the app's long waits as ~1.5 s each (your own pacing `wait`s are never touched); `voiceover: true` reads the captions aloud (edge-tts, `pipx install edge-tts` once). **Local voices** run on an Apple Silicon Mac and send nothing anywhere: `retake routine set voice heart` (Kokoro, female), `michael` (Kokoro, male) or `aiden` (Qwen3). They need [uv](https://docs.astral.sh/uv/) (`brew install uv`). The first narrated video downloads the voice engine and model once: about 2.6 GB for Kokoro, about 4 GB for Aiden. Kokoro reads demo words the demo way ("press re-CORD", "deh-mohz") and every local voice is levelled to Edge's loudness; `typing: brisk` makes typed text land fast with the pauses carrying the meaning. All render-time except typing. **Music.** `music: track.mp3` (or `{ file, gainDb, fadeOutMs }`) mixes a bed under the video at render time, looped or trimmed to fit and faded out at the end. Bring your own track — it ships inside your video, so it must be one you may use (CC0 or licensed). **Cards and callouts.** `intro:`/`outro:` add a title card in Retake's own look — rendered at render time, so changing a word is a re-render, and the intro's settled frame is written as `cover.png`, the poster. `{ action: callout, selector, label, ms }` draws an animated ring and label around an element while the take holds — recorded coordinates, drawn at render, moving with the camera. Sparingly: the captions carry the story.
 
 **Seeds** put the app in a known state before the camera: write a JSON file, run JS in the page, or run a shell command. **Setup** is the stuff that runs before recording and is trimmed off the front — logins live there. **`tempo`** speeds the finished video up or down at render time; **`lock`** names a shared resource so two demos that touch the same backend don't record over each other.
 

package/dist/ext/flag-store.js

@@ -0,0 +1,14 @@
+/** Where a demo's flags live and how they are read — on its own so that
+    `verify` (which checks them) and `flags` (which raises them, and asks
+    `verify` to judge) do not import each other. */
+import fs from "node:fs";
+export const flagsPath = (manifestFile) => manifestFile.replace(/\.(ya?ml|json)$/i, "") + ".flags.json";
+export function readFlags(manifestFile) {
+    try {
+        const v = JSON.parse(fs.readFileSync(flagsPath(manifestFile), "utf8"));
+        return Array.isArray(v.flags) ? v.flags : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/ext/flags.js

@@ -23,16 +23,8 @@ import { pickJudge, pool } from "./judge.js";
 import { judgeWith } from "./verify.js";
 import { clipFor } from "./clip.js";
 import { noteCheck } from "./checked.js";
-export const flagsPath = (manifestFile) => manifestFile.replace(/\.(ya?ml|json)$/i, "") + ".flags.json";
-export function readFlags(manifestFile) {
-    try {
-        const v = JSON.parse(fs.readFileSync(flagsPath(manifestFile), "utf8"));
-        return Array.isArray(v.flags) ? v.flags : [];
-    }
-    catch {
-        return [];
-    }
-}
+export { flagsPath, readFlags } from "./flag-store.js";
+import { flagsPath, readFlags } from "./flag-store.js";
 function writeFlags(manifestFile, flags) {
     fs.writeFileSync(flagsPath(manifestFile), JSON.stringify({
         _readme: "Things you flagged on this demo. Each one is also an `expect:` on its scene in the manifest — that is what actually gets checked. Delete an entry here and in the manifest to stop watching it.",

package/dist/ext/heal.js

@@ -64,7 +64,7 @@ export function findOrphans(outRoot, demosDir) {
  * came from, and this is not cosmetic. A take recorded with `--from` or
  * `--until` keeps the PARENT demo's name in its used manifest, so restoring
  * two fragments of one demo produced three files all declaring
- * `name: avex-full-flow` — and the window, which keys on that name, showed the
+ * `name: booking-full-flow` — and the window, which keys on that name, showed the
  * same demo three times. It looked broken because it was.
  */
 export function healOrphans(orphans, demosDir) {

package/dist/ext/sense.js

@@ -4,7 +4,7 @@
  * `verify` judges one frame: is the button readable, is the card inside its
  * box. This judges the whole run: what went IN against what came OUT.
  *
- * The bug that produced it: an Avex demo entered two legs — SGN→SIN and
+ * The bug that produced it: a flight-booking demo entered two legs — SGN→SIN and
  * SIN→SGN — and quoted a single price of 17,400. Nothing caught it. Every
  * step passed, every frame looked fine, and the take recorded both halves:
  *

package/dist/ext/verify.js

@@ -23,7 +23,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { askAsync, pickJudge, pool, readJson, why as short } from "./judge.js";
-import { readFlags } from "./flags.js";
+import { readFlags } from "./flag-store.js";
 import { NO_INTENT_NOTE, intentBlock } from "./intent.js";
 import { tag } from "./evidence.js";
 import { noteCheck } from "./checked.js";

package/dist/media-bin.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { bundledFfmpeg } from "./self-repair.js";
 let cachedBin;
 /** Resolve the bundled media binary first, then fall back to PATH. */
@@ -21,3 +21,18 @@ export function ffmpegBin() {
     }
     return (cachedBin = "ffmpeg");
 }
+/** ffmpeg -i probe: duration and stream size, no ffprobe needed. */
+export function probe(file) {
+    const out = String(spawnSync(ffmpegBin(), ["-hide_banner", "-i", file], { encoding: "utf8" }).stderr);
+    const d = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(out);
+    const v = /Video:.*?\s(\d{2,5})x(\d{2,5})[\s,].*?(\d+(?:\.\d+)?)\s*fps/.exec(out) ?? /Video:.*?\s(\d{2,5})x(\d{2,5})/.exec(out);
+    if (!d)
+        throw new Error(`could not read duration of ${file}`);
+    return {
+        duration: Number(d[1]) * 3600 + Number(d[2]) * 60 + Number(d[3]),
+        width: v ? Number(v[1]) : 0,
+        height: v ? Number(v[2]) : 0,
+        fps: v && v[3] ? Number(v[3]) : 0,
+    };
+}
+export const videoDuration = (file) => probe(file).duration;

package/dist/operator/tools.js

@@ -383,7 +383,7 @@ server.registerTool("env", {
     }
 });
 server.registerTool("routine", {
-    description: "Call this FIRST in any session. The workspace's locked standard — output format, captions, voice and speaking rate, music — and, when the product has one, its full recording brief: where the app runs, how to seed it, the selectors that hold, and what breaks. READ THIS BEFORE DRAFTING and do not set `preset`, `layout`, `captions`, `viewport`, `scale`, `voiceover.voice`, `voiceover.ratePercent` or `music` yourself — they are not yours to choose, and choosing them is how two videos from the same workspace come back looking and sounding different. Write the steps and the captions; call routine_apply when the manifest exists.",
+    description: "Call this FIRST in any session. The workspace's locked standard — output format, captions, voice and speaking rate, music — and, when the product has one, its full recording brief: where the app runs, how to seed it, the selectors that hold, and what breaks. READ THIS BEFORE DRAFTING and do not set `preset`, `layout`, `captions`, `viewport`, `scale`, `voiceover.voice`, `voiceover.ratePercent` or `music` yourself — they are not yours to choose, and choosing them is how two videos from the same workspace come back looking and sounding different. Write the steps and the captions; call routine_apply when the manifest exists. Voices are names (andrew, ava, brian, emma, aria, ryan online; heart, michael, aiden local on the person's Mac): if the routine says silent and they want narration, ask which one.",
     inputSchema: {},
     annotations: READ_ONLY,
 }, async () => {

package/dist/record.js

@@ -19,7 +19,7 @@ import { execFileSync, spawn } from "node:child_process";
 import YAML from "yaml";
 import { recordPage, moveCursorToPoint } from "testreel";
 import { expandEnv, signInAt, resolve } from "./manifest.js";
-import { ffmpegBin, videoDuration } from "./render.js";
+import { ffmpegBin, videoDuration } from "./media-bin.js";
 import { assessActionProof, proofMatches, snapshotActionProof, waitForActionProof } from "./action-proof.js";
 /** What the *recording* depends on — nothing that render can change afterwards.
     A scene's caption, hold and camera zoom are render-time, so editing them must

package/dist/render.js

@@ -24,7 +24,7 @@ import { bandHeightFor, maxCharsFor, wrap } from "./captions.js";
 import { renderCard, renderCalloutOverlay, renderPoster, renderTitledCover } from "./cards.js";
 import { describeIdle, planIdle, warpFilterArgs, warpTake } from "./pace.js";
 import { holdFilterArgs, holdTake, planHolds } from "./hold.js";
-import { DEFAULT_VOICE, LOCAL_VOICE, LOCAL_VOICE_VERSION, audioSeconds, cueGroups, cuesPerParagraph, cutPoints, silences, synthesize, synthesizeWithCues } from "./voice.js";
+import { DEFAULT_VOICE, LOCAL_VOICE, LOCAL_VOICE_VERSION, voiceId, audioSeconds, cueGroups, cuesPerParagraph, cutPoints, silences, synthesize, synthesizeWithCues } from "./voice.js";
 import { expandEnv, resolve, Manifest } from "./manifest.js";
 import { ffmpegBin } from "./media-bin.js";
 export { ffmpegBin } from "./media-bin.js";
@@ -41,7 +41,7 @@ export function renderHash(m, take) {
             }
             catch {
                 return null;
-            } }) : null], idle: m.compressIdle, vo: m.voiceover, voEngine: typeof m.voiceover === "object" && LOCAL_VOICE.test(m.voiceover.voice) ? LOCAL_VOICE_VERSION : undefined, music: m.music ? [m.music, (() => { try {
+            } }) : null], idle: m.compressIdle, vo: m.voiceover, voEngine: typeof m.voiceover === "object" && LOCAL_VOICE.test(voiceId(m.voiceover.voice)) ? LOCAL_VOICE_VERSION : undefined, music: m.music ? [m.music, (() => { try {
                 const f = typeof m.music === "string" ? m.music : m.music.file;
                 const st = fs.statSync(path.resolve(f));
                 return [st.size, Math.round(st.mtimeMs)];
@@ -67,21 +67,8 @@ function ff(args, log) {
     log?.(`$ ffmpeg ${args.join(" ")}`);
     execFileSync(ffmpegBin(), ["-hide_banner", "-loglevel", "error", "-y", ...args], { stdio: "inherit" });
 }
-/** ffmpeg -i probe: duration and stream size, no ffprobe needed. */
-export function probe(file) {
-    const out = String(spawnSync(ffmpegBin(), ["-hide_banner", "-i", file], { encoding: "utf8" }).stderr);
-    const d = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(out);
-    const v = /Video:.*?\s(\d{2,5})x(\d{2,5})[\s,].*?(\d+(?:\.\d+)?)\s*fps/.exec(out) ?? /Video:.*?\s(\d{2,5})x(\d{2,5})/.exec(out);
-    if (!d)
-        throw new Error(`could not read duration of ${file}`);
-    return {
-        duration: Number(d[1]) * 3600 + Number(d[2]) * 60 + Number(d[3]),
-        width: v ? Number(v[1]) : 0,
-        height: v ? Number(v[2]) : 0,
-        fps: v && v[3] ? Number(v[3]) : 0,
-    };
-}
-export const videoDuration = (file) => probe(file).duration;
+export { probe, videoDuration } from "./media-bin.js";
+import { probe } from "./media-bin.js";
 /** Whether a file carries a sound track at all. */
 export function probeHasAudio(file) {
     return /Stream #\d+:\d+.*: Audio:/.test(String(spawnSync(ffmpegBin(), ["-hide_banner", "-i", file], { encoding: "utf8" }).stderr));

package/dist/routine.js

@@ -20,6 +20,7 @@ import path from "node:path";
 import YAML from "yaml";
 import { execFileSync } from "node:child_process";
 import * as mediaBin from "./media-bin.js";
+import { VOICES, voiceId } from "./voice.js";
 import { z } from "zod";
 export const STYLES = {
     showcase: {
@@ -53,24 +54,7 @@ export const STYLES = {
    workspace; it is not a per-video decision and never was. The language rides
    on the voice — a Vietnamese routine is a Vietnamese voice id, not a separate
    setting that would have to agree with this one. */
-export const VOICES = {
-    ryan: { id: "en-GB-RyanNeural", note: "British, easy, positive. The one the Capture demos use." },
-    andrew: { id: "en-US-AndrewNeural", note: "Warm, confident, unhurried." },
-    ava: { id: "en-US-AvaNeural", note: "Expressive and friendly, a little closer in." },
-    brian: { id: "en-US-BrianNeural", note: "Casual and sincere — least like a narrator." },
-    emma: { id: "en-US-EmmaNeural", note: "Clear and conversational, good over fast UI." },
-    aria: { id: "en-US-AriaNeural", note: "A news read: even, flat, no colour." },
-    // Local: these run on this Mac (Apple Silicon) and send nothing anywhere.
-    heart: { id: "kokoro:af_heart", note: "Local (Kokoro). Warm, natural, female. First use downloads ~300 MB." },
-    michael: { id: "kokoro:am_michael", note: "Local (Kokoro). Steady, male. Shares Heart's ~300 MB download." },
-    aiden: { id: "qwen:aiden", note: "Local (Qwen3). Natural, male. First use downloads ~1.8 GB." },
-};
-/** A routine's `voice` is a name above, "silent", a raw edge-tts voice id
- *  (`vi-VN-HoaiMyNeural`) for a language the named set does not cover, or a
- *  raw local id (`kokoro:af_bella`, `qwen:ryan`). */
-export function voiceId(voice) {
-    return VOICES[voice]?.id ?? voice;
-}
+export { VOICES, voiceId } from "./voice.js";
 /* ─── the file ─────────────────────────────────────────────────────────────── */
 export const RoutineSchema = z.object({
     style: z.enum(["showcase", "fullscreen", "mobile"]).default("showcase"),
@@ -165,6 +149,20 @@ export function routineFile(demosDir) {
 export function starter() {
     return { use: "default", routines: { default: RoutineSchema.parse({ note: "The house standard. Change it here, not per video." }) } };
 }
+/** The narration chosen in the window's first run, kept in the routine so
+    every later agent reads it — not only the one that was told. It sets
+    whose voice reads a script; nothing is narrated until one is approved. */
+export function rememberNarration(demosDir, narration) {
+    if (narration === "silent")
+        return;
+    const voice = { edge: "andrew", kokoro: "heart", aiden: "aiden" }[narration];
+    const file = readRoutines(demosDir) ?? starter();
+    const merged = RoutineSchema.safeParse({ ...(file.routines[file.use] ?? {}), voice });
+    if (merged.success) {
+        file.routines[file.use] = merged.data;
+        writeRoutines(demosDir, file);
+    }
+}
 export function readRoutines(demosDir) {
     const f = routineFile(demosDir);
     if (!fs.existsSync(f))

package/dist/self-repair.js

@@ -52,13 +52,25 @@ export function bundledFfmpeg() {
     }
     if (!bin)
         return null;
-    if (fs.existsSync(bin))
+    if (runs(bin))
         return bin;
+    // Missing, or there but not working: an install cut off mid-download
+    // leaves a partial file that is not executable, and "it exists" used to be
+    // enough to hand it to every render (EACCES, nothing could render).
     const installer = path.join(path.dirname(require.resolve("ffmpeg-static/package.json")), "install.js");
     if (!fs.existsSync(installer))
         return null;
-    say("… downloading ffmpeg (one time, ~45 MB — npm skipped it at install)");
+    const broken = fs.existsSync(bin);
+    if (broken)
+        fs.rmSync(bin, { force: true });
+    say(broken ? "… ffmpeg was only partly downloaded — fetching it again (~45 MB)" : "… downloading ffmpeg (one time, ~45 MB — npm skipped it at install)");
     spawnSync(process.execPath, [installer], { cwd: path.dirname(installer), stdio: ["ignore", "ignore", "inherit"] });
-    return fs.existsSync(bin) ? bin : null;
+    return runs(bin) ? bin : null;
+}
+/** Whether this is an ffmpeg that actually starts. */
+function runs(bin) {
+    if (!fs.existsSync(bin))
+        return false;
+    return spawnSync(bin, ["-version"], { stdio: "ignore", timeout: 15_000 }).status === 0;
 }
 patchRecorder();

package/dist/ui/chat.html

@@ -352,6 +352,9 @@
   .ob-operator-question button, .ob-retry { min-height:42px; border:1px solid var(--ink); border-radius:11px; padding:0 15px; color:#fff; background:var(--ink); font-weight:600; cursor:pointer; }
   .ob-operator-question button.secondary { color:var(--ink); background:#fff; }
   .ob-operator-result { margin-top:18px; }
+  .ob-next { margin:18px auto 0; max-width:520px; color:var(--muted); font-size:13px; line-height:1.6; }
+  .ob-next code { display:inline-block; margin-top:4px; padding:3px 8px; border-radius:7px; background:#fff; border:1px solid var(--rule); color:var(--ink); font:12.5px ui-monospace,Menlo,monospace; }
+  .ob-copy { border:1px solid var(--rule2); border-radius:8px; background:#fff; padding:3px 9px; font:inherit; font-size:12px; cursor:pointer; }
   .ob-operator-result.bad { color:var(--bad); }
   @media (max-width:700px) {
     .wrap.onboarding-only { padding:14px 12px 36px; }
@@ -526,10 +529,10 @@
               <span class="vicon" aria-hidden="true">∞</span><b>Edge</b><small>Online. Small install, many voices, and fast generation. Your script goes to Microsoft's service.</small><span class="tag">Tap to hear</span>
             </button>
             <button class="voice-card" type="button" data-voice="aiden" data-sample="aiden" role="radio" aria-checked="false">
-              <span class="vicon" aria-hidden="true">A</span><b>Aiden</b><small>Local Qwen voice. The most natural one, and the biggest: about 1.8 GB. Runs on your Mac, so your script never leaves it.</small><span class="tag">Tap to hear</span>
+              <span class="vicon" aria-hidden="true">A</span><b>Aiden</b><small>Local Qwen voice. The most natural one, and the biggest: about 4 GB, once. Runs on your Mac, so your script never leaves it.</small><span class="tag">Tap to hear</span>
             </button>
             <button class="voice-card" type="button" data-voice="kokoro" data-sample="kokoro" role="radio" aria-checked="false">
-              <span class="vicon" aria-hidden="true">K</span><b>Kokoro</b><small>Local and much smaller: about 300 MB, many voices. Runs on your Mac, so your script never leaves it.</small><span class="tag">Tap to hear</span>
+              <span class="vicon" aria-hidden="true">K</span><b>Kokoro</b><small>Local and smaller: about 2.6 GB once, many voices. Runs on your Mac, so your script never leaves it.</small><span class="tag">Tap to hear</span>
             </button>
           </div>
           <div class="voice-demo" id="voice-demo"><video id="voice-demo-video" controls playsinline preload="metadata"></video><small id="voice-demo-label"></small></div>
@@ -642,8 +645,8 @@ function renderOnboarding() {
   consent.classList.toggle('show', needsConsent);
   box.checked = onboardingState.consent;
   if (onboardingState.voice === 'edge') $('voice-consent-copy').textContent = 'I understand that Edge sends the narration script to Microsoft’s online speech service.';
-  if (onboardingState.voice === 'aiden') $('voice-consent-copy').textContent = 'I understand that Aiden needs a one-time local model download of about 1.8 GB, the first time a video is narrated. Nothing downloads on this screen.';
-  if (onboardingState.voice === 'kokoro') $('voice-consent-copy').textContent = 'I understand that Kokoro needs a one-time local model download of about 300 MB, the first time a video is narrated. Nothing downloads on this screen.';
+  if (onboardingState.voice === 'aiden') $('voice-consent-copy').textContent = 'I understand that Aiden needs a one-time download of about 4 GB (its voice engine and model), the first time a video is narrated. Nothing downloads on this screen.';
+  if (onboardingState.voice === 'kokoro') $('voice-consent-copy').textContent = 'I understand that Kokoro needs a one-time download of about 2.6 GB (its voice engine and model), the first time a video is narrated. Nothing downloads on this screen.';
   $('onboard-next').disabled =
     (onboardingStep === 1 && !normalUrl($('onboard-url').value)) ||
     (onboardingStep === 2 && brandRead.state === 'reading') ||
@@ -798,7 +801,12 @@ function finishOnboardingOperator(data) {
   if (ok) {
     localStorage.removeItem(ONBOARD_KEY);
     sessionStorage.removeItem(ONBOARD_SIGNED_KEY);
-    card.innerHTML = `<div class="ob-success" data-operator-done><div class="ob-icon" aria-hidden="true">✓</div><h2>Your first draft is ready</h2><p class="ob-lead">${esc(data.summary || 'Open it from the library.')}</p><button type="button" data-open-first>Open first draft</button></div>`;
+    card.innerHTML = `<div class="ob-success" data-operator-done><div class="ob-icon" aria-hidden="true">✓</div><h2>Your first draft is ready</h2><p class="ob-lead">${esc(data.summary || 'Open it from the library.')}</p><button class="ob-retry" type="button" data-open-first>Open first draft</button>${onboardingState.voice && onboardingState.voice !== 'silent' ? `<p class="ob-next">To add a voiceover, tell your coding agent: <code data-next-ask>Add a voiceover to my Retake demo “${esc(data.demo)}”, using the voice in my Retake routine.</code> <button type="button" class="ob-copy" data-copy-next>Copy</button></p>` : ''}</div>`;
+    const copyNext = card.querySelector('[data-copy-next]');
+    if (copyNext) copyNext.onclick = async () => {
+      try { await navigator.clipboard.writeText(card.querySelector('[data-next-ask]').textContent); copyNext.textContent = 'Copied'; }
+      catch { copyNext.textContent = 'Select and copy it'; }
+    };
     card.querySelector('[data-open-first]').onclick = async () => {
       onboardingSubmitted = false;
       await drawDemos();

package/dist/ui/server.js

@@ -51,7 +51,7 @@ import { startOffer, startApp, listeningPorts } from "../appserver.js";
 import { PKG_ROOT, PROJECT_ROOT, VERSION, entry, isDemoFile } from "../paths.js";
 import { SECRET_NAME, missingSecrets, writeEnvFile } from "../env.js";
 import { captureMatchesTake, readPreviewReceipt } from "../preview.js";
-import { STYLES, VOICES, RoutineSchema, environmentFor, readRoutines, starter, voiceId, writeRoutines } from "../routine.js";
+import { STYLES, VOICES, RoutineSchema, environmentFor, readRoutines, rememberNarration, starter, voiceId, writeRoutines } from "../routine.js";
 import { loadEnvSpec } from "../recording-env.js";
 import { describeSchedule, readSchedule, scheduleLoaded } from "../schedule.js";
 import { synthesize, voiceCachePath, LOCAL_VOICE, localModelReady } from "../voice.js";
@@ -1236,13 +1236,17 @@ export function serve(port) {
                 if (!b.describe?.trim())
                     return json(res, 400, { error: "say what the demo should show" });
                 const narration = ["silent", "edge", "aiden", "kokoro"].includes(b.narration) ? b.narration : "silent";
+                // The choice outlives this session: it goes into the routine, which is
+                // what any later agent reads. A video still stays silent until someone
+                // approves a script; this only settles whose voice reads it.
+                rememberNarration(DEMOS, narration);
                 const sound = narration === "silent"
                     ? "Make the first draft silent and do not add captions."
                     : narration === "edge"
-                        ? "Make the first draft silent and do not add captions. The person chose Edge for the final narration. Do not synthesize it until they approve both the recording and one continuous script."
+                        ? "Make the first draft silent and do not add captions. The person chose Edge for the final narration; the workspace routine now says `voice: andrew`. Do not synthesize it until they approve both the recording and one continuous script."
                         : narration === "aiden"
-                            ? "Make the first draft silent and do not add captions. The person chose the local Aiden voice for the final narration: `voiceover.voice: qwen:aiden` (a routine says `voice: aiden`). It runs on their Mac; its first use downloads a ~1.8 GB model. Do not narrate until they approve the recording and one continuous script, and say the download is coming before the first narrated render."
-                            : "Make the first draft silent and do not add captions. The person chose the local Kokoro voice for the final narration: `voiceover.voice: kokoro:af_heart` (a routine says `voice: heart`). It runs on their Mac; its first use downloads a ~300 MB model. Do not narrate until they approve the recording and one continuous script, and say the download is coming before the first narrated render.";
+                            ? "Make the first draft silent and do not add captions. The person chose the local Aiden voice for the final narration: `voiceover.voice: qwen:aiden` (the workspace routine now says `voice: aiden`). It runs on their Mac; its first use downloads about 4 GB (the voice engine and the model, once). Do not narrate until they approve the recording and one continuous script, and say the download is coming before the first narrated render."
+                            : "Make the first draft silent and do not add captions. The person chose the local Kokoro voice for the final narration: `voiceover.voice: kokoro:af_heart` (the workspace routine now says `voice: heart`). It runs on their Mac; its first use downloads about 2.6 GB (the voice engine and the model, once). Do not narrate until they approve the recording and one continuous script, and say the download is coming before the first narrated render.";
                 const describe = `${b.describe.trim()}\n\n${sound}`;
                 const prov = pickProvider();
                 const which = prov?.name === "codex" ? "codex" : prov?.name === "claude-code" ? "claude-code" : null;

package/dist/voice.js

@@ -27,11 +27,36 @@ export function voiceCachePath(text, voice, ratePercent = 0) {
     const key = createHash("sha256").update(`${v}\0${ratePercent}\0${text}`).digest("hex");
     return path.join(root, `${key}.mp3`);
 }
+export const VOICES = {
+    ryan: { id: "en-GB-RyanNeural", note: "British, easy, positive. The one the Capture demos use." },
+    andrew: { id: "en-US-AndrewNeural", note: "Warm, confident, unhurried." },
+    ava: { id: "en-US-AvaNeural", note: "Expressive and friendly, a little closer in." },
+    brian: { id: "en-US-BrianNeural", note: "Casual and sincere — least like a narrator." },
+    emma: { id: "en-US-EmmaNeural", note: "Clear and conversational, good over fast UI." },
+    aria: { id: "en-US-AriaNeural", note: "A news read: even, flat, no colour." },
+    // Local: these run on this Mac (Apple Silicon) and send nothing anywhere.
+    heart: { id: "kokoro:af_heart", note: "Local (Kokoro). Warm, natural, female. First use downloads ~2.6 GB (voice engine and model)." },
+    michael: { id: "kokoro:am_michael", note: "Local (Kokoro). Steady, male. Shares Heart's download." },
+    aiden: { id: "qwen:aiden", note: "Local (Qwen3). Natural, male. First use downloads ~4 GB (voice engine and model; ~1.8 GB if Kokoro is already set up)." },
+};
+/** A routine's `voice` is a name above, "silent", a raw edge-tts voice id
+ *  (`vi-VN-HoaiMyNeural`) for a language the named set does not cover, or a
+ *  raw local id (`kokoro:af_bella`, `qwen:ryan`). */
+export function voiceId(voice) {
+    // The names a person or an agent reaches for: a name above, Kokoro's own
+    // id (`af_heart` — what an agent guessed first, and Retake handed to Edge),
+    // or the full form. Anything else is taken as an edge-tts id.
+    if (VOICES[voice])
+        return VOICES[voice].id;
+    if (/^[a-z][fm]_[a-z]+$/.test(voice))
+        return `kokoro:${voice}`;
+    return voice;
+}
 /** Voices that run on this Mac: `kokoro:<voice>` and `qwen:<speaker>`. */
 export const LOCAL_VOICE = /^(kokoro|qwen):[a-z_]+$/;
 /** Bump when local pronunciation or levelling changes: it re-renders them. */
 export const LOCAL_VOICE_VERSION = "local-voice-1";
-const LOCAL_MODEL = { kokoro: { repo: "models--mlx-community--Kokoro-82M-8bit", size: "~300 MB" }, qwen: { repo: "models--mlx-community--Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit", size: "~1.8 GB" } };
+const LOCAL_MODEL = { kokoro: { repo: "models--mlx-community--Kokoro-82M-8bit", size: "~2.6 GB with the voice engine, once" }, qwen: { repo: "models--mlx-community--Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit", size: "~4 GB with the voice engine, once" } };
 /** The local voice engine: Retake's script under uv, with the MLX audio stack. */
 export function localEngine(voice, platform = process.platform, arch = process.arch) {
     if (platform !== "darwin" || arch !== "arm64")
@@ -71,6 +96,8 @@ export function edgeFailure(stderr, cmd) {
     const upgrade = cmd === "python3" ? "`pip install -U edge-tts`" : "`pipx upgrade edge-tts` (or `pip install -U edge-tts`)";
     if (/\b403\b|WSServerHandshakeError/.test(stderr))
         return `voiceover: Microsoft's voice service refused the request (403). That almost always means edge-tts is out of date — run ${upgrade}, then re-render. If it is already current, check that this computer's clock is right.`;
+    if (/Invalid voice/i.test(stderr))
+        return `voiceover: Edge does not know that voice. Use a name — ${Object.keys(VOICES).join(", ")} (heart, michael and aiden run on this Mac) — or an edge-tts id like en-US-AriaNeural. Local voices can also be written kokoro:<voice> or qwen:<speaker>.`;
     if (/getaddrinfo|ClientConnectorError|Cannot connect|Network is unreachable|TimeoutError/i.test(stderr))
         return "voiceover: could not reach Microsoft's voice service — is the network up? (edge-tts is a network service)";
     const last = stderr.trim().split("\n").filter(Boolean).pop() ?? "";
@@ -78,14 +105,28 @@ export function edgeFailure(stderr, cmd) {
 }
 function runEdge(e, args, timeout) {
     const local = e.cmd === "uvx";
+    // The first use of a local voice downloads its engine and model (~2.6 GB
+    // for Kokoro): on a slow line that is far past 15 minutes. Allow an hour
+    // then, keep the downloaders' progress bars out of the captured output
+    // (they overflowed it), and say which of the two went wrong.
+    const voice = args[args.indexOf("--voice") + 1] ?? "";
+    const firstUse = local && !localModelReady(voice);
     try {
-        execFileSync(e.cmd, [...e.args, ...args], { stdio: "pipe", timeout: local ? Math.max(timeout, 900_000) : timeout, env: local ? { ...process.env, FFMPEG_BIN: ffmpegPath() } : process.env });
+        execFileSync(e.cmd, [...e.args, ...args], {
+            stdio: "pipe", maxBuffer: 64 * 1024 * 1024,
+            timeout: local ? (firstUse ? 3_600_000 : Math.max(timeout, 900_000)) : timeout,
+            env: local ? { ...process.env, FFMPEG_BIN: ffmpegPath(), HF_HUB_DISABLE_PROGRESS_BARS: "1", TQDM_DISABLE: "1" } : process.env,
+        });
     }
     catch (err) {
         const x = err;
         if (local) {
+            if (x.code === "ETIMEDOUT" || x.signal === "SIGTERM")
+                throw new Error(firstUse
+                    ? "voiceover: the local voice's one-time setup (downloading its engine and model) did not finish within an hour — check the connection, then render again; what was downloaded is kept"
+                    : "voiceover: the local voice took too long to speak — render again; if it keeps happening, use an Edge voice for now");
             const last = String(x.stderr ?? "").trim().split("\n").filter(Boolean).pop() ?? "";
-            throw new Error(`voiceover: the local voice failed${last ? ` — ${last.slice(0, 240)}` : ""}`);
+            throw new Error(`voiceover: the local voice failed${last ? ` — ${last.slice(0, 240)}` : " without saying why"}${firstUse ? " (during its one-time setup)" : ""}`);
         }
         if (x.code === "ETIMEDOUT" || x.signal === "SIGTERM")
             throw new Error("voiceover: Microsoft's voice service did not answer in time — try again in a minute");
@@ -104,6 +145,7 @@ function ffmpegPath() {
     return "ffmpeg";
 }
 export function synthesize(text, voice, out, ratePercent = 0) {
+    voice = voiceId(voice);
     const cached = voiceCachePath(text, voice, ratePercent);
     if (fs.existsSync(cached) && fs.statSync(cached).size >= 200) {
         fs.copyFileSync(cached, out);
@@ -151,6 +193,7 @@ function parseSrt(srt) {
  * performance at those points. edge-tts writes the sentence timings itself.
  */
 export function synthesizeWithCues(text, voice, out, ratePercent = 0) {
+    voice = voiceId(voice);
     const cached = voiceCachePath(`cues\0${text}`, voice, ratePercent);
     const cachedSrt = cached.replace(/\.mp3$/, ".srt");
     if (fs.existsSync(cached) && fs.statSync(cached).size >= 200 && fs.existsSync(cachedSrt)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retake-demos",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "Demo-as-code for coding agents: a YAML manifest in, a product walkthrough video out. Rerun the demo instead of re-recording it.",
   "keywords": [
     "demo",
@@ -52,7 +52,7 @@
     "retake": "tsx src/cli.ts",
     "ui": "tsx src/cli.ts ui",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test --test-concurrency=3 test/*.test.ts",
     "site:dev": "node scripts/serve-landing.mjs",
     "site:test": "node --test test/*-static.test.mjs",
     "site:test:browser": "node --test test/landing.test.mjs"

package/scripts/local-voice.py

@@ -39,6 +39,37 @@ def pronounce(text: str) -> str:
     return "".join(out)
 
 
+def short_espeak_data() -> None:
+    """espeak-ng keeps its data path in a fixed-size buffer: past ~150
+    characters it silently falls back to the path it was built with
+    (/Users/runner/work/…) and exits the process. uv's cache path plus
+    site-packages reaches that with a long username or a custom cache
+    folder. So espeak reads a copy of its data (~20 MB, made once) from a
+    short folder. A link would not do: phonemizer resolves it back to the
+    long path. Set after misaki has imported, which sets the long path."""
+    import shutil
+    import espeakng_loader
+    from phonemizer.backend.espeak.wrapper import EspeakWrapper
+    try:
+        import misaki.espeak  # noqa: F401  (sets the long path; overridden below)
+    except Exception:
+        pass
+    data = espeakng_loader.get_data_path()
+    if len(data) > 100:
+        short = os.path.join(os.path.expanduser("~/Library/Caches/retake"), "espeak-ng-data")
+        marker = os.path.join(short, ".copied-from")
+        fresh = os.path.isfile(marker) and open(marker).read() == data
+        if not fresh:
+            if os.path.lexists(short):
+                shutil.rmtree(short) if os.path.isdir(short) and not os.path.islink(short) else os.remove(short)
+            shutil.copytree(data, short)
+            with open(marker, "w") as f:
+                f.write(data)
+        data = short
+    EspeakWrapper.set_library(espeakng_loader.get_library_path())
+    EspeakWrapper.set_data_path(data)
+
+
 EDGE_LUFS = -19.8   # measured: Edge's Andrew reading the same lines
 SR = 24000
 MODELS = {"kokoro": "mlx-community/Kokoro-82M-8bit", "qwen": "mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-8bit"}
@@ -57,6 +88,8 @@ def main() -> None:
     from mlx_audio.tts.utils import load_model
 
     engine, name = a.voice.split(":", 1)
+    if engine == "kokoro":
+        short_espeak_data()
     speed = 1 + int(re.sub(r"[%+]", "", a.rate) or 0) / 100
     model = load_model(MODELS[engine])
 

package/site/releases.json

@@ -1,6 +1,19 @@
 {
   "_readme": "What's new, written for the person using Retake — not for whoever wrote it. Both the landing page and the Retake window read THIS file; there is no second copy. Rules for adding one: say what changed for them, name no files, no flags they will not type, no words like refactor or regression. If a line only makes sense to someone who has read the source, it does not belong here. Newest first. Add an entry on every release that changes what people see.",
   "releases": [
+    {
+      "version": "0.14.3",
+      "date": "2026-10-19",
+      "headline": "Choosing Kokoro or Aiden now works for someone starting from nothing",
+      "notes": [
+        "The voice you pick when you first open Retake is now remembered. Before, only the agent that made your first draft was told; the next one had to ask which voice you meant.",
+        "When your first draft is ready, the window shows the exact sentence to give your agent to add a voiceover, with a copy button.",
+        "Kokoro no longer fails to start when your Mac's user name or cache folder makes its files' path long.",
+        "Agents can name a voice the way they naturally would — heart, aiden, or Kokoro's own af_heart — and a voice name Retake does not know now says which names work.",
+        "The first use of a local voice downloads its engine as well as the voice: about 2.6 GB for Kokoro and 4 GB for Aiden. The window now says so, and allows up to an hour for it on a slow connection.",
+        "If an install was interrupted part-way through downloading ffmpeg, Retake now notices the broken copy and fetches it again instead of failing every render."
+      ]
+    },
     {
       "version": "0.14.2",
       "date": "2026-10-16",

package/skill/SKILL.md

@@ -338,7 +338,7 @@ typed, chose and clicked, against the frames that came out.
 Nothing needs declaring. The inputs are already in the take — this is the half
 of the recording nothing has ever read.
 
-It found a real one on its first outing. An Avex quote entered two legs:
+It found a real one on its first outing. A flight-booking demo's quote entered two legs:
 
 ```
 type "SGN" → #leg-from-0      type "SIN" → #leg-to-0
@@ -505,6 +505,12 @@ narrated too fast, the next too slow, and a third in a voice nobody picked.
 person who has heard it; the routine only says which voice, at what pace,
 once somebody has written one.
 
+Voices are names: `andrew`, `ava`, `brian`, `emma`, `aria`, `ryan` (Edge,
+online) and `heart`, `michael`, `aiden` (local: they run on the person's Mac
+and the first narrated render downloads the model). The voice a person picked
+when they first opened Retake is the routine's voice. If the routine says
+`silent` and they want narration, ask which voice — never guess an id.
+
 If there is no routine, the advice below applies and nothing is locked.
 
 ## Style — how the person wants their videos to look