ffmpeg

通过组合参考资料中的配方，为媒体处理任务构建正确的 FFmpeg 命令，而不是凭记忆回想命令。FFmpeg 语法对位置非常敏感，很容易出现细微错误，因此应优先改编这些参考资料中经过验证的命令，而不是凭空编写。

工作流：

1. 确定任务类别（简单编辑、音频处理、高级滤镜、素材生成、编码调优）。
2. 打开相应的参考文件，选择最接近的配方。
3. 根据用户的要求调整输入路径、时间范围、尺寸、编解码器和滤镜参数。
4. 返回命令前，逐项检查 references/glossary.md，确认流选择器、-map、-c copy 的用法以及寻址位置。
5. 如果用户使用的是没有 GPU 的 macOS 或 Linux，不要建议使用 *_nvenc、*_qsv 或 VAAPI 编码器。

如果只完成部分工作，只加载相关的参考文件。

核心说明

• 覆盖输出文件时，始终以 -y 开头；否则省略该选项，让 FFmpeg 在覆盖文件前提示。
• 如果不需要滤镜、编解码器转换或精准剪辑，优先使用 -c copy（流复制／重新封装），这样可以避免重新编码，速度也快得多。
• 应用任何视频滤镜（scale、overlay、subtitles、trim、fade）、混合或修改音频（amix、atempo、volume）、烧录字幕、在编解码器之间转码或压缩时，不要使用 -c copy。
• 如需按帧精准剪辑，请使用输出寻址（将 -ss 放在 -i 之后），且不要使用 -c:v copy。输入寻址（将 -ss 放在 -i 之前）速度较快，但只会寻址到最近的关键帧，可能导致黑帧或剪辑时间偏差数秒。
• 对于 H.264 输出，除非用户另有要求，默认使用 -c:v libx264 -crf 18 -preset veryslow -movflags +faststart -pix_fmt yuv420p。QuickTime 和大多数消费级播放器都需要 yuv420p。
• 输出面向 Apple 设备的 H.265（HEVC）时，添加 -vtag hvc1，确保文件可通过 AirDrop 传输并被 QuickTime 接受。
• 将 CRF 视为主要的质量调节参数：数值越低，质量越高；增加 6 大致会使比特率减半。libx264 的合理范围是 17-28；18 表示“视觉无损”；libvpx-vp9 的取值范围为 15-35，恒定质量模式需配合 -b:v 0 使用。
• 需要命名流（[v0]、[a1]）、多个输入，或同时处理音频和视频时，串联滤镜应优先使用一次 -filter_complex。单流滤镜则使用 -vf／-af。
• 使用 trim／atrim 后，始终通过 setpts=PTS-STARTPTS／asetpts=PTS-STARTPTS 重置时间戳，否则 concat 和后续滤镜会出错。
• 混合不同时长的输入且输出应以较短的流为准时，使用 -shortest。两种行为都需要时，在 amix 中配合 duration=shortest。
• 对于 pad，应在缩放／填充链后添加 setsar=1:1，将像素宽高比锁定为 1:1；省略它可能导致输出看起来被拉伸，即使尺寸看起来正确。
• 使用单引号为 -vf 和 -filter_complex 参数加引号（或在表达式中的逗号前添加 \,），避免 Shell 或 FFmpeg 的表达式解析器误处理字符。
• 以编程方式生成文件名时，优先使用与编解码器相匹配的扩展名（H.264/H.265 使用 .mp4，VP9/Opus 使用 .webm，需要多条字幕轨道时使用 .mkv，ProRes／Apple 风格工作流使用 .mov）。
• 如果用户报告播放失败（黑帧、音频漂移、“不支持该文件”），首先检查是否缺少 -pix_fmt yuv420p、+faststart，是否在输入寻址时使用了 -c copy，或 Apple 设备上的 HEVC 是否使用了错误的 -vtag。
• 如果用户已有目标文件大小，请改用两遍 ABR（使用 -b:v <rate>，先设置 -pass 1，再设置 -pass 2）；CRF 无法确保文件大小上限。
• 调试滤镜图之前，先使用 ffprobe -show_streams -i <file> 验证元数据和流布局——流索引不匹配是最常见的隐性故障。

输出格式

当用户要求提供命令时，请返回：

1. 放在 sh 代码块中的完整单行 FFmpeg 命令，可直接粘贴运行。
2. 简短的项目符号列表，说明每个重要标志和滤镜的作用。
3. 任何注意事项：播放器兼容性、预计运行开销、有损处理步骤，或相关参考文件中提到的已知 FFmpeg 特性。

只有当用户明确要求“仅命令”时，才跳过说明部分。

当用户要求审查现有命令时，请按以下结构整理结果：

1. 正确性 - 会导致失败或产生错误输出的标志或滤镜顺序。
2. 质量 - CRF、预设、色彩空间、faststart、音频码率。
3. 性能 - 不必要的重新编码、缓慢的滤镜链、缺少硬件加速。
4. 可移植性 - 编解码器与容器不匹配、Apple HEVC 标签、面向消费级播放的 yuv420p。

例如，对于“压缩此 MP4 以便在网页上使用，同时保持视觉质量”这类请求：

ffmpeg -i input.mp4 -c:v libx264 -crf 20 -preset veryslow -pix_fmt yuv420p -movflags +faststart -c:a aac -b:a 128k output.mp4

• -crf 20 可在缩小文件的同时保持接近源文件的画质；归档时可调低至 18。
• -preset veryslow 以更长的编码时间为代价，在相同 CRF 下可将输出文件缩小约 20-30%。
• -pix_fmt yuv420p 可确保视频能在 Safari、QuickTime 和大多数浏览器中播放。
• +faststart 会将 moov atom 移至文件开头，让视频在下载完成前就开始播放。
• -c:a aac -b:a 128k 会以透明级立体声码率重新编码音频。

示例结束。

参考资料

• references/glossary.md - 标志和滤镜语法、流选择器、-map、-c copy 规则、输入与输出定位。
• references/simple-editing.md - 格式转换（MP4/MKV/MOV/AVI）、调整大小和填充、按时间裁剪。
• references/audio-processing.md - 替换、提取、混音、交叉淡化、降采样、立体声转单声道、格式转换。
• references/advanced-editing.md - 播放速度、fps、跳剪、社交媒体裁剪、drawtext 叠加、字幕、水印、vstack、片头/片尾拼接。
• references/asset-generation.md - 图片转视频、使用 xfade 制作幻灯片、Ken Burns 效果、GIF、缩略图、场景变化分镜图。
• references/encoding-and-tuning.md - 日常使用模板、libx264/libx265/libvpx-vp9、faststart、CRF 指引、定位、GPU 编码器、ffprobe。

来源

改编自 Rendi FFmpeg cheatsheet 中的示例。参考资料中的示例 URL 指向 storage.rendi.dev，因此无需本地文件即可直接运行命令。