用途
ffmpeg-ops 是为 ffmpeg/ffprobe 提供操作级专业知识的技能，目标是用约 30 条覆盖多数真实工作的命令、避免那些会悄悄毁掉输出的常见陷阱，以及用八个脚本替代智能体每次都要重新推导的逻辑。
其核心原则是“先探测”：绝不盲目转码、剪切或加滤镜。每个媒体任务都从探测输入开始，检查编码、时长、帧率（固定还是可变）、像素格式、旋转、流布局。很多“ffmpeg 行为怪异”的报告，其实都是命令从未检查的输入属性造成的。
主要能力
探测与诊断
使用 probe-media.py 可输出人类可读摘要、JSON、关键帧邻近信息；--doctor 会强制贯彻探测原则，把 VFR、HDR 传递特性、旋转元数据、隔行、非 yuv420p 交付、moov 位于文件尾等问题反馈为发现项，并附带精确修复命令，退出码 10 表示“处理前先修复”。--keyframes-near 用于回答“能否在 92.5 秒处流拷贝剪切”，报告最近的关键帧位置。命令报错难以理解时，可查阅错误解码参考。
在推荐编码器前，需先确认当前 ffmpeg 构建是否具备该编码器，因为已安装构建差异很大，尤其是硬件编码器（列出不等于可用）。capability-scan.sh 会逐一验证硬件编码器，--quick 仅列出不触碰 GPU。
配方与陷阱
cookbook.md 提供可复制的配方，每条注释里写明它避免的陷阱，命令为 bash 形式（Windows 有专门说明），并要求始终显式传 -y 或 -n，避免智能体运行命令时进入交互。覆盖的内容包括：Web H.264/HEVC/AV1、重封装、VFR 规范化、FFV1 归档、按体积适配；拷贝与帧精确剪切、concat 解复用器与滤镜拼接；缩放裁剪、9:16 模糊填充、旋转、帧率、变速、慢动作、延时；水印、drawtext 时间码、烧录与软字幕；音频提取、替换、混音、响度、去静音；语音识别准备；缩略图、联系人表、GIF、章节、数据集帧、精灵图；损坏检查、帧哈希、元数据剥离、ffprobe 单行命令；yt-dlp 互操作；合成测试源。
陷阱表列出了各类静默失败，例如：-ss 配合 -c copy 会导致剪切从更早处开始或出现冻结/黑场；输入侧 -ss 后输出侧 -to 会让 -to 悄悄变成时长；缺少 -pix_fmt yuv420p 会让 Safari/QuickTime/电视黑屏或拒播；缺少 -movflags +faststart 会令浏览器无法边下边播；默认流选择会让 ffmpeg 每种类型只挑一路流，额外音轨和字幕被静默丢弃；-vf 与 -c:v copy 同时出现是硬错误；VFR 源会导致剪切漂移、拼接失步；-vsync 已弃用，应改用 -fps_mode；scale=W:-1 奇数高度在 yuv420p 下会报错，应使用 -2；在参数不一致的输入上用 concat 解复用器会在边界处出现故障或失步；amix 默认会把每个输入音量减半；单程 loudnorm 会让轻音段抽气且输出静默变成 192 kHz；音频替换时缺少 -shortest 会让输出长度等于最长输入；BT.601/709 色彩偏移；drawtext/subtitles 路径转义在 Windows 下会爆炸；交互式覆盖提示会让智能体命令永久挂起；cmd.exe 中的 % 会被变量展开破坏。
Windows 注意事项
命令本身跨平台，但在 Windows 上运行需注意：PowerShell 引号更友好，单引号完全字面化，因此 -vf 'scale=1280:-2,fps=30' 无需转义；双引号只插值 $ 和反引号。两遍日志用 NUL 而非 /dev/null，但也接受 -f null -，更可移植。drawtext 字体路径需写成 fontfile='C:/Windows/Fonts/arial.ttf'。优先使用 -f null - 和相对路径以同时规避两套引号规则。
决策树与工作流
编码器选择：H.264（libx264）为默认，通用播放、快速，-crf 18..23 下每比特质量好；H.265（libx265）同质量约小 40%，更慢，Apple 需 -tag:v hvc1；AV1（libsvtav1）压缩最好、免版税、Web 优先，但编码成本最高，旧硬件只能软解；VP9 仅在管线要求 webm 且无 AV1 时用；FFV1 仅用于归档母版。剪切方法：需要精确帧或要加任何滤镜时重新编码；剪切点恰好落在关键帧上或 ±2 秒误差可接受时用流拷贝加 -avoid_negative_ts make_zero；从一个源做多个剪切时用 EDL 工作流。CPU 与硬件编码：硬件编码快 5-20 倍，但同比特质量不如慢预设的 libx264/x265，适合速度关键的批处理、直播、草稿和“够用”交付，需把比特率提高约 30% 补偿。
EDL 工作流（剪辑即代码）：任何多段剪辑都不要临时发剪切命令，而是写一份编辑决策表——JSON 文件，标明每个片段、时间范围和理由——然后据此剪切。这样剪辑可审查、可重跑、可对比。步骤：先用 detect-segments.py --silence 找候选剪切点；再撰写 EDL；然后 cut-from-edl.py 干跑并打印将执行的每条 ffmpeg 命令（默认不执行）；最后加 --execute 执行剪切与拼接，默认重新编码以保证帧精确，--copy 用于关键帧对齐的 EDL。规则：剪切必须落在静音处；模型应基于转录稿而非帧推理；剪完后重新转录验证输出。
调色、质量门与脚本
调色方面，可用 lut3d 应用 .cube LUT（interp=tetrahedral 为最高质量插值），并可用 gen-luts.py 生成一组调色候选和 HTML 静帧选择器，由人挑选，绝不自动选定风格。
质量门用 quality-compare.py 给出 VMAF/SSIM/PSNR 判定，退出码 10 表示低于阈值。VMAF 在 1080p 下 ≥ 93 约等于视觉无损，80-93 可察觉。
脚本包括：probe-media.py（标准化探测、关键帧邻近、--doctor 分类）、capability-scan.sh（验证构建能力）、quality-compare.py（质量门）、loudnorm-scan.py（两遍响度归一化）、detect-segments.py（静音/场景边界输出 JSON）、cut-from-edl.py（EDL 到剪切与拼接）、make-chapters.py（章节生成）、smart-compress.py（按体积上限压缩）、make-sprites.py（拖拽预览精灵图与 WebVTT）、gen-luts.py（生成 .cube 变体）、verify-commands.sh（命令陈旧度验证）。所有脚本遵循 Skill Resource Protocol：--help 带示例、stdout 仅数据、--json 信封、语义化退出码（0 正常、2 用法、3 输入缺失、4 输入无效、5 依赖缺失、7 ffmpeg 不可用、10 领域发现）。
参考文件按需加载，一个概念一个文件，包括编码、硬件加速、滤镜图、剪切拼接、剪辑即代码、音频、STT/Whisper、字幕、调色、风格配方、色彩 HDR、质量指标、流媒体 HLS、图像 GIF、修复、分析验证、采集设备、错误解码、可视化、配方等。资产包括编码预设、HLS 阶梯、EDL schema。自测命令为 bash skills/ffmpeg-ops/tests/run.sh，离线套件用 lavfi 合成夹具，仅在 PATH 中有 ffmpeg 时运行媒体往返测试。
适用场景
适合转码与压缩、精确剪切与拼接、缩放旋转变速、水印字幕、音频提取混音与响度归一化、语音识别准备、缩略图与 GIF、HLS 打包、硬件加速编码、调色与质量对比、多段剪辑的 EDL 工作流等。
限制
需要已安装 ffmpeg；部分硬件编码器需能力扫描验证，列出不等于可用；Windows 下需注意引号、路径转义与 % 展开；脚本遵循固定协议与退出码。具体平台、收费与价格信息暂未提供。