retake-demos 0.14.1 → 0.14.2

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, ~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.
 
 **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/record.js

@@ -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, 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(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)];

package/dist/routine.js

@@ -60,9 +60,14 @@ export const VOICES = {
     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", or a raw edge-tts voice id
- *  (`vi-VN-HoaiMyNeural`) for a language the named set does not cover. */
+/** 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;
 }

package/dist/ui/chat.html

@@ -520,16 +520,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 1.8 GB. 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 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>
             </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 +642,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 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.';
   $('onboard-next').disabled =
     (onboardingStep === 1 && !normalUrl($('onboard-url').value)) ||
     (onboardingStep === 2 && brandRead.state === 'reading') ||

package/dist/ui/server.js

@@ -54,7 +54,7 @@ import { captureMatchesTake, readPreviewReceipt } from "../preview.js";
 import { STYLES, VOICES, RoutineSchema, environmentFor, readRoutines, 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 {
@@ -1231,8 +1241,8 @@ export function serve(port) {
                     : 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."
                         : 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` (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.";
                 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,56 @@
  * 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`);
 }
+/** 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" } };
+/** 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")]) {
@@ -44,23 +77,39 @@ export function edgeFailure(stderr, cmd) {
     return `voiceover: edge-tts failed${last ? ` — ${last.slice(0, 200)}` : ""}`;
 }
 function runEdge(e, args, timeout) {
+    const local = e.cmd === "uvx";
     try {
-        execFileSync(e.cmd, [...e.args, ...args], { stdio: "pipe", timeout });
+        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 });
     }
     catch (err) {
         const x = err;
+        if (local) {
+            const last = String(x.stderr ?? "").trim().split("\n").filter(Boolean).pop() ?? "";
+            throw new Error(`voiceover: the local voice failed${last ? ` — ${last.slice(0, 240)}` : ""}`);
+        }
         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) {
     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);
@@ -108,7 +157,7 @@ export function synthesizeWithCues(text, voice, out, ratePercent = 0) {
         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.2",
   "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"

package/scripts/local-voice.py

@@ -0,0 +1,98 @@
+"""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)
+
+
+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)
+    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,18 @@
 {
   "_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.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",