ffmpeg

FFmpeg 专家

将 FFmpeg 视为类型化媒体管线，并将媒体编辑视为以证据为依据的工作流。检查实际源文件，区分测量结果与解读，确保决策可供审查，渲染到新路径，并在预期边界进行验证。

不适用场景

• 不要将此技能用于 libav API 编程、不透明的整段视频语义理解、自动发布、版权许可确认、规避 DRM、专业广播/色彩认证，或使用 HyperFrames 编写的合成内容。
• 在线媒体或转录文本的获取应交由负责该内容的源技能；语义帧解读应交由具备视觉能力的审阅者；平台上传/API 操作应交由平台技能。

边界与路由

• 使用 YouTube/转录能力获取在线视频或转录文本；仅在处理本地提供的媒体和转录文本文件时返回此处。
• 对于以 HTML 编写的动态图形或合成内容，使用 HyperFrames；使用此技能检查和预处理其媒体输入，或验证渲染输出。
• 上传、发布、账户或 API 操作应使用指定的平台技能。
• FFmpeg 可以提取有界的帧和音频片段，但无法解读其语义内容。将视觉解读交由具备视觉能力的审阅者，并将其观察结果作为注明来源的证据保留。
• 不要根据技术元数据、稀疏帧、静音区间或未对齐的转录文本，推断权利、同意、身份、意图或整个节目的含义。

证据类别

为重要主张标注类别，避免混淆不同类型的证据：

• 技术约定 — 官方 FFmpeg 文档或标准来源中记录的行为。
• 观测到的产物 — 对此源文件/输出的探测结果、测量的信号结果、提取的帧、试听片段或下游测试。
• 可复现实验 — 准确的版本、输入身份/生成器、命令、结果和限制。
• 编辑启发式判断 — 需要人工审核的可撤销判断，并非 FFmpeg 确立的事实。
• 用户要求 — 所请求的输出约定、保留策略和验收阈值。

媒体编辑工作流

1. 接收。 确认授权和隐私边界；识别所有来源；使用 templates/media-intake.json 的私有工作区副本记录探测证据、时序、输出约定、保留策略和未解决的假设。将原始探测输出和媒体保存在受限任务工作区中，并尽量减少可共享的衍生内容。
2. 检查。 探测流和格式。通过清单或 scripts/ffmpeg-preflight 检查所需的本地能力；切勿假设某个滤镜、编码器或硬件后端存在。
3. 收集有界证据。 仅提取决策所需的帧、片段、波形／信号测量值或转录片段。记录采样时间戳、数量、字节／大小限制，并注明样本仅涵盖已采样的时间点。
4. 渲染前先规划。 对编辑性更改，编写可供审核的 EDL 或播客编辑计划。每个重要剪切都需要注明源范围、原因、证据、置信度、处理方式、映射和验证状态。不要即兴处理有歧义的决策，应将其保留为未解决状态。
5. 安全渲染。 明确指定流映射；优先使用 -n 和新的输出路径；避免拼接不可信的 shell 命令。区分受关键帧限制的流复制与解码／重新编码的精准剪切。
6. 分层验证。 视情况检查退出状态、可解码性、输出探测结果、流／时序约定、有界帧／音频证据、编辑审核，以及实际的下游使用方。将探测／解码成功与目标位置接受视为独立关卡；本地文件可能通过前者，却未通过后者。
7. 接受或停止。 使用 templates/media-acceptance-report.md 的私有工作区副本，逐项记录通过／失败／受阻状态。容器有效或命令成功本身并不代表已验收。

从以下步骤开始进行技术检查：

ffprobe -v error -show_format -show_streams -of json INPUT

对于随项目提供的辅助工作流，请从技能根目录运行辅助工具，并明确指定输出路径和限制；将其 JSON 结果视为待验证的报告，而非验收结论。使用 extract-review-frames 时，请将时间戳作为单独的值传入（--timestamps 0 5 9），不要将其写成一个逗号分隔的值。

查阅对应的专项参考资料

以证据为依据的媒体处理

• 在处理提供的／生成的媒体、敏感材料、多个来源或已定义的交付约定之前，请阅读 references/media-intake-and-manifest.md。
• 在提取或审核帧／片段、选择样本或提出视觉相关主张时，请阅读 references/video-inspection-and-visual-evidence.md。
• 有关借助转录内容进行选段、排序、节奏控制、转场、叠加以及可供审核的编辑决策，请阅读 references/editorial-video-editing.md。
• 有关播客剪切、信号清理、静音／噪声分析、响度测量和试听关卡，请阅读 references/audio-and-podcast-editing.md。
• 在创建、验证 EDL 或将 EDL 转换为命令计划之前，请阅读 references/ffmpeg-edit-decision-lists.md。
• 在宣布输出已完成或兼容之前，请阅读 references/media-verification-and-acceptance.md。
• 当证据相互矛盾、剪切出现漂移、缺少滤镜、审核样本稀疏或工作流反复失败时，请阅读 references/media-failure-modes.md。
• 在为主张提供依据、更新与版本相关的指南或记录技术实验时，请阅读 references/media-research-source-index.md。
• 在合成样本上端到端验证接收、证据、EDL、渲染和验收产物能否配合使用时，请阅读 references/editorial-workflow-example.md。
• 当更改需要有界的真实媒体样本来测试剪切、帧率节奏、拼接、音频、字幕或视觉边界采样时，请阅读 references/synthetic-media-fixtures.md。

