音视频工具箱（video-toolbox）
基于 ffmpeg 的音视频处理封装。核心价值：电商平台规格预设——商品视频要投稿/发送时常因"太大/比例不对/格式不合"卡住，本技能把常见平台的限制变成一条命令。
子命令速查
SKILL_DIR="$HOME/.workbuddy/skills/video-toolbox"
[ -f "$SKILL_DIR/scripts/video_toolkit.py" ] || SKILL_DIR="$PWD/.workbuddy/skills/video-toolbox"
[ -f "$SKILL_DIR/scripts/video_toolkit.py" ] || SKILL_DIR="/sandbox/workspace/skills/video-toolbox"
S="$SKILL_DIR/scripts/video_toolkit.py"
python3 $S info 视频.mp4 # 查看信息（时长/分辨率/编码/码率/大小）
python3 $S platforms # 列出内置平台规格预设
python3 $S compress 视频.mp4 -o 出.mp4 --platform wx # 按平台预设压缩
python3 $S compress 视频.mp4 -o 出.mp4 --target-mb 50 # 压到目标大小
python3 $S compress 视频.mp4 -o 出.mp4 --crf 23 # 不限额，按质量压缩
python3 $S extract-audio 视频.mp4 -o 音频.mp3 # 提取音频（mp3/m4a/wav）
python3 $S vertical 视频.mp4 -o 出.mp4 --mode crop # 转竖屏 1080x1920
python3 $S frame 视频.mp4 -o 封面.jpg --at 2.5 # 抽帧做封面
python3 $S gif 视频.mp4 -o 动图.gif --fps 12 --width 480
python3 $S trim 视频.mp4 -o 片段.mp4 --start 5 --duration 8
python3 $S convert 视频.mp4 -o 出.webm # 格式转换
内置平台预设（platforms 子命令可查）
| 预设 | 平台 | 上限 | 建议比例 |
|---|---|---|---|
wx |
微信发送/朋友圈 | 10 MB | 原比例 |
wxch |
微信视频号 | 1000 MB | 9:16 |
dy / ks |
抖音 / 快手 | 4000 MB | 9:16 |
tb |
淘宝主图视频 | 60 MB | 1:1 |
jd |
京东主图视频 | 100 MB | 1:1 |
pdd |
拼多多 | 100 MB | 1:1 |
xhs |
小红书 | 500 MB | 3:4 |
> 规格为常见参考值，平台政策会调整，以官方最新规则为准（详见 references/platform-specs.md）。
智能保护（脚本内置）
- 源文件已达标 → 直接流复制：如源 0.4MB 要发微信（限 10MB），不会重编码，秒级输出无损
- 源码率低于目标 → 自动降码率：避免"压缩后反而变大"的常见坑
- 格式校验：转 GIF 会建议用
gif子命令（高质量两遍调色板）；转音频建议用extract-audio
典型场景（电商）
- 商品视频发微信：
compress -o wx.mp4 --platform wx→ 一条命令搞定 10MB 限制 - 横屏转抖音竖屏：
vertical -o out.mp4 --mode crop（裁剪填满，无黑边） - 从商品视频抽主图封面：
frame -o cover.jpg --at 2.5 - 详情页动图：
gif --fps 12 --width 480 - 平台投稿适配：先
info看原参数 → 按需compress/vertical/convert - 提取音频做配音参考：
extract-audio -o ref.mp3
依赖与边界
- 依赖：ffmpeg + ffprobe（当前运行环境自带）；无需任何 API Key
- 全程本地处理，不上传任何内容；产物写
./或用户指定目录 - 仅做格式/参数转换，不改变内容本身；下载视频请用 videodl-download 配合
- 大文件处理耗时随体积增长（CPU 编码，1080p 约每分钟素材数秒到十几秒）
⚖️ 合规声明
仅提供本地音视频参数转换能力。使用者需自行确保对处理内容拥有相应权利，遵守目标平台服务条款。
运行环境
- 脚本：
scripts/video_toolkit.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 原样贴给用户。
示例
# 先看有哪些平台预设（抖音/视频号/小红书…的码率与分辨率）
python3 "${SKILL_DIR:-$PWD/.workbuddy/skills/video-toolbox}/scripts/video_toolkit.py" platforms
# 按平台预设压缩
python3 "${SKILL_DIR:-$PWD/.workbuddy/skills/video-toolbox}/scripts/video_toolkit.py" compress \
./原片.mp4 --platform douyin -o ./成品.mp4
# 按目标体积压（例如压到 10MB 以内）
python3 "${SKILL_DIR:-$PWD/.workbuddy/skills/video-toolbox}/scripts/video_toolkit.py" compress \
./原片.mp4 --target-mb 10 -o ./成品.mp4
输出：-o 指定的成片；终端会打印压缩前后体积与码率，便于判断是否达到平台要求。
失败时：--target-mb 太小会撞到画质下限，脚本会给出提示，此时改大目标或降低分辨率，不要硬压。
