retake-demos 0.14.1 → 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); `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/cli.js

@@ -1685,8 +1685,8 @@ routine
     const parsed = RoutineSchema.safeParse(next);
     if (!parsed.success)
         throw new Error(parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
-    if (key === "voice" && value !== "silent" && !VOICES[value] && !/^[a-z]{2}-[A-Z]{2}-/.test(value)) {
-        say(`ℹ "${value}" is not one of ${Object.keys(VOICES).join(", ")} and does not look like an edge-tts id (en-US-AriaNeural). \`retake routine voices\` lists what is here.`);
+    if (key === "voice" && value !== "silent" && !VOICES[value] && !/^[a-z]{2}-[A-Z]{2}-/.test(value) && !/^(kokoro|qwen):[a-z_]+$/.test(value)) {
+        say(`ℹ "${value}" is not one of ${Object.keys(VOICES).join(", ")} and does not look like an edge-tts id (en-US-AriaNeural) or a local one (kokoro:af_heart). \`retake routine voices\` lists what is here.`);
     }
     if (typeof parsed.data.music === "string" && !fs.existsSync(path.resolve(parsed.data.music))) {
         say(`ℹ ${parsed.data.music} is not there yet — the render will fail until it is. It ships inside your video, so it must be a track you may use.`);
@@ -1701,7 +1701,7 @@ routine
     .option("--line <text>", "what they should say", "This is the voice your demos will use, at the pace they will use it.")
     .option("--rate <percent>", "try a speed", "0")
     .action(async (opts) => {
-    const { synthesize } = await import("./voice.js");
+    const { synthesize, LOCAL_VOICE, localModelReady } = await import("./voice.js");
     const dir = path.resolve("outputs", ".voices");
     fs.mkdirSync(dir, { recursive: true });
     const rate = Number(opts.rate);
@@ -1710,6 +1710,11 @@ routine
     for (const [name, v] of Object.entries(VOICES)) {
         const out = path.join(dir, `${name}.mp3`);
         process.stdout.write(`  ${name.padEnd(14)} ${v.id} … `);
+        // A sample is not worth a download: local voices are heard once chosen.
+        if (LOCAL_VOICE.test(v.id) && !localModelReady(v.id)) {
+            process.stdout.write(`local, not downloaded yet — ${v.note}\n`);
+            continue;
+        }
         try {
             synthesize(opts.line, v.id, out, rate);
             process.stdout.write(`${path.relative(process.cwd(), out)}\n`);

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
@@ -1003,7 +1003,26 @@ export async function record(m, opts) {
         fs.rmSync(path.join(opts.outDir, "reached.json"), { force: true });
     }
     catch { /* fine */ }
-    const trimBefore = sec(setupEnd - t0);
+    // The start is marked by painting the empty tab (paintFirstFrame), which
+    // holds on an ordinary machine. On a loaded one — CI, a laptop running a
+    // test suite — the browser can begin the video before that paint lands,
+    // and the cut falls on the blank page. So check the picture itself: if the
+    // take's first frame is flat while the page was proven painted, move the
+    // start to the first real frame and every step with it.
+    let late = 0;
+    if (video) {
+        late = blankLead(video, sec(setupEnd - t0));
+        if (late > 0) {
+            for (const e of timeline) {
+                e.start = sec(e.start + late);
+                e.end = sec(e.end + late);
+            }
+            for (const e of pageErrors)
+                e.at = sec(e.at + late);
+            log(`start: the video began ${late.toFixed(2)}s before the marked start — every step moved to match the picture`);
+        }
+    }
+    const trimBefore = sec(setupEnd - t0 + late);
     // The recording keeps rolling while the browser is torn down, so the raw
     // video always has a tail of nothing after the last step. The take ends
     // where the demo ends (plus a breath), never where the recorder stopped —
@@ -1566,6 +1585,23 @@ export function describe(step) {
             return `scene: ${step.label}`;
     }
 }
+/** Seconds of flat, empty picture from `at` onward, before the first frame
+    with anything on it — 0 when `at` already shows the page. Bounded: past
+    4s it is the app, not the clock, and the take is left alone. */
+export function blankLead(video, at, maxSeconds = 4) {
+    try {
+        const out = execFileSync(ffmpegBin(), ["-hide_banner", "-ss", at.toFixed(3), "-t", String(maxSeconds), "-i", video,
+            "-vf", "fps=20,signalstats,metadata=print:file=-", "-f", "null", "-"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30_000 });
+        const frames = [...out.matchAll(/pts_time:([\d.]+)[\s\S]*?YMIN=(\d+)[\s\S]*?YMAX=(\d+)/g)].map((m) => ({ t: Number(m[1]), flat: Number(m[3]) - Number(m[2]) <= 8 }));
+        if (!frames.length || !frames[0].flat)
+            return 0;
+        const first = frames.find((f) => !f.flat);
+        return first ? Math.round(first.t * 1000) / 1000 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 /** Paint the empty tab and return the wall-clock ms of that paint — the
     video's first frame. Null if the page would not paint (then the old
     estimate stands). It happens during setup, so it is trimmed away. */

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, 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, 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,19 +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." },
-};
-/** A routine's `voice` is a name above, "silent", or a raw edge-tts voice id
- *  (`vi-VN-HoaiMyNeural`) for a language the named set does not cover. */
-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"),
@@ -160,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; }
@@ -520,16 +523,16 @@
           <p class="ob-lead">The first draft stays silent. Narration comes after you approve the recording and script.</p>
           <div class="voice-grid" role="radiogroup" aria-label="Narration choice">
             <button class="voice-card selected" type="button" data-voice="silent" role="radio" aria-checked="true">
-              <span class="vicon" aria-hidden="true">×</span><b>No voiceover</b><small>Skip this for now. You can add your own voice later.</small><span class="tag">No setup</span>
+              <span class="vicon" aria-hidden="true">×</span><b>No voiceover</b><small>Skip this for now. You can choose a voice later.</small><span class="tag">No setup</span>
             </button>
             <button class="voice-card" type="button" data-voice="edge" data-sample="edge" role="radio" aria-checked="false">
               <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 natural voice tested and selected for Retake. About 2 GB.</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. Roughly 100–200 MB with many voices. This is Retake's first Kokoro test.</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 separate local model download of about 2 GB. Nothing downloads on this screen.';
-  if (onboardingState.voice === 'kokoro') $('voice-consent-copy').textContent = 'I understand that Kokoro needs a separate local model download of roughly 100–200 MB. 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,10 +51,10 @@ 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 } from "../voice.js";
+import { synthesize, voiceCachePath, LOCAL_VOICE, localModelReady } from "../voice.js";
 const ROOT = PROJECT_ROOT;
 const DEMOS = path.join(ROOT, "demos");
 /** Where takes land. Default outputs/ in the project; changeable in Settings
@@ -789,6 +789,16 @@ export function serve(port) {
                 if (!Number.isInteger(rate) || rate < -50 || rate > 50)
                     return json(res, 400, { error: "rate is a whole percent, -50 to 50" });
                 const id = voiceId(voice);
+                // A local voice is never downloaded just to be previewed (and Aiden is
+                // ~30s to speak even when present, which would hold this whole window
+                // up): play the sample that ships with Retake instead.
+                if (LOCAL_VOICE.test(id) && (id.startsWith("qwen:") || !localModelReady(id))) {
+                    const f = path.join(PKG_ROOT, "assets", "voice-samples", id.startsWith("qwen:") ? "aiden.mp4" : "kokoro.mp4");
+                    if (!fs.existsSync(f))
+                        return json(res, 404, { error: "no sample for this voice yet" });
+                    res.writeHead(200, { "content-type": "video/mp4", "content-length": fs.statSync(f).size, "cache-control": "no-store" });
+                    return stream(f, res);
+                }
                 const line = "This is the voice your demos will use, at the pace they will use it.";
                 const out = voiceCachePath(line, id, rate);
                 try {
@@ -1226,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 Qwen voice for the final narration. Do not download a model or synthesize speech until they separately approve the install, recording, and one continuous script."
-                            : "Make the first draft silent and do not add captions. The person chose the compact local Kokoro voice for the final narration. Do not download a model or synthesize speech until they separately approve the install, recording, and one continuous script.";
+                            ? "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

@@ -3,23 +3,81 @@
  * scene's line is synthesized once and placed at the scene's start, so the
  * narration is honest to the take by construction.
  *
- * Engine: edge-tts (Microsoft's neural voices — free, network). Found as a
- * CLI (`edge-tts`, pipx/pip) or module (`python3 -m edge_tts`). Retake does
- * not bundle a voice engine; the error says how to install one.
+ * Engines: edge-tts (Microsoft's neural voices — free, network), found as a
+ * CLI (`edge-tts`, pipx/pip) or module (`python3 -m edge_tts`); and two local
+ * voices that run on this Mac and send nothing anywhere — Kokoro
+ * (`kokoro:af_heart`) and Qwen3 (`qwen:aiden`) — through scripts/local-voice.py
+ * under uv. Retake bundles neither; the errors say how to get them.
  */
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { PKG_ROOT } from "./paths.js";
 export const DEFAULT_VOICE = "en-US-JennyNeural";
 /** Content-addressed speech cache. Narration text and voice are immutable
  * inputs, so generating the same line again is pure wasted network time. */
 export function voiceCachePath(text, voice, ratePercent = 0) {
     const root = process.env.RETAKE_TTS_CACHE || path.join(os.homedir(), ".cache", "retake-tts", "edge");
-    const key = createHash("sha256").update(`${voice}\0${ratePercent}\0${text}`).digest("hex");
+    // A local voice's output changes when its pronunciation or levelling does;
+    // the version is part of the key so an improvement is heard, not cached away.
+    const v = LOCAL_VOICE.test(voice) ? `${voice}\0${LOCAL_VOICE_VERSION}` : voice;
+    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: "~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")
+        throw new Error(`voiceover: ${voice} is a local voice, and local voices run on Apple Silicon Macs for now — use an Edge voice here (andrew, ava, emma…)`);
+    if (spawnSync("uvx", ["--version"], { stdio: "ignore" }).status !== 0)
+        throw new Error(`voiceover: ${voice} runs locally through uv, which is not installed — install it once (\`brew install uv\`), then re-render`);
+    const kind = voice.split(":")[0];
+    if (!localModelReady(voice))
+        process.stderr.write(`… first use of ${voice}: downloading its voice model (${LOCAL_MODEL[kind].size}, one time). Nothing you narrate leaves this computer.\n`);
+    return { cmd: "uvx", args: ["--quiet", "--python", "3.12", "--from", "mlx-audio==0.5.5", "--with", "soundfile", "--with", "misaki[en]", "python", path.join(PKG_ROOT, "scripts", "local-voice.py")] };
+}
+/** Whether a local voice's model is already on this computer. */
+export function localModelReady(voice) {
+    const kind = voice.split(":")[0];
+    if (!LOCAL_MODEL[kind])
+        return false;
+    return fs.existsSync(path.join(process.env.HF_HOME || path.join(os.homedir(), ".cache", "huggingface"), "hub", LOCAL_MODEL[kind].repo));
+}
+function engineFor(voice) {
+    return LOCAL_VOICE.test(voice) ? localEngine(voice) : engine();
+}
 function engine() {
     const home = process.env.HOME ?? "";
     for (const c of ["edge-tts", path.join(home, ".local", "bin", "edge-tts")]) {
@@ -38,29 +96,62 @@ 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() ?? "";
     return `voiceover: edge-tts failed${last ? ` — ${last.slice(0, 200)}` : ""}`;
 }
 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 });
+        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)}` : " 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");
         throw new Error(edgeFailure(String(x.stderr ?? ""), e.cmd));
     }
 }
+/** ffmpeg for the local voice's levelling: the one Retake renders with. */
+function ffmpegPath() {
+    try {
+        const require = createRequire(import.meta.url);
+        const p = require("ffmpeg-static");
+        if (p && fs.existsSync(p))
+            return p;
+    }
+    catch { /* system ffmpeg */ }
+    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);
         return;
     }
-    const e = engine();
+    const e = engineFor(voice);
     const temp = `${out}.tmp-${process.pid}`;
     try {
         runEdge(e, ["--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp], 60_000);
@@ -102,13 +193,14 @@ 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)) {
         fs.copyFileSync(cached, out);
         return parseSrt(fs.readFileSync(cachedSrt, "utf8"));
     }
-    const e = engine();
+    const e = engineFor(voice);
     const temp = `${out}.tmp-${process.pid}`, srt = `${out}.srt`;
     try {
         runEdge(e, ["--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp, "--write-subtitles", srt], 120_000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retake-demos",
-  "version": "0.14.1",
+  "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",
@@ -39,6 +39,7 @@
     "docs/stitch.md",
     "LICENSE",
     "scripts/patch-testreel.mjs",
+    "scripts/local-voice.py",
     "AGENTS.md",
     "llms.txt",
     "site/releases.json"
@@ -51,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

@@ -0,0 +1,131 @@
+"""Retake's local voices: Kokoro and Qwen3 (Aiden), on this Mac.
+
+Speaks the way edge-tts does, so narration does not care which it got:
+  --voice kokoro:<voice> | qwen:<speaker>   --rate +N%   --text ...
+  --write-media out.mp3   [--write-subtitles out.srt]
+Each sentence is its own take (the voice keeps its shape), joined with short
+breaths; the SRT says where each falls. Levelled to Edge's loudness so a
+comparison hears the voice, not the volume.
+
+  --pronounce "text"   print the text as Kokoro will be given it (no models)
+
+Run by Retake through uv:  uvx --from mlx-audio==0.5.5 --with soundfile
+--with "misaki[en]" python local-voice.py ...  Apple Silicon only (MLX).
+"""
+import argparse, os, re, subprocess, sys, tempfile
+
+# ---------- words Kokoro's guesser gets wrong in demo narration ----------
+# "record" is a heteronym: the guesser hears a music RE-cord in "press record".
+# In a demo script it is almost always the verb (re-CORD); after a word that
+# makes it a noun ("a record", "the record") it is left alone. "demos" came
+# out "dee-moss". Overrides use misaki's own [word](/phonemes/) form.
+NOUN_BEFORE = {"a", "an", "the", "this", "that", "my", "your", "our", "their", "its", "his", "her",
+               "any", "no", "new", "old", "track", "world", "public", "permanent", "every"}
+FIXED = {"demos": "dˈɛmOz", "demo": "dˈɛmO"}
+VERB = {"record": "ɹəkˈɔɹd", "records": "ɹəkˈɔɹdz"}
+
+
+def pronounce(text: str) -> str:
+    out, prev = [], ""
+    for tok in re.split(r"(\W+)", text):
+        low = tok.lower()
+        if low in VERB and prev not in NOUN_BEFORE:
+            tok = f"[{tok}](/{VERB[low]}/)"
+        elif low in FIXED:
+            tok = f"[{tok}](/{FIXED[low]}/)"
+        if tok.strip() and re.match(r"\w", tok):
+            prev = low
+        out.append(tok)
+    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"}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser()
+    p.add_argument("--voice"); p.add_argument("--rate", default="+0%"); p.add_argument("--text")
+    p.add_argument("--write-media"); p.add_argument("--write-subtitles"); p.add_argument("--pronounce")
+    a = p.parse_args()
+    if a.pronounce is not None:
+        print(pronounce(a.pronounce))
+        return
+
+    import numpy as np, soundfile as sf
+    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])
+
+    def say(sentence: str):
+        if engine == "kokoro":
+            gen = model.generate(text=pronounce(sentence), voice=name, speed=speed, lang_code="a" if name[0] == "a" else "b")
+        else:
+            gen = model.generate(text=sentence, voice=name, speed=speed, lang_code="english", verbose=False)
+        return np.concatenate([np.array(r.audio, dtype=np.float32).reshape(-1) for r in gen])
+
+    paras = [x.strip() for x in re.split(r"\n\s*\n|\n", a.text) if x.strip()] or [a.text]
+    audio, cues, t = [], [], 0.0
+    for para in paras:
+        for sentence in [s for s in re.split(r"(?<=[.!?])\s+", para) if s.strip()]:
+            chunk = say(sentence)
+            audio.append(chunk); cues.append((t, t + len(chunk) / SR, sentence)); t += len(chunk) / SR
+            audio.append(np.zeros(int(SR * 0.3), dtype=np.float32)); t += 0.3
+        audio.append(np.zeros(int(SR * 0.35), dtype=np.float32)); t += 0.35
+
+    ff = os.environ.get("FFMPEG_BIN", "ffmpeg")
+    wav = tempfile.mktemp(suffix=".wav")
+    sf.write(wav, np.concatenate(audio), SR)
+    try:
+        meas = subprocess.run([ff, "-hide_banner", "-nostats", "-i", wav, "-af", "ebur128=framelog=quiet", "-f", "null", "-"], capture_output=True, text=True).stderr
+        found = re.findall(r"I:\s+(-?[\d.]+) LUFS", meas)
+        gain = EDGE_LUFS - float(found[-1]) if found else 0.0
+        subprocess.run([ff, "-hide_banner", "-loglevel", "error", "-y", "-i", wav, "-af", f"volume={gain:.2f}dB,alimiter=limit=0.97",
+                        "-c:a", "libmp3lame", "-b:a", "128k", "-f", "mp3", a.write_media], check=True)
+    finally:
+        os.remove(wav)
+    if a.write_subtitles:
+        ts = lambda s: f"{int(s // 3600):02d}:{int(s % 3600 // 60):02d}:{int(s % 60):02d},{int(round((s % 1) * 1000)) % 1000:03d}"
+        with open(a.write_subtitles, "w") as f:
+            for i, (st, en, tx) in enumerate(cues, 1):
+                f.write(f"{i}\n{ts(st)} --> {ts(en)}\n{tx}\n\n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/site/releases.json

@@ -1,6 +1,31 @@
 {
   "_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",
+      "headline": "The local voices you can pick are now the voices you get",
+      "notes": [
+        "Kokoro and Aiden, the two local voices offered when you first open Retake, now narrate your videos. Before, choosing one only told your agent your preference: Retake itself could speak only Edge. They run on your Mac (Apple Silicon), so your script never leaves it, and they come out exactly as loud as Edge.",
+        "Pick them by name: heart (Kokoro, female), michael (Kokoro, male) or aiden. The model downloads once, the first time a video is narrated: about 300 MB for Kokoro, 1.8 GB for Aiden.",
+        "Kokoro now says demo words the demo way: “press record” as re-CORD, not the music kind, and “demos” as deh-mohz.",
+        "Hearing a voice before you pick it never downloads anything, and never freezes the window.",
+        "On a busy computer, a recording could still start on a blank frame. Retake now checks the picture itself and starts on the first real frame."
+      ]
+    },
     {
       "version": "0.14.1",
       "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