kajisho5/remotion-ffmpeg-skill

remotion-ffmpeg-skill 是做什么的？

ffmpeg-skill 测量 → Remotion 绘制 → ffmpeg-skill 检查并交付。 脚本位于此文件旁边的 scripts/ 目录中；使用 python3 <skill-dir>/scripts/<name>.py 运行。--help 可查看脚本的完整参数列表；references/timeline.md 描述了时间线格式以及每个构图接受的选项。

此技能依赖于 ffmpeg-skill（位于此技能旁边，~/.claude/skills/ffmpeg-skill 中，或通过 FFMPEG_SKILL_DIR 指定）。它从不自己运行原始的 ffmpeg/ffprobe 命令：测量、检查和交付都通过 ffmpeg-skill 的脚本完成，因此其保证得以延续。

共享标志（所有脚本）：--json（在标准输出上输出一个 JSON 对象；推荐使用）、--dry-run（仅规划，不写入文件）、--overwrite（覆盖现有输出的唯一方式）、--timeout SECONDS。

工作流程（按此顺序）

1. 初始化项目。 如果没有 Remotion 项目：init.py ./motion --install（复制模板，运行 npm install；Remotion 的无头浏览器会在首次渲染时下载）。如果已有此技能创建的项目，则直接复用。
2. 测量。 analyze.py SOURCE [--captions FILE.srt] [--beats] -o SOURCE.timeline.json。阅读摘要和 warnings：可变帧率（VFR）或高动态范围（HDR）源必须在开始绘制前使用 ffmpeg-skill 修复（color.py --to-sdr、恒定帧率导出）——Remotion 在固定帧网格上渲染 SDR。切勿手动编辑时间线数字；而是重新测量（--threshold、--min-silence 适用于安静环境）。
3. 预览静态帧。 still.py --project ./motion --comp NAME --timeline TL --at 1.5 --at 6 并查看 PNG 图像：字幕位置、放大效果、颜色。成本低廉，建议在完整渲染前进行。
4. 渲染。 render.py --project ./motion --comp NAME --timeline TL [--options look.json] -o OUT.mp4（--fast = 半尺寸预览，--frames 0-89 = 指定帧范围，--codec prores -o master.mov = 母版）。它会根据时间线验证输出（帧数、帧率、尺寸、音频），如果不匹配则非零退出。
   • 画面比例： 以最终交付的画面比例绘制。面向 Reels / TikTok / Shorts 使用 --aspect 9:16（也支持 1:1、4:5、16:9）；--fit blur（画面比例改变时的默认值：内容配合模糊背景）、contain（黑边）或 cover（裁剪——请先通过静态帧检查主体）。切勿渲染 16:9 然后让 9:16 模板裁剪：字幕边缘会丢失。pipeline.py --platform 会根据 ffmpeg-skill 模板自动为你选择画面比例。
   • 字体： 日文/中文/韩文字幕会自动使用 ffmpeg-skill 在机器上找到的 CJK 字体（预置到项目中，避免豆腐框）；--font-file F.ttf 使用指定的字体；报告中的 font: 行显示使用的字体，或提示未找到字体。
   • 编辑软件图层： --overlay --keep-graphics（Captioned / PeakPulse，原始画面比例）仅以透明 ProRes 4444 格式绘制图形，生成 .graphics.mov，然后使用 ffmpeg-skill overlay.py 将其合成到未修改的原始视频上；将 .mov 交给在 Premiere / Resolve / Final Cut 中进行后期制作的工作人员。这不比普通渲染更快。
5. 交付。 deliver.py OUT.mp4 --platform youtube|reels|tiktok|shorts|x|... 运行 ffmpeg-skill 的交付模板及其 check.py 表。格式行可安全修复；判断行（时长、画面比例）涉及内容变更——需询问用户。提及警告，但无需追究。未指定目标平台：跳过此步骤并告知用户。
6. 检查。 在回复中必须提到 render.py 创建的联系人列表（Look: PATH）以及它所显示的内容。机械性检查（查看并报告）：文字是否位于要求的位置，提示是否在其时间点出现，内容是否被画面边缘裁剪。判断性检查（你说你看到了什么，由用户决定）：文字是否遮挡面部、跳切是否效果不佳。无图像查看：Look: PATH (pixels not inspected)——切勿声称你查看了。无联系人列表（结果中包含 look_error，例如 FFmpeg 缺少 drawtext 过滤器）：改为查看 still.py 帧，并向用户传递错误名称中指示的修复方法。

选项文件在渲染前会进行检查：未知键或错误类型会被拒绝（kind: input），而不是静默忽略。

MCP：mcp/server.py 公开相同的工具（模式来自 scripts/_contract.py，contract --json 会打印它们）。

