voxflow 1.17.0 → 1.17.1

package/lib/commands/card-render.js

@@ -118,12 +118,99 @@ function escapeDrawtext(text) {
     .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 }) {
+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);
 
@@ -139,8 +226,9 @@ async function renderCardClip({ pngPath, wavPath, outPath, durationMs, ratio, su
     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}':fontsize=${fontSize}:fontcolor=white:` +
+      `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}`,
     );
@@ -177,7 +265,7 @@ async function renderCardClip({ pngPath, wavPath, outPath, durationMs, ratio, su
  * 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 }) {
+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;
 
@@ -185,19 +273,21 @@ async function renderTitleCard({ outPath, ratio, title, subtitle, durationSec =
   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}':fontsize=${titleSize}:fontcolor=0x${textColor}:` +
+        `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}':fontsize=${subSize}:fontcolor=0x${textColor}@0.6:` +
+        `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)}`,
       );
     }
@@ -283,6 +373,7 @@ async function cardRender(opts) {
 
   // Check drawtext filter availability (needs libfreetype)
   let hasDrawtext = false;
+  let cjkFontPath = null;
   if (!noSubtitle) {
     try {
       const { stdout } = await runCommand('ffmpeg', ['-hide_banner', '-filters']);
@@ -290,6 +381,24 @@ async function cardRender(opts) {
     } 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.)`);
+        }
+      }
     }
   }
 
@@ -313,7 +422,7 @@ async function cardRender(opts) {
         outPath: introPath, ratio, title,
         subtitle: deck.meta?.language === 'zh' ? '知识卡片' : 'Card Series',
         durationSec: introDuration, fadeSeconds: 0,
-        isFirst: true, isLast: false, hasDrawtext,
+        isFirst: true, isLast: false, hasDrawtext, cjkFontPath,
       });
       clipPaths.push(introPath);
     }
@@ -354,7 +463,7 @@ async function cardRender(opts) {
       console.log(`  Rendering card ${i + 1}/${cards.length}...`);
       await renderCardClip({
         pngPath, wavPath, outPath: clipOut,
-        durationMs, ratio, hasDrawtext,
+        durationMs, ratio, hasDrawtext, cjkFontPath,
         subtitle: noSubtitle ? null : (card.narration || card.title || null),
       });
       clipPaths.push(clipOut);
@@ -370,7 +479,7 @@ async function cardRender(opts) {
         subtitle: 'voxflow.studio',
         durationSec: outroDuration, fadeSeconds: 0,
         bgColor: '0d0b14',
-        isFirst: false, isLast: true, hasDrawtext,
+        isFirst: false, isLast: true, hasDrawtext, cjkFontPath,
       });
       clipPaths.push(outroPath);
     }
@@ -516,5 +625,8 @@ module.exports = {
   renderTitleCard,
   escapeDrawtext,
   writePcmAsWav,
+  containsCjk,
+  findCjkFontFile,
+  drawtextFontfileClause,
   handle,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "AI audio content creation CLI — stories, podcasts, narration, dubbing, transcription, translation, and video translation with TTS",
   "bin": {
     "voxflow": "./dist/index.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "AI voice CLI bundled as 6 skills (hub, podcast, transcribe, video, slice, card). Synthesize speech in 200+ voices across 40+ languages, generate multi-speaker AI podcasts, transcribe audio/video with word-level timestamps, dub videos from SRT subtitles, run end-to-end video translation, turn long articles into vertical card video reels via Remotion, and turn text into polished shareable card images or narrated card videos. Backed by a hosted TTS/ASR/LLM/render service with per-user quota (free tier 10K/mo).",
   "author": {
     "name": "VoxFlow",

package/skills/card/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: card
-description: "Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces narrated MP4 video from those cards via `voxflow card render` (Ken Burns + TTS). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast."
+description: "Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces a narrated MP4 video from those cards via `voxflow card render` (per-card TTS + FFmpeg static-image clips with optional subtitle bar / intro+outro cards / BGM mix). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast."
 ---
 
 # VoxFlow Skill — Card
@@ -374,7 +374,7 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
      "meta": {
        "title": "<Series title>",
        "ratio": "<ratio used: 9:16 | 1:1 | 3:4>",
-       "language": "<zh | en>"
+       "language": "<zh | en | ja | ...>"
      },
      "cards": [
        { "file": "card-01.html", "title": "...", "narration": "1-3 sentence spoken caption." },
@@ -383,6 +383,11 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
    }
    ```
 
+   - Field semantics:
+     - `meta.title` — drives the intro card text and the default output filename (slugified: `[^a-z0-9一-鿿]` → `-`, lowercased; CJK is preserved).
+     - `meta.language` — only `"zh"` switches the intro subtitle to "知识卡片"; any other value (including `"ja"`, `"en"`, `"mixed"`) falls back to "Card Series".
+     - `card.title` — used as the on-screen subtitle bar fallback when `card.narration` is empty.
+     - `card.narration` — the spoken caption fed to TTS and (by default) also rendered as the subtitle bar text.
    - Narration rules:
      - Write narration in the same language as the card copy.
      - 1-3 sentences per card. Natural spoken rhythm — avoid lists, avoid bullet-speak.
@@ -405,22 +410,33 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
       ├── deck.json                     (narration + metadata)
       ├── exports/card-01.png …         (PNG exports)
       ├── sources.md                    (attribution)
-      └── my-topic.mp4                  (final video — default output here)
+      └── my-topic.mp4                  (final video — slug derived from deck.meta.title)
       ```
 
-    - **Key parameters** (pick based on user preference):
+    - **Audio / TTS**:
       - `--voice <id>` — TTS voice. Suggest `voxflow voices` to browse.
       - `--speed <n>` — narration speed 0.5-2.0 (default: 1.0)
-      - `--pause <sec>` — silence after each card's narration for reading time (default: 2.5)
+      - `--no-audio` — skip TTS, produce a silent video (zero quota)
+    - **Timing**:
+      - `--pause <sec>` — silence after each card's narration for reading time (default: 2.5). Baked into the WAV so it always shows in the final clip.
       - `--hold <sec>` — card duration in `--no-audio` mode (default: 5)
-      - `--bgm <path>` — background music file (loops at low volume)
-      - `--no-audio` — skip TTS, produce silent video
-      - `--no-intro` / `--no-outro` — skip title/branding cards
-      - `-o <path>` — custom output path
-
-    - Default output: `<dir>/<deck title>.mp4` (next to the cards).
-    - No external dependencies beyond FFmpeg (auto-detected; `ffmpeg-static` as fallback).
+    - **Structure**:
+      - `--no-intro` / `--no-outro` — skip title / branding cards
+      - `--intro-dur <sec>` — intro card duration (default: 2.5)
+      - `--outro-dur <sec>` — outro card duration (default: 2)
+    - **Overlay & mix**:
+      - `--no-subtitle` — disable the bottom subtitle bar (subtitles need FFmpeg with `libfreetype`; auto-detected and skipped if missing)
+      - `--bgm <path>` — background music, looped at low volume
+      - `--bgm-volume <n>` — BGM volume 0-1 (default: 0.08)
+    - **Output**:
+      - `-o <path>` / `--output <path>` — custom output path (parents auto-created)
+
+    - **CJK content** (since CLI 1.17.1): subtitles, intro, and outro overlays auto-detect CJK text in `meta.title` / `card.title` / `card.narration` and inject a CJK-capable system fontfile (PingFang / Hiragino / Heiti on macOS; Noto CJK / WQY on Linux; msyh / SimSun on Windows). If your platform has no CJK font installed, set `VOXFLOW_CJK_FONT=/path/to/font.ttc` to point at one explicitly. When neither autodetect nor override finds a font, the command logs a warning and you should fall back to `--no-subtitle --no-intro --no-outro` to avoid `□` tofu boxes.
+
+    - Default output: `<dir>/<slugified deck.meta.title>.mp4` (next to the cards). If `meta.title` is empty, falls back to `cards.mp4`.
+    - No external dependencies beyond FFmpeg (auto-detected; falls back to `ffmpeg-static` npm package when system ffmpeg is missing).
     - Intermediate files (WAVs, clips) stored in `<dir>/.card-render-work/` — auto-cleaned on success, preserved on failure for debugging.
+    - **Quota**: ~50 per card narrated (`tts-synthesize`); zero with `--no-audio`. A 5-card deck costs ~250 quota total.
     - For article-to-card VIDEO with Slice themes (paper-slide, editorial-mag, etc.), prefer `voxflow:slice` instead.
 
 ## Asset and Source Discipline

package/skills/hub/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hub
-description: Use when the user wants to read text aloud (TTS), search VoxFlow voices, sample AI stories, or set up VoxFlow install/auth/quota — the entry-point voice toolkit. For podcasts use voxflow:podcast; for short videos / AI clips use voxflow:video; for article-to-card reels (Slice) use voxflow:slice; for transcription / dubbing / subtitle translation use voxflow:transcribe.
+description: Use when the user wants to read text aloud (TTS), search VoxFlow voices, sample AI stories, or set up VoxFlow install/auth/quota — the entry-point voice toolkit. For podcasts use voxflow:podcast; for short videos / AI clips use voxflow:video; for article-to-card reels (Slice) use voxflow:slice; for shareable card images or narrated card videos use voxflow:card; for transcription / dubbing / subtitle translation use voxflow:transcribe.
 ---
 
 # VoxFlow Skill — Hub
@@ -19,7 +19,8 @@ For specialized tasks, switch to:
 
 - **Podcasts** (multi-speaker dialogue) → `voxflow:podcast`
 - **Short videos / AI clips / knowledge cards** (`picstory`, `present`, `slides`, `explain`) → `voxflow:video`
-- **Article → vertical card video (Slice)** — 6 themes (paper / editorial / poster / Notion / brutalist / glass), web app + Remotion → `voxflow:slice`
+- **Article → vertical card video (Slice)** — 13 themes (paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), web app + Remotion → `voxflow:slice`
+- **Shareable card images & narrated card videos** (HTML/CSS + Playwright export, optional `voxflow card render` for narrated MP4) → `voxflow:card`
 - **Transcription, subtitle translation, dubbing, summarize, publish** (`asr`, `asr-jobs`, `translate`, `dub`, `video-translate`, `summarize`, `publish`) → `voxflow:transcribe`
 
 ## Install & login

package/skills/video/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: video
-description: Use when the user wants AI-generated short-form video — knowledge cards (picstory / 小红书 / TikTok / Reels), narrated explainers, presentations, AI clips, or slides — covering picstory, present, slides, explain, and image generation. For article-to-card reels (Slice — 6 themes including paper-slide), use voxflow:slice.
+description: Use when the user wants AI-generated short-form video — knowledge cards (picstory / 小红书 / TikTok / Reels), narrated explainers, presentations, AI clips, or slides — covering picstory, present, slides, explain, and image generation. For article-to-card reels (Slice — 13 themes including paper-slide), use voxflow:slice. For shareable HTML/CSS card images or narrated card MP4 videos (`voxflow card render`) use voxflow:card.
 ---
 
 # VoxFlow Video Skill
 
 Generate short-form videos with AI: LLM writes the script, AI draws cards or scenes, TTS narrates, FFmpeg / Remotion renders the final MP4.
 
-For article-to-card reels (Slice — 6 themes: paper / editorial / poster / Notion / brutalist / glass), switch to `voxflow:slice`.
+For article-to-card reels (Slice — 13 themes: paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), switch to `voxflow:slice`. For shareable HTML/CSS card image sets or narrated card-to-MP4 export, switch to `voxflow:card`.
 
 Five entry points — pick by what the user wants: