视频剪辑工具箱（video-editor-toolbox）
基于 ffmpeg 的"剪辑操作"命令封装。一句话概括定位：成品文件公式——给素材 + 一句话，直接交付剪辑好的成品文件。
> 与"视频压缩工具箱"的分工（务必区分）
> | 技能 | 管什么 | 典型问题 |
> |---|---|---|
> | 视频压缩工具箱（video-toolbox） | 体积与平台规格 | "视频太大发不出去""压到 50MB""转抖音竖屏比例""抽帧做封面" |
> | 本技能（video-editor-toolbox） | 对内容的剪辑加工 | "剪掉开头 10 秒""把两段拼起来""加速 2 倍""转成 GIF""加个背景音乐" |
>
> 两者都基于 ffmpeg，但职责不重叠：先"剪"，再"压"。需要压缩/平台适配时请改用 video-toolbox，本技能不提供 compress 子命令。
功能 / 子命令速查
SKILL_DIR="$HOME/.workbuddy/skills/video-editor-toolbox"
[ -f "$SKILL_DIR/scripts/video_edit.py" ] || SKILL_DIR="$PWD/.workbuddy/skills/video-editor-toolbox"
[ -f "$SKILL_DIR/scripts/video_edit.py" ] || SKILL_DIR="/sandbox/workspace/skills/video-editor-toolbox"
S="$SKILL_DIR/scripts/video_edit.py"
python3 $S trim in.mp4 -o clip.mp4 --start 00:00:10 --end 00:00:30 # 截取片段
python3 $S trim in.mp4 -o clip.mp4 --start 5 --duration 8 # 截取片段（按时长）
python3 $S concat a.mp4 b.mp4 -o merged.mp4 # 拼接多个视频
python3 $S crop in.mp4 -o out.mp4 --width 720 --height 720 --x 100 --y 50 # 画面裁剪
python3 $S speed in.mp4 -o fast.mp4 --rate 2.0 # 变速（2 倍速）
python3 $S speed in.mp4 -o slow.mp4 --rate 0.5 # 慢放
python3 $S gif in.mp4 -o out.gif --start 2 --duration 5 --fps 15 --width 480 # 转 GIF
python3 $S extract-audio in.mp4 -o a.mp3 --format mp3 # 提取音频（mp3/wav/m4a）
python3 $S add-bgm in.mp4 -o out.mp4 --bgm music.mp3 --volume 0.3 # 加背景音乐（混音）
python3 $S add-bgm in.mp4 -o out.mp4 --bgm music.mp3 --replace # 加背景音乐（替换原声）
python3 $S rotate in.mp4 -o out.mp4 --angle 90 # 旋转 90/180/270
python3 $S fade in.mp4 -o out.mp4 --in 1 --out 1 # 淡入淡出（转场）
| 子命令 | 作用 | 关键参数 |
|---|---|---|
trim |
截取片段 | --start --end 或 --duration（支持 00:00:10 / 10.5 / 600） |
concat |
拼接多个视频 | 位置参数可给多个文件；同编码流复制快速合并，否则自动重编码统一 |
crop |
画面裁剪 | --width --height（必填）--x --y（默认居中） |
speed |
变速 | --rate（视频 setpts + 音频 atempo 联动，>2 自动链式拆分） |
gif |
转 GIF | --start --duration --fps(默认 15) --width(默认 480)，两遍调色板 |
extract-audio |
提取音频 | --format mp3\|wav\|m4a |
add-bgm |
加背景音乐 | --bgm --volume(默认 0.3) --replace(替换原声) |
rotate |
旋转 | --angle 90\|180\|270 |
fade |
淡入淡出（转场） | --in --out（秒） |
工作流程（SOP）
- 听清意图 → 选子命令：先判断用户要的是"剪"（trim/concat/crop/speed/rotate/fade）、"导出"（gif/extract-audio）还是"加料"（add-bgm）。
- 确认输出路径：默认写到
./或用户指定目录；文件已存在会被覆盖（脚本内部-y）。 - 跑一条命令：脚本会先打印输入信息（时长/大小/音视频轨），执行后打印输出信息，便于对比。
- 校验结果：看输出行的"时长/大小"是否符合预期（如变速后应约等于
原时长 ÷ 速率），必要时用ffprobe复核分辨率/编码。 - 交付：把输出文件的绝对路径给用户；多步操作（如先 trim 再 speed）串联执行。
命令参考（各子命令实现要点）
- trim：
-ss前置快速定位 +libx264/aac重编码，保证帧级精确与音画同步；同时给--end与--duration时以--end为准。 - concat：先用
ffprobe比对各视频的编码/宽高/pix_fmt/fps/音频编码采样。全部一致 → concat demuxer-c copy（无损秒级）；不一致 → filter_complex 重编码（统一到最大宽高 + pad 居中 + 30fps + yuv420p + 48kHz 立体声，缺音轨自动补静音）。 - crop：
crop=w:h:x:y，未给x/y时默认居中(in_w-w)/2。 - speed：视频
setpts=PTS/rate；音频atempo（单次限 0.5~2.0，脚本自动把rate拆成多个atempo串联，如 4.0 →atempo=2.0,atempo=2.0）。atempo 保持音高不变。 - gif：两遍法——先
palettegen生成调色板，再paletteuse套用，避免 256 色直出的劣质感；-loop 0无限循环。 - extract-audio：
mp3→libmp3lame-q:a 2；wav→pcm_s16le；m4a→aac 192k。 - add-bgm：默认
amix混音（原声 1.0 + BGM--volume，duration=first锁定为视频长度）；--replace用 BGM 替换原声。BGM 短于视频时自动循环补齐，输出时长恒等于视频。 - rotate：90°→
transpose=1，180°→hflip,vflip，270°→transpose=2。 - fade：
fade视频 +afade音频，淡出起始时间自动取视频时长 - 淡出时长。
示例对话
例 1｜剪掉片头
> 用户：这段视频开头 10 秒是废镜头，帮我剪掉，只要 10 秒到 30 秒。
> 助手：python3 $S trim in.mp4 -o clip.mp4 --start 00:00:10 --end 00:00:30 → 交付 ./clip.mp4（20 秒）。
例 2｜拼接多个片段
> 用户：把 a.mp4、b.mp4、c.mp4 合成一条。
> 助手：python3 $S concat a.mp4 b.mp4 c.mp4 -o merged.mp4 → 脚本自动判断是否可无损合并。
例 3｜变速
> 用户：把这条视频加速 2 倍。
> 助手：python3 $S speed in.mp4 -o fast.mp4 --rate 2.0 → 结果时长约为原来的一半，声音音高不变。
例 4｜转 GIF
> 用户：把这个视频 2 秒到 7 秒那段做成 GIF。
> 助手：python3 $S gif in.mp4 -o out.gif --start 2 --duration 5 --fps 15 --width 480。
例 5｜加背景音乐
> 用户：给它配个轻音乐当 BGM，原声留着但小一点。
> 助手：python3 $S add-bgm in.mp4 -o out.mp4 --bgm music.mp3 --volume 0.3。
例 6｜提取音频 / 换比例裁剪
> 用户：把视频里的声音导成 mp3；顺便把画面裁成 1:1 方图。
> 助手：extract-audio in.mp4 -o a.mp3 --format mp3 + crop in.mp4 -o sq.mp4 --width 720 --height 720。
运行环境
- 脚本：
scripts/video_edit.py（相对技能根目录） - Python：3.9+
- 外部命令：
ffmpeg、ffprobe
开工前先跑一次自检，缺什么当场补，别等跑到一半报错：
command -v ffmpeg >/dev/null 2>&1 || echo "缺 ffmpeg，请先安装再重试"
command -v ffprobe >/dev/null 2>&1 || echo "缺 ffprobe，请先安装再重试"
> 缺依赖时用中文告诉用户缺什么、装完就能用，不要把 Python 的英文 traceback 原样贴给用户。
注意事项与边界
- 环境依赖：
ffmpeg+ffprobe（本环境/usr/bin/ffmpeg，已实测 ffmpeg 7.1.5），无需任何 API Key，全程本地处理，不上传内容。 - 输出目录：产物写
./或用户指定路径；测试产物可放/tmp。 - 性能：除
concat(同编码) 走流复制是秒级外，其余需要重编码（CPU），耗时随分辨率/时长增长。 - 编码：默认
libx264 + aac（crf 20），兼容性好、体积适中。若源为 HEVC/ProRes 等，重编码后统一为 H.264。 - 无损优先：
concat仅当所有输入编码参数完全一致才走-c copy；一旦不一致（分辨率/帧率/编码不同）会自动降级重编码，属预期行为。 - 不做什么：压缩到指定体积 / 平台规格预设 / 抽帧做封面 / 转竖屏 → 用 video-toolbox；下载视频 → 用 videodl-download；文字转语音 → 用 voiceover-tts；视频转字幕 → 用 video-to-srt。
⚖️ 合规声明
本技能仅提供本地音视频剪辑处理能力（裁剪/拼接/变速/转码等）。使用者需自行确保对处理的内容拥有相应权利，并遵守目标平台的服务条款；本技能不对内容版权负责，也不提供任何受版权保护素材的下载能力。