一气呵成：pipeline.py SOURCE --project ./motion --comp NAME [--captions F] [--platform P] 依次运行 2→4→5 步，应用相同的检查，并在第一步失败时停止。

请求 → 脚本 / 构图

请求	运行
"在此视频上添加动画字幕/字幕"	analyze.py --captions → render.py --comp Captioned
"剪切静音段/跳切/紧凑此讲话"（带运动效果）	analyze.py → render.py --comp Jumpcut（如果提供了字幕，则会重新定时）
"图形响应音频/在节拍上跳动/在切换时触发"	analyze.py [--beats] → render.py --comp PeakPulse（如果测量了节拍网格，则在节拍上脉冲）
"卡拉OK字幕/单词在说话时高亮"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke（单词时间来自本地语音引擎、whisper JSON；没有 SRT 时，提示根据单词分组）
"下方三分之一条/名字标题/章节标题"	render.py --comp Titled --options，包含 lowerThirds / sceneTitles——文本来自用户；请向用户询问，切勿编造名字
"精彩集锦/最佳时刻"	analyze.py --highlights N [--target S] → render.py --comp Highlights（音频能量排序：给出候选建议，告知用户）
"按节拍剪辑/音乐蒙太奇"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage（音频不间断，画面在每 beatsPerCut 个测量节拍处切换；如果节拍网格不可靠，则在场景切换处切换）
"用于 YouTube / Reels / TikTok ..."	pipeline.py --platform（以模板的画面比例渲染，然后交付并检查），或 render.py --aspect + deliver.py --platform
"竖屏/9:16/方形"	render.py --aspect 9:16（或 1:1、4:5）
"日文字幕" / 指定字体	CJK 自动字体无需额外操作；--font-file 用于选择字体
"将图形作为独立图层提供给我"	render.py --overlay --keep-graphics
"更改颜色/字体/字幕大小/缩放"	使用 --options JSON（references/timeline.md），重新渲染
多个剪辑（"开场 + 讲话 + 结尾"）	analyze.py A.mp4 B.mov C.mp4（或 pipeline.py 使用多个输入）：ffmpeg-skill join.py 会标准化并合并它们，然后在合并后的文件上进行所有测量
"预览" / "显示一帧"	still.py
一种新的图形	在项目的 src/ 中添加一个读取 src/timeline.ts 中 Props 的构图；使用 --comp YourId 渲染（render.py 会报告测量的数字，而无需内置期望）
仅剪切/修剪/调整大小/调节响度，无图形	不属于此技能：直接使用 ffmpeg-skill
出错了	doctor.py [--project DIR]

此技能决定的内容和不确定的内容

• 决定（机械性）： 构图时长、帧率和尺寸（来自探测）；剪切位置（来自测量的静音段）；提示显示时间（来自字幕文件）；脉冲触发时间（来自测量的峰值）；渲染是否与其时间线匹配。
• 不确定： 名字、标题和章节名称（下方三分之一条和场景标题是用户的文本——请询问），字幕所说的词语——提示文本完全按原样绘制，绝不缩写或转述，即使为了"适应"（请建议更小的 captionSize）；什么算作精彩集锦；检查结果是否良好。这些属于用户或调用的代理。
• 绝不编造数据。 没有用户提供的定时字幕文件或本地语音转文本引擎，就不生成字幕；没有 --beats 测量的节拍网格，就不使用它。

避免任务失败的规则

• Remotion 许可证：对个人和最多 3 名员工（含）的营利性组织免费；规模较大的公司需要 Remotion 公司许可证（https://www.remotion.dev/license）。如果用户明确是规模较大的公司，请告知一次。
• 保留用户的原始文件：源文件链接到项目的 public/media/ 中，绝不修改；输出文件不会覆盖现有文件，除非使用 --overwrite。
• CJK 字幕：自动字体来自 ffmpeg-skill 的字体检测；当报告显示未找到字体时，请安装一个（Noto Sans CJK）或传递 --font-file——联系人列表中的豆腐框是失败的任务。日语文本在短语之间换行，而不是在单词内部。
• 速度（在双核 Linux 机器上进行测量，使用所有核心——render.py 的默认设置）：约 2.6 倍片段时长（30 秒片段耗时 80 秒）。在完整渲染长片段前，使用 still.py 和 --fast 进行预览；在开始长时间渲染前，告知用户预计时间。--concurrency 超过核心数会被 Remotion 拒绝。
• 项目中的 Remotion 包必须版本一致；模板已固定版本。不要混入不同版本的 remotion。
• 未通过验证的渲染视为失败：从 --json 报告失败的行，不要交付。