MG Video Factory——MG 讲解视频生产线

把「文案 → 配音 → 分镜 → 38 镜并行构建 → 渲染 → 三轮 QC → 交付」的完整流程工程化。本 skill 从一个已交付项目（38 镜 / 7.5 分钟 / 1080p）沉淀而来，模板与脚本均为实战验证版本。

何时使用

制作带中文配音的黑底 MG 风格讲解视频（课程/科普/产品介绍）
已有本项目类工程，需要：改文案后重出片、配音换声/调节奏、成片节奏 QC 修复
网络受限环境下搭建 Remotion + 本地 TTS 管线

开工前必读 references/lessons.md——8 大类实战教训（网络/中文 TTS/时间轴重映射/QC 判据/Remotion 约定/Windows/多 agent/交付偏好），能避开绝大多数返工。

资源清单

| 资源 | 用途 | |---|---| | assets/template/ | 可编译的 Remotion 工程骨架（1280×720@30fps，黑底 MG 风格；含 ui 图元库、fx 特效库、common 公共层、overlay 常驻层、G1 完整四镜示例、中文字体） | | assets/audio-samples/ | 随包音频样例（见下「音频依赖与随包样例」）：成片配音节选 + edge-tts 逐句分块缓存，用于验证音频链路与节拍对齐 | | scripts/scaffold.py | 从模板创建新项目（跨平台，替代 rsync/zsh 方案） | | scripts/setup_models.py | 下载 kokoro 模型+声音库（hf-mirror，断点续传+sha256） | | scripts/tts_build.py | 解说词 → 分段配音 → timeline.json（帧级时间轴）。支持 kokoro_onnx 中文（misaki ZHG2P + 数字/专名归一化 + 标点停顿逐段合成）、4 种引擎 | | scripts/remap_beats.py | TTS 重跑后全片帧号重映射（章锚点 + DP + 句内 1:1 规范 + 段末约束校验，幂等） | | scripts/motion_check.py | 节奏体检：最长静止 ≤3s、末拍稳定期（hold）≥30 帧；支持组级与成片帧目录两种模式 | | scripts/sheet.py / frame_metrics.py | 全片缩略图速览 HTML / 帧级指标 | | scripts/selfcheck.py | 工程自检 |

音频依赖与随包样例

配音有两条链路，按可用性二选一（tts_build.py 的 auto 模式会自动探测并降级）：

| 链路 | 依赖 | 说明 | |---|---|---| | edge-tts 云端（默认） | 联网访问微软 TTS 端点 | 音色最自然、词级边界节拍最准；默认 zh-CN-YunjianNeural +6% 语速 +3Hz 音调 | | kokoro_onnx 本地 | kokoro-v1.0.onnx（~310 MB）+ voices-v1.0.bin（~28 MB） | 被墙时的离线兜底。两个大模型不随本包分发，用 python scripts/setup_models.py 从 hf-mirror 下载（断点续传 + sha256 校验），默认落到工程根 models/ |

assets/audio-samples/ 随包提供一组已有成片音频素材（取自已交付的 sysdash 项目，edge-tts 中文男声），无需网络即可核对音频链路：

narration-sample-60s.mp3——成片配音节选（60 s），用于试听音色与整体节奏。
tts-cache/——tts_build.py 的逐句分块产物（133 组 *.mp3 + *.json 词边界数据，共 266 文件 / ≈2.95 MB），可直接对照 script/timeline.json 校验句级节拍与停顿处理。

样例仅供链路验证与节拍对齐参考，不参与新项目构建；成片完整音轨（约 76 MB 的 audio.wav）体积过大，不入包，需要时从该项目的 public/assets/<slug>/audio.wav 取用。

生产线（8 阶段）

建项目：python scripts/scaffold.py <目标目录> <slug> → 按提示 npm install --registry=https://registry.npmmirror.com → npx tsc --noEmit 验证骨架。
调研 + 解说词：与用户确认时长/语言/文案。解说词格式：# CHAPTER n 章名 分章；竖线 | 切字幕块（每块 ≤16 字）；空行分段（=镜头粒度）；## gap N 追加停留帧。
配音：首选 edge-tts 云健（音色最自然 + 词级边界节拍最准）——直接 python scripts/tts_build.py，默认 zh-CN-YunjianNeural +6% 语速 +3Hz 音调。auto 模式会先探测微软端点，被墙（WSS 403）时自动降级本地 kokoro_onnx；本地兜底需先装模型 python scripts/setup_models.py，再：
```
TTS_ENGINE=kokoro_onnx KOKORO_ONNX_MODEL=models/kokoro-v1.0.onnx \
KOKORO_ONNX_VOICES=models/voices-v1.0.bin KOKORO_ONNX_VOICE=zm_yunjian \
python scripts/tts_build.py
```
产出 public/assets/<slug>/audio.wav + src/common/timeline.ts（TOTAL_FRAMES 自动写入）+ script/timeline.json。改任何配音参数都会全量重合成（约 3–4 分钟），缓存键含方案版本。
分镜：按 timeline.json 逐句/逐块排镜头表（镜头区间、节拍帧、画面描述、动效、白名单）。输出两份：人读的 script/分镜表.md + 机器读的 script/beats.json（{shots: {SCxx: {range, beats: [{old, text}]}}}）。
打样：先渲前 30 秒（bundle + --frames=0-899），请用户确认风格与配音节奏。时间轴在此锁死——之后配音再变就要全片重映射（用 remap_beats.py，见 lessons §3）。
并行构建：按章分组派 agent（每组 5–7 镜），prompt 内嵌帧区间/节拍/白名单/数字事实/验证闭环（tsc 零错误 + motion_check 0 failing + BUILD_NOTES）。约定见 lessons §5、§7。
渲染：npx remotion bundle + npx remotion render <bundle> Video <out.mp4> --codec=h264 --crf=16 --concurrency=6 --timeout=300000。
成片级 QC（三轮以内收敛）：ffmpeg 抽帧到全新版本化目录 → motion_check.py --frames <目录> → 不达标镜头按 lessons §4 诊断修复（离场曲线前载 / hold 窗口动作预算 <800px / quietK 安静期）→ 重渲复测 → 交付三件套（mp4 + sheet HTML + 交付说明，注明用户特殊要求的落实情况）。

关键约定速查

帧号：组件内 const N = useCurrentFrame() + F0；帧从 1 起（Sequence from = shot.from − 1）。
导入来源：scaleIn/SoftIn/exitOp ← ui；countTo/ghostOpacity/setPiece ← fx；GlitchIn/缓动 ← common。
GlitchIn/扫光是稀缺资源：每镜 ≤1 处，且仅白名单镜头；全片扫光 ≤2 处。
动效预算：入场后完全静止 ≤3s；末拍落位 30–45 帧稳定期；hold 窗口全分辨率变化像素 <800。
片尾不署名（用户偏好，builtBy: ''）。
字幕带 y637–690 不放内容；有流程轨的章主区 y175–620。