WenwuMap/tools/demo-video-kit

demo-video-kit

配置驱动的演示视频生成工具：Playwright 自动操作录屏 + 与配音逐句同步的字幕解说 + 中文 TTS 自然配音，一条命令产出带解说的 MP4。可独立安装到任意项目。

安装

# 发布到 npm 后：
npm i -D demo-video-kit

# 或从 Git / 本地路径安装：
npm i -D <git-url>
npm i -D file:../tools/demo-video-kit

还需要（一次性）：

npx playwright install chromium      # 录屏用浏览器
# 系统安装 ffmpeg / ffprobe（含 libx264），例如：brew install ffmpeg
export AI_API_KEY=sk-xxx             # DashScope qwen-tts 密钥（或写入项目 .env）

无密钥或调用失败时，自动回退 macOS say 离线语音，流程不中断。

快速开始

npx demo-video init            # 生成 demo.config.mjs 模板
# 编辑 demo.config.mjs（填 baseUrl 与 steps）
npx demo-video demo.config.mjs --out out

产物：

• out/demo.mp4 — 无声（含字幕）
• out/demo-voiced.mp4 — 带配音成品

配置（demo.config.mjs）

export default {
  baseUrl: "http://localhost:3000",
  brand: "我的产品 · 功能演示",
  voice: { name: "Cherry", apiKeyEnv: "AI_API_KEY", fallbackVoice: "Tingting" },
  intro: { narration: "欢迎使用我的产品。" },
  outro: { narration: "感谢观看。" },
  steps: [
    {
      label: "搜索",
      narration: "输入关键词即可快速定位。", // 同时作为字幕与配音
      run: async ({ page, pause }) => {
        await page.getByPlaceholder("搜索").fill("示例");
        await pause(1500);
      },
    },
  ],
};

run(ctx) 的 ctx = { page, pause(ms), say(text) }，page 为 Playwright Page。

CLI

demo-video <config.mjs> [--out dir] [--skip-tts] [--silent]
demo-video init [path]
demo-video --version | --help

• --skip-tts：复用 out/voice/clips.json（改了操作但没改文案时加速）
• --silent：跳过配音，仅出无声视频

程序化 API

import { generateVoices, record, transcode, muxVoice } from "demo-video-kit";

设计原则：声画字三同步

解说常比单步操作长。本工具采用 "画面等解说"：先测每句语音时长 → 录制时每步至少停留该句时长 → 字幕显示解说词本身 → 配音按字幕真实时间点放置。三者天然对齐，不会漂移。

健壮性

• qwen-tts 自动重试 + 限速，失败回退系统 TTS
• 单步操作失败只记录、不中断整段录制
• 解说总时长超视频时，自动冻结末帧补足，保证解说完整

许可证

MIT