wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/huashu-design/scripts/mix-voiceover.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# mix-voiceover.sh · Mix voiceover (人声主轨) + optional BGM into an MP4
+#
+# Usage:
+#   bash mix-voiceover.sh <video.mp4> --voiceover=<voice.mp3> [options]
+#
+# Required:
+#   --voiceover=<path>    Path to voiceover mp3 (人声主轨, 来自 narrate-pipeline.mjs)
+#
+# Optional:
+#   --bgm=<path>          BGM mp3 path (overrides --bgm-mood)
+#   --bgm-mood=<name>     Pick a preset BGM from assets/ (educational / tech / tutorial / ...)
+#   --bgm-volume=<0-1>    BGM 静态音量, 默认 0.18 (相对人声)
+#   --no-ducking          关闭 sidechain ducking（默认开启：人声响时 BGM 自动让路）
+#   --voice-volume=<0-2>  人声音量倍率, 默认 1.0
+#   --out=<path>          输出路径, 默认 <input>-voiced.mp4
+#
+# Behavior:
+#   - 视频流 stream copy（不重编码，快）
+#   - 人声始终是主轨，必带；BGM 可选
+#   - 默认开 ducking：人声响时 BGM 压到约 -10dB，人声停时回升
+#   - 输出长度 = 视频长度（人声/BGM 较短就尾静音；较长就截断）
+#
+# Examples:
+#   bash mix-voiceover.sh anim.mp4 --voiceover=narration/voiceover.mp3
+#   bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm-mood=educational
+#   bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm=~/Music/song.mp3 --bgm-volume=0.12
+#   bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm-mood=tech --no-ducking
+#
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ASSETS_DIR="$SCRIPT_DIR/../assets"
+
+INPUT=""
+VOICEOVER=""
+BGM=""
+BGM_MOOD=""
+BGM_VOLUME="0.18"
+VOICE_VOLUME="1.0"
+DUCKING="1"
+OUTPUT=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --voiceover=*)    VOICEOVER="${arg#*=}" ;;
+    --bgm=*)          BGM="${arg#*=}" ;;
+    --bgm-mood=*)     BGM_MOOD="${arg#*=}" ;;
+    --bgm-volume=*)   BGM_VOLUME="${arg#*=}" ;;
+    --voice-volume=*) VOICE_VOLUME="${arg#*=}" ;;
+    --no-ducking)     DUCKING="0" ;;
+    --out=*)          OUTPUT="${arg#*=}" ;;
+    -*)               echo "未知参数：$arg" >&2; exit 1 ;;
+    *)                INPUT="$arg" ;;
+  esac
+done
+
+if [ -z "$INPUT" ] || [ ! -f "$INPUT" ]; then
+  echo "Usage: bash mix-voiceover.sh <video.mp4> --voiceover=<v.mp3> [--bgm=<b.mp3> | --bgm-mood=<name>]" >&2
+  exit 1
+fi
+if [ -z "$VOICEOVER" ] || [ ! -f "$VOICEOVER" ]; then
+  echo "✗ 缺 --voiceover=<path>" >&2
+  exit 1
+fi
+
+# 解析 BGM 来源
+if [ -z "$BGM" ] && [ -n "$BGM_MOOD" ]; then
+  BGM="$ASSETS_DIR/bgm-${BGM_MOOD}.mp3"
+fi
+if [ -n "$BGM" ] && [ ! -f "$BGM" ]; then
+  echo "✗ BGM 文件不存在: $BGM" >&2
+  echo "  可用 mood: $(ls "$ASSETS_DIR" 2>/dev/null | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2
+  exit 1
+fi
+
+# 输出路径
+if [ -z "$OUTPUT" ]; then
+  base="${INPUT%.*}"
+  OUTPUT="${base}-voiced.mp4"
+fi
+
+echo "─ mix-voiceover ──────────────"
+echo "  视频:     $INPUT"
+echo "  人声:     $VOICEOVER (vol=$VOICE_VOLUME)"
+if [ -n "$BGM" ]; then
+  echo "  BGM:      $BGM (vol=$BGM_VOLUME, ducking=$DUCKING)"
+else
+  echo "  BGM:      （无）"
+fi
+echo "  输出:     $OUTPUT"
+echo "──────────────────────────────"
+
+# ── ffmpeg filter graph ─────────────────────────────────────
+if [ -z "$BGM" ]; then
+  # 仅人声
+  ffmpeg -y -i "$INPUT" -i "$VOICEOVER" \
+    -filter_complex "[1:a]volume=${VOICE_VOLUME}[a]" \
+    -map 0:v -map "[a]" \
+    -c:v copy -c:a aac -b:a 192k -shortest \
+    "$OUTPUT"
+elif [ "$DUCKING" = "1" ]; then
+  # 人声 + BGM + sidechain ducking
+  ffmpeg -y -i "$INPUT" -i "$VOICEOVER" -i "$BGM" \
+    -filter_complex "
+      [1:a]volume=${VOICE_VOLUME}[voice];
+      [2:a]volume=${BGM_VOLUME},aloop=loop=-1:size=2e9[bgm_lo];
+      [bgm_lo][voice]sidechaincompress=threshold=0.04:ratio=8:attack=5:release=300:makeup=1[bgm_ducked];
+      [voice][bgm_ducked]amix=inputs=2:duration=first:dropout_transition=0,afade=t=out:st=0:d=0.5:curve=tri[a]
+    " \
+    -map 0:v -map "[a]" \
+    -c:v copy -c:a aac -b:a 192k -shortest \
+    "$OUTPUT"
+else
+  # 人声 + BGM 静态混合
+  ffmpeg -y -i "$INPUT" -i "$VOICEOVER" -i "$BGM" \
+    -filter_complex "
+      [1:a]volume=${VOICE_VOLUME}[voice];
+      [2:a]volume=${BGM_VOLUME},aloop=loop=-1:size=2e9[bgm];
+      [voice][bgm]amix=inputs=2:duration=first:dropout_transition=0[a]
+    " \
+    -map 0:v -map "[a]" \
+    -c:v copy -c:a aac -b:a 192k -shortest \
+    "$OUTPUT"
+fi
+
+echo "✓ 完成：$OUTPUT"

