voxflow 1.16.0 → 1.17.1

package/lib/commands/_registry.js

@@ -25,6 +25,7 @@ module.exports = {
   asr: () => require('./asr'),
   'asr-jobs': () => require('./asr-jobs'),
   'auth-cmds': () => require('./auth-cmds'),
+  card: () => require('./card'),
   dub: () => require('./dub'),
   explain: () => require('./explain'),
   feedback: () => require('./feedback'),

package/lib/commands/card-render.js

@@ -0,0 +1,632 @@
+/**
+ * VoxFlow CLI — card render subcommand
+ *
+ * Renders a card-skill output directory into a polished narrated MP4:
+ *   1. Read deck.json (narration text per card)
+ *   2. Ensure PNGs exist
+ *   3. Synthesize TTS per card → WAV
+ *   4. Render per-card clip: PNG + subtle zoom + subtitle bar + fade
+ *   5. Render intro title card + outro branding card
+ *   6. Concat all clips (intro + cards + outro)
+ *   7. Mix background music (optional)
+ *
+ * Features:
+ *   - Subtle center zoom (2%) — content stays readable
+ *   - Bottom subtitle bar with narration text
+ *   - Auto intro card (series title) + outro card (branding)
+ *   - Crossfade via per-clip fade-in/fade-out
+ *   - Background music loop at low volume
+ *   - ffmpeg-static fallback (no system FFmpeg required)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseFlag, runWithRetry } = require('../core/args');
+const { getToken, getTokenInfo } = require('../core/auth');
+const { API_BASE } = require('../core/config');
+const { buildWav, createSilence, PCM_SAMPLE_RATE } = require('../core/audio');
+const { BYTES_PER_MS } = require('../core/timeline');
+const { synthesizeTTS } = require('../core/tts-synthesizer');
+const { runCommand, checkFfmpeg, concatVideos } = require('../core/ffmpeg');
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const RATIO_DIMS = {
+  '1:1': { w: 1080, h: 1080 },
+  '3:4': { w: 1080, h: 1440 },
+  '4:5': { w: 1080, h: 1350 },
+  '9:16': { w: 1080, h: 1920 },
+  '16:9': { w: 1920, h: 1080 },
+};
+
+// Subtitle styling
+const SUB_FONT_SIZE = 36;
+const SUB_BOX_OPACITY = 0.6;
+const SUB_MARGIN_BOTTOM = 80;
+const SUB_PADDING = 20;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function readDeckJson(dir) {
+  const p = path.join(dir, 'deck.json');
+  if (!fs.existsSync(p)) {
+    throw new Error(
+      `No deck.json found in ${dir}.\n` +
+      `  The card SKILL.md workflow must produce a deck.json alongside the HTML files.\n` +
+      `  See: cli/skills/card/SKILL.md — Step 9.`,
+    );
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function resolveCardPng(dir, cardFile) {
+  const base = path.basename(cardFile, path.extname(cardFile));
+  const candidates = [
+    path.join(dir, 'exports', `${base}.png`),
+    path.join(dir, `${base}.png`),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function writePcmAsWav(pcmBuffer, dest, trailingSilenceSec = 0) {
+  // Append silence to the PCM itself so the WAV's natural duration includes
+  // the post-narration "reading time" pause. Using `-shortest` in ffmpeg
+  // would otherwise truncate the clip back to the narration-only length.
+  const totalPcm = trailingSilenceSec > 0
+    ? Buffer.concat([pcmBuffer, createSilence(trailingSilenceSec, PCM_SAMPLE_RATE)])
+    : pcmBuffer;
+  const { wav } = buildWav([totalPcm], { silenceSec: 0 });
+  fs.writeFileSync(dest, wav);
+  return dest;
+}
+
+function pcmToDurationMs(buf) {
+  return Math.round(buf.length / BYTES_PER_MS);
+}
+
+/**
+ * Escape text for an FFmpeg drawtext `text='...'` value.
+ *
+ * FFmpeg filtergraph parsing has two layers of escaping:
+ *   1. The filter argument splitter (`,` and `;` separate filters/chains).
+ *   2. The drawtext text= value, single-quoted; `\` and `:` are special.
+ *
+ * For each special char we therefore emit `\\<char>` \u2014 a single literal
+ * backslash plus the char \u2014 so JS source `'\\\\'` (4 chars) = 2-char string `\\`,
+ * which ffmpeg parses as one literal backslash.
+ *
+ * Apostrophes inside a single-quoted text= value cannot be escaped reliably
+ * across ffmpeg versions, so we substitute the typographic right single quote
+ * (U+2019) which renders identically for human readers.
+ */
+function escapeDrawtext(text) {
+  return text
+    .replace(/\\/g, '\\\\')      // \  \u2192 \\  (one literal backslash)
+    .replace(/'/g, '\u2019')     // '  \u2192 \u2019   (avoid breaking the surrounding quotes)
+    .replace(/;/g, '\\;')        // ;  \u2192 \;  (filter chain separator)
+    .replace(/,/g, '\\,')        // ,  \u2192 \,  (filter argument separator)
+    .replace(/:/g, '\\:')        // :  \u2192 \:  (option separator inside drawtext)
+    .replace(/\[/g, '\\[')
+    .replace(/\]/g, '\\]')
+    .replace(/%/g, '%%')         // drawtext format-string escape
+    .replace(/\n/g, ' ');
+}
+
+/**
+ * Detect whether a string contains CJK characters that need a CJK fontfile.
+ * Covers Han (CJK Unified), Hiragana, Katakana, Hangul, and full-width punctuation.
+ */
+function containsCjk(text) {
+  if (!text) return false;
+  // U+3001–303F CJK symbols & punctuation (skip U+3000 IDEOGRAPHIC SPACE — eslint flags it)
+  // U+3040–30FF Hiragana + Katakana
+  // U+3400–9FFF CJK Ext A + CJK Unified
+  // U+AC00–D7AF Hangul; U+FF00–FFEF Halfwidth/Fullwidth forms
+  return /[、-ヿ㐀-鿿가-힯＀-￯]/.test(text);
+}
+
+/**
+ * Locate a fontfile that supports CJK glyphs on the host platform.
+ *
+ * ffmpeg's `drawtext` filter, when no `fontfile=` is given, falls back to a
+ * built-in default that ships only Latin-1. CJK content rendered without an
+ * explicit CJK fontfile shows as `□` tofu boxes (issue #3592).
+ *
+ * Returns an absolute path to a known CJK-capable font, or null if none of
+ * the platform-specific candidates exist. Cached for the process lifetime.
+ * Override the search via `VOXFLOW_CJK_FONT=/path/to/font.ttc`.
+ *
+ * @returns {string|null}
+ */
+let _cjkFontPathCache; // undefined = unknown, null = absent, string = found
+function findCjkFontFile() {
+  if (_cjkFontPathCache !== undefined) return _cjkFontPathCache;
+
+  // User override wins over platform autodetect
+  if (process.env.VOXFLOW_CJK_FONT && fs.existsSync(process.env.VOXFLOW_CJK_FONT)) {
+    _cjkFontPathCache = process.env.VOXFLOW_CJK_FONT;
+    return _cjkFontPathCache;
+  }
+
+  const candidates = [];
+  if (process.platform === 'darwin') {
+    candidates.push(
+      '/System/Library/Fonts/PingFang.ttc',
+      '/System/Library/Fonts/Hiragino Sans GB.ttc',
+      '/System/Library/Fonts/STHeiti Medium.ttc',
+      '/System/Library/Fonts/STHeiti Light.ttc',
+      '/Library/Fonts/Songti.ttc',
+    );
+  } else if (process.platform === 'linux') {
+    candidates.push(
+      '/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc',
+      '/usr/share/fonts/opentype/noto/NotoSansCJK.ttc',
+      '/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc',
+      '/usr/share/fonts/wqy-microhei/wqy-microhei.ttc',
+      '/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc',
+      '/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc',
+    );
+  } else if (process.platform === 'win32') {
+    candidates.push(
+      'C:/Windows/Fonts/msyh.ttc',
+      'C:/Windows/Fonts/msyhbd.ttc',
+      'C:/Windows/Fonts/simsun.ttc',
+      'C:/Windows/Fonts/yugothic.ttf',
+    );
+  }
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) {
+      _cjkFontPathCache = p;
+      return _cjkFontPathCache;
+    }
+  }
+  _cjkFontPathCache = null;
+  return null;
+}
+
+/**
+ * Build the drawtext fontfile= clause when the text contains CJK and a
+ * suitable font is available on the host. Returns either ":fontfile=…" (with
+ * leading colon, ready to splice into a drawtext arg list) or "" when no
+ * font override is needed (ASCII-only text or no CJK font on host).
+ */
+function drawtextFontfileClause(text, cjkFontPath) {
+  if (!text || !cjkFontPath) return '';
+  if (!containsCjk(text)) return '';
+  // ffmpeg fontfile= path needs `:` and `\` escaped inside a filter arg.
+  const escaped = cjkFontPath.replace(/\\/g, '/').replace(/:/g, '\\:');
+  return `:fontfile='${escaped}'`;
+}
+
+// ── Render functions ──────────────────────────────────────────────────────────
+
+/**
+ * Render a single card: PNG + optional WAV → MP4 clip with subtitle overlay.
+ */
+async function renderCardClip({ pngPath, wavPath, outPath, durationMs, ratio, subtitle, hasDrawtext = false, cjkFontPath = null }) {
+  const { w, h } = RATIO_DIMS[ratio] || RATIO_DIMS['9:16'];
+  const durationSec = Math.max(3, durationMs / 1000);
+
+  // No fade between clips — hard cut. Fade-to-black causes visible
+  // black frames at transitions since clips are concatenated, not overlaid.
+  const vfParts = [
+    `scale=${w}:${h}:force_original_aspect_ratio=increase`,
+    `crop=${w}:${h}`,
+  ];
+
+  // Subtitle bar overlay (only if drawtext is available — checked at pipeline level)
+  if (subtitle && hasDrawtext) {
+    const escaped = escapeDrawtext(subtitle);
+    const fontSize = Math.round(SUB_FONT_SIZE * (w / 1080));
+    const boxY = h - SUB_MARGIN_BOTTOM - fontSize - SUB_PADDING * 2;
+    const fontfile = drawtextFontfileClause(subtitle, cjkFontPath);
+    vfParts.push(
+      `drawtext=text='${escaped}'${fontfile}:fontsize=${fontSize}:fontcolor=white:` +
+      `x=(w-text_w)/2:y=${boxY + SUB_PADDING}:` +
+      `box=1:boxcolor=black@${SUB_BOX_OPACITY}:boxborderw=${SUB_PADDING}`,
+    );
+  }
+
+  vfParts.push('format=yuv420p');
+
+  const args = ['-loop', '1', '-t', String(durationSec + 0.1), '-i', path.resolve(pngPath)];
+
+  if (wavPath) {
+    args.push('-i', path.resolve(wavPath));
+    args.push('-vf', vfParts.join(','));
+    args.push(
+      '-c:v', 'libx264', '-preset', 'fast', '-crf', '22', '-bf', '0',
+      '-c:a', 'aac', '-b:a', '128k', '-ar', '24000', '-ac', '1',
+      '-shortest',
+    );
+  } else {
+    args.push(
+      '-f', 'lavfi', '-t', String(durationSec), '-i', 'anullsrc=channel_layout=mono:sample_rate=24000',
+      '-vf', vfParts.join(','),
+      '-c:v', 'libx264', '-preset', 'fast', '-crf', '22', '-bf', '0',
+      '-c:a', 'aac', '-b:a', '128k',
+      '-t', String(durationSec),
+      '-shortest',
+    );
+  }
+
+  args.push('-movflags', '+faststart', '-y', path.resolve(outPath));
+  await runCommand('ffmpeg', args);
+}
+
+/**
+ * Generate an intro or outro card via FFmpeg color source (simple solid + no text).
+ * Text overlay requires drawtext (libfreetype); if unavailable, renders a plain color card.
+ */
+async function renderTitleCard({ outPath, ratio, title, subtitle, durationSec = 3, bgColor = '1a1520', textColor = 'f4efe6', fadeSeconds = 0.4, isFirst = false, isLast = false, hasDrawtext = false, cjkFontPath = null }) {
+  const { w, h } = RATIO_DIMS[ratio] || RATIO_DIMS['9:16'];
+  const fd = fadeSeconds;
+
+  const titleSize = Math.round(72 * (w / 1080));
+  const subSize = Math.round(32 * (w / 1080));
+  const escapedTitle = escapeDrawtext(title || '');
+  const escapedSub = escapeDrawtext(subtitle || '');
+  const titleFontfile = drawtextFontfileClause(title, cjkFontPath);
+  const subFontfile = drawtextFontfileClause(subtitle, cjkFontPath);
+
+  const vfParts = [`color=c=0x${bgColor}:s=${w}x${h}:d=${durationSec}:r=30`];
+
+  if (hasDrawtext) {
+    if (escapedTitle) {
+      vfParts.push(
+        `drawtext=text='${escapedTitle}'${titleFontfile}:fontsize=${titleSize}:fontcolor=0x${textColor}:` +
+        `x=(w-text_w)/2:y=(h-text_h)/2-${Math.round(subSize * 1.5)}`,
+      );
+    }
+    if (escapedSub) {
+      vfParts.push(
+        `drawtext=text='${escapedSub}'${subFontfile}:fontsize=${subSize}:fontcolor=0x${textColor}@0.6:` +
+        `x=(w-text_w)/2:y=(h-text_h)/2+${Math.round(titleSize * 0.8)}`,
+      );
+    }
+  }
+
+  if (fd > 0) {
+    const fadeOutStart = (durationSec - fd).toFixed(3);
+    if (!isFirst) vfParts.push(`fade=t=in:st=0:d=${fd}`);
+    if (!isLast) vfParts.push(`fade=t=out:st=${fadeOutStart}:d=${fd}`);
+  }
+  vfParts.push('format=yuv420p');
+
+  const args = [
+    '-f', 'lavfi', '-i', vfParts.join(','),
+    '-f', 'lavfi', '-t', String(durationSec), '-i', 'anullsrc=channel_layout=mono:sample_rate=24000',
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', '22',
+    '-c:a', 'aac', '-b:a', '128k',
+    '-t', String(durationSec),
+    '-shortest',
+    '-movflags', '+faststart', '-y', path.resolve(outPath),
+  ];
+
+  await runCommand('ffmpeg', args);
+}
+
+/**
+ * Mix background music into a video at low volume.
+ */
+async function mixBgm(videoPath, bgmPath, outputPath, { volume = 0.08, fadeIn = 1.5 } = {}) {
+  await runCommand('ffmpeg', [
+    '-i', path.resolve(videoPath),
+    '-stream_loop', '-1',
+    '-i', path.resolve(bgmPath),
+    '-filter_complex',
+    `[1:a]volume=${volume},afade=t=in:st=0:d=${fadeIn}[bgm];[0:a][bgm]amix=inputs=2:duration=first:dropout_transition=2[out]`,
+    '-map', '0:v', '-map', '[out]',
+    '-c:v', 'copy', '-c:a', 'aac', '-b:a', '128k',
+    '-movflags', '+faststart', '-y', path.resolve(outputPath),
+  ]);
+}
+
+// ── Main pipeline ─────────────────────────────────────────────────────────────
+
+async function cardRender(opts) {
+  const {
+    token, api: apiBase, dir,
+    noAudio = false,
+    noSubtitle = false, noIntro = false, noOutro = false,
+    bgm, bgmVolume,
+    pause = 2.5,    // seconds of silence after narration ends (reading time)
+    hold = 5,       // seconds to hold each card when --no-audio (no narration)
+    introDuration = 2.5,
+    outroDuration = 2,
+  } = opts;
+  const voice = opts.voice || 'female-kefu-xiaoyue';
+  const speed = Number(opts.speed) || 1.0;
+
+  const deck = readDeckJson(dir);
+  const cards = deck.cards || [];
+  const ratio = deck.meta?.ratio || '9:16';
+  const title = deck.meta?.title || '';
+
+  if (cards.length === 0) throw new Error('deck.json has no cards array entries.');
+
+  console.log(`\n=== VoxFlow Card Render ===`);
+  console.log(`Cards: ${cards.length}  |  Ratio: ${ratio}  |  Audio: ${!noAudio}`);
+  if (!noAudio) console.log(`Voice: ${voice}  |  Speed: ${speed}`);
+  console.log(`Subtitle: ${!noSubtitle}  |  Intro: ${!noIntro}  |  Outro: ${!noOutro}`);
+  if (bgm) console.log(`BGM: ${path.basename(bgm)}`);
+
+  const ffmpegInfo = await checkFfmpeg();
+  if (!ffmpegInfo.available) {
+    throw new Error(
+      'ffmpeg not found. Install: brew install ffmpeg (macOS) / sudo apt install ffmpeg (Linux)\n' +
+      '  Or: npm install ffmpeg-static',
+    );
+  }
+  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})`);
+  }
+
+  // Check drawtext filter availability (needs libfreetype)
+  let hasDrawtext = false;
+  let cjkFontPath = null;
+  if (!noSubtitle) {
+    try {
+      const { stdout } = await runCommand('ffmpeg', ['-hide_banner', '-filters']);
+      hasDrawtext = stdout.includes('drawtext');
+    } catch { /* unavailable */ }
+    if (!hasDrawtext) {
+      console.log(`  (drawtext unavailable — subtitles disabled)`);
+    } else {
+      // Detect CJK content in titles/narrations and locate a CJK fontfile if needed.
+      // ffmpeg's default drawtext font is Latin-1 only; without an explicit fontfile
+      // CJK characters render as `□` tofu boxes (#3592).
+      const allText = [
+        deck.meta?.title || '',
+        ...cards.flatMap((c) => [c.title || '', c.narration || '']),
+      ].join('\n');
+      if (containsCjk(allText)) {
+        cjkFontPath = findCjkFontFile();
+        if (cjkFontPath) {
+          console.log(`  (CJK detected — using ${path.basename(cjkFontPath)} for overlay text)`);
+        } else {
+          console.log(`  (CJK detected but no CJK font found — overlay text will show as □.`);
+          console.log(`   Install Noto Sans CJK or set VOXFLOW_CJK_FONT=/path/to/font.ttc,`);
+          console.log(`   or rerun with --no-subtitle --no-intro --no-outro.)`);
+        }
+      }
+    }
+  }
+
+  // Working directory for intermediate files (WAVs, clips).
+  // Lives inside the card dir so user can inspect on failure.
+  // Cleaned up on success.
+  const workDir = path.join(dir, '.card-render-work');
+  if (fs.existsSync(workDir)) {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(workDir, { recursive: true });
+  const clipPaths = [];
+  let totalQuota = 0;
+
+  try {
+    // ── Intro card (only if drawtext available — otherwise it's just a blank dark frame) ──
+    if (!noIntro && title && hasDrawtext) {
+      console.log(`  Rendering intro...`);
+      const introPath = path.join(workDir, 'intro.mp4');
+      await renderTitleCard({
+        outPath: introPath, ratio, title,
+        subtitle: deck.meta?.language === 'zh' ? '知识卡片' : 'Card Series',
+        durationSec: introDuration, fadeSeconds: 0,
+        isFirst: true, isLast: false, hasDrawtext, cjkFontPath,
+      });
+      clipPaths.push(introPath);
+    }
+
+    // ── Per-card clips ──────────────────────────────────────────────────────
+    for (let i = 0; i < cards.length; i++) {
+      const card = cards[i];
+      const pngPath = resolveCardPng(dir, card.file);
+      if (!pngPath) {
+        throw new Error(
+          `PNG for ${card.file} not found. Run render-cards.mjs first:\n` +
+          `  node cli/skills/card/scripts/render-cards.mjs --input ${dir} --output ${dir}/exports --ratio ${ratio}`,
+        );
+      }
+
+      let wavPath = null;
+      let durationMs = hold * 1000; // silent card hold time
+
+      if (!noAudio && card.narration) {
+        const { audio: pcm, quota } = await synthesizeTTS({
+          apiBase, token,
+          text: card.narration,
+          voiceId: voice, speed,
+          format: 'pcm',
+          index: i, total: cards.length,
+        });
+        if (quota?.costDelta) totalQuota += quota.costDelta;
+        const wavDest = path.join(workDir, `card-${i}.wav`);
+        // Bake the post-narration pause into the WAV itself — otherwise
+        // ffmpeg's `-shortest` truncates the clip to the narration length
+        // and `--pause` becomes a no-op.
+        writePcmAsWav(pcm, wavDest, pause);
+        wavPath = wavDest;
+        durationMs = pcmToDurationMs(pcm) + Math.round(pause * 1000); // narration + reading time
+      }
+
+      const clipOut = path.join(workDir, `clip-${i}.mp4`);
+      console.log(`  Rendering card ${i + 1}/${cards.length}...`);
+      await renderCardClip({
+        pngPath, wavPath, outPath: clipOut,
+        durationMs, ratio, hasDrawtext, cjkFontPath,
+        subtitle: noSubtitle ? null : (card.narration || card.title || null),
+      });
+      clipPaths.push(clipOut);
+    }
+
+    // ── Outro card (only if drawtext available) ───────────────────────────
+    if (!noOutro && hasDrawtext) {
+      console.log(`  Rendering outro...`);
+      const outroPath = path.join(workDir, 'outro.mp4');
+      await renderTitleCard({
+        outPath: outroPath, ratio,
+        title: 'VoxFlow',
+        subtitle: 'voxflow.studio',
+        durationSec: outroDuration, fadeSeconds: 0,
+        bgColor: '0d0b14',
+        isFirst: false, isLast: true, hasDrawtext, cjkFontPath,
+      });
+      clipPaths.push(outroPath);
+    }
+
+    // ── Concat ──────────────────────────────────────────────────────────────
+    const slug = (title
+      ? title.replace(/[^a-z0-9一-鿿]/gi, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase()
+      : '') || 'cards';
+    const outputPath = path.resolve(opts.output || path.join(dir, `${slug}.mp4`));
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    console.log(`\n  Concatenating ${clipPaths.length} clips...`);
+    await concatVideos(clipPaths, outputPath, { remux: true });
+
+    // ── BGM mix ─────────────────────────────────────────────────────────────
+    if (bgm && fs.existsSync(bgm)) {
+      console.log(`  Mixing BGM...`);
+      const withBgmPath = outputPath.replace(/\.mp4$/, '-bgm.mp4');
+      await mixBgm(outputPath, bgm, withBgmPath, { volume: bgmVolume || 0.08 });
+      fs.renameSync(withBgmPath, outputPath);
+    }
+
+    console.log(`\n=== Done ===`);
+    console.log(`Output: ${outputPath}`);
+    if (totalQuota > 0) console.log(`Quota used: ${totalQuota}`);
+
+    // Success — clean up work directory
+    fs.rmSync(workDir, { recursive: true, force: true });
+
+    return { outputPath, cardCount: cards.length, quotaUsed: totalQuota };
+  } catch (err) {
+    // Failure — keep work directory for debugging
+    if (fs.existsSync(workDir)) {
+      console.error(`\n  Work directory preserved for debugging: ${workDir}`);
+    }
+    throw err;
+  }
+}
+
+// ── CLI handler ───────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`Usage: voxflow card render <dir> [options]
+
+Options:
+  <dir>               Card output directory (must contain deck.json + exports/*.png)
+
+  Audio:
+  --voice <id>        TTS voice ID (default: female-kefu-xiaoyue)
+  --speed <n>         TTS speed, 0.5-2.0 (default: 1.0)
+  --no-audio          Silent video — skip TTS synthesis
+
+  Timing:
+  --pause <sec>       Silence after narration before next card (default: 2.5)
+  --hold <sec>        Duration per card in --no-audio mode (default: 5)
+
+  Structure:
+  --no-intro          Skip intro title card
+  --no-outro          Skip outro branding card
+  --intro-dur <sec>   Intro card duration (default: 2.5)
+  --outro-dur <sec>   Outro card duration (default: 2)
+
+  Overlay:
+  --no-subtitle       Disable subtitle overlay (requires FFmpeg with libfreetype)
+  --bgm <path>        Background music file (loops at low volume)
+  --bgm-volume <n>    BGM volume, 0-1 (default: 0.08)
+
+  Output:
+  -o, --output <path> Output MP4 path (default: <dir>/<title>.mp4)
+
+Examples:
+  voxflow card render cards/fermentation/
+  voxflow card render cards/my-set/ --voice v-female-R2s4N9qJ --pause 3
+  voxflow card render cards/my-set/ --no-audio --hold 4
+  voxflow card render cards/my-set/ --bgm ~/music/ambient.mp3 --bgm-volume 0.1
+  voxflow card render cards/my-set/ --no-intro --no-outro`);
+    return;
+  }
+
+  // First positional arg = directory
+  const valuedFlags = new Set([
+    '--voice', '--speed', '--output', '-o',
+    '--pause', '--hold', '--intro-dur', '--outro-dur',
+    '--bgm', '--bgm-volume', '--token', '--api',
+  ]);
+  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 voice = parseFlag(args, '--voice');
+  const speed = parseFlag(args, '--speed');
+  const output = parseFlag(args, '--output', '-o');
+  const pauseArg = parseFlag(args, '--pause');
+  const holdArg = parseFlag(args, '--hold');
+  const introDurArg = parseFlag(args, '--intro-dur');
+  const outroDurArg = parseFlag(args, '--outro-dur');
+  const bgm = parseFlag(args, '--bgm');
+  const bgmVolume = parseFlag(args, '--bgm-volume');
+  const noAudio = args.includes('--no-audio');
+  const noSubtitle = args.includes('--no-subtitle');
+  const noIntro = args.includes('--no-intro');
+  const noOutro = args.includes('--no-outro');
+  const explicitToken = parseFlag(args, '--token');
+  const api = parseFlag(args, '--api') || API_BASE;
+
+  let token = explicitToken;
+  if (!noAudio && !token) {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+  }
+
+  await runWithRetry(cardRender, {
+    token, api,
+    dir: path.resolve(dir),
+    voice: voice || undefined,
+    speed: speed ? Number(speed) : undefined,
+    output: output || undefined,
+    noAudio, noSubtitle, noIntro, noOutro,
+    pause: pauseArg ? Number(pauseArg) : undefined,
+    hold: holdArg ? Number(holdArg) : undefined,
+    introDuration: introDurArg ? Number(introDurArg) : undefined,
+    outroDuration: outroDurArg ? Number(outroDurArg) : undefined,
+    bgm: bgm ? path.resolve(bgm) : undefined,
+    bgmVolume: bgmVolume ? Number(bgmVolume) : undefined,
+  }, api, explicitToken);
+}
+
+module.exports = {
+  cardRender,
+  readDeckJson,
+  resolveCardPng,
+  renderCardClip,
+  renderTitleCard,
+  escapeDrawtext,
+  writePcmAsWav,
+  containsCjk,
+  findCjkFontFile,
+  drawtextFontfileClause,
+  handle,
+};