beat-sync-video-editing

节拍同步视频剪辑

用途

为创建节拍同步的视频剪辑提供领域专业知识：选取源视频和音轨，从视频中挑选与音乐节奏相符的片段，并使用 FFmpeg 渲染最终成片。

核心概念：EditPlan

每次剪辑都从 EditPlan 开始——这是一种 JSON 结构，用于描述要使用哪些视频片段，以及将它们放在音频中的什么位置：

{
  "audio_start": "00:13",
  "audio_duration": 6.5,
  "clips": [
    { "video_start": "00:08", "duration": 2.0, "description": "Opening shot" },
    { "video_start": "00:45", "duration": 1.5, "description": "Action moment" },
    { "video_start": "01:22", "duration": 3.0, "description": "Build-up" }
  ],
  "reasoning": "Matches rising intensity with beat drops"
}

时间戳格式： audio_start 和 video_start 使用 MM:SS 字符串（例如，"01:15" 表示 1 分 15 秒）。audio_duration 和片段 duration 使用以秒为单位的数字。

关键约束：

• audio_start 必须是有效的 MM:SS 格式，且为非负值
• audio_duration 必须为正数（秒）
• 每个片段的 video_start 必须是有效的 MM:SS 格式，且 duration 必须为正数（秒）
• 所有片段的时长总和必须等于 audio_duration（误差不超过 0.5 秒）
• 片段顺序是有意安排的——不一定按时间顺序排列。非线性排序能让剪辑更具动感。

工作流：从文件到最终视频

步骤 1：通过 Gemini 生成 EditPlan

运行 Gemini 脚本，分析视频和音频并生成计划：

# Fresh upload (default: files kept 48h for reuse, ECLIPTIC_FILES printed on stderr):
bash ${CLAUDE_PLUGIN_ROOT}/scripts/gemini-edit-plan.sh \
  --video <video_path> \
  --audio <audio_path> \
  --prompt "<user's edit description>"

# Reuse previously uploaded files (skips upload, much faster):
bash ${CLAUDE_PLUGIN_ROOT}/scripts/gemini-edit-plan.sh \
  --video-uri <uri> --video-mime <mime> \
  --audio-uri <uri> --audio-mime <mime> \
  --prompt "<different description>"

# One-shot mode (delete files immediately after use):
bash ${CLAUDE_PLUGIN_ROOT}/scripts/gemini-edit-plan.sh \
  --video <video_path> \
  --audio <audio_path> \
  --prompt "<description>" --cleanup

• 将 EditPlan JSON 输出到 stdout，将进度输出到 stderr
• 需要 GEMINI_API_KEY、curl 和 jq
• Gemini 会同时观看视频并聆听音频

支持的格式（Interactions API 会强制执行这些格式要求，不支持的格式会被拒绝）：

• 视频：mp4、mov、avi、mpeg、mpg、webm、wmv、3gpp（不支持 mkv——请参阅故障排除）
• 音频：mp3、wav、aac、ogg、flac、m4a、opus、aiff

文件生命周期。 默认情况下，脚本会保留已上传的文件，方便后续运行复用，无需重新上传。Gemini 会强制执行 48 小时的 TTL，过期后 URI 将失效，必须重新上传。每次运行都会在 stderr 中输出一行 ECLIPTIC_FILES JSON，其中包含 video_name、audio_name、URI 和 MIME 类型；请捕获这行内容，以便通过 --video-uri / --audio-uri 进行迭代。每次新上传运行结束时，脚本还会打印准确的 cleanup-gemini-files.sh 命令，方便明确删除文件并直接复制粘贴执行。如果丢失了 ECLIPTIC_FILES 行，运行 bash ${CLAUDE_PLUGIN_ROOT}/scripts/list-gemini-files.sh 即可列出当前所有已上传文件的名称、URI、MIME 类型和过期时间。如需将默认行为改为一次性删除，请传入 --cleanup，或在环境中导出 GEMINI_CLEANUP=1。--no-cleanup 是一个无操作别名，与默认行为相同。

模型选择。 脚本默认使用 gemini-3.6-flash。如需使用其他模型，请在调用前导出 GEMINI_MODEL：

export GEMINI_MODEL=gemini-3.1-pro-preview   # stronger reasoning, slower
# or
export GEMINI_MODEL=gemini-3.5-flash-lite    # cheaper/faster for simple edits

模型名称会直接传入请求正文，因此任何支持视频和音频输入以及结构化 JSON 输出的 Gemini 模型都可以使用。请避免使用已弃用的 gemini-2.x 和 gemini-1.5 模型。

调优（可选环境变量）。 两者默认均不设置，此时会使用 API/模型的默认值：

export GEMINI_MEDIA_RESOLUTION=high    # low | medium | high | ultra_high
export GEMINI_THINKING_LEVEL=medium    # minimal | low | medium | high