package/src/skills-lib/huashu-design/scripts/narrate-pipeline.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * narrate-pipeline.mjs · L2 长解说总指挥
+ *
+ * 输入：markdown 解说稿（## scene-id 分段，[[cue:id]] 标关键句）
+ * 输出：voiceover.mp3（拼接好的整段人声）+ timeline.json（每段 start/end + cues 绝对时间）
+ *
+ * 用法：
+ *   node scripts/narrate-pipeline.mjs --script demo.md --out-dir _narration_demo
+ *
+ * 解说稿格式：
+ *   ---
+ *   title: 什么是 LLM
+ *   voice: S_JSdgdWk22   # 可选，不填走 .env
+ *   speed: 1.0           # 可选
+ *   gap: 0.3             # 段间静音秒数，默认 0.3
+ *   ---
+ *
+ *   ## intro
+ *   大家好，我是花叔。今天我们 5 分钟讲清楚 LLM 是什么。
+ *
+ *   ## what-is
+ *   LLM 全称 Large Language Model，[[cue:bigmodel]]它是一个有几千亿参数的神经网络。
+ *   本质是一个文字接龙的预测器。
+ *
+ * 输出文件结构（out-dir 下）：
+ *   audio/
+ *     intro.mp3
+ *     what-is.mp3
+ *   voiceover.mp3       拼接全部 scene 的整段人声
+ *   timeline.json       schema 见 references/voiceover-pipeline.md
+ *
+ * 依赖：tts-doubao.mjs、ffmpeg、ffprobe
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync, execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, '..');
+const TTS_SCRIPT = path.join(__dirname, 'tts-doubao.mjs');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--script') args.script = argv[++i];
+    else if (a === '--out-dir') args.outDir = argv[++i];
+    else if (a === '--help' || a === '-h') args.help = true;
+  }
+  return args;
+}
+
+function usage() {
+  console.error(`
+narrate-pipeline.mjs · L2 长解说总指挥
+
+  --script <path>     解说稿 .md 文件（必填）
+  --out-dir <path>    输出目录（必填）
+
+输出：<out-dir>/voiceover.mp3 + <out-dir>/timeline.json
+`.trim());
+  process.exit(1);
+}
+
+/**
+ * Parse frontmatter + scene blocks from markdown
+ * Returns { meta, scenes: [{ id, raw }] }
+ */
+function parseScript(md) {
+  const meta = {};
+  let body = md;
+  const fmMatch = md.match(/^---\n([\s\S]*?)\n---\n/);
+  if (fmMatch) {
+    for (const line of fmMatch[1].split('\n')) {
+      const idx = line.indexOf(':');
+      if (idx < 0) continue;
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim();
+      meta[key] = val;
+    }
+    body = md.slice(fmMatch[0].length);
+  }
+  const scenes = [];
+  const re = /^##\s+([\w-]+)\s*\n([\s\S]*?)(?=^##\s+[\w-]+\s*\n|$(?![\r\n]))/gm;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    scenes.push({ id: m[1], raw: m[2].trim() });
+  }
+  return { meta, scenes };
+}
+
+/**
+ * Split a scene's text by [[cue:id]] markers into chunks.
+ * Returns: { chunks: [{ text, cueAfter? }] }
+ *   cueAfter is the cue id that follows this chunk (chunk's end = cue position)
+ *
+ * Example: "A[[cue:x]]B[[cue:y]]C" =>
+ *   chunks: [
+ *     { text: "A", cueAfter: "x" },
+ *     { text: "B", cueAfter: "y" },
+ *     { text: "C" }
+ *   ]
+ */
+function splitByCues(text) {
+  const chunks = [];
+  const re = /\[\[cue:([\w-]+)\]\]/g;
+  let lastIdx = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const before = text.slice(lastIdx, m.index).trim();
+    chunks.push({ text: before, cueAfter: m[1] });
+    lastIdx = m.index + m[0].length;
+  }
+  const tail = text.slice(lastIdx).trim();
+  chunks.push({ text: tail });
+  // 过滤空文本块（cue 紧贴段首/段尾时）
+  return chunks.filter((c) => c.text.length > 0 || c.cueAfter);
+}
+
+function getDuration(filePath) {
+  const out = execFileSync('ffprobe', [
+    '-v', 'error',
+    '-show_entries', 'format=duration',
+    '-of', 'default=noprint_wrappers=1:nokey=1',
+    filePath,
+  ], { encoding: 'utf8' });
+  return parseFloat(out.trim());
+}
+
+function callTTS(text, outPath, opts) {
+  const args = ['--text', text, '--out', outPath];
+  if (opts.voice) args.push('--voice', opts.voice);
+  if (opts.speed) args.push('--speed', String(opts.speed));
+  const out = execFileSync('node', [TTS_SCRIPT, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
+  return JSON.parse(out.trim());
+}
+
+function ffmpegConcat(inputs, output) {
+  // 用 concat demuxer 合并相同编码的 mp3
+  const listFile = output + '.list';
+  fs.writeFileSync(
+    listFile,
+    inputs.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join('\n'),
+  );
+  execSync(
+    `ffmpeg -y -f concat -safe 0 -i "${listFile}" -c copy "${output}"`,
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  fs.unlinkSync(listFile);
+}
+
+function makeSilence(duration, outPath) {
+  execSync(
+    `ffmpeg -y -f lavfi -i anullsrc=r=24000:cl=mono -t ${duration} -q:a 9 -acodec libmp3lame "${outPath}"`,
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help || !args.script || !args.outDir) usage();
+
+  const scriptPath = path.resolve(args.script);
+  const outDir = path.resolve(args.outDir);
+  const audioDir = path.join(outDir, 'audio');
+  const tmpDir = path.join(outDir, '.tmp');
+  fs.mkdirSync(audioDir, { recursive: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const md = fs.readFileSync(scriptPath, 'utf8');
+  const { meta, scenes } = parseScript(md);
+  if (scenes.length === 0) {
+    console.error('错：解说稿没有 ## scene 段，至少一段。');
+    process.exit(1);
+  }
+
+  const voice = meta.voice || undefined;
+  const speed = meta.speed ? parseFloat(meta.speed) : 1.0;
+  const gap = meta.gap ? parseFloat(meta.gap) : 0.3;
+
+  console.error(`[narrate] script=${path.basename(scriptPath)} scenes=${scenes.length} voice=${voice || '(env)'} speed=${speed} gap=${gap}s`);
+
+  // 段间静音文件（共用一个）
+  const gapFile = path.join(tmpDir, 'gap.mp3');
+  if (gap > 0) makeSilence(gap, gapFile);
+
+  const timeline = {
+    title: meta.title || path.basename(scriptPath, '.md'),
+    voice: voice || null,
+    speed,
+    gap,
+    totalDuration: 0,
+    scenes: [],
+  };
+
+  let cursor = 0;
+  const sceneAudioFiles = [];
+
+  for (let i = 0; i < scenes.length; i++) {
+    const scene = scenes[i];
+    console.error(`[narrate] (${i + 1}/${scenes.length}) scene="${scene.id}"`);
+
+    const chunks = splitByCues(scene.raw);
+    const chunkFiles = [];
+    const cueRecords = [];
+    const chunkRecords = []; // 每个 chunk 的实测 start/end 段内时间，用于字幕显示
+    let sceneInternalCursor = 0;
+
+    for (let j = 0; j < chunks.length; j++) {
+      const chunk = chunks[j];
+      if (!chunk.text) {
+        // 空文本块（cue 紧贴），跳过 TTS 但仍记录 cue 位置
+        if (chunk.cueAfter) {
+          cueRecords.push({
+            id: chunk.cueAfter,
+            offset: sceneInternalCursor,
+          });
+        }
+        continue;
+      }
+      const chunkPath = path.join(tmpDir, `${scene.id}-${j}.mp3`);
+      const result = callTTS(chunk.text, chunkPath, { voice, speed });
+      const chunkStart = sceneInternalCursor;
+      chunkFiles.push(chunkPath);
+      sceneInternalCursor += result.duration;
+      chunkRecords.push({
+        text: chunk.text,
+        start: chunkStart,
+        end: sceneInternalCursor,
+        duration: result.duration,
+      });
+      console.error(`  chunk ${j}: ${result.duration.toFixed(2)}s · ${chunk.text.length} 字 · ${chunk.text.slice(0, 30)}${chunk.text.length > 30 ? '…' : ''}`);
+      if (chunk.cueAfter) {
+        cueRecords.push({
+          id: chunk.cueAfter,
+          offset: sceneInternalCursor,
+        });
+      }
+    }
+
+    // 合并段内子段
+    const sceneAudio = path.join(audioDir, `${scene.id}.mp3`);
+    if (chunkFiles.length === 1) {
+      fs.copyFileSync(chunkFiles[0], sceneAudio);
+    } else {
+      ffmpegConcat(chunkFiles, sceneAudio);
+    }
+    const sceneDuration = getDuration(sceneAudio);
+
+    // 拼接到总轨：先加 gap（除了第一段），再加 scene
+    if (i > 0 && gap > 0) {
+      sceneAudioFiles.push(gapFile);
+      cursor += gap;
+    }
+    sceneAudioFiles.push(sceneAudio);
+
+    timeline.scenes.push({
+      id: scene.id,
+      start: cursor,
+      end: cursor + sceneDuration,
+      duration: sceneDuration,
+      audio: path.relative(outDir, sceneAudio),
+      text: scene.raw.replace(/\[\[cue:[\w-]+\]\]/g, ''),
+      // chunks: 用于字幕逐句显示。start/end 是段内相对时间，absoluteStart/absoluteEnd 是整轨绝对时间
+      chunks: chunkRecords.map((c) => ({
+        text: c.text,
+        start: c.start,
+        end: c.end,
+        absoluteStart: cursor + c.start,
+        absoluteEnd: cursor + c.end,
+      })),
+      cues: cueRecords.map((c) => ({
+        id: c.id,
+        offset: c.offset,
+        absoluteTime: cursor + c.offset,
+      })),
+    });
+
+    cursor += sceneDuration;
+  }
+
+  // 合并整轨
+  const voiceoverPath = path.join(outDir, 'voiceover.mp3');
+  ffmpegConcat(sceneAudioFiles, voiceoverPath);
+  timeline.totalDuration = getDuration(voiceoverPath);
+  timeline.voiceover = 'voiceover.mp3';
+
+  fs.writeFileSync(
+    path.join(outDir, 'timeline.json'),
+    JSON.stringify(timeline, null, 2),
+  );
+
+  // 清理 tmp
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  console.error(`\n[narrate] 完成。`);
+  console.error(`  voiceover: ${voiceoverPath}`);
+  console.error(`  timeline:  ${path.join(outDir, 'timeline.json')}`);
+  console.error(`  总时长:    ${timeline.totalDuration.toFixed(2)}s (${(timeline.totalDuration / 60).toFixed(2)} min)`);
+  console.error(`  段数:      ${timeline.scenes.length}`);
+  const totalCues = timeline.scenes.reduce((sum, s) => sum + s.cues.length, 0);
+  console.error(`  cue 数:    ${totalCues}`);
+}
+
+main().catch((err) => {
+  console.error(`narrate-pipeline 失败：${err.message}`);
+  console.error(err.stack);
+  process.exit(1);
+});

package/src/skills-lib/huashu-design/scripts/render-narration.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# render-narration.sh · 一条龙：HTML 解说动画 → 最终 MP4（带人声）
+#
+# 流水线：
+#   1. render-video.js  录无声 MP4（按 timeline.totalDuration）
+#   2. mix-voiceover.sh 混入 voiceover.mp3（可选 BGM）
+#   3. 输出 <basename>-narrated.mp4
+#
+# Usage:
+#   bash render-narration.sh <html> --timeline=<path> [options]
+#
+# Required:
+#   <html>                解说动画的 HTML（应内嵌 NarrationStage + recording 模式 rAF 自驱）
+#   --timeline=<path>     timeline.json 路径（自动读 totalDuration 和 voiceover.mp3 路径）
+#
+# Optional:
+#   --bgm-mood=<name>     BGM 预设（educational / tech / tutorial / ...）
+#   --bgm=<path>          自定义 BGM 文件
+#   --bgm-volume=<0-1>    BGM 静态音量，默认 0.18
+#   --no-ducking          关 sidechain ducking
+#   --keep-silent         保留中间产物（无声 MP4），便于 debug
+#   --seek                用 render-video-seek.js 逐帧 seek 渲染（真 60fps·确定性·无黑帧）
+#   --seek-fps=<n>        seek 渲染帧率，默认 60，需配合 --seek
+#   --out=<path>          输出路径，默认 <html-basename>-narrated.mp4
+#   --width=<px>          视频宽度（默认 1920）
+#   --height=<px>         视频高度（默认 1080）
+#
+# Examples:
+#   bash render-narration.sh demo.html --timeline=_narration/timeline.json
+#   bash render-narration.sh demo.html --timeline=_narration/timeline.json --bgm-mood=educational
+#
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$SCRIPT_DIR/.."
+
+HTML=""
+TIMELINE=""
+BGM_MOOD=""
+BGM=""
+BGM_VOLUME="0.18"
+NO_DUCKING=""
+KEEP_SILENT=""
+USE_SEEK=""
+SEEK_FPS="60"
+OUT=""
+WIDTH="1920"
+HEIGHT="1080"
+
+for arg in "$@"; do
+  case "$arg" in
+    --timeline=*)    TIMELINE="${arg#*=}" ;;
+    --bgm-mood=*)    BGM_MOOD="${arg#*=}" ;;
+    --bgm=*)         BGM="${arg#*=}" ;;
+    --bgm-volume=*)  BGM_VOLUME="${arg#*=}" ;;
+    --no-ducking)    NO_DUCKING="--no-ducking" ;;
+    --keep-silent)   KEEP_SILENT="1" ;;
+    --seek)          USE_SEEK="1" ;;
+    --seek-fps=*)    SEEK_FPS="${arg#*=}" ;;
+    --out=*)         OUT="${arg#*=}" ;;
+    --width=*)       WIDTH="${arg#*=}" ;;
+    --height=*)      HEIGHT="${arg#*=}" ;;
+    -*)              echo "未知参数：$arg" >&2; exit 1 ;;
+    *)               HTML="$arg" ;;
+  esac
+done
+
+if [ -z "$HTML" ] || [ ! -f "$HTML" ]; then
+  echo "Usage: bash render-narration.sh <html> --timeline=<path> [options]" >&2
+  exit 1
+fi
+if [ -z "$TIMELINE" ] || [ ! -f "$TIMELINE" ]; then
+  echo "✗ 缺 --timeline=<path>（timeline.json 由 narrate-pipeline.mjs 生成）" >&2
+  exit 1
+fi
+
+# ── 从 timeline.json 读 totalDuration 和 voiceover 路径 ──
+TIMELINE_DIR="$(cd "$(dirname "$TIMELINE")" && pwd)"
+TOTAL_DURATION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$TIMELINE','utf8')).totalDuration)")
+VOICEOVER_REL=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$TIMELINE','utf8')).voiceover || 'voiceover.mp3')")
+VOICEOVER="$TIMELINE_DIR/$VOICEOVER_REL"
+
+if [ ! -f "$VOICEOVER" ]; then
+  echo "✗ voiceover.mp3 不存在: $VOICEOVER" >&2
+  exit 1
+fi
+
+# 录制时长 = 总时长 + 1s 安全缓冲
+RECORD_DURATION=$(node -e "console.log(Math.ceil($TOTAL_DURATION + 1))")
+
+HTML_ABS="$(cd "$(dirname "$HTML")" && pwd)/$(basename "$HTML")"
+HTML_DIR="$(dirname "$HTML_ABS")"
+HTML_BASE="$(basename "$HTML" .html)"
+SILENT_MP4="$HTML_DIR/$HTML_BASE.mp4"
+
+if [ -z "$OUT" ]; then
+  OUT="$HTML_DIR/$HTML_BASE-narrated.mp4"
+fi
+
+echo "═══ render-narration ═══════════════════"
+echo "  HTML:        $HTML_ABS"
+echo "  Timeline:    $TIMELINE"
+echo "  Voiceover:   $VOICEOVER"
+echo "  Total dur:   ${TOTAL_DURATION}s (录 ${RECORD_DURATION}s)"
+echo "  尺寸:        ${WIDTH}×${HEIGHT}"
+[ -n "$BGM_MOOD" ] && echo "  BGM mood:    $BGM_MOOD"
+[ -n "$BGM" ] && echo "  BGM:         $BGM"
+echo "  最终输出:    $OUT"
+echo "════════════════════════════════════════"
+
+# ── Step 1: 录无声 MP4 ──────────────────────
+echo ""
+if [ -n "$USE_SEEK" ]; then
+  echo "▸ Step 1/2 · 逐帧 seek 渲染 HTML 动画 (无声 · ${SEEK_FPS}fps 确定性)"
+  NODE_PATH=$(npm root -g) node "$SCRIPT_DIR/render-video-seek.js" "$HTML_ABS" \
+    --duration="$RECORD_DURATION" \
+    --fps="$SEEK_FPS" \
+    --width="$WIDTH" \
+    --height="$HEIGHT"
+else
+  echo "▸ Step 1/2 · 录制 HTML 动画 (无声)"
+  NODE_PATH=$(npm root -g) node "$SCRIPT_DIR/render-video.js" "$HTML_ABS" \
+    --duration="$RECORD_DURATION" \
+    --width="$WIDTH" \
+    --height="$HEIGHT"
+fi
+
+if [ ! -f "$SILENT_MP4" ]; then
+  echo "✗ 无声 MP4 没生成: $SILENT_MP4" >&2
+  exit 1
+fi
+
+# ── Step 2: 混入人声 ──────────────────────
+echo ""
+echo "▸ Step 2/2 · 混入人声"
+MIX_ARGS=("$SILENT_MP4" "--voiceover=$VOICEOVER" "--out=$OUT")
+[ -n "$BGM_MOOD" ] && MIX_ARGS+=("--bgm-mood=$BGM_MOOD")
+[ -n "$BGM" ]      && MIX_ARGS+=("--bgm=$BGM")
+[ -n "$BGM_MOOD$BGM" ] && MIX_ARGS+=("--bgm-volume=$BGM_VOLUME")
+[ -n "$NO_DUCKING" ] && MIX_ARGS+=("$NO_DUCKING")
+
+bash "$SCRIPT_DIR/mix-voiceover.sh" "${MIX_ARGS[@]}"
+
+# 清理中间产物
+if [ -z "$KEEP_SILENT" ]; then
+  rm -f "$SILENT_MP4"
+fi
+
+echo ""
+echo "✓ 完成: $OUT"
+[ -n "$KEEP_SILENT" ] && echo "  (中间产物保留: $SILENT_MP4)"