Video Edit

素材加工与拼接（video-edit）

适用场景

用户提供（或指定复用）已有视频素材，要求做简单后处理：

• 抽取素材片段、把几段素材合并成一片、补片头片尾
• 给素材加背景音乐、旁白配音
• 烧录字幕
• 看画面挑精彩片段剪成集锦（画面集锦）
• 把编号好的片段合成最终成片

不适用：

• 从零生产一个完整视频（出脚本、规划分镜、端到端制作）→ 委托 content-producer
• 口播/演讲类视频按说话内容去口气词或剪高光 → 走 talking-head-cut
• 录制产品操作视频 → 走 ui-demo

所有子命令统一走 video-edit <子命令> [参数...]，每个子命令支持 --help 查看完整参数。

工作区目录准备

平台内容直接用对应平台运营项目目录 <platform>/outputs/<video-name>/ 作为 project-dir（平台专家包 workflow 已建好）；其他零散任务在 output_videos/ 下创建项目文件夹，如 output_videos/<topic-en-slug>/。

工作区结构：

<project-dir>/
├── raw_materials/        # 用户提供的原始内容，或者从别处拷贝过来的复用素材
├── downloads/            # 下载的内容
├── generations/          # AIGC产物
├── frames/               # 画面集锦抽帧产物（仅画面集锦流程用）
├── artifacts/            # 最终定稿需要使用的素材片段
│   ├── 01_xxx.mp4        # 按编号排序的视频片段
│   ├── 02_xxx.mp4
│   └── ...
├── previews/              # 逐段确认用压缩预览（仅用于发聊天确认，不参与合成）
│   └── NN_xxx_preview.mp4
└── video.mp4              # 最终成品

只按实际用到的能力建对应子目录，不必全建。

素材补充（按需）

仅当用户素材不足、且补充是为了完成本次组装时才补：

• AIGC 生成：使用公共 aigc-video-gen 技能（百炼/火山声画同出，详见其 SKILL.md）
• Stock Footage：AIGC 不可用或用户要求不用 AIGC 时，用公共 pexels-footage 搜索下载（9:16 竖屏优先），无结果再用 pixabay-footage

素材下载规则：

• 一次只下载一个视频
• 时长精准匹配（按目标片段时长设置 --min-duration / --max-duration）
• 下载后按片段编号重命名，放入 artifacts/

能力一：抽段与拼接（extract）

从 MP4 抽片段（head/tail/slice）并可选多段拼接为一片。补片头片尾也走这里（片头/正片/片尾按序作为多段拼接）。

# 单段抽取：取开头 6 秒
video-edit extract -i input.mp4 --mode head --seconds 6 -o out.mp4

# 多段拼接：a 的开头 6s + b 的 10-20s + 完整片尾
video-edit extract \
    --segment input=a.mp4 mode=head seconds=6 \
    --segment input=b.mp4 mode=slice start=10 end=20 \
    --segment input=outro.mp4 mode=head seconds=999 \
    -o out.mp4

要点：

• --mode：head 开头 / tail 结尾 / slice 中段（start/end）
• 默认统一到 720x1280@30fps；--keep-resolution 保持首段分辨率
• --audio speech.mp3 可在拼接时替换音轨；--no-audio 出无声片
• 时间量支持 6 / 6s / 1m30s 写法

能力二：按编号合成成片（assemble）

把 artifacts/ 下按数字前缀排序的片段拼成最终成片。

⚠️ 合成前必须先清理废弃片段：逐段确认过程中产生的废弃版本（如 02_choose_path.v1_bad.mp4）和正式片段共用同一数字前缀，会被当成对应段一起拼进去，导致成片重复/错乱。合成前先删除或移出 artifacts/：

