voxflow 1.18.2 → 1.18.4

package/lib/commands/card-render.js

@@ -30,7 +30,7 @@ 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');
+const { runCommand, checkFfmpeg, concatVideos, probeFfmpegWithFilter, forceFfmpegBin } = require('../core/ffmpeg');
 
 // ── Constants ─────────────────────────────────────────────────────────────────
 
@@ -371,16 +371,33 @@ async function cardRender(opts) {
     console.log(`  (using ffmpeg-static${pkgVersion ? ` v${pkgVersion}` : ''} — ffmpeg ${ffmpegInfo.version})`);
   }
 
-  // Check drawtext filter availability (needs libfreetype)
+  // Check drawtext filter availability (needs libfreetype). drawtext is used
+  // by ALL THREE of: subtitle bar, intro card, outro card — so probe whenever
+  // any of them is enabled (a pre-1.18.4 oversight only checked when
+  // !noSubtitle, leaving --no-subtitle but with-intro/outro decks to
+  // silently render text-less title cards on libfreetype-less ffmpeg).
+  //
+  // Homebrew's default `brew install ffmpeg` formula on macOS lacks
+  // libfreetype outright. Probe both system and bundled ffmpeg-static; pick
+  // whichever has the filter, then force the rest of this command's ffmpeg
+  // calls onto the same binary so half the pipeline doesn't keep hitting
+  // the filterless system one.
   let hasDrawtext = false;
   let cjkFontPath = null;
