voxflow 1.17.2 → 1.18.0

package/lib/commands/card-render.js

@@ -413,6 +413,23 @@ async function cardRender(opts) {
   const clipPaths = [];
   let totalQuota = 0;
 
+  // Timeline tracking: each clip we render has a known duration; we accumulate
+  // them so the final timeline.json maps absolute output-mp4 offsets to cards.
+  // Downstream tools (e.g. `voxflow card subtitle`) use this to allocate
+  // per-sentence captions without re-running silencedetect.
+  let cumulativeMs = 0;
+  const timeline = {
+    title,
+    ratio,
+    language: deck.meta?.language || null,
+    voice: noAudio ? null : voice,
+    speed: noAudio ? null : speed,
+    intro: null,
+    cards: [],
+    outro: null,
+    totalDurationMs: 0,
+  };
+
   try {
     // ── Intro card (only if drawtext available — otherwise it's just a blank dark frame) ──
     if (!noIntro && title && hasDrawtext) {
@@ -425,6 +442,9 @@ async function cardRender(opts) {
         isFirst: true, isLast: false, hasDrawtext, cjkFontPath,
       });
       clipPaths.push(introPath);
+      const introMs = Math.round(introDuration * 1000);
+      timeline.intro = { start: cumulativeMs, end: cumulativeMs + introMs };
+      cumulativeMs += introMs;
     }
 
     // ── Per-card clips ──────────────────────────────────────────────────────
@@ -467,6 +487,16 @@ async function cardRender(opts) {
         subtitle: noSubtitle ? null : (card.narration || card.title || null),
       });
       clipPaths.push(clipOut);
+      const cardStart = cumulativeMs;
+      const cardEnd = cumulativeMs + durationMs;
+      timeline.cards.push({
+        file: card.file,
+        title: card.title || null,
+        narration: card.narration || null,
+        start: cardStart,
+        end: cardEnd,
+      });
+      cumulativeMs = cardEnd;
     }
 
     // ── Outro card (only if drawtext available) ───────────────────────────
@@ -482,7 +512,11 @@ async function cardRender(opts) {
         isFirst: false, isLast: true, hasDrawtext, cjkFontPath,
       });
       clipPaths.push(outroPath);
+      const outroMs = Math.round(outroDuration * 1000);
+      timeline.outro = { start: cumulativeMs, end: cumulativeMs + outroMs };
+      cumulativeMs += outroMs;
     }
