建议:加载 Remotion 最佳实践
本技能建议配合
remotion-best-practices(未捆绑)使用以获取完整的 Remotion 模式库。该功能是可选的——若未安装,可使用下方最低规则。
- Pi:从已加载的技能列表中读取
remotion-best-practices。- Claude Code:在继续之前调用
remotion-best-practices技能/工具。未安装?请从 remotion-dev/skills 获取(文档:remotion.dev/docs/ai/skills)。
如果未安装
remotion-best-practices,最低规则:必须可用 Chromium,始终将4K内容包装在<Scale4K>中,使用linearTiming的<TransitionSeries>,并将音频作为主时钟。
视频播客制作工具 是做什么的?
从主题自动生成 4K Bilibili 横向知识视频 的流水线。包含编码代理、TTS 后端、Remotion 和 FFmpeg。
目录
- 引导 — 先决条件(在步骤1之前运行)
- 执行模式 — 自动模式 vs 交互模式 → references/workflow-script.md
- 重新生成现有视频 — 在已完成视频上迭代
- 工作流程 — 11步流水线 + 阶段文件指针 + 强制停止点
- 硬性规则 — 不可协商的生产约束
- 音频-主时钟与同步
- 每视频布局
- 额外资源 — 何时加载每个
references/文件 - 用户偏好
- 故障排除
引导
将 SKILL_DIR 设置为包含此 SKILL.md 的目录:
- Pi:代理从已加载的技能列表中知道技能路径——在运行命令前将
SKILL_DIR设置为该目录。 - Claude Code:
${CLAUDE_SKILL_DIR}自动填充。
SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
# 先决条件(CLI + 后端环境变量)
python3 "${SKILL_DIR}/scripts/check_prereqs.py"
更新通过 skills CLI 进行 (npx skills update video-podcast-maker -g);直接 git-clone 安装则按 README 使用 git pull。本技能不执行更新检查。
先决条件失败 — 请参阅 README.md 了解设置。检查是支持后端的(解析 TTS_BACKEND 环境变量 → user_prefs.json global.tts.backend → 默认 edge),因此只有活动后端所需的环境变量会被验证。
新项目中的第一个视频? 建议重用已有的包含 node_modules/ 的 Remotion 项目——创建新项目将下载约 2.2 GB 的 npm 包和 90 MB 的 Chrome headless shell(每个项目一次性)。如果用户有之前视频的项目,请使用它。如果需要新项目,在您执行步骤 1-4(主题研究和脚本编写)时在后台运行 npm install。
所有渲染输出放入 videos/{name}/ — 每个 output.mp4、final_video.mp4 和 thumbnail_*.png 都直接放入每个视频的目录。绝不要渲染到 out/ 或 dist/ 目录;--public-dir videos/{name}/ 约定保持一切自包含。
TTS 引擎 — 两个本地后端,无需外部技能:
edge(默认)— 免费,无需密钥,通过 edge-tts 实现。azure— 需要AZURE_SPEECH_KEY+AZURE_SPEECH_REGION(Microsoft Speech SDK)。
每个都在内部合成(scripts/tts/backends/native.py)——发音(显示 → 朗读 → 回到显示用于字幕)和音素应用均已内置。check_prereqs.py 验证活动后端的环境变量。
多平台 TTS? 先前提供9后端矩阵的 ttscn 组件技能不再是本技能的依赖项。如果您需要这些平台,请单独安装 Agents365-ai/ttsCN 并直接调用它——本技能仅捆绑 edge + azure。
设计学习捷径:如果用户提供了参考视频/图片或要求保存/列出/删除样式配置文件,请参阅 references/design-learning.md 而不是运行下方的工作流程。
执行模式
在工作流程开始时检测自动模式(默认)与交互模式——自动模式默认决策表和每次请求的覆盖规则见 references/workflow-script.md。
重新生成现有视频
如果 videos/{name}/ 已存在,并且用户正在迭代一个已完成或进行中的视频,请重用该目录。不要启动新项目或新的 videos/{newname}/。
根据实际更改的内容选择最小的重新运行:
| 更改内容 | 重新运行 | 重用(不重做) |
|---|---|---|
旁白脚本 (podcast.txt) | 步骤 7(TTS)→ 步骤 8 预览 → 渲染+混音 | 主题研究 + 章节设计 |
| 仅视觉(组件、布局、颜色) | 步骤 8 预览 → 渲染+混音 | 音频(podcast_audio.wav / timing.json) |
| 仅背景音乐 | 重新混音 BGM | output.mp4(无需重新渲染) |
| 仅字幕 | 步骤 10.1 最终化 | output.mp4 / video_with_bgm.mp4 |
任何更改观众看到或听到内容的重新运行都要再次通过步骤 8 的门控:应用更改,让 Studio 热重载,然后等待新的明确“渲染 4K”确认——之前的确认不再适用。脚本更改会改变每个下游时间戳,因此始终通过 TTS 重新生成 timing.json——绝不要手动编辑。在任何重新运行后,重新验证:
python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/
工作流程
在已完成视频上迭代? 如果
videos/{name}/已存在,请参阅上方的 重新生成现有视频 以获取最小重新运行——不要从步骤 1 开始。
在步骤 1 开始时,在代理的任务跟踪器中为每个步骤创建一个任务。开始标记为 in_progress,完成标记为 completed。videos/{name}/ 中的文件是持久的记录——如果中断,检查目录以确定从哪里恢复。
| # | 步骤 | 输出 | 阶段文件 |
|---|---|---|---|
| 1 | 定义主题方向 | topic_definition.md | workflow-script.md |
| 2 | 研究主题 | topic_research.md | workflow-script.md |
| 3 | 设计 5-7 个章节 | (内存中) | workflow-script.md |
| 4 | 编写旁白脚本 | podcast.txt | workflow-script.md |
| 4.5 | 发音预检(zh-CN) | phonemes.json | workflow-script.md |
| 5 | 资产计划与解析 | assets/manifest.json | workflow-assets.md |
| 6 | 生成缩略图(16:9 + 4:3) | thumbnail_*.png | workflow-production.md |
| 7 | 生成 TTS 音频 | podcast_audio.wav, timing.json | workflow-production.md |
| 8 | Remotion 合成 + Studio 预览 | — | workflow-production.md |
| 9 | 渲染 4K + 混音 BGM | output.mp4, video_with_bgm.mp4 | workflow-production.md |
| 10 | 发布信息 + 验证输出 | publish_info.md, final_video.mp4 | workflow-publish.md |
| 11 | 生成竖版短视频(可选) | shorts/ | workflow-publish.md |
强制停止点(上方加粗行):
- 步骤 8 — Studio 审查。 必须启动
npx remotion studio并等待用户反馈后再渲染。在用户明确确认(“渲染 4K” / “渲染最终版”)之前,绝不要渲染 4K。包含调整请求的回复不是确认——应用更改,让 Studio 热重载,然后再次询问。每一轮调整都需要自己的新确认,然后再进行步骤 9。 - 步骤 10 —
verify_output.py。 必须通过才能宣布视频完成。退出码 0 = 通过;退出码 2 = 有警告但仍可发布。自动修复常见遗漏(如果缺失则创建final_video.mp4)。针对平台矩阵验证发布信息(标题、描述、标签、章节)——在步骤 5.5 和 10.2 中生成。要获得机器可读的输出,请添加--format json。
渲染前审计(推荐) — 在步骤 8 之前:
python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>
标记与旁白偏差超过 1.5 秒的节拍。
自动模式:视觉自检。 在自动模式下运行时(无用户观看 Studio),在请求渲染确认之前先渲染 3-5 个关键帧静帧:
npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<中点帧>
选择帧:起始标题(约 10% 处)、密集章节中点、结尾。将静帧作为图像读取,并对照实际渲染输出运行 design-guide.md 和 visual-taste.md 检查清单。在 4K 渲染之前捕获溢出、对比度和布局回归。审查后删除 _review_*.png。
验证检查点
| 在步骤之后 | 检查 |
|---|---|
| 7(TTS) | podcast_audio.wav 可播放 · timing.json 覆盖所有章节 · SRT 为 UTF-8 编码 |
| 9(渲染) | output.mp4 为 3840×2160 · 音视频同步 · 无黑帧 |
| 10(验证) | verify_output.py 退出码 0(或经审查的警告后退出码 2) |
硬性规则
| 规则 | 要求 |
|---|---|
| 单一项目 | 所有视频放在用户 Remotion 项目的 videos/{name}/ 下。绝不要为每个视频创建新项目。 |
| 4K 输出 | 3840×2160(或竖版 2160×3840),在 1920×1080 设计空间上使用 scale(2) 包装 |
| 音频同步 | 音频(podcast_audio.wav + podcast_audio.srt)是主时钟。timing.json 必须从真实的 TTS 输出生成,绝不要手动估算。渲染前,最终视频时长必须与音频匹配,误差在 ±0.5 秒内。参见 音频-主时钟与同步。 |
| 缩略图 | 必须同时生成 16:9(1920×1080)和 4:3(1200×900)——参见 design-guide.md |
| 先 Studio 再渲染 | 必须启动 remotion studio 进行审查。绝不要在用户明确确认前渲染 4K。调整反馈 ≠ 确认——应用更改,热重载,再次询问。 |
--public-dir | 每个 Remotion 命令都使用 --public-dir videos/{name}/。所有输出文件(output.mp4、final_video.mp4、缩略图)都直接放入 videos/{name}/——绝不要放入 out/ 或 dist/ 目录。 |
视觉最小值(文本大小、内容宽度、安全区域、动画安全)在 references/design-guide.md 中。必须在步骤 8 之前加载。
音频-主时钟与同步
黄金规则
- 音频是主时钟。 每个幻灯片开始、字幕、章节和动画节拍都源自
podcast_audio.wav和podcast_audio.srt。 - 从 TTS 生成时间轴,而不是文本估算。 流水线:
podcast.txt→generate_tts.py→podcast_audio.wav+podcast_audio.srt+timing.json→ 合成 → 渲染。 - 在音频存在之前,绝不要手动编写
timing.json。 如果您已经策划了幻灯片,请运行align_timing_from_srt.py将它们锚定到真实的 SRT。 - 补偿 TransitionSeries 重叠。
TransitionSeries渲染sum(section.duration_frames) - (N-1) * transitionFrames帧。按比例缩放每个章节,使渲染长度等于timing.total_frames。不要将所有重叠帧塞入第一个章节。修正后的模式在templates/Video.tsx中。
强制性同步检查点
| 何时 | 检查 |
|---|---|
| 步骤 7(TTS)之后 | timing.json.total_duration 与 podcast_audio.wav 匹配,误差 ±0.5 秒 |
| 渲染之前 | Video.tsx 为过渡重叠缩放所有章节 |
| 渲染之后 | final_video.mp4 时长与 podcast_audio.wav 匹配,误差 ±0.5 秒 |
| 步骤 10(验证) | verify_output.py 退出码 0 且音频/时间轴报告绿色 |
如果任何检查点失败,请停止。不要发布。
输出规格
| 参数 | 横向 (16:9) | 竖版 (9:16) |
|---|---|---|
| 分辨率 | 3840×2160 (4K) | 2160×3840 (4K) |
| 帧率 | 30 fps | 30 fps |
| 编码 | H.264, 16Mbps | H.264, 16Mbps |
| 音频 | AAC, 192kbps | AAC, 192kbps |
| 时长 | 1-15 分钟 | 60-90 秒(高亮) |
每视频布局
project-root/ # Remotion 项目根目录
├── src/remotion/ # Remotion 源码 (Root.tsx, compositions, index.ts)
├── videos/{video-name}/ # 每视频目录
│ ├── topic_definition.md # 步骤 1
│ ├── topic_research.md # 步骤 2
│ ├── podcast.txt # 步骤 4: 旁白脚本
│ ├── phonemes.json # 步骤 4.5: 中文发音覆盖
│ ├── assets/manifest.json # 步骤 5: 每章节资产注册表
│ ├── publish_info.md # 步骤 10: 标题/描述/标签
│ ├── podcast_audio.wav # 步骤 7: TTS 音频
│ ├── podcast_audio.srt # 步骤 7: 字幕
│ ├── timing.json # 步骤 7: 时间轴(驱动动画)
│ ├── thumbnail_*.png # 步骤 6
│ ├── output.mp4 # 步骤 9: 4K 渲染
│ ├── video_with_bgm.mp4 # 步骤 9: 带 BGM
│ ├── final_video.mp4 # 步骤 10: 最终输出
│ └── bgm.mp3 # 背景音乐
└── remotion.config.ts
每视频 --public-dir
每个 Remotion 命令都使用 --public-dir videos/{name}/——每个视频的资产保留在自己的目录中,支持并行渲染:
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16M
...
额外资源
在引用文件时通过相对路径加载这些文件——它们与 SKILL.md 在同一个目录中。对于 Pi/Claude Code 将文件内容读取到上下文(当触发时加载)。
| 文件 | 何时加载 |
|---|---|
| references/workflow-script.md | 步骤 1-4.5 的阶段细则(主题、脚本、发音)及执行模式 |
| references/workflow-assets.md | 步骤 5:资产清单模式、来源政策、解析步骤 |
| references/workflow-production.md | 步骤 6-9:缩略图、TTS、Remotion 合成、渲染 |
| references/workflow-publish.md | 步骤 10-11:发布信息、平台矩阵、验证、竖版短视频 |
| references/design-guide.md | 步骤 8 前必须加载:文本大小、内容宽度、安全区域、动画安全、缩略图规格 |
| references/visual-taste.md | 自动模式步骤 8 自检;作为设计审美检查清单 |
| references/design-learning.md | 替代主工作流程:当用户提供参考视频/图片或要求样式配置文件时 |
将所有 references/ 文件视为权威来源,如果出现冲突,它们优先于此 SKILL.md 中的概要部分。
用户偏好
用户偏好存储在 user_prefs.json 中。如果不存在,则在第一次运行 check_prereqs.py 时创建。手动创建:
{
"global": {
"tts": {
"backend": "edge",
"voice": "zh-CN-XiaoxiaoNeural"
},
"bgm": {
"default_volume": 0.15
},
"platforms": ["bilibili", "youtube"]
},
"videos": {
"example-video": {
"title": "我的自定义标题"
}
}
}
全局设置:
| 键 | 描述 | 默认值 |
|---|---|---|
global.tts.backend | TTS 后端:edge 或 azure | edge |
global.tts.voice | TTS 声音 | zh-CN-XiaoxiaoNeural |
global.bgm.default_volume | BGM 默认音量 (0-1) | 0.15 |
global.platforms | 发布目标平台列表 | ["bilibili", "youtube"] |
每视频设置: 覆盖特定视频的全局值。在步骤 10(发布)期间应用。
故障排除
| 症状 | 解决方案 |
|---|---|
check_prereqs.py 因缺少 Python 模块失败 | 运行 pip install -r ${SKILL_DIR}/requirements.txt |
edge-tts 运行时错误 | 确保已安装 edge-tts(pip install edge-tts)且系统具有有效的互联网连接 |
| Remotion Studio 因端口冲突无法启动 | 使用 npx remotion studio --port <free_port> |
output.mp4 音频不同步 | 运行 python3 ${SKILL_DIR}/scripts/check_audio_sync.py videos/{name}/output.mp4。如果失败,重新运行 TTS 步骤 (7)。 |
verify_output.py 退出码 2 | 查看警告——它们可能是可接受的(例如 BGM 文件已存在)。如果不确定,询问用户。 |
| NVIDIA GPU / CUDA 错误 | Remotion 使用系统的 Chrome;确保安装了 GPU 驱动程序。如果显存不足,降级到软件渲染。 |