-  if (!noSubtitle) {
-    try {
-      const { stdout } = await runCommand('ffmpeg', ['-hide_banner', '-filters']);
-      hasDrawtext = stdout.includes('drawtext');
-    } catch { /* unavailable */ }
+  const needDrawtext = !noSubtitle || !noIntro || !noOutro;
+  if (needDrawtext) {
+    const probe = await probeFfmpegWithFilter('drawtext');
+    hasDrawtext = !!probe;
+    if (probe && probe.source === 'ffmpeg-static' && ffmpegInfo.source !== 'ffmpeg-static') {
+      forceFfmpegBin(probe.binary);
+      console.log(`  (system ffmpeg lacks libfreetype — using bundled ffmpeg-static for drawtext)`);
+    }
     if (!hasDrawtext) {
-      console.log(`  (drawtext unavailable — subtitles disabled)`);
+      const disabledFeatures = [];
+      if (!noSubtitle) disabledFeatures.push('subtitles');
+      if (!noIntro) disabledFeatures.push('intro');
+      if (!noOutro) disabledFeatures.push('outro');
+      console.log(`  (drawtext unavailable — ${disabledFeatures.join('/')} text 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

package/lib/commands/card-subtitle.js

@@ -26,82 +26,36 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFile } = require('child_process');
 
 const { parseFlag } = require('../core/args');
-const { runCommand, checkFfmpeg, resolveFfmpegStaticBin } = require('../core/ffmpeg');
+const { runCommand, checkFfmpeg, probeFfmpegWithFilter, forceFfmpegBin } = 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.
+ * libass), thin shim around the shared `probeFfmpegWithFilter` so this module
+ * still exports the named symbol used by tests and external callers.
  *
- * 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.
+ * 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. The shared probe
+ * tries system ffmpeg first, falls back to bundled ffmpeg-static.
  *
- * Returns: { binary: string, source: 'system'|'ffmpeg-static' } or throws
- * with a helpful message when neither path has libass.
+ * Resolves: { binary, source: 'system' | 'ffmpeg-static' }
+ * Rejects:  Error with install hint 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.
-      // NOTE: cannot use `require('ffmpeg-static')` directly here — when this
-      // module is ncc-bundled into dist/index.js, ffmpeg-static's own
-      // `path.join(__dirname, ...)` collapses to the bundle's directory and
-      // returns a non-existent path. resolveFfmpegStaticBin() handles the
-      // ncc-safe recovery via require.resolve('ffmpeg-static/package.json').
-      const staticPath = resolveFfmpegStaticBin();
-      if (!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 });
-    });
-  });
+async function probeSubtitlesCapableFfmpeg() {
+  const result = await probeFfmpegWithFilter('subtitles');
+  if (!result) {
+    throw 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.',
+    );
+  }
+  return result;
 }
 
 // ── Constants ─────────────────────────────────────────────────────────────────
@@ -402,13 +356,16 @@ async function cardSubtitle(opts) {
   // (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.
+  // actually has the filter, then force the rest of the run onto it via
+  // forceFfmpegBin so plain runCommand('ffmpeg', ...) calls land on the
+  // libass-capable binary.
   const { binary: ffmpegBin, source: ffmpegSource } = await probeSubtitlesCapableFfmpeg();
   if (ffmpegSource === 'ffmpeg-static') {
     console.log(`  (system ffmpeg lacks libass — using bundled ffmpeg-static)`);
   }
+  forceFfmpegBin(ffmpegBin);
 
-  await runSpecificFfmpeg(ffmpegBin, [
+  await runCommand('ffmpeg', [
     '-i', mp4Path,
     '-vf', vfArg,
     '-c:a', 'copy',

package/lib/core/ffmpeg.js

@@ -68,6 +68,70 @@ function resolveFfmpegBin() {
   return _resolvedFfmpegPath;
 }
 
+/**
+ * Override the cached ffmpeg binary used by `runCommand('ffmpeg', ...)` for
+ * the rest of this process.
+ *
+ * Used when a command (`card render`, `card subtitle`) discovers via
+ * `probeFfmpegWithFilter` that the resolved system ffmpeg lacks a required
+ * filter (libfreetype/drawtext, libass/subtitles) and needs to switch the
+ * whole pipeline to bundled ffmpeg-static. Setting it once at the top of the
+ * command keeps every downstream `runCommand`/`concatVideos` call on the
+ * same binary — without that, half the pipeline would keep hitting the
+ * filterless system ffmpeg.
+ *
+ * Idempotent. Pass null to reset (used by tests).
+ */
+function forceFfmpegBin(binary) {
+  _resolvedFfmpegPath = binary;
+}
+
+/**
+ * Find an ffmpeg binary that has the named filter compiled in. Probes the
+ * resolved system ffmpeg first; if it lacks the filter, falls back to the
+ * bundled ffmpeg-static. Used to recover from minimal ffmpeg builds — most
+ * importantly Homebrew's default formula on macOS, which ships without
+ * libfreetype (drawtext) AND without libass (subtitles), so any command
+ * relying on those filters silently degrades or fatally fails on stock
+ * `brew install ffmpeg` machines.
+ *
+ * Returns: { binary: string, source: 'system' | 'ffmpeg-static' } when a
+ *          capable binary is found, or null when no installed ffmpeg has
+ *          the requested filter.
+ *
+ * @param {string} filterName e.g. 'drawtext', 'subtitles'
+ * @returns {Promise<{binary: string, source: 'system'|'ffmpeg-static'} | null>}
+ */
+function probeFfmpegWithFilter(filterName) {
+  const filterRe = new RegExp(`\\b${filterName}\\b`);
+
+  return new Promise((resolve) => {
+    const tryBinary = (binary, source, onMiss) => {
+      execFile(binary, ['-hide_banner', '-filters'], { timeout: 10_000 }, (err, stdout) => {
+        if (err) return onMiss();
+        if (filterRe.test(stdout || '')) resolve({ binary, source });
+        else onMiss();
+      });
+    };
+
+    // 1. Whatever resolveFfmpegBin already picked (system if on PATH, else
+    //    static). Re-using the cache keeps a single source of truth for
+    //    "which ffmpeg are we using right now".
+    const primary = resolveFfmpegBin();
+    const primarySource = primary === 'ffmpeg' ? 'system' : 'ffmpeg-static';
+
+    tryBinary(primary, primarySource, () => {
+      // 2. If the primary missed AND it wasn't already ffmpeg-static, try
+      //    ffmpeg-static. This is the common Homebrew case: system ffmpeg
+      //    on PATH but missing libfreetype/libass.
+      if (primarySource === 'ffmpeg-static') return resolve(null);
+      const staticPath = resolveFfmpegStaticBin();
+      if (!staticPath) return resolve(null);
+      tryBinary(staticPath, 'ffmpeg-static', () => resolve(null));
+    });
+  });
+}
+
 /**
  * Run a command via execFile and return { stdout, stderr }.
  * Rejects on non-zero exit code or spawn error.
@@ -563,4 +627,9 @@ module.exports = {
   detectCjkFont,
   // ffmpeg-static path resolution (used by card-subtitle's libass fallback)
   resolveFfmpegStaticBin,
+  // Filter-capability probe + binary override (used by card-render / card-subtitle
+  // to recover from filterless ffmpeg builds — Homebrew default lacks both
+  // libfreetype/drawtext and libass/subtitles)
+  probeFfmpegWithFilter,
+  forceFfmpegBin,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.18.2",
+  "version": "1.18.4",
   "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.18.2",
+  "version": "1.18.4",
   "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

@@ -460,6 +460,28 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
     - `--input <path>` / `-o, --output <path>` — operate on / write to a different mp4 (otherwise: replace in place).
     - **Quota**: 0 — pure FFmpeg pipeline.
 
+    **Card-design constraint when planning to burn subtitles** (applies during Workflow steps 4–6, *before* writing the HTML):
+
+    The default subtitle style sits at ASS `MarginV=14` with `BorderStyle=3` (opaque box) — roughly the bottom **12–18% of the canvas height** on a 1080×1920 card. Anything the card itself places in that band will be overlapped by the captions. Verified during 1.18 dogfooding: page-number footers, citation chrome, italic closing pull-quotes, and "endcap" lines at the bottom edge all got partially covered.
+
+    Rules of thumb:
+    - **Reserve the bottom 15% of every card as a captioning-safe zone**: no body copy, no citation footer, no closing pull-quote there. Move card-level chrome (page number, citation, kicker) to the *top* band, or shrink the live area so it ends at ~85% of canvas height.
+    - The editorial chrome (top kicker / series indicator) is always safe — captions live at the bottom only.
+    - **Visual anchors that span full height** (oversized type, edge-cropped illustrations, photo-led covers) are fine: subtitles sit on top of the artwork, which is the intended layering. Only legibility-critical text needs to clear the band.
+    - When a card legitimately needs a bottom-edge element (e.g. a stamp, big page number, full-bleed image), skip captions for that card by leaving its `narration` empty in `deck.json` — `card subtitle` will silently absorb the empty card into adjacent windows.
+    - If you forget and discover the collision in QA: run `card subtitle --dry-run` to inspect `subs.srt` first, then either redesign the offending card's bottom band or pass `--style 'MarginV=24,...'` to push captions higher (cards with a wider safe zone trade some readability — captions get smaller relative to the canvas).
+
+    **Card-design constraint when planning to burn subtitles** (applies during Workflow steps 4–6, *before* writing the HTML):
+
+    The default subtitle style sits at ASS `MarginV=14` with `BorderStyle=3` (opaque box) — roughly the bottom **12–18% of the canvas height** on a 1080×1920 card. Anything the card itself places in that band will be overlapped by the captions. Verified during 1.18 dogfooding: page-number footers, citation chrome, italic closing pull-quotes, and "endcap" lines at the bottom edge all got partially covered.
+
+    Rules of thumb:
+    - **Reserve the bottom 15% of every card as a captioning-safe zone**: no body copy, no citation footer, no closing pull-quote there. Move card-level chrome (page number, citation, kicker) to the *top* band, or shrink the live area so it ends at ~85% of canvas height.
+    - The editorial chrome (top kicker / series indicator) is always safe — captions live at the bottom only.
+    - **Visual anchors that span full height** (oversized type, edge-cropped illustrations, photo-led covers) are fine: subtitles sit on top of the artwork, which is the intended layering. Only legibility-critical text needs to clear the band.
+    - When a card legitimately needs a bottom-edge element (e.g. a stamp, big page number, full-bleed image), skip captions for that card by leaving its `narration` empty in `deck.json` — `card subtitle` will silently absorb the empty card into adjacent windows.
+    - If you forget and discover the collision in QA: run `card subtitle --dry-run` to inspect `subs.srt` first, then either redesign the offending card's bottom band or pass `--style 'MarginV=24,...'` to push captions higher (cards with a wider safe zone trade some readability — captions get smaller relative to the canvas).
+
     Note: `card subtitle` also has a `silencedetect` fallback for old mp4s that pre-date the `timeline.json` emission (introduced in CLI 1.18). Prefer the timeline path; it is exact rather than heuristic.
 
 ## Asset and Source Discipline