chore: 初始化仓库

中华文明全图鉴——文物全图系统（PC Web 地图 + NestJS API + 管理后台）。含三大 IP（文物南迁北归 / 国宝海外回归 / 博物馆手艺人）、AI 文物对话、文物地图与详情、以及 demo-video-kit 演示视频生成工具。
2026-06-13 20:55:44 +08:00
commit 2d847e154f
161 changed files with 22629 additions and 0 deletions
@@ -0,0 +1,91 @@
+# 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