playhead-cli 0.1.1 → 0.1.3

package/README.md

@@ -142,6 +142,24 @@ Scaffold one with `npx playhead init`.
 Add `--vision` to `render`/`verify` for an optional Claude review of the contact sheet (needs
 `ANTHROPIC_API_KEY`; skipped cleanly without one, so CI stays deterministic).
 
+### Narration voices
+
+`output.audio.narration: tts` speaks each step's narration line. Two providers:
+
+| `provider` | Voice | Deps | Platforms |
+|---|---|---|---|
+| `kokoro` (recommended) | Natural neural (Kokoro-82M). `voice:` = `heart` (**default**) or `michael` | `npm i -g kokoro-js` (~400MB, one-time; model ~90MB auto-downloads on first use) | Mac · Linux · Windows |
+| `say` | macOS built-in (robotic). `voice:` = a `say` voice name | none | macOS only |
+
+```yaml
+output:
+  audio: { narration: tts, provider: kokoro }   # → Heart, offline, cross-platform
+```
+
+Behind a TLS-intercepting proxy, the one-time model download needs the system CA:
+`NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem playhead render …`. `playhead doctor --ci` reports which
+providers are available.
+
 **Exit codes are a contract:** `0` publishable · `1` the app broke the flow (a partial bundle
 **and a watchable failure clip** are written) · `2` rendered but failed verification ·
 `3` infra · `4` bad spec/arguments.

package/dist/audio/tts.d.ts