+    timeline.totalDurationMs = cumulativeMs;
 
     // ── Concat ──────────────────────────────────────────────────────────────
     const slug = (title
@@ -511,10 +545,17 @@ async function cardRender(opts) {
     console.log(`Output: ${outputPath}`);
     if (totalQuota > 0) console.log(`Quota used: ${totalQuota}`);
 
+    // Write timeline.json next to the deck so downstream tools (e.g.
+    // `voxflow card subtitle`) can map output offsets back to per-card
+    // narration windows without re-running silencedetect.
+    const timelinePath = path.join(dir, 'timeline.json');
+    timeline.output = path.basename(outputPath);
+    fs.writeFileSync(timelinePath, JSON.stringify(timeline, null, 2) + '\n');
+
     // Success — clean up work directory
     fs.rmSync(workDir, { recursive: true, force: true });
 
-    return { outputPath, cardCount: cards.length, quotaUsed: totalQuota };
+    return { outputPath, cardCount: cards.length, quotaUsed: totalQuota, timelinePath, timeline };
   } catch (err) {
     // Failure — keep work directory for debugging
     if (fs.existsSync(workDir)) {

package/lib/commands/card-subtitle.js

@@ -0,0 +1,497 @@
+/**
+ * VoxFlow CLI — card subtitle subcommand
+ *
+ * Burns per-sentence synchronised subtitles into a previously rendered
+ * `voxflow card render` MP4. Replaces the original mp4 atomically; original
+ * is preserved as `<name>-no-subs.mp4` so iteration is non-destructive.
+ *
+ * Sources of timing truth (in priority order):
+ *   1. <dir>/timeline.json           (emitted by `card render` since 1.18.0)
+ *   2. ffmpeg silencedetect fallback (~2.5s pauses ≈ card boundaries)
+ *
+ * Per-card flow:
+ *   1. Window = [card.start, card.end] from timeline (or detected silences).
+ *   2. Split narration on CJK + ASCII sentence enders: 。！？!?.…— ; , 、
+ *   3. Allocate each sentence a slice proportional to char count.
+ *   4. Manual line-wrap every ≤ MAX_LINE_CHARS (CJK has no auto-wrap in
+ *      ffmpeg's `subtitles=` filter — must inject `\n` ourselves).
+ *   5. Write SRT, then ffmpeg subtitles= filter with ASS force_style.
+ *
+ * ASS coordinate system note: PlayResY defaults to 288, NOT 1920. So the
+ * "small" font/margin numbers in DEFAULT_STYLE are correct — they are
+ * scaled to whatever vertical resolution the source video uses.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+
+const { parseFlag } = require('../core/args');
+const { runCommand, checkFfmpeg } = require('../core/ffmpeg');
+
+// ── ffmpeg binary capability probe ────────────────────────────────────────────
+
+/**
+ * Find an ffmpeg binary that has the `subtitles` filter (i.e. is built with
+ * libass). Many minimal builds — notably Homebrew's default `ffmpeg` formula
+ * on macOS — ship without libass; the `subtitles=` filter then fails to even
+ * parse, with a misleading "Error parsing filterchain" message.
+ *
+ * Strategy:
+ *   1. Probe whatever the core ffmpeg helper resolves (system ffmpeg first).
+ *   2. If that binary lacks the `subtitles` filter, fall back to the bundled
+ *      `ffmpeg-static` package, which is built with libass.
+ *
+ * Returns: { binary: string, source: 'system'|'ffmpeg-static' } or throws
+ * with a helpful message when neither path has libass.
+ */
+function probeSubtitlesCapableFfmpeg() {
+  return new Promise((resolve, reject) => {
+    const tryBinary = (binary, source, onFail) => {
+      execFile(binary, ['-hide_banner', '-filters'], (err, stdout) => {
+        if (err) return onFail();
+        if (/\bsubtitles\b/.test(stdout || '')) {
+          resolve({ binary, source });
+        } else {
+          onFail();
+        }
+      });
+    };
+
+    // 1. System ffmpeg via PATH (or whatever core/ffmpeg.js already resolved)
+    tryBinary('ffmpeg', 'system', () => {
+      // 2. Bundled ffmpeg-static
+      let staticPath = null;
+      try { staticPath = require('ffmpeg-static'); } catch { /* not installed */ }
+      if (!staticPath || !fs.existsSync(staticPath)) {
+        return reject(new Error(
+          'No ffmpeg with libass / `subtitles` filter found.\n' +
+          '  System ffmpeg lacks libass (e.g. Homebrew default formula).\n' +
+          '  Install ffmpeg-static: `npm install ffmpeg-static` (any project),\n' +
+          '  or rebuild ffmpeg with --enable-libass.',
+        ));
+      }
+      tryBinary(staticPath, 'ffmpeg-static', () => {
+        reject(new Error(
+          `ffmpeg-static at ${staticPath} also lacks libass. Reinstall ffmpeg-static.`,
+        ));
+      });
+    });
+  });
+}
+
+/**
+ * Run a specific ffmpeg binary directly (bypassing core/ffmpeg's resolveFfmpegBin
+ * cache, which prefers system ffmpeg). Used by the subtitle burn step when the
+ * system binary lacks libass and we have to force ffmpeg-static.
+ */
+function runSpecificFfmpeg(binary, args) {
+  return new Promise((resolve, reject) => {
+    execFile(binary, args, { timeout: 600_000 }, (err, stdout, stderr) => {
+      if (err) {
+        err.stderr = stderr;
+        err.stdout = stdout;
+        return reject(err);
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const MAX_LINE_CHARS = 16;        // CJK characters per visual line
+const PUNCT_BIAS = 4;             // last N chars: prefer to break after a punct
+const SENTENCE_SPLIT_RE = /[^。！？!?.…—]+[。！？!?.…—]?/g;
+const PUNCT_BREAK_RE = /[，,、；;：:—]/;
+const MIN_SENTENCE_DURATION_MS = 600;
+
+// ASS PlayResY=288 default — these "small" numbers map to ~14% of frame height.
+// FontSize=8, MarginV=14 gives a clean bottom-third caption strip on 1080×1920.
+const DEFAULT_STYLE = (
+  'FontName=PingFang SC,FontSize=8,' +
+  'PrimaryColour=&HFFFFFF&,OutlineColour=&H000000&,BackColour=&HC0000000&,' +
+  'BorderStyle=3,Outline=2,Shadow=0,' +
+  'MarginV=14,MarginL=24,MarginR=24,Alignment=2,Bold=1'
+);
+
+// ── Sentence splitting & wrapping ────────────────────────────────────────────
+
+/**
+ * Split narration into sentences. Falls back to the whole text when no
+ * punctuation exists (single short narration).
+ */
+function splitSentences(text) {
+  const cleaned = text.replace(/\s+/g, '');
+  const matches = cleaned.match(SENTENCE_SPLIT_RE);
+  const sentences = matches ? matches.map((s) => s.trim()).filter(Boolean) : [cleaned];
+  return sentences.length > 0 ? sentences : [cleaned];
+}
+
+/**
+ * Wrap a CJK sentence into at most maxChars per line. Prefers to break after
+ * comma/semicolon/em-dash when within the last PUNCT_BIAS chars of a line —
+ * keeps phrasing intact rather than slicing mid-word.
+ */
+function wrapText(s, maxChars = MAX_LINE_CHARS) {
+  if (s.length <= maxChars) return s;
+  const lines = [];
+  let cur = '';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    cur += ch;
+    const isPunct = PUNCT_BREAK_RE.test(ch);
+    if (cur.length >= maxChars) {
+      lines.push(cur);
+      cur = '';
+    } else if (cur.length >= maxChars - PUNCT_BIAS && isPunct) {
+      lines.push(cur);
+      cur = '';
+    }
+  }
+  if (cur) lines.push(cur);
+  return lines.join('\n');
+}
+
+// ── SRT formatting ────────────────────────────────────────────────────────────
+
+function pad(n) { return String(n).padStart(2, '0'); }
+function pad3(n) { return String(n).padStart(3, '0'); }
+
+function fmtTime(seconds) {
+  const t = Math.max(0, seconds);
+  const h = Math.floor(t / 3600);
+  const m = Math.floor((t % 3600) / 60);
+  const s = Math.floor(t % 60);
+  const ms = Math.floor((t - Math.floor(t)) * 1000);
+  return `${pad(h)}:${pad(m)}:${pad(s)},${pad3(ms)}`;
+}
+
+/**
+ * Allocate per-sentence time slices proportional to char count, then format
+ * each into a numbered SRT cue with manual line wraps.
+ */
+function buildCuesForCard({ narration, startMs, endMs, startIndex }) {
+  const sentences = splitSentences(narration);
+  const totalChars = sentences.reduce((sum, s) => sum + s.length, 0) || 1;
+  const winDur = Math.max(0, endMs - startMs);
+
+  let cursor = startMs;
+  const cues = [];
+  for (let j = 0; j < sentences.length; j++) {
+    const s = sentences[j];
+    const isLast = j === sentences.length - 1;
+    let sStart = cursor;
+    let sEnd = isLast
+      ? endMs
+      : cursor + Math.max(MIN_SENTENCE_DURATION_MS, Math.round((s.length / totalChars) * winDur));
+    if (sEnd > endMs) sEnd = endMs;
+    if (sEnd <= sStart) sEnd = sStart + MIN_SENTENCE_DURATION_MS;
+    cursor = sEnd;
+    const wrapped = wrapText(s, MAX_LINE_CHARS);
+    cues.push({
+      index: startIndex + j,
+      start: sStart / 1000,
+      end: sEnd / 1000,
+      text: wrapped,
+    });
+  }
+  return cues;
+}
+
+function formatSrt(cues) {
+  return cues
+    .map((c) => `${c.index}\n${fmtTime(c.start)} --> ${fmtTime(c.end)}\n${c.text}\n`)
+    .join('\n');
+}
+
+// ── Timeline + silence detection ─────────────────────────────────────────────
+
+async function probeDurationSec(mp4) {
+  const { stdout } = await runCommand('ffprobe', [
+    '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', mp4,
+  ]);
+  const dur = parseFloat(stdout.trim());
+  if (!Number.isFinite(dur)) throw new Error(`Could not probe duration of ${mp4}`);
+  return dur;
+}
+
+async function detectSilences(mp4, { dB = -30, minSec = 2.0 } = {}) {
+  // silencedetect emits to stderr, not stdout. runCommand doesn't capture stderr
+  // separately, but on success ffmpeg prints to stderr and runCommand returns it
+  // bundled. We invoke directly through the ffmpeg path via runCommand which
+  // returns { stdout, stderr } on the version in core/ffmpeg.js.
+  const result = await runCommand('ffmpeg', [
+    '-i', mp4, '-af', `silencedetect=n=${dB}dB:d=${minSec}`, '-f', 'null', '-',
+  ]).catch((err) => err); // silencedetect path always exits 0; defensive
+  const stderr = (result && result.stderr) || '';
+  const silences = [];
+  let cur = null;
+  for (const line of stderr.split('\n')) {
+    let m;
+    if ((m = line.match(/silence_start:\s*([\d.]+)/))) cur = { start: parseFloat(m[1]) };
+    else if ((m = line.match(/silence_end:\s*([\d.]+)/)) && cur) {
+      cur.end = parseFloat(m[1]);
+      silences.push(cur);
+      cur = null;
+    }
+  }
+  return silences;
+}
+
+/**
+ * Build per-card narration windows (in ms) by either reading timeline.json
+ * directly or, when absent, falling back to silencedetect on the mp4.
+ */
+async function buildWindows({ deck, timelinePath, mp4Path }) {
+  if (timelinePath && fs.existsSync(timelinePath)) {
+    const timeline = JSON.parse(fs.readFileSync(timelinePath, 'utf8'));
+    const cards = timeline.cards || [];
+    if (cards.length !== deck.cards.length) {
+      throw new Error(
+        `timeline.json has ${cards.length} cards but deck.json has ${deck.cards.length}. ` +
+        `Re-run \`voxflow card render\` to regenerate.`,
+      );
+    }
+    return {
+      source: 'timeline',
+      windows: cards.map((c) => ({ start: c.start, end: c.end, narration: c.narration })),
+    };
+  }
+
+  // Fallback: silencedetect heuristic
+  const totalSec = await probeDurationSec(mp4Path);
+  const silences = await detectSilences(mp4Path);
+  if (silences.length < deck.cards.length - 1) {
+    throw new Error(
+      `silencedetect found ${silences.length} pauses but expected ≥ ${deck.cards.length - 1}. ` +
+      `Re-render with \`voxflow card render\` to emit timeline.json instead.`,
+    );
+  }
+  const windows = deck.cards.map((card, i) => {
+    const start = i === 0 ? 0 : silences[i - 1].end;
+    const end = i < silences.length ? silences[i].start : totalSec;
+    return {
+      start: Math.round(start * 1000),
+      end: Math.round(end * 1000),
+      narration: card.narration || '',
+    };
+  });
+  return { source: 'silencedetect', windows };
+}
+
+// ── Main pipeline ─────────────────────────────────────────────────────────────
+
+function readDeck(dir) {
+  const p = path.join(dir, 'deck.json');
+  if (!fs.existsSync(p)) {
+    throw new Error(`No deck.json found in ${dir}.`);
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function findSourceMp4(dir, override) {
+  if (override) {
+    if (!fs.existsSync(override)) throw new Error(`--input mp4 not found: ${override}`);
+    return path.resolve(override);
+  }
+  const entries = fs.readdirSync(dir);
+  // Skip prior `-no-subs.mp4` backups so re-running the command idempotently
+  // re-burns from the same source.
+  const candidates = entries.filter((f) => f.endsWith('.mp4') && !f.endsWith('-no-subs.mp4'));
+  if (candidates.length === 0) {
+    throw new Error(
+      `No source .mp4 in ${dir}. Run \`voxflow card render <dir>\` first.`,
+    );
+  }
+  if (candidates.length > 1) {
+    throw new Error(
+      `Multiple .mp4 in ${dir}: ${candidates.join(', ')}. Pass --input <file> to disambiguate.`,
+    );
+  }
+  return path.join(dir, candidates[0]);
+}
+
+/**
+ * Escape a path for use as the VALUE of `subtitles='...'` in an ffmpeg -vf
+ * argument. The filter parser strips one level of quoting, so single quotes
+ * and colons inside the path need backslash escapes.
+ */
+function escapeSubsPath(p) {
+  return p.replace(/\\/g, '/').replace(/'/g, "\\'").replace(/:/g, '\\:');
+}
+
+async function cardSubtitle(opts) {
+  const { dir, input, output, style: styleOverride, dryRun = false } = opts;
+
+  const ffmpegInfo = await checkFfmpeg();
+  if (!ffmpegInfo.available) {
+    throw new Error(
+      'ffmpeg not found. Install: brew install ffmpeg (macOS) / sudo apt install ffmpeg (Linux)',
+    );
+  }
+  if (ffmpegInfo.source === 'ffmpeg-static') {
+    let pkgVersion = '';
+    try { pkgVersion = require('ffmpeg-static/package.json').version; } catch { /* unknown */ }
+    console.log(`  (using ffmpeg-static${pkgVersion ? ` v${pkgVersion}` : ''} — ffmpeg ${ffmpegInfo.version})`);
+  }
+
+  const deck = readDeck(dir);
+  const mp4Path = findSourceMp4(dir, input);
+  const timelinePath = path.join(dir, 'timeline.json');
+
+  console.log(`\n=== VoxFlow Card Subtitle ===`);
+  console.log(`Source : ${path.relative(process.cwd(), mp4Path)}`);
+  console.log(`Cards  : ${deck.cards.length}`);
+
+  const { source, windows } = await buildWindows({ deck, timelinePath, mp4Path });
+  console.log(`Timing : ${source}${source === 'timeline' ? ` (${path.basename(timelinePath)})` : ' (silencedetect fallback)'}`);
+
+  // Build cues
+  const cues = [];
+  let cueIndex = 1;
+  for (let i = 0; i < deck.cards.length; i++) {
+    const win = windows[i];
+    if (!win.narration) continue;
+    const cardCues = buildCuesForCard({
+      narration: win.narration,
+      startMs: win.start,
+      endMs: win.end,
+      startIndex: cueIndex,
+    });
+    cueIndex += cardCues.length;
+    cues.push(...cardCues);
+  }
+
+  if (cues.length === 0) {
+    throw new Error('No narration text to subtitle. All cards have empty `narration`.');
+  }
+
+  const srtPath = path.join(dir, 'subs.srt');
+  fs.writeFileSync(srtPath, formatSrt(cues));
+  console.log(`SRT    : ${cues.length} cues → ${path.relative(process.cwd(), srtPath)}`);
+
+  if (dryRun) {
+    console.log(`\n--dry-run: stopped before ffmpeg burn-in. Edit ${path.basename(srtPath)} and re-run without --dry-run to bake.`);
+    return { cues: cues.length, srtPath, source };
+  }
+
+  // ── Burn into mp4 ──────────────────────────────────────────────────────────
+  const subbedTmp = mp4Path.replace(/\.mp4$/i, '-subbed.mp4');
+  const noSubsBackup = mp4Path.replace(/\.mp4$/i, '-no-subs.mp4');
+  const finalOut = output ? path.resolve(output) : mp4Path;
+
+  const ratioWidth = 1080;  // PlayResY hint — most card decks are 1080×1920
+  const ratioHeight = 1920;
+  const style = styleOverride || DEFAULT_STYLE;
+  const escSrt = escapeSubsPath(srtPath);
+
+  console.log(`\n  Burning subs (FontSize / MarginV via ASS PlayResY=288 default)...`);
+  const vfArg = `subtitles='${escSrt}':original_size=${ratioWidth}x${ratioHeight}:force_style='${style}'`;
+  if (process.env.VOXFLOW_DEBUG_SUBS) {
+    console.error('[DEBUG vf]', JSON.stringify(vfArg));
+  }
+
+  // The `subtitles=` filter requires libass. Many minimal ffmpeg builds
+  // (notably Homebrew's default formula on macOS) ship without it and fail
+  // at filtergraph parse time with a misleading "Error parsing filterchain"
+  // message. Probe both system ffmpeg and ffmpeg-static; pick the one that
+  // actually has the filter.
+  const { binary: ffmpegBin, source: ffmpegSource } = await probeSubtitlesCapableFfmpeg();
+  if (ffmpegSource === 'ffmpeg-static') {
+    console.log(`  (system ffmpeg lacks libass — using bundled ffmpeg-static)`);
+  }
+
+  await runSpecificFfmpeg(ffmpegBin, [
+    '-i', mp4Path,
+    '-vf', vfArg,
+    '-c:a', 'copy',
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', '20',
+    '-movflags', '+faststart',
+    '-y', subbedTmp,
+  ]);
+
+  if (finalOut === mp4Path) {
+    // In-place replace: keep the original as -no-subs backup.
+    if (!fs.existsSync(noSubsBackup)) {
+      fs.renameSync(mp4Path, noSubsBackup);
+    } else {
+      // backup already exists from a previous run — just overwrite the head.
+      fs.unlinkSync(mp4Path);
+    }
+    fs.renameSync(subbedTmp, finalOut);
+    console.log(`\n=== Done ===`);
+    console.log(`Output : ${path.relative(process.cwd(), finalOut)} (original kept as ${path.basename(noSubsBackup)})`);
+  } else {
+    fs.renameSync(subbedTmp, finalOut);
+    console.log(`\n=== Done ===`);
+    console.log(`Output : ${path.relative(process.cwd(), finalOut)}`);
+  }
+
+  return { cues: cues.length, srtPath, source, output: finalOut };
+}
+
+// ── CLI handler ───────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`Usage: voxflow card subtitle <dir> [options]
+
+Burn per-sentence synced subtitles into a card-render MP4. Reads
+<dir>/timeline.json (preferred) or falls back to ffmpeg silencedetect.
+The original mp4 is preserved as <name>-no-subs.mp4.
+
+Options:
+  <dir>               Card output directory (must contain deck.json + .mp4)
+
+  --input <path>      Override source mp4 (default: the only .mp4 in <dir>
+                      that doesn't end with -no-subs.mp4).
+  -o, --output <path> Write output here instead of replacing the source.
+  --style <ass>       Override ASS force_style string (advanced).
+  --dry-run           Write subs.srt but skip ffmpeg burn-in.
+
+Examples:
+  voxflow card subtitle cards/why-no-savings/
+  voxflow card subtitle cards/why-no-savings/ --dry-run    # inspect SRT first
+  voxflow card subtitle cards/why-no-savings/ -o subbed.mp4`);
+    return;
+  }
+
+  const valuedFlags = new Set(['--input', '--output', '-o', '--style']);
+  let dir;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('-')) { if (valuedFlags.has(args[i])) i++; continue; }
+    dir = args[i]; break;
+  }
+  if (!dir) { console.error('Error: provide the card output directory'); process.exit(1); }
+
+  const input = parseFlag(args, '--input');
+  const output = parseFlag(args, '--output', '-o');
+  const style = parseFlag(args, '--style');
+  const dryRun = args.includes('--dry-run');
+
+  await cardSubtitle({
+    dir: path.resolve(dir),
+    input: input ? path.resolve(input) : undefined,
+    output: output || undefined,
+    style: style || undefined,
+    dryRun,
+  });
+}
+
+module.exports = {
+  cardSubtitle,
+  splitSentences,
+  wrapText,
+  fmtTime,
+  buildCuesForCard,
+  formatSrt,
+  buildWindows,
+  escapeSubsPath,
+  probeSubtitlesCapableFfmpeg,
+  DEFAULT_STYLE,
+  MAX_LINE_CHARS,
+  handle,
+};

package/lib/commands/card.js

@@ -1,55 +1,76 @@
 /**
  * VoxFlow CLI — card command
  *
- * Dispatches `voxflow card render <dir>` to card-render.js.
+ * Dispatches:
+ *   - `voxflow card render <dir>`   → card-render.js  (deck → narrated MP4)
+ *   - `voxflow card subtitle <dir>` → card-subtitle.js (MP4 → +synced subs)
+ *
  * The card *generation* workflow lives in cli/skills/card/SKILL.md —
- * Claude Code calls render-cards.mjs directly. This command handles the
- * post-generation video render step which needs API auth (TTS quota).
+ * Claude Code calls render-cards.mjs directly. These commands handle the
+ * post-generation video render + subtitle steps which need API auth /
+ * ffmpeg-static fallback / timeline.json plumbing.
  */
 
 'use strict';
 
 async function handle(args) {
-  if (args.length > 0 && args[0] === 'render') {
-    const cardRender = require('./card-render');
-    return cardRender.handle(args.slice(1));
+  if (args.length > 0) {
+    if (args[0] === 'render') {
+      const cardRender = require('./card-render');
+      return cardRender.handle(args.slice(1));
+    }
+    if (args[0] === 'subtitle' || args[0] === 'subtitles' || args[0] === 'subs') {
+      const cardSubtitle = require('./card-subtitle');
+      return cardSubtitle.handle(args.slice(1));
+    }
   }
 
   // Default: usage
   console.log(`Usage:
-  voxflow card render <dir>   Render card directory → narrated MP4 video
+  voxflow card render <dir>     Render card directory → narrated MP4 video
+  voxflow card subtitle <dir>   Burn per-sentence synced subs into the rendered MP4
 
 Subcommands:
   render     Synthesize TTS narration + render Ken Burns video from card PNGs
+             (emits timeline.json next to deck.json — used by \`subtitle\`)
+  subtitle   Read deck.json + timeline.json, allocate per-sentence cues by
+             char count, and burn subtitles into the source mp4 in-place.
+             Original kept as <name>-no-subs.mp4. Aliases: subs / subtitles.
 
-See: voxflow card render --help`);
+See: voxflow card render --help
+     voxflow card subtitle --help`);
 }
 
 const meta = {
   card: {
-    usage: 'render <dir> [options]',
-    description: 'Card video export: narrated MP4 with subtitles, intro/outro, and BGM from a card-skill output directory',
+    usage: '<subcommand> <dir> [options]',
+    description: 'Card video pipeline: deck.json + PNGs → narrated MP4 (`render`) → synced sentence-level subtitles (`subtitle`).',
     options: [
       'render <dir>           Render deck.json + PNGs → narrated MP4 video',
-      '--voice <id>           TTS voice ID (default: v-female-R2s4N9qJ)',
-      '--speed <n>            TTS speed, 0.5-2.0 (default: 1.0)',
-      '--no-audio             Silent video — skip TTS synthesis',
-      '--pause <sec>          Silence after narration (reading time, default: 2.5)',
-      '--hold <sec>           Card duration in --no-audio mode (default: 5)',
-      '--no-intro             Skip intro title card',
-      '--no-outro             Skip outro branding card',
-      '--intro-dur <sec>      Intro duration (default: 2.5)',
-      '--outro-dur <sec>      Outro duration (default: 2)',
-      '--no-subtitle          Disable subtitle overlay',
-      '--bgm <path>           Background music (loops at low volume)',
-      '--bgm-volume <n>       BGM volume, 0-1 (default: 0.08)',
-      '-o, --output <path>    Output MP4 path (default: <dir>/<title>.mp4)',
+      'subtitle <dir>         Burn per-sentence synced subs into the rendered MP4',
+      '--voice <id>           [render] TTS voice ID (default: v-female-R2s4N9qJ)',
+      '--speed <n>            [render] TTS speed, 0.5-2.0 (default: 1.0)',
+      '--no-audio             [render] Silent video — skip TTS synthesis',
+      '--pause <sec>          [render] Silence after narration (default: 2.5)',
+      '--hold <sec>           [render] Card duration in --no-audio mode (default: 5)',
+      '--no-intro             [render] Skip intro title card',
+      '--no-outro             [render] Skip outro branding card',
+      '--intro-dur <sec>      [render] Intro duration (default: 2.5)',
+      '--outro-dur <sec>      [render] Outro duration (default: 2)',
+      '--no-subtitle          [render] Disable in-render subtitle bar',
+      '--bgm <path>           [render] Background music (loops at low volume)',
+      '--bgm-volume <n>       [render] BGM volume, 0-1 (default: 0.08)',
+      '--input <path>         [subtitle] Override source mp4',
+      '--style <ass>          [subtitle] ASS force_style override (advanced)',
+      '--dry-run              [subtitle] Write subs.srt but skip ffmpeg burn-in',
+      '-o, --output <path>    Output MP4 path (default: <dir>/<title>.mp4 or in-place)',
     ],
     examples: [
       'voxflow card render cards/fermentation/',
-      'voxflow card render cards/fermentation/ --voice v-female-R2s4N9qJ -o out.mp4',
+      'voxflow card render cards/fermentation/ --no-intro --no-outro --no-subtitle',
+      'voxflow card subtitle cards/fermentation/',
+      'voxflow card subtitle cards/fermentation/ --dry-run',
       'voxflow card render cards/fermentation/ --bgm ~/music/ambient.mp3',
-      'voxflow card render cards/fermentation/ --no-audio --no-subtitle',
     ],
   },
 };