selfrelease
2d847e154f
中华文明全图鉴——文物全图系统（PC Web 地图 + NestJS API + 管理后台）。 含三大 IP（文物南迁北归 / 国宝海外回归 / 博物馆手艺人）、AI 文物对话、 文物地图与详情、以及 demo-video-kit 演示视频生成工具。
演示视频标准制作方法（视频 + 配音 + 字幕解说）
一套可复现的流程：用 Playwright 自动操作真实应用录屏，叠加与配音逐句同步的字幕解说，再用 DashScope qwen-tts 生成自然中文配音并合成进视频。
成品
e2e/videos/wenwumap-e2e.mp4— 无声演示（含屏幕字幕）e2e/videos/wenwumap-e2e-voiced.mp4— 带配音成品（视频 + 字幕 + 中文解说，三者同步）
核心原则：声画字三同步
解说往往比单步操作时间长。若把语音顺序排布去避免重叠，会越积越晚、滞后于画面。正确做法是 "画面等解说"：
- 先把每句解说生成语音并测得时长；
- 录制时，每一步至少停留其解说时长（动作在这段时间内完成，解说同时播完）；
- 字幕直接显示解说词本身（即"配音字幕"），与语音同时出现；
- 配音按字幕出现的真实时间点放置，不做重排。
这样画面动作、屏幕字幕、配音三者天然对齐。
文件结构
| 文件 | 职责 |
|---|---|
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）；离线兜底用 macOSsay
制作步骤
# 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
改解说词 / 加步骤
- 在
narration.mjs的NARRATION里增改步骤标签: "解说词"； - 在
run.mjs中用相同的标签调safe("标签", async () => { ...操作... })，字幕与停留自动按解说词处理； - 重新跑 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 流式回答耗时，单次运行略有浮动，但同步逻辑不受影响。