# demo-video-kit

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

## 安装

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

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

还需要（一次性）：

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

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

## 快速开始

```bash
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）

```js
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

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

## 设计原则：声画字三同步

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

## 健壮性

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

## 许可证

MIT