voila-recorder 0.6.0 → 0.7.0

package/AGENTS.md

@@ -58,8 +58,12 @@ npx -y voila-recorder rerender <dir> --voice bf_emma
 - Narration style: short sentences, product language, 8-15 words per beat.
 - Prefer `zoom` with a `selector` over a raw `level`: voila measures the element
   and picks the level and camera centre so nothing gets cropped.
-- Voices: 28 English (US/UK). af_heart (A) is the default, af_bella (A-) and
-  bf_emma (British) are the other good ones. `speed` 0.5-1.6 sets pace.
+- Voices: Kokoro is English only (af_heart A, af_bella A-, bf_emma British).
+  `speed` 0.5-1.6 sets pace.
+- Other languages: set `voice:` per narration step, so one demo can mix them.
+  `say:Monica` uses a macOS system voice (~50 languages, `voila voices --all`);
+  `--tts-cmd 'engine -o {out} "{text}"'` plugs in any engine on any platform;
+  `audio: clip.mp3` on a step uses a file you already have.
 - Sign-in walls: recording refuses to film a login page. Run `voila login <url>`
   (or the voila_login tool), let the HUMAN sign in in the window that opens, and
   the session persists in a local profile for every later recording.

package/README.md

@@ -73,6 +73,28 @@ on-device, no cloud, no API keys ([audio.js](audio.js)). Falls back to macOS
 `say` if Kokoro can't load. Voices: `af_heart` (default), `af_bella`,
 `am_adam`, … (`voice` param). Disable with `narrate: false` / `--no-narrate`.
 