• GEMINI_MEDIA_RESOLUTION — 控制模型能看到的每帧视觉细节程度。较高的值能提升模型对细节丰富的视频素材的片段选择效果，但会增加 token 成本。
• GEMINI_THINKING_LEVEL — 控制模型对剪辑方案进行推理的时长。对于简单剪辑，minimal 速度最快、成本最低；对于复杂的节奏安排要求，high 效果更好。

API 说明。 脚本会调用 Gemini Interactions API（POST /v1beta/interactions），将视频和音频作为带类型的输入部分传入，并通过 response_format 强制执行 EditPlan 架构。请求使用 store: false 发送，因此交互不会保留在服务端（上传的文件是单独处理的——请参阅上文的文件生命周期）。

步骤 2：验证计划

echo '<plan_json>' | bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plan.sh

• 输出 {"valid": true, "errors": []} 或 {"valid": false, "errors": [...]}
• 退出代码 0 = 有效，1 = 无效

步骤 3：构建 FFmpeg 滤镜

echo '<plan_json>' | bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-filter.sh

• 输出 {"videoFilter": "...", "audioFilter": "...", "fullFilter": "..."}
• fullFilter 字段即为传入 FFmpeg -filter_complex 参数的内容

步骤 4：使用 FFmpeg 渲染

ffmpeg -y -i "<video_path>" -i "<audio_path>" \
  -filter_complex "<fullFilter>" \
  -map "[outv]" -map "[outa]" \
  -c:v libx264 -preset fast -crf 23 \
  -c:a aac -shortest \
  "<output_path>"

FFmpeg 滤镜结构

对于 3 段素材的剪辑，fullFilter 如下所示：

[0:v]trim=start=8.000:duration=2.000,setpts=PTS-STARTPTS[v0];
[0:v]trim=start=45.000:duration=1.500,setpts=PTS-STARTPTS[v1];
[0:v]trim=start=22.000:duration=3.000,setpts=PTS-STARTPTS[v2];
[v0][v1][v2]concat=n=3:v=1:a=0[outv];
[1:a]atrim=start=13.000:duration=6.500,asetpts=PTS-STARTPTS[outa]

• [0:v] = 第一个输入（视频），[1:a] = 第二个输入（音频）
• trim 提取片段，setpts=PTS-STARTPTS 重置时间戳
• concat 按顺序拼接所有视频片段
• atrim 提取音频片段

完整的 FFmpeg 滤镜参考，请参阅 ${CLAUDE_SKILL_DIR}/references/ffmpeg-filters.md。

故障排除

时长不匹配错误：片段时长总和与 audio_duration 不符。调整最后一个片段的时长以弥补差值，或使用更严格的提示词重新运行 Gemini。

FFmpeg 在 stderr 中显示“Error”：FFmpeg 会将进度和警告写入 stderr。只有在未创建输出文件时，才应将其视为真正的错误。检查是否存在 No such file、Invalid data 或 Conversion failed 等实际错误模式。

不支持的格式（.mkv）：Interactions API 不接受 Matroska。请先无损重新封装：ffmpeg -i input.mkv -c copy input.mp4。

文件 URI 过期：上传的文件会在 48 小时后过期。如果使用 --video-uri/--audio-uri 重用文件的运行因 Gemini 报告文件错误（例如找不到文件或权限被拒绝）而失败，则 URI 已失效；请使用 --video/--audio 本地路径重新运行，以重新上传文件。

Gemini 返回的片段效果不佳：在提示词中增加具体要求。不要只说“制作一段剪辑”，可以改为“制作一段节奏快速的 30 秒动作剪辑，每隔 1-2 秒跟随节拍落点切换画面，从副歌部分开始”。

其他资源

参考文件

• ${CLAUDE_SKILL_DIR}/references/ffmpeg-filters.md — 详细介绍 FFmpeg filter_complex 语法、编码选项和常用标志
• ${CLAUDE_SKILL_DIR}/references/edit-plan-schema.md — 完整的 EditPlan JSON 架构、验证规则和边缘情况

脚本

• ${CLAUDE_PLUGIN_ROOT}/scripts/gemini-edit-plan.sh — 通过 REST API 上传到 Gemini 并获取 EditPlan（支持 --cleanup，以及通过 --video-uri/--audio-uri 重用已上传文件）
• ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plan.sh — 验证 EditPlan JSON
• ${CLAUDE_PLUGIN_ROOT}/scripts/build-filter.sh — 将 EditPlan 转换为 FFmpeg 滤镜
• ${CLAUDE_PLUGIN_ROOT}/scripts/list-gemini-files.sh — 列出已上传文件的名称、URI 和过期时间
• ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-gemini-files.sh — 完成迭代后，从 Gemini 删除已上传的文件