voxflow 1.15.6 → 1.17.0

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,520 @@
+/**
+ * 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, ' ');
+}
+
+// ── 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 }) {
+  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;
+    vfParts.push(
+      `drawtext=text='${escaped}':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 }) {
+  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 vfParts = [`color=c=0x${bgColor}:s=${w}x${h}:d=${durationSec}:r=30`];
+
+  if (hasDrawtext) {
+    if (escapedTitle) {
+      vfParts.push(
+        `drawtext=text='${escapedTitle}':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}':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;
+  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)`);
+    }
+  }
+
+  // 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,
+      });
+      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,
+        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,
+      });
+      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,
+  handle,
+};

package/lib/commands/card.js

@@ -0,0 +1,57 @@
+/**
+ * VoxFlow CLI — card command
+ *
+ * Dispatches `voxflow card render <dir>` to card-render.js.
+ * 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).
+ */
+
+'use strict';
+
+async function handle(args) {
+  if (args.length > 0 && args[0] === 'render') {
+    const cardRender = require('./card-render');
+    return cardRender.handle(args.slice(1));
+  }
+
+  // Default: usage
+  console.log(`Usage:
+  voxflow card render <dir>   Render card directory → narrated MP4 video
+
+Subcommands:
+  render     Synthesize TTS narration + render Ken Burns video from card PNGs
+
+See: voxflow card render --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',
+    options: [
+      'render <dir>           Render deck.json + PNGs → narrated MP4 video',
+      '--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',
+      '--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)',
+    ],
+    examples: [
+      'voxflow card render cards/fermentation/',
+      'voxflow card render cards/fermentation/ --voice v-female-R2s4N9qJ -o out.mp4',
+      'voxflow card render cards/fermentation/ --bgm ~/music/ambient.mp3',
+      'voxflow card render cards/fermentation/ --no-audio --no-subtitle',
+    ],
+  },
+};
+
+module.exports = { handle, meta };

package/lib/commands/skills.js

@@ -23,7 +23,7 @@ const { detectAIAgent } = require('../core/agent-env');
 const execFileAsync = promisify(execFile);
 
 const SKILLS_NPM_TARGET = 'VoxFlowStudio/skills';
-const SKILL_LIST = ['hub', 'podcast', 'transcribe', 'video', 'slice'];
+const SKILL_LIST = ['hub', 'podcast', 'transcribe', 'video', 'slice', 'card'];
 
 // Universal install command — same for every agent. The `skills` npm package
 // detects which AI agents are present on the user's machine and installs the
@@ -32,8 +32,8 @@ const SKILL_LIST = ['hub', 'podcast', 'transcribe', 'video', 'slice'];
 //   - `claude skills add voxflow` does NOT exist (was wrong in earlier docs)
 //   - `npx skills add VoxFlowStudio/skills --skill voxflow` was wrong too —
 //     `--skill voxflow` is interpreted as "find a skill literally named
-//     voxflow", but our repo has 5 skills (hub / podcast / transcribe /
-//     video / slice), no skill called voxflow.
+//     voxflow", but our repo has 6 skills (hub / podcast / transcribe /
+//     video / slice / card), no skill called voxflow.
 //
 // Flags:
 //   --all     install every skill in the target repo (we ship all 5).

package/lib/commands/slice-fork.js

@@ -4,7 +4,7 @@
  * `voxflow slice fork <template-id>` — copy a curated Slice template's
  * deck.json into the current working directory.
  *
- * Templates live under `cli/skills/voxflow-slice/templates/<id>/deck.json`
+ * Templates live under `cli/skills/slice/templates/<id>/deck.json`
  * with a sibling `manifest.json` describing the gallery. The CLI ships
  * them verbatim (the `files` whitelist in package.json includes `skills/`),
  * so `npm install voxflow` is enough — no separate download.
@@ -28,11 +28,11 @@ const { validatePaperSlideDeck } = require('../internal/deck-validator');
 function resolveTemplatesDir() {
   const candidates = [
     // Source / dev: cli/lib/commands/slice-fork.js → cli/skills/...
-    path.resolve(__dirname, '../../skills/voxflow-slice/templates'),
+    path.resolve(__dirname, '../../skills/slice/templates'),
     // Published: <pkg>/dist/index.js (bundled) sits beside <pkg>/skills/...
-    path.resolve(__dirname, '../skills/voxflow-slice/templates'),
+    path.resolve(__dirname, '../skills/slice/templates'),
     // Alt published layout (some build configs flatten skills/ into dist/)
-    path.resolve(__dirname, 'skills/voxflow-slice/templates'),
+    path.resolve(__dirname, 'skills/slice/templates'),
   ];
   for (const c of candidates) {
     try {

package/lib/commands/slice.js

@@ -216,7 +216,7 @@ async function handle(args) {
     }
     // `voxflow slice fork <template-id>` — copy a curated template's
     // deck.json into the user's cwd. No quota / network — assets ship in
-    // the published `skills/voxflow-slice/templates/` directory.
+    // the published `skills/slice/templates/` directory.
     if (args.length > 0 && args[0] === 'fork') {
         const sliceFork = require('./slice-fork');
         return sliceFork.handle(args.slice(1));