+**Other languages, and mixing them.** Kokoro's JS port speaks English only, so
+non-English narration comes from one of two other engines, chosen per step:
+
+```yaml
+- action: hover
+  selector: h1
+  narration: "This part is English."          # Kokoro
+- action: scroll_to
+  selector: "#pricing"
+  voice: "say:Mónica"                          # macOS system voice
+  narration: "Esta parte está en español."
+- action: wait
+  ms: 500
+  audio: ./clips/intro-ja.mp3                  # a clip you already have
+```
+
+`voila voices --all` lists the ~180 system voices across ~50 languages on
+macOS. On Linux and Windows use any engine you like:
+`--tts-cmd 'piper -m es.onnx -f {out} -- "{text}"'` ({out}, {text}, {voice}).
+Every step is still paced to its own spoken clip, so mixed-language demos stay
+in sync.
+
 ## Recipes — demos as code
 
 Every video ships with its source: `recipe.json` (URL + steps + narration +

package/RECIPE.md

@@ -51,6 +51,10 @@ Each step: `{ action, ...params, caption?, narration?, optional?, pause? }`
 | `zoom`      | `level` (1-3) or `selector`, `ms`   | camera zoom; with a selector it frames that element |
 | `wait`      | `ms`                                | hold (cursor keeps breathing on long holds) |
 
+Any step may also carry `voice:` (Kokoro id, `say:Name`, or an id for your
+`--tts-cmd` engine) and `audio:` (a ready-made clip, skipping TTS entirely).
+Because voice is per step, a recipe can mix languages.
+
 `caption` renders as a lower-third; `narration` is spoken by on-device TTS and
 **paces the segment** — the recording holds until the clip finishes, so a
 recreated demo re-times itself to whatever voice regenerates it.

package/audio.js

@@ -31,7 +31,7 @@ async function getKokoro() {
   return kokoroInstance;
 }
 
-async function synthKokoro(texts, dir, voice, onStatus, speed = 1) {
+async function _unusedSynthKokoro(texts, dir, voice, onStatus, speed = 1) {
   // Fail loudly on a bad voice name rather than silently using the default.
   if (voice && /^[a-z]{2}_/.test(voice) && !voices.isValid(voice)) {
     throw new Error(`unknown voice "${voice}". Try: ${voices.suggest(voice).join(', ')} (run \`voila voices\` for all ${voices.ranked().length})`);
@@ -77,7 +77,7 @@ async function pickSayVoice(preferred) {
   return 'Samantha';
 }
 
-async function synthSay(texts, dir, voice, onStatus) {
+async function _unusedSynthSay(texts, dir, voice, onStatus) {
   const v = await pickSayVoice(voice);
   onStatus(`narrating with say (${v})`);
   const clips = [];
@@ -90,25 +90,113 @@ async function synthSay(texts, dir, voice, onStatus) {
 }
 
 // --- pipeline entry ----------------------------------------------------------
+// Each narration item is {text, voice?, audio?}. Voice decides the engine:
+//   af_heart          -> Kokoro (English, best quality, cross platform)
+//   say:Monica        -> a system voice (macOS; ~50 languages)
+//   (--tts-cmd set)   -> any external engine, any language
+// A step can also point at a ready-made file with `audio:`, which bypasses TTS.
+// Because the voice is per item, one demo can mix languages.
+
+function engineFor(voice, ttsCmd) {
+  // Supplying --tts-cmd means "use my engine", unless a step names a specific
+  // Kokoro or system voice, which then wins for that step.
+  if (!voice) {
+    if (ttsCmd) return 'cmd';
+    return process.env.VOILA_TTS === 'say' ? 'say' : 'kokoro';
+  }
+  if (String(voice).startsWith('cmd:') || (ttsCmd && String(voice).startsWith('cmd'))) return 'cmd';
+  if (String(voice).startsWith('say:')) return 'say';
+  if (voices.isValid(voice)) return 'kokoro';
+  if (voices.isSystemVoice(voice)) return 'say';
+  if (ttsCmd) return 'cmd';
+  throw new Error(
+    `unknown voice "${voice}". Kokoro (English): ${voices.suggest(voice).join(', ')}. ` +
+    `For other languages use a system voice like "say:Monica" (see \`voila voices --all\`) ` +
+    `or supply --tts-cmd for your own engine.`
+  );
+}
+
+async function sayOne(text, file, voiceName, speed) {
+  const rate = Math.round(185 * (speed || 1));
+  await run('say', ['-v', voiceName, '-r', String(rate), '-o', file, text]);
+}
+
+async function cmdOne(text, file, voiceName, ttsCmd) {
+  const cmd = ttsCmd
+    .replaceAll('{text}', text.replace(/"/g, '\\"'))
+    .replaceAll('{out}', file)
+    .replaceAll('{voice}', voiceName || '');
+  await new Promise((res, rej) => {
+    require('child_process').exec(cmd, { maxBuffer: 1e7 }, (err, _o, se) =>
+      err ? rej(new Error(`tts-cmd failed: ${String(se || err.message).slice(0, 200)}`)) : res());
+  });
+  if (!fs.existsSync(file)) throw new Error(`tts-cmd produced no file at ${file}`);
+}
 
-// Synthesize narration clips up front so the recorder can pace segments to the
-// spoken durations. Returns {clips: [{file, durMs}], voice, backend}.
-async function prepareNarration(texts, dir, voice, onStatus = () => {}, speed = 1) {
+// Synthesize every narration clip up front so the recorder can pace segments
+// to real spoken durations. Returns {clips:[{file,durMs}], voice, backend}.
+async function prepareNarration(items, dir, defaultVoice, onStatus = () => {}, speed = 1, ttsCmd = null) {
   fs.mkdirSync(dir, { recursive: true });
-  const backend = process.env.VOILA_TTS || 'kokoro';
-  if (backend === 'kokoro') {
-    try {
-      return await synthKokoro(texts, dir, voice, onStatus, speed);
-    } catch (e) {
-      if (/unknown voice/.test(e.message)) throw e;   // user error, not a fallback case
-      onStatus(`kokoro unavailable (${e.message.slice(0, 80)})`);
+  const norm = items.map(it => (typeof it === 'string' ? { text: it } : it));
+  const clips = [];
+  const used = new Set();
+  let kokoro = null;
+
+  for (let i = 0; i < norm.length; i++) {
+    const it = norm[i];
+    const voice = it.voice || defaultVoice || null;
+
+    // A pre-made audio file wins over any engine.
+    if (it.audio) {
+      if (!fs.existsSync(it.audio)) throw new Error(`audio file not found: ${it.audio}`);
+      clips.push({ file: it.audio, durMs: await ffDurationMs(it.audio) });
+      used.add('file');
+      continue;
+    }
+
+    const engine = engineFor(voice, ttsCmd);
+    const ext = engine === 'kokoro' ? 'wav' : engine === 'say' ? 'aiff' : 'wav';
+    const file = path.join(dir, `seg${i}.${ext}`);
+
+    if (engine === 'kokoro') {
+      if (!kokoro) {
+        onStatus('loading Kokoro TTS');
+        require('./modelcache').useStableCache();
+        const { KokoroTTS } = require('kokoro-js');
+        kokoro = await KokoroTTS.from_pretrained('onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'q8' });
+      }
+      const v = voice && voices.isValid(voice) ? voice : 'af_heart';
+      onStatus(`narrating ${i + 1}/${norm.length} with Kokoro (${v})`);
+      const audio = await kokoro.generate(it.text, { voice: v, speed });
+      await audio.save(file);
+      clips.push({
+        file,
+        durMs: audio.audio && audio.sampling_rate
+          ? Math.round((audio.audio.length / audio.sampling_rate) * 1000)
+          : await ffDurationMs(file),
+      });
+      used.add(`kokoro:${v}`);
+    } else if (engine === 'say') {
+      if (process.platform !== 'darwin') {
+        throw new Error(`system voices need macOS. Use a Kokoro voice for English, or --tts-cmd on this platform.`);
+      }
+      const name = String(voice).replace(/^say:/, '');
+      onStatus(`narrating ${i + 1}/${norm.length} with system voice (${name})`);
+      await sayOne(it.text, file, name, speed);
+      clips.push({ file, durMs: await ffDurationMs(file) });
+      used.add(`say:${name}`);
+    } else {
+      onStatus(`narrating ${i + 1}/${norm.length} with tts-cmd`);
+      await cmdOne(it.text, file, String(voice || '').replace(/^cmd:/, ''), ttsCmd);
+      clips.push({ file, durMs: await ffDurationMs(file) });
+      used.add('cmd');
     }
   }
-  if (process.platform === 'darwin') return synthSay(texts, dir, voice, onStatus);
-  throw new Error('no TTS backend available');
+
+  return { clips, voice: [...used].join(', ') || 'none', backend: [...used].join(', ') };
 }
 
-async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1, prepared = null, onStatus = () => {} } = {}) {
+async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1, ttsCmd = null, prepared = null, onStatus = () => {} } = {}) {
   const segs = (meta.segments || []).filter(s => s.narration);
   if (!segs.length) {
     fs.copyFileSync(videoIn, videoOut);
@@ -120,7 +208,9 @@ async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1,
   let synth = prepared && prepared.clips.length === segs.length ? prepared : null;
   if (!synth) {
     try {
-      synth = await prepareNarration(segs.map(s => s.narration), dir, voice, onStatus, speed);
+      synth = await prepareNarration(
+        segs.map(s => ({ text: s.narration, voice: s.voice, audio: s.audio })),
+        dir, voice, onStatus, speed, ttsCmd);
     } catch (e) {
       onStatus(`narration skipped: ${e.message}`);
       fs.copyFileSync(videoIn, videoOut);
@@ -154,7 +244,7 @@ async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1,
     ff.on('error', rej);
   });
 
-  fs.rmSync(dir, { recursive: true, force: true });
+  fs.rmSync(dir, { recursive: true, force: true });   // only generated clips live here
   return { narrated: true, voice: synth.voice, backend: synth.backend, segments: clips.length };
 }
 

package/cli.js

@@ -20,10 +20,10 @@ function arg(name, fallback = null) {
 const USAGE = `usage:
   voila doctor                          (check + download everything voila needs)
   voila outline <url> [--device desktop|mobile|tablet]
-  voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--no-narrate] [--headful] [--keep-frames] [--no-dismiss] [--dismiss sel] [--out dir] [--profile dir]
+  voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--tts-cmd tmpl] [--no-narrate] [--headful] [--keep-frames] [--no-dismiss] [--dismiss sel] [--out dir] [--profile dir]
   voila review <video.mp4> [--frames 12] [--out dir]
   voila login <url> [--profile dir]     (sign in yourself; session is saved locally)
-  voila voices                          (list every narration voice, best first)
+  voila voices [--all]                  (Kokoro voices; --all adds system voices for other languages)
   voila fork <video.mp4> [--url u] [--voice v] [--print] [--out dir]
   voila rerender <dir> [--voice v] [--speed n]   (needs --keep-frames on the original)
   voila skill   (install the voila skill into ~/.claude/skills)
@@ -49,7 +49,9 @@ const USAGE = `usage:
     process.exit(r.ready ? 0 : 1);
   }
   if (cmd === 'voices') {
-    console.log(require('./voices').format());
+    const v = require('./voices');
+    console.log(process.argv.includes('--all') ? v.formatAll() : v.format());
+    if (!process.argv.includes('--all')) console.log('\nNon-English? run: voila voices --all');
     return;
   }
   if (cmd === 'skill') {
@@ -124,6 +126,7 @@ const USAGE = `usage:
     const r = await rerender(dir, {
       voice: arg('--voice'),
       speed: Number(arg('--speed', '1')) || 1,
+      ttsCmd: arg('--tts-cmd'),
       narrate: !process.argv.includes('--no-narrate'),
       onStatus: m => console.error('[voila]', m),
     });
@@ -166,6 +169,7 @@ const USAGE = `usage:
         narrate: !process.argv.includes('--no-narrate'),
         voice: arg('--voice'),
         speed: Number(arg('--speed', '1')) || 1,
+        ttsCmd: arg('--tts-cmd'),
         keepFrames: process.argv.includes('--keep-frames'),
         onStatus: s => console.error('[voila]', s),
       });

package/mcp.js

@@ -37,7 +37,7 @@ function getSession(device) {
   return sessions.get(key);
 }
 
-const server = new McpServer({ name: 'voila', version: '0.6.0' });
+const server = new McpServer({ name: 'voila', version: '0.7.0' });
 const deviceParam = z.enum(['desktop', 'mobile', 'tablet']).optional().default('desktop');
 
 server.tool(
@@ -61,6 +61,7 @@ server.tool(
   'caption is burned into the video as a lower-third; narration is spoken via on-device TTS (Kokoro) at that step, ' +
   'and segment pacing automatically stretches to fit each narration clip — no need to pad waits. ' +
   'Steps marked optional:true are skipped on failure instead of aborting. ' +
+  'A step may set its own voice: (mixing languages within one demo) or audio: (a ready-made clip). ' +
   'device selects the recorded viewport (mobile emulates an iPhone-class device). ' +
   'On failure the error names the failing step and includes the live page outline — patch the steps and retry. ' +
   'Returns the MP4 path, the recipe path, and any warnings.',
@@ -68,16 +69,17 @@ server.tool(
     url: z.string().url(),
     steps_yaml: z.string().optional(),
     narrate: z.boolean().optional().default(true),
-    voice: z.string().optional().describe('narration voice id, e.g. af_heart (A), af_bella (A-), bf_emma (B-, British). Call voila_voices for the full list.'),
+    voice: z.string().optional().describe('default narration voice. Kokoro is ENGLISH ONLY (af_heart, af_bella, bf_emma). For other languages use a macOS system voice ("say:Monica") or set tts_cmd. Per-step `voice:` overrides this, so one demo can mix languages.'),
     speed: z.number().min(0.5).max(1.6).optional().default(1).describe('narration speed; 0.9 reads calmer'),
+    tts_cmd: z.string().optional().describe('external TTS engine template for any language/platform, e.g. \'piper -m es.onnx -f {out} -- "{text}"\'. Placeholders: {out} {text} {voice}.'),
     device: deviceParam,
   },
-  async ({ url, steps_yaml, narrate, voice, speed, device }) => enqueue(async () => {
+  async ({ url, steps_yaml, narrate, voice, speed, tts_cmd, device }) => enqueue(async () => {
     const steps = steps_yaml ? yaml.load(steps_yaml) : null;
     const workDir = path.join(__dirname, 'recordings', `mcp-${Date.now()}`);
     fs.mkdirSync(workDir, { recursive: true });
     const result = await produceDemo(getSession(device), {
-      url, steps, workDir, narrate, voice: voice || null, speed,
+      url, steps, workDir, narrate, voice: voice || null, speed, ttsCmd: tts_cmd || null,
       onStatus: () => {},
     });
     return {
@@ -116,11 +118,19 @@ server.tool(
 
 server.tool(
   'voila_voices',
-  'List every narration voice with its quality grade, best first. Use before voila_record when the ' +
-  'user asks for a different voice, an accent, or a male or female narrator.',
-  {},
-  async () => ({
-    content: [{ type: 'text', text: JSON.stringify(voiceCatalogue.ranked(), null, 2) }],
+  'List narration voices. Kokoro voices are English only, with quality grades. Pass system:true to ' +
+  'also get the machine\'s system voices, which is how you narrate other languages (macOS only; on ' +
+  'Linux or Windows use tts_cmd instead). Use before voila_record when the user asks for a different ' +
+  'voice, an accent, a male or female narrator, or a non-English language.',
+  { system: z.boolean().optional().default(false) },
+  async ({ system }) => ({
+    content: [{ type: 'text', text: JSON.stringify({
+      kokoro: voiceCatalogue.ranked(),
+      englishOnly: true,
+      system: system ? voiceCatalogue.systemVoices() : undefined,
+      systemLanguages: system ? Object.keys(voiceCatalogue.systemLanguages()) : undefined,
+      note: 'Non-English: use a system voice (say:Name) on macOS, or tts_cmd on any platform.',
+    }, null, 2) }],
   })
 );
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voila-recorder",
-  "version": "0.6.0",
-  "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out \u2014 with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
+  "version": "0.7.0",
+  "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out — with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
   "license": "MIT",
   "main": "pipeline.js",
   "bin": {
@@ -62,4 +62,4 @@
     "playwright": "^1.48.0",
     "sharp": "^0.33.5"
   }
-}
+}

package/pipeline.js

@@ -44,15 +44,16 @@ function embedRecipe(videoIn, videoOut, recipe) {
   });
 }
 
-async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, speed = 1, narrate = true, keepFrames = false, onStatus = () => {} }) {
+async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, speed = 1, ttsCmd = null, narrate = true, keepFrames = false, onStatus = () => {} }) {
   // Steps mode: synthesize narration BEFORE recording so segment pacing and
   // caption lifetimes match the spoken clip durations exactly.
   let prepared = null;
   if (steps && narrate) {
-    const texts = steps.filter(s => s.narration).map(s => s.narration);
-    if (texts.length) {
+    const items = steps.filter(s => s.narration)
+      .map(s => ({ text: s.narration, voice: s.voice, audio: s.audio }));
+    if (items.length) {
       try {
-        prepared = await prepareNarration(texts, path.join(workDir, 'tts'), voice, onStatus, speed);
+        prepared = await prepareNarration(items, path.join(workDir, 'tts'), voice, onStatus, speed, ttsCmd);
         let i = 0;
         for (const s of steps) if (s.narration) s._narrDurMs = prepared.clips[i++].durMs;
       } catch (e) {
@@ -69,7 +70,7 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
   await render(meta, raw, { onStatus });
 
   let narration = { narrated: false };
-  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, prepared, onStatus });
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, ttsCmd, prepared, onStatus });
   else fs.copyFileSync(raw, narrated);
 
   const recipe = buildRecipe({ url, mode, steps, meta });
@@ -88,7 +89,7 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
 
 // Re-produce the video from frames already on disk: no browser, no re-driving
 // the page. Used to swap the narration voice or speed after the fact.
-async function rerender(workDir, { voice = null, speed = 1, narrate = true, onStatus = () => {} } = {}) {
+async function rerender(workDir, { voice = null, speed = 1, ttsCmd = null, narrate = true, onStatus = () => {} } = {}) {
   const metaPath = path.join(workDir, 'meta.json');
   if (!fs.existsSync(metaPath)) throw new Error(`no meta.json in ${workDir}`);
   const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
@@ -102,7 +103,7 @@ async function rerender(workDir, { voice = null, speed = 1, narrate = true, onSt
   await render(meta, raw, { onStatus });
 
   let narration = { narrated: false };
-  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, onStatus });
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, ttsCmd, onStatus });
   else fs.copyFileSync(raw, narrated);
 
   const recipe = JSON.parse(fs.readFileSync(path.join(workDir, 'recipe.json'), 'utf8'));

package/recorder.js

@@ -40,8 +40,11 @@ class Timeline {
     this.zoom = 1;
     this.center = null;
   }
-  recordSegment(caption, narration, dur = null) {
-    this.segments.push({ t: Date.now(), caption: caption || null, narration: narration || null, dur });
+  recordSegment(caption, narration, dur = null, voice = null, audio = null) {
+    this.segments.push({
+      t: Date.now(), caption: caption || null, narration: narration || null, dur,
+      ...(voice ? { voice } : {}), ...(audio ? { audio } : {}),
+    });
   }
   recordMove(to, dur) {
     this.moves.push({ t: Date.now(), from: { ...this.pos }, to: { ...to }, dur });

package/scripts/tts-cmd-fixture.js

@@ -0,0 +1,10 @@
+// CI fixture: a stand-in "external TTS engine". Writes a short tone to {out}
+// so the --tts-cmd plumbing can be exercised on every platform, including
+// ones with no system voices installed.
+const { execFileSync } = require('child_process');
+const ffmpeg = require('ffmpeg-static');
+const out = process.argv[2];
+const text = process.argv.slice(3).join(' ');
+const seconds = Math.max(1, Math.min(8, text.split(/\s+/).length / 3)).toFixed(2);
+execFileSync(ffmpeg, ['-y', '-f', 'lavfi', '-i', `sine=frequency=340:duration=${seconds}`, '-ac', '1', out], { stdio: 'pipe' });
+console.log(`fixture wrote ${seconds}s to ${out}`);

package/skills/voila/SKILL.md

@@ -64,7 +64,14 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
   for them in chat.
 - Prefer `zoom` with a `selector` over a bare `level`: voila measures the
   element and picks the level and camera centre, so nothing is cropped.
-- Voices: `voila voices` lists 28 English voices with quality grades. af_heart
+- Languages: narration voice is per step, so demos can mix languages. Kokoro
+  is ENGLISH ONLY (af_heart A, af_bella A-, bf_emma British). For other
+  languages use a macOS system voice (`voice: "say:Monica"`, `voila voices
+  --all` lists ~180 across ~50 languages), or `--tts-cmd` with any engine on
+  any platform (placeholders {out} {text} {voice}), or point a step at a
+  ready-made clip with `audio: file.mp3`. On Linux/Windows non-English needs
+  --tts-cmd: tell the user rather than silently narrating in English.
+- Voices: `voila voices` lists the English voices with quality grades. af_heart
   (A) default, af_bella (A-), af_nicole (B-), bf_emma (B-, British). `--speed`
   or the speed param (0.5-1.6) changes pace; 0.9 reads calmer.
 - A failing step is retried once automatically; warnings appear in the result.

package/tour.js

@@ -242,7 +242,7 @@ async function runSteps(page, tl, steps, opts) {
     const step = steps[si];
     if (step.caption || step.narration) {
       await finishSegment();
-      tl.recordSegment(step.caption, step.narration, step._narrDurMs || null);
+      tl.recordSegment(step.caption, step.narration, step._narrDurMs || null, step.voice || null, step.audio || null);
       segStart = Date.now();
       segMinMs = (step._narrDurMs || 0) + 600;
     }

package/voices.js

@@ -55,4 +55,52 @@ function format() {
   return lines.join('\n');
 }
 
-module.exports = { allVoices, ranked, isValid, suggest, format };
+// --- system voices (macOS `say`) ---------------------------------------------
+// Kokoro is English-only in JS (its other voice files ship without a
+// grapheme-to-phoneme stage for those languages). Every Mac already carries
+// ~180 voices across ~50 languages, so those cover non-English narration.
+
+let sysCache = null;
+function systemVoices() {
+  if (sysCache) return sysCache;
+  sysCache = [];
+  if (process.platform !== 'darwin') return sysCache;
+  try {
+    const { execFileSync } = require('child_process');
+    const out = String(execFileSync('say', ['-v', '?'], { maxBuffer: 4e6 }));
+    for (const line of out.split('\n')) {
+      const m = /^(.+?)\s{2,}([a-z]{2}_[A-Z]{2})\s/.exec(line);
+      if (m) sysCache.push({ id: `say:${m[1].trim()}`, name: m[1].trim(), language: m[2].replace('_', '-'), gender: '', grade: 'system' });
+    }
+  } catch { /* no say binary */ }
+  return sysCache;
+}
+
+function systemLanguages() {
+  const langs = {};
+  for (const v of systemVoices()) (langs[v.language] = langs[v.language] || []).push(v.name);
+  return langs;
+}
+
+function isSystemVoice(id) {
+  if (!id) return false;
+  const name = String(id).replace(/^say:/, '').toLowerCase();
+  return systemVoices().some(v => v.name.toLowerCase() === name);
+}
+
+function formatAll() {
+  const lines = [format()];
+  const langs = systemLanguages();
+  const codes = Object.keys(langs).sort();
+  if (!codes.length) {
+    lines.push('\nSystem voices: none found (macOS only). For other languages use --tts-cmd.');
+    return lines.join('\n');
+  }
+  lines.push(`\nSystem voices (macOS, ${systemVoices().length} across ${codes.length} languages)`);
+  for (const c of codes) lines.push(`  ${c.padEnd(7)} ${langs[c].slice(0, 6).join(', ')}${langs[c].length > 6 ? ` +${langs[c].length - 6}` : ''}`);
+  lines.push('\nUse a system voice for non-English narration:  --voice "say:Monica"');
+  lines.push('Any other engine:  --tts-cmd \'piper --model es.onnx -f {out} -- "{text}"\'');
+  return lines.join('\n');
+}
+
+module.exports = { allVoices, ranked, isValid, suggest, format, formatAll, systemVoices, systemLanguages, isSystemVoice };