@@ -1,8 +1,10 @@
 export interface NarrationOptions {
-    /** Only 'say' (macOS local TTS) is implemented today; the seam is here for cloud providers. */
-    provider: 'say';
+    /** 'say' — macOS built-in (zero deps, Mac-only). 'kokoro' — natural neural voice, offline,
+     *  cross-platform, via the optional kokoro-js package. */
+    provider: 'say' | 'kokoro';
+    /** say: a macOS voice name (Samantha). kokoro: a voice id (af_heart, am_michael, …). */
     voice?: string;
-    /** Words per minute (say-specific). */
+    /** say: words per minute. kokoro: playback speed × 100 (100 = 1.0×). */
     rate?: number;
 }
 export interface NarrationLine {

package/dist/audio/tts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../src/audio/tts.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAqCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EAAE,EACtB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAWrC"}
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../src/audio/tts.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,gBAAgB;IAC/B;8DAC0D;IAC1D,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC3B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AA6FD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EAAE,EACtB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAYrC"}

package/dist/cli/index.js

@@ -359,7 +359,10 @@ var init_schema = __esm({
          */
         audio: z.object({
           narration: z.enum(["none", "tts"]).default("none"),
-          provider: z.enum(["say"]).default("say"),
+          // 'say' — macOS built-in (zero deps, Mac-only, robotic).
+          // 'kokoro' — natural neural voice, offline, cross-platform; needs the optional
+          //   kokoro-js package (npm i kokoro-js). Voices: af_heart (default), am_michael, …
+          provider: z.enum(["say", "kokoro"]).default("say"),
           voice: z.string().optional(),
           rate: z.number().int().min(80).max(400).optional(),
           /** Click sound effects at click/select beats. Defaults on when this block is present. */
@@ -369,7 +372,10 @@ var init_schema = __esm({
             file: z.string(),
             gainDb: z.number().min(-40).max(6).default(-19)
           }).strict().optional()
-        }).strict().optional(),
+        }).strict().refine(
+          (a) => a.provider !== "kokoro" || a.voice === void 0 || ["heart", "af_heart", "michael", "am_michael"].includes(a.voice),
+          { message: "kokoro voice must be 'heart' (default) or 'michael'", path: ["voice"] }
+        ).optional(),
         /** Closing card. When set, the video ends on a title-card-styled end card. */
         endCard: z.object({
           title: z.string().min(1),
@@ -4037,11 +4043,25 @@ import { join as join5 } from "path";
 import { createHash as createHash2 } from "crypto";
 import { createRequire as createRequire4 } from "module";
 function providerFor(opts) {
-  const voice = opts.voice ?? "Samantha";
-  const rate = opts.rate ?? 178;
   switch (opts.provider) {
-    case "say":
+    case "say": {
+      const voice = opts.voice ?? "Samantha";
+      const rate = opts.rate ?? 178;
       return { provider: new SayProvider(voice, rate), voice, rate };
+    }
+    case "kokoro": {
+      const KOKORO_VOICES = {
+        heart: "af_heart",
+        af_heart: "af_heart",
+        michael: "am_michael",
+        am_michael: "am_michael"
+      };
+      const requested = opts.voice ?? "heart";
+      const voice = KOKORO_VOICES[requested];
+      if (!voice) throw new Error(`kokoro voice must be 'heart' (default) or 'michael', got '${requested}'`);
+      const rate = opts.rate ?? 100;
+      return { provider: new KokoroProvider(voice, rate / 100), voice, rate };
+    }
     default:
       throw new Error(`unknown TTS provider: ${opts.provider}`);
   }
@@ -4061,16 +4081,17 @@ async function probeDurationMs(file) {
 async function synthesizeNarration(lines, opts, cacheDir) {
   await mkdir2(cacheDir, { recursive: true });
   const { provider, voice, rate } = providerFor(opts);
+  const ext = provider.name === "kokoro" ? "wav" : "aiff";
   const out = /* @__PURE__ */ new Map();
   for (const { stepRef, text } of lines) {
     const key = createHash2("sha256").update(`${provider.name}|${voice}|${rate}|${text}`).digest("hex").slice(0, 16);
-    const file = join5(cacheDir, `${key}.aiff`);
+    const file = join5(cacheDir, `${key}.${ext}`);
     if (!existsSync2(file)) await provider.synth(text, file);
     out.set(stepRef, { stepRef, file, durationMs: await probeDurationMs(file) });
   }
   return out;
 }
-var require3, ffprobePath2, exec, SayProvider;
+var require3, ffprobePath2, exec, SayProvider, KokoroProvider;
 var init_tts = __esm({
   "src/audio/tts.ts"() {
     "use strict";
@@ -4091,6 +4112,39 @@ var init_tts = __esm({
         await exec("say", ["-v", this.voice, "-r", String(this.rate), "-f", txt, "-o", outFile]);
       }
     };
+    KokoroProvider = class {
+      constructor(voice, speed) {
+        this.voice = voice;
+        this.speed = speed;
+      }
+      voice;
+      speed;
+      name = "kokoro";
+      tts = null;
+      load() {
+        if (this.tts) return this.tts;
+        this.tts = (async () => {
+          let mod;
+          try {
+            mod = await import("kokoro-js");
+          } catch {
+            throw new Error(
+              "the 'kokoro' voice needs the optional kokoro-js package \u2014 install it with `npm i -g kokoro-js` (or add it to your project). It bundles the neural model runtime (~400MB); the base playhead-cli stays lean."
+            );
+          }
+          return await mod.KokoroTTS.from_pretrained("onnx-community/Kokoro-82M-v1.0-ONNX", {
+            dtype: "q8",
+            device: "cpu"
+          });
+        })();
+        return this.tts;
+      }
+      async synth(text, outFile) {
+        const tts = await this.load();
+        const audio = await tts.generate(text, { voice: this.voice, speed: this.speed });
+        await audio.save(outFile);
+      }
+    };
   }
 });
 
@@ -6611,8 +6665,11 @@ program.command("doctor").description("check that ffmpeg, the browser, and fonts
     const { promisify: promisify3 } = await import("util");
     const which = promisify3(execFile3);
     const hasSay = await which("which", ["say"]).then(() => true).catch(() => false);
-    if (hasSay) log.ok("tts: macOS `say` available");
-    else log.warn("tts: no `say` binary \u2014 output.audio.narration will render SILENT on this host (Linux TTS provider planned)");
+    if (hasSay) log.ok("tts (say): macOS `say` available");
+    else log.info("tts (say): no `say` binary here \u2014 the `say` provider is macOS-only");
+    const hasKokoro = await import("kokoro-js").then(() => true).catch(() => false);
+    if (hasKokoro) log.ok("tts (kokoro): kokoro-js installed \u2014 the natural offline voice is available");
+    else log.warn("tts (kokoro): kokoro-js not installed \u2014 `provider: kokoro` needs `npm i -g kokoro-js` (~400MB, one time)");
     if (process.platform === "linux") {
       log.info("linux: run chromium with a base image that provides fonts + sandbox deps (see Dockerfile), and give /dev/shm \u2265 512MB or pass --disable-dev-shm-usage");
     }