selfrelease
2d847e154f
中华文明全图鉴——文物全图系统（PC Web 地图 + NestJS API + 管理后台）。 含三大 IP（文物南迁北归 / 国宝海外回归 / 博物馆手艺人）、AI 文物对话、 文物地图与详情、以及 demo-video-kit 演示视频生成工具。
80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# 演示视频标准制作方法（视频 + 配音 + 字幕解说）
|
||
|
||
一套可复现的流程：用 Playwright 自动操作真实应用录屏，叠加与配音**逐句同步**的字幕解说，再用 DashScope qwen-tts 生成自然中文配音并合成进视频。
|
||
|
||
## 成品
|
||
|
||
- `e2e/videos/wenwumap-e2e.mp4` — 无声演示（含屏幕字幕）
|
||
- `e2e/videos/wenwumap-e2e-voiced.mp4` — **带配音成品**（视频 + 字幕 + 中文解说，三者同步）
|
||
|
||
## 核心原则：声画字三同步
|
||
|
||
解说往往比单步操作时间长。若把语音顺序排布去避免重叠，会越积越晚、滞后于画面。正确做法是 **"画面等解说"**：
|
||
|
||
1. 先把每句解说生成语音并测得**时长**；
|
||
2. 录制时，**每一步至少停留其解说时长**（动作在这段时间内完成，解说同时播完）；
|
||
3. 字幕直接显示**解说词本身**（即"配音字幕"），与语音同时出现；
|
||
4. 配音按字幕出现的**真实时间点**放置，不做重排。
|
||
|
||
这样画面动作、屏幕字幕、配音三者天然对齐。
|
||
|
||
## 文件结构
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `e2e/narration.mjs` | 解说词词库：`步骤标签 → 完整解说`，及文本归一化 `clean()`。**唯一的文案来源** |
|
||
| `e2e/gen-voice.mjs` | 预生成语音：逐句调用 qwen-tts（失败回退 macOS `say`），输出 `e2e/voice/*.wav` 与 `clips.json`（文本→{file,dur}） |
|
||
| `e2e/run.mjs` | Playwright 录屏：注入字幕条、按 `clips.json` 时长让每步停留、导出录像与 `e2e/videos/narration.json`（字幕时间轴） |
|
||
| `e2e/add-voice.mjs` | 按 `narration.json` 时间点把 `clips.json` 语音用 ffmpeg `adelay`+`amix` 合成进视频；解说超长时冻结末帧补足 |
|
||
|
||
## 前置依赖
|
||
|
||
- Node ≥ 20、pnpm；应用已在本地运行（`pnpm dev:web` + `pnpm dev:api`）
|
||
- Playwright + Chromium：`pnpm add -w -D playwright && pnpm exec playwright install chromium`
|
||
- `ffmpeg` / `ffprobe`（系统安装，需含 libx264）
|
||
- DashScope 配音：`.env` 中的 `AI_API_KEY`（qwen-tts）；离线兜底用 macOS `say`
|
||
|
||
## 制作步骤
|
||
|
||
```bash
|
||
# 1) 预生成解说语音（得到每句时长，供录制对齐）
|
||
node e2e/gen-voice.mjs
|
||
|
||
# 2) 录屏：每步停留至解说播完，字幕=解说词，导出 narration.json
|
||
node e2e/run.mjs
|
||
|
||
# 3) webm → mp4（H.264，便于合成与分享）
|
||
ffmpeg -y -i e2e/videos/wenwumap-e2e.webm \
|
||
-c:v libx264 -pix_fmt yuv420p -movflags +faststart \
|
||
e2e/videos/wenwumap-e2e.mp4
|
||
|
||
# 4) 合成配音 → wenwumap-e2e-voiced.mp4
|
||
node e2e/add-voice.mjs
|
||
```
|
||
|
||
## 改解说词 / 加步骤
|
||
|
||
1. 在 `narration.mjs` 的 `NARRATION` 里增改 `步骤标签: "解说词"`；
|
||
2. 在 `run.mjs` 中用相同的 `标签` 调 `safe("标签", async () => { ...操作... })`，字幕与停留自动按解说词处理；
|
||
3. 重新跑 1→4 即可。
|
||
|
||
> 字幕展示与配音文本都来自同一份解说词，无需两处维护。
|
||
|
||
## 可配置项
|
||
|
||
- 配音音色：`QWEN_TTS_VOICE=Cherry|Serena|Ethan|Chelsie node e2e/gen-voice.mjs`
|
||
- 离线兜底音色：`TTS_VOICE=Tingting`（macOS 中文语音）
|
||
- 录制目标地址：`BASE_URL=http://localhost:3000 node e2e/run.mjs`
|
||
|
||
## 健壮性设计
|
||
|
||
- **限流重试**：qwen-tts 每句最多重试 3 次并间隔限速，失败自动回退系统 TTS，保证流程不中断。
|
||
- **容错操作**：`run.mjs` 的 `safe()` 单步失败只记录、不中断整段录制。
|
||
- **时长自适应**：解说总时长超过视频时，`add-voice.mjs` 冻结末帧补足，保证解说完整不被截断。
|
||
- **沙箱兼容**：图片等外链由浏览器侧加载/回退；服务端只依赖可达的 DashScope。
|
||
|
||
## 已知注意点
|
||
|
||
- qwen-tts 有突发频率限制，密集重复生成会触发回退（混入系统语音）。`gen-voice.mjs` 已加间隔；如需全部自然语音，单独重试个别句子即可。
|
||
- 录制时长依赖 AI 流式回答耗时，单次运行略有浮动，但同步逻辑不受影响。
|