视频处理工具箱
概述
本 Skill 提供一套基于 FFmpeg 的本地视频处理工作流，覆盖常见的 12 类视频编辑需求：
- 视频格式转换
- 音频格式转换 / 提取
- 视频大小压缩
- 视频添加水印
- 视频去除水印
- 视频合并
- 视频分割
- 视频裁切
- 视频翻转
- 视频截图
- 视频转 GIF
- 视频加字幕
WorkBuddy 根据用户请求判断对应操作，收集输入/输出路径与必要参数后，调用 scripts/video_processor.py 执行处理。
前置条件
- 系统已安装 FFmpeg，且
ffmpeg命令在 PATH 中可用。 - 若未安装，提示用户前往 https://ffmpeg.org/download.html 下载对应系统版本，
或参考references/ffmpeg_install_guide.md进行安装。
快速使用流程
- 识别用户请求对应的操作名称（见下节）。
- 确认输入视频路径、输出文件路径，以及该操作所需的额外参数。
- 构建并执行
python scripts/video_processor.py <operation> ...命令。 - 检查命令输出，向用户报告成功或失败信息。
操作映射与常用命令
1. 视频格式转换（convert）
转换视频封装格式或编码。
python scripts/video_processor.py convert input.mp4 output.mkv
python scripts/video_processor.py convert input.mov output.mp4 --vcodec libx264 --acodec aac
2. 音频格式转换 / 提取（audio-convert）
提取视频音轨或转换音频编码。
python scripts/video_processor.py audio-convert input.mp4 output.mp3
python scripts/video_processor.py audio-convert input.mp4 output.aac --codec aac
3. 视频大小压缩（compress）
通过降低 CRF、调整分辨率或码率来减小文件体积。
python scripts/video_processor.py compress input.mp4 output.mp4 --crf 28
python scripts/video_processor.py compress input.mp4 output.mp4 --scale 1280:-2 --crf 24 --preset fast
4. 视频添加水印（add-watermark）
支持图片水印（PNG 透明最佳）或文字水印。
python scripts/video_processor.py add-watermark input.mp4 output.mp4 --image logo.png --position bottom-right
python scripts/video_processor.py add-watermark input.mp4 output.mp4 --text "Sample" --position top-left --fontsize 32 --fontcolor red
5. 视频去除水印（remove-watermark）
通过 delogo 滤镜模糊指定区域，或选择直接裁剪。
python scripts/video_processor.py remove-watermark input.mp4 output.mp4 --x 10 --y 10 --w 200 --h 60
python scripts/video_processor.py remove-watermark input.mp4 output.mp4 --x 10 --y 10 --w 200 --h 60 --crop
6. 视频合并（merge）
按顺序合并多个视频。默认流拷贝，速度最快；若视频参数不一致，使用 --reencode。
python scripts/video_processor.py merge output.mp4 --inputs part1.mp4 part2.mp4 part3.mp4
python scripts/video_processor.py merge output.mp4 --inputs a.mp4 b.mp4 --reencode
7. 视频分割（split）
支持按固定时长分段，或按时间点切分。
python scripts/video_processor.py split input.mp4 segment_%03d.mp4 --mode duration --duration 60
python scripts/video_processor.py split input.mp4 segment_%03d.mp4 --mode points --points 00:00:00,00:01:00,00:02:00
8. 视频裁切（cut）
截取指定时间范围内的片段。
python scripts/video_processor.py cut input.mp4 output.mp4 --start 00:00:10 --end 00:00:30
python scripts/video_processor.py cut input.mp4 output.mp4 --start 00:00:10 --duration 20 --accurate
9. 视频翻转（flip）
水平或垂直翻转。
python scripts/video_processor.py flip input.mp4 output.mp4 --direction horizontal
python scripts/video_processor.py flip input.mp4 output.mp4 --direction vertical
10. 视频截图（screenshot）
截取指定时间点的单帧。
python scripts/video_processor.py screenshot input.mp4 poster.jpg --time 00:00:05
11. 视频转 GIF（to-gif）
生成优化过的 GIF。
python scripts/video_processor.py to-gif input.mp4 output.gif --fps 10 --scale 480:-2
python scripts/video_processor.py to-gif input.mp4 output.gif --start 00:00:10 --end 00:00:15
12. 视频加字幕（add-subtitles）
将 SRT 或 ASS 字幕烧录进视频。
python scripts/video_processor.py add-subtitles input.mp4 output.mp4 --subtitle subtitle.srt
参数说明
运行以下命令可查看全部子命令与参数：
python scripts/video_processor.py --help
python scripts/video_processor.py <operation> --help
注意事项
- 涉及时间戳的参数支持
HH:MM:SS或纯秒数。 - 使用
-c copy的操作（如默认 merge / cut）依赖视频的关键帧位置，
若需要精确到帧的截取，请添加--accurate重新编码。 - 去除水印需要用户提供水印区域的坐标与尺寸；若不确定，
可先通过截图查看像素位置，再执行去除。 - 字幕烧录依赖 FFmpeg 的 libass，若失败请确认字幕文件编码为 UTF-8。
资源文件
scripts/video_processor.py：核心处理脚本，统一调用 FFmpeg。references/ffmpeg_install_guide.md：FFmpeg 安装参考。
支付宝付费改造契约（PAYSKILL）
本技能为付费技能（PAYSKILL）。调用遵循支付宝 AI 生意画像契约，由平台调度层执行 probe → pay → complete → ack 流程：
- probe（探测）：平台调用前先探测是否已持有本技能的支付宝有效订阅 / 付费凭证。已付费则直接放行。
- 402 Payment-Needed：未付费时，脚本向标准输出返回 HTTP 状态
402与Payment-Needed标记，提示用户通过支付宝完成付费（pay），平台据此唤起付费页。 - complete（扣费确认）：用户在支付宝完成扣费后，平台下发
Payment-Proof（付费凭证）。 - ack（验签放行）：平台携带
Payment-Proof重试本次调用；scripts/payment_gate.py验签该凭证，确认有效后放行主流程。
订阅持久化与幂等：
- 付费状态缓存在本地
.pay_cache/state.json，避免每次调用重复付费（订阅持久化）。 - 同一
Payment-Proof在 24h 幂等窗口内仅生效一次，避免重复扣费。
现金流改造后的调用套路：
用户调用 → 平台 probe →
未付费：下发 402 Payment-Needed → 支付宝 pay → complete → 下发 Payment-Proof
已付费/携带 Proof：脚本 ack 验签 → 放行主流程
> 本契约由 SkillHUB 平台调度层解析，脚本本地仅处理 402 / 验签 / 持久化 三环节；付费本体交给支付宝。
支付宝 AI 按量付费（Machine Pay / A2M）改造说明
本 Skill 已按支付宝官方 A2M 协议改造为 Pay Skill，付费闸口位于 scripts/payment_gate.py，统一调用云端计费服务 https://pay.pembroli.cn/api/resource。
付费流程
- 未付费调用时，服务端返回 HTTP 402 +
Payment-Needed头，携带金额、商户、订单号及 RSA2 签名。 - 买家侧
payment_gate.py收到 402 后引导用户完成支付，平台回传Payment-Proof。 - 客户端携带
Payment-Proof重试资源端点。
验付调用
服务端收到 Payment-Proof 后，调用支付宝验付接口（alipay.aipay.agent.payment.verify）核验凭证有效性（trade_no、out_trade_no、active 状态），验证失败返回 400，验证通过才进入资源发放。
履约确认
资源发放成功后，服务端异步调用履约确认接口（alipay.aipay.agent.fulfillment.confirm，trade_no）回执，标记本笔订单已履约；并按 out_trade_no 做幂等，重复请求直接返回已缓存结果，杜绝重复收费。
幂等与缓存
买家侧按 slug 本地缓存 Payment-Proof（24h TTL），有效期内免重复支付；服务端按订单号幂等，保证同一笔订单只履约一次。