# 把废弃版本移到 artifacts/_deprecated/ 子目录（assemble 非递归扫描，子目录不参与拼接）
mkdir -p <project-dir>/artifacts/_deprecated
mv <project-dir>/artifacts/*.v*_*.mp4 <project-dir>/artifacts/_deprecated/ 2>/dev/null

清理后确认 artifacts/ 顶层只剩 01_*.mp4 … NN_*.mp4 每段一个正式片段，再合成：

video-edit assemble <project-dir>/artifacts/ --output <project-dir>/video.mp4

合成规则：

• 按文件名数字前缀（01_、02_…）顺序拼接，同一前缀内按文件名字典序
• 无外部音频文件：保留每段视频自带音轨拼接；个别无音轨的片段自动补静音，不会把成片变无声
• 有外部音频文件（speech.mp3 等）：外部音频替换视频原音轨
• --transition crossfade 可开段间交叉淡化（默认 none 硬切）
• 不烧录字幕（需要字幕的话合成后走能力四）

合成后确认 video.mp4 存在且非空。

能力三：配音配乐（audio-mix）

给已有视频加旁白和/或背景音乐：

# 加 BGM（循环/裁剪到视频时长，默认 0.25 音量垫底，结尾 2s 淡出）
video-edit audio-mix input.mp4 --bgm music.mp3 --output out.mp4

# 加旁白（默认替换原音轨；--original-volume 0.3 可保留原音轨垫底）
video-edit audio-mix input.mp4 --narration speech.mp3 --output out.mp4

# 旁白 + BGM
video-edit audio-mix input.mp4 --narration speech.mp3 --bgm music.mp3 --output out.mp4

旁白音频的生成：

1. 优先使用 OpenClaw 内置 TTS 工具（tts_generate 或 agent 内置语音合成能力）
2. 内置 TTS 不可用时，使用公共 awk-tts 技能（火山方舟豆包语音合成 2.0，要求环境变量已配置 VOLC_TTS_* 凭据）
3. 旁白时长必须与视频时长匹配（TTS 语速可微调以适配），混音前先核对两者时长

BGM（--bgm 文件）的来源：

• ✅ 优先公共 bgm-library 技能：ccMixter 免版税曲库（CC BY / CC BY-SA，商用安全），免 key、自动署名。bgm-library pick "<主题>" --output <project-dir>/audio/ 选曲下载后传给 --bgm
• 需要定制风格 / ccMixter 无匹配时，用公共 aigc-video-gen music（MiniMax 生成，需 MINIMAX_API_KEY）
• 用户自带曲目直接用；成片发布时必须把 bgm-library 产出的 ATTRIBUTION.txt 附到视频简介（CC 协议法律要求）

能力四：字幕烧录（subtitles）

video-edit subtitles input.mp4 subs.srt --output out.mp4

• 接受 .srt（统一样式：白字黑描边，--font-size / --margin-v / --position bottom|top 可调）或 .ass（自带样式）
• 字幕文件来源：用户提供；用户只给文案没给时间轴时，由 agent 按片段时长手写 SRT（时间轴与画面/旁白对齐后再烧）
• 视频会重编码，音频不动

能力五：画面精彩集锦（frames + apply-cut）

对无人声或以画面为主的素材（运动、旅拍、活动记录、游戏录屏等），看画面挑精彩片段剪成集锦。口播/演讲类按说话内容剪的活不走这里，走 talking-head-cut。

Step 1：抽帧

video-edit frames <source.mp4> --interval 3 --output-dir <project-dir>/frames

• 每 --interval 秒抽一帧（默认 3s），超过 --max-frames（默认 100）自动放大间隔
• 产物：frames/frame_NNNN_<t>s.jpg（帧名带时间戳）+ frames/index.json

Step 2：看图定精彩窗口，写 cut_plan.json

用 Read 工具逐帧看图（帧名里的时间戳就是该帧在源视频中的位置），识别精彩窗口：动作高潮、场景切换、情绪峰值、构图出彩的段落。然后把结论写成 <project-dir>/cut_plan.json：

{
  "ok": true,
  "source": "source.mp4",
  "duration": 300.0,
  "mode": "visual-highlight",
  "plan": [
    {"keep": true,  "start": 21.0, "end": 33.0, "reason": "highlight"},
    {"keep": false, "start": 33.0, "end": 87.0, "reason": "normal"},
    {"keep": true,  "start": 87.0, "end": 99.0, "reason": "highlight"},
    ...
  ]
}

写 plan 的要求：

• 段边界取抽帧时间戳附近的整数秒即可；精彩动作两侧各留 1–2s 余量，避免掐头去尾
• 全部段（keep + remove）必须首尾相接覆盖 0 → duration，不留空洞
• keep 段总时长贴近用户目标时长；差距 >20% 时调整窗口选择，或用更小 --interval 重抽再定
• reason 只用 highlight（keep=true）/ normal（keep=false）

Step 3：用户确认 plan（关键闸门）

cut_plan.json 落盘后必须先让用户确认再剪：报告 keep 段数、各段起止与挑选理由（画面内容）、keep 段总时长。用户认 plan 后才剪。

Step 4：剪拼 + 自检

video-edit apply-cut <source.mp4> <project-dir>/cut_plan.json \
    --output <project-dir>/highlight.mp4 --fade-ms 40
video-review <project-dir>/highlight.mp4

逐段确认预览（preview）

需要把大文件发聊天让用户逐段确认时，先压预览（产物仅用于确认，不参与合成）：

video-edit preview <input.mp4> --output <project-dir>/previews/<NN>_preview.mp4

默认压到 ≤16MB，--target-mb 可调。

成片自检（强制闸门）

任何成片（assemble / apply-cut / audio-mix / subtitles 的最终产物）交付前必须跑：

video-review <project-dir>          # 审 <project-dir>/video.mp4 + artifacts/ 段一致性
video-review <final.mp4>            # 或直接审单个成片文件

verdict=pass 才交付；fail 按 critical 项修复后重审；warn 向用户复述由其决定。详见 video-review 技能 SKILL.md。

制作封面

每个成片视频都必须配封面图。封面要求：

• 必须包含视频标题文字，不允许纯图片封面
• 标题文字必须有设计感（字体选择、排版布局、颜色搭配）
• 竖屏封面 1080x1920
• 可以使用视频关键画面作为背景，但文字是必须元素

使用公共 siliconflow-img-gen 技能制作封面，保存为 <project-dir>/cover.jpg。

仅对交付成片的项目做封面；中间加工产物（如只是帮用户给一段素材加 BGM）不需要封面。

用户确认

向用户展示：

• 成品视频（发文件本体）
• 封面图（发文件本体，如有）
• 关键参数（时长、分辨率、片段数）

用户确认后，流程结束。后续发布由各平台发布技能执行。

子命令清单

禁止事项（强制）

违反以下任何一条都会导致系统死机或产出异常，必须严格遵守：

• 禁止直接写 ffmpeg 命令：不得在 exec 中直接调用 ffmpeg/ffprobe，也不得写 Python 脚本内嵌 ffmpeg 调用。所有视频处理一律通过 video-edit 子命令完成
• 禁止从静态图生成视频：不得将 JPEG/PNG 等静态图片转为 MP4。用户提供的静态图片仅作为 AIGC 参考图或搜索风格参考
• 禁止跳过 video-review 交付：成片交付前必须自检，verdict=pass 才交付
• 禁止代用户出脚本：本技能不写视频脚本、不规划分镜；用户要从零做视频时转介 content-producer