FFmpeg 核心工作

• 阅读 references/core-model-and-command-anatomy.md，了解容器、流、编解码器、选项作用范围、映射、复制/转码和时间戳。
• 阅读 references/filters-and-transformations.md，了解滤镜图、标签、音频/视频处理和增量式图调试。
• 阅读 references/intermediate-workflows.md，了解定位、剪辑、拼接、元数据、字幕、批处理、管道和流媒体。
• 阅读 references/advanced-operations-and-safety.md，了解硬件加速、同步、可复现性、网络安全和失败边界。
• 仅在检查并确认功能支持后阅读 references/command-cookbook.md；所有示例命令均需视具体情况而定。
• 阅读 references/learning-summary.md，了解面向新手的思维模型。
• 阅读 references/source-inventory.md，了解原始 FFmpeg 源码调研；仅在需要了解明确针对特定主机的 FFmpeg 8.1.2 观察结果时阅读 references/local-verification.md。

模板

• templates/media-intake.json — 来源身份、探测、契约、隐私、保留事项、假设
• templates/edit-decision-list.json — 可供审查的源范围和处理方式
• templates/video-inspection-report.md — 技术检查和有边界的证据台账
• templates/visual-review-packet.md — 带归属信息的帧／片段观察结果和覆盖范围限制
• templates/vision-review-observations.json — 为已准备的数据包提供的、可解析且带归属信息的观察结果块
• templates/podcast-edit-plan.md — 音频的机械、信号和编辑决策
• templates/media-acceptance-report.md — 分层验证和各项标准的判定
• templates/media-acceptance-contract.json — 机器可读的流、格式、证据、响度和下游要求
• templates/target-compatibility-manifest.json — 一个指定目标、来源明确的要求、技术约束和下游流程
• templates/research-experiment-record.md — 可复现的版本／命令／结果记录

当需要可复现的合成集成验证时，请在新的或空的任务专用目录中运行 scripts/editorial-workflow-example。其 PASS_WITH_UNVERIFIED_BOUNDARIES 结果的范围有意小于编辑验收或目标验收。

当测试需要确定性且不含个人信息的媒体时，请运行 scripts/generate-media-fixtures。将其生成的二进制文件和清单保留在任务工作区；提交生成器和断言，不提交生成结果。

使用 scripts/render-edl 执行单源或多源计划，但不实际渲染。默认使用解码后的 concat-filter 组装；仅当基于探测结果得出的签名一致，且数据包／关键帧边界已验证时，才选择 concat-demuxer 流复制。不支持的转场必须明确报错。

使用 scripts/audio-inspect 获取有边界的静音、EBU R128、峰值／削波和转录对齐证据。明确请求每项测量，将不可用的滤镜保留为 UNAVAILABLE，并将每个时间区间或转录范围都视为需要听审的候选项。其可选的报告输出会拒绝覆盖已有文件。

使用 scripts/media-verify，并提供已声明的验收契约、输出 FFprobe JSON，以及可选的证据 JSON。它会将每项标准独立报告为 PASS、FAIL、BLOCKED、UNVERIFIED 或 NOT_APPLICABLE；只有不存在失败项或缺失的必要证据时，整体报告才算通过。

当验收指定了真实的播放器、编辑器、主机、存档或服务时，请使用 scripts/target-compatibility。将来源明确的技术要求和本地探测结果，与该确切使用方产生的证据分开；通过结果仅适用于指定的目标／版本。

使用 scripts/vision-review-handoff 为获授权的人类或视觉审查者准备有边界且保护隐私的帧数据包。仅使用 scripts/import-vision-review 导入带归属信息且经过审查的观察结果；将拟议的编辑后果视为待审查的证据，绝不可自动作出决策。

将模板复制到任务工作区，并替换其中的占位符／示例值。不要将私人路径、媒体、转录文本或审查证据放入公开的技能仓库。

不可妥协的检查项

• 涉及多个输入／轨道或复杂图时，必须明确选择流。
• 选项顺序很重要：选项通常作用于下一个输入或输出。
• 不要称静音毫无用处；silencedetect 报告的是阈值越界，而非编辑价值。
• 仅依据可用的测量方法声明响度、削波、时序或关键帧状态，并保留其输出。
• 转录文本只能作为其文本内容及所提供时序质量的证据；在进行帧级精确剪辑前，应抽查其与媒体的对齐情况。
• 当证据稀少、歧义可能导致有意义的内容被删除、可选工具／滤镜缺失、隐私／授权不明确，或两种实质不同的方法均失败时，应暂停并交由人工审查。

完成

仅当所请求的产物已生成在新路径下、所需的探测和有界审查均已记录、输出已在相关下游边界进行验证，并且每项验收标准都已通过或明确标记为受阻时，才算完成。报告未经测试的说法和剩余假设，不要用看似合理的输出来填补缺口。