ffmpeg

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Build correct FFmpeg commands for media-processing tasks by composing recipes from the references instead of recalling commands from memory. FFmpeg syntax is highly position-sensitive and easy to get subtly wrong, so prefer adapting a known-good command from these references over inventing one.
Workflow:
  1. Identify the task category (simple edit, audio processing, advanced filtering, asset generation, encoding tune-up).
  2. Open the matching reference file and pick the closest recipe.
  3. Adapt input paths, time ranges, dimensions, codecs, and filter parameters to the user's request.
  4. Before returning the command, walk through
    references/glossary.md
    to validate stream selectors,
    -map
    ,
    -c copy
    use, and seeking position.
  5. If the user is running on macOS or Linux without a GPU, do not suggest
    *_nvenc
    ,
    *_qsv
    , or VAAPI encoders.
If doing partial work, load only the relevant reference files.
通过组合参考文件中的配方来构建适用于媒体处理任务的正确 FFmpeg 命令,而不是凭记忆回忆命令。FFmpeg 语法对参数位置非常敏感,很容易出现细微错误,因此应优先调整这些参考文件中的已知可用命令,而不是自行编写。
工作流:
  1. 确定任务类别(简单编辑、音频处理、高级滤镜处理、素材生成、编码调优)。
  2. 打开匹配的参考文件,并选择最接近的配方。
  3. 根据用户需求调整输入路径、时间范围、尺寸、编解码器和滤镜参数。
  4. 在返回命令前,逐一检查
    references/glossary.md
    ,以验证流选择器、
    -map
    、
    -c copy
    的使用方式以及 seek 位置。
  5. 如果用户在 macOS 或 Linux 上运行且没有 GPU,请勿建议使用
    *_nvenc
    、
    *_qsv
    或 VAAPI 编码器。
如果只完成部分工作,请仅加载相关的参考文件。

Core Instructions

核心说明

  • Always start commands with
    -y
    when overwriting is acceptable; otherwise omit it so FFmpeg prompts before clobbering output.
  • Prefer
    -c copy
    (stream copy / remux) when no filter, codec change, or precise trim is needed - it avoids re-encoding and is much faster.
  • Do not use
    -c copy
    when applying any video filter (
    scale
    ,
    overlay
    ,
    subtitles
    ,
    trim
    ,
    fade
    ), mixing or modifying audio (
    amix
    ,
    atempo
    ,
    volume
    ), burning subtitles, transcoding between codecs, or compressing.
  • For frame-accurate trimming, use output seeking (
    -ss
    after
    -i
    ) without
    -c:v copy
    . Input seeking (
    -ss
    before
    -i
    ) is fast but only seeks to the nearest keyframe and can produce black frames or off-by-seconds cuts.
  • For H.264 output, default to
    -c:v libx264 -crf 18 -preset veryslow -movflags +faststart -pix_fmt yuv420p
    unless the user specifies otherwise.
    yuv420p
    is required for QuickTime and most consumer players.
  • For H.265 (HEVC) output destined for Apple devices, add
    -vtag hvc1
    so AirDrop and QuickTime accept the file.
  • Treat CRF as the primary quality knob: lower = higher quality, +6 roughly halves bitrate. Sane libx264 range is 17-28; 18 is "visually lossless"; libvpx-vp9 uses 15-35 with
    -b:v 0
    for constant quality.
  • When chaining filters, prefer
    -filter_complex
    once you need named streams (
    [v0]
    ,
    [a1]
    ), multiple inputs, or both audio and video manipulation. Use
    -vf
    /
    -af
    for single-stream filtering.
  • After
    trim
    /
    atrim
    , always reset timestamps with
    setpts=PTS-STARTPTS
    /
    asetpts=PTS-STARTPTS
    , otherwise
    concat
    and downstream filters break.
  • Use
    -shortest
    when mixing inputs of different durations and the output should follow the shortest stream. Pair with
    duration=shortest
    inside
    amix
    when both behaviors are needed.
  • For
    pad
    ,
    setsar=1:1
    should follow the resize/pad chain to lock pixel aspect ratio to 1:1 - omitting it can make the output appear stretched even when dimensions look correct.
  • Quote
    -vf
    and
    -filter_complex
    arguments in single quotes (or escape commas inside expressions with
    \,
    ) to avoid the shell or FFmpeg's expression parser swallowing characters.
  • When generating filenames programmatically, prefer extensions that match the codec (
    .mp4
    for H.264/H.265,
    .webm
    for VP9/Opus,
    .mkv
    when multiple subtitle tracks are needed,
    .mov
    for ProRes / Apple-flavored workflows).
  • If the user reports playback failures (black frames, audio drift, "file not supported"), check first for: missing
    -pix_fmt yuv420p
    , missing
    +faststart
    , input seeking with
    -c copy
    , or wrong
    -vtag
    for HEVC on Apple.
  • If the user already has a target file size, switch to two-pass ABR (
    -b:v <rate>
    with
    -pass 1
    then
    -pass 2
    ); CRF cannot enforce a size cap.
  • Verify metadata and stream layout with
    ffprobe -show_streams -i <file>
    before debugging filter graphs - mismatched stream indices are the most common silent failure.
  • 如果允许覆盖文件,命令中应始终加入
    -y
    ;否则省略该参数,让 FFmpeg 在覆盖输出文件前进行提示。
  • 当不需要滤镜、编解码器变更或精确裁剪时,优先使用
    -c copy
    (流复制(stream copy)/ 重封装(remux))——这样可以避免重新编码,速度也快得多。
  • 应用任何视频滤镜(
    scale
    、
    overlay
    、
    subtitles
    、
    trim
    、
    fade
    )、混合或修改音频(
    amix
    、
    atempo
    、
    volume
    )、烧录字幕、在编解码器之间转码或压缩时,不要使用
    -c copy
    。
  • 对于帧级精确裁剪,请使用输出定位(输出 seek,
    -ss
    放在
    -i
    之后),并且不要使用
    -c:v copy
    。输入定位(输入 seek,
    -ss
    放在
    -i
    之前)速度更快,但只能定位到最近的关键帧,可能产生黑帧或相差数秒的裁剪偏差。
  • 对于 H.264 输出,除非用户另有说明,否则默认使用
    -c:v libx264 -crf 18 -preset veryslow -movflags +faststart -pix_fmt yuv420p
    。
    yuv420p
    是 QuickTime 和大多数消费级播放器的必要格式。
  • 对于面向 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 表达式解析器吞掉字符。
  • 以编程方式生成文件名时,优先选择与编解码器匹配的扩展名(
    .mp4
    用于 H.264/H.265,
    .webm
    用于 VP9/Opus,需要多个字幕轨时使用
    .mkv
    ,
    .mov
    用于 ProRes 或 Apple 生态工作流)。
  • 如果用户反馈播放失败(黑帧、音频漂移、“文件不受支持”),优先检查:是否缺少
    -pix_fmt yuv420p
    、是否缺少
    +faststart
    、是否在搭配
    -c copy
    时使用了输入 seek,以及 Apple 设备上的 HEVC 是否缺少正确的
    -vtag
    。
  • 如果用户已经指定目标文件大小,请改用两遍 ABR 编码(先使用
    -b:v <rate>
    和
    -pass 1
    ,再使用
    -pass 2
    );CRF 无法强制限制文件大小。
  • 调试滤镜图之前,使用
    ffprobe -show_streams -i <file>
    验证元数据和流布局——流索引不匹配是最常见的无提示故障。

Output Format

输出格式

When the user asks for a command, return:
  1. The full one-line FFmpeg command in a
    sh
    code block, ready to paste.
  2. A short bullet list explaining each non-trivial flag and filter.
  3. Any caveats: player compatibility, expected runtime cost, lossy steps, or known FFmpeg quirks linked from the relevant reference file.
Skip the explanation block only if the user explicitly asks for "command only".
When the user asks for a review of an existing command, organize findings as:
  1. Correctness - flags or filter ordering that will fail or produce wrong output.
  2. Quality - CRF, preset, color space, faststart, audio bitrate.
  3. Performance - unnecessary re-encodes, slow filter chains, missing hardware acceleration.
  4. Portability - codec/container mismatches, Apple HEVC tag, yuv420p for consumer playback.
Example output for a request like "compress this MP4 for the web, keep visual quality":
sh
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
    keeps near-source quality while shrinking the file; drop to 18 for archival.
  • -preset veryslow
    trades encode time for ~20-30% smaller output at the same CRF.
  • -pix_fmt yuv420p
    ensures playback in Safari, QuickTime, and most browsers.
  • +faststart
    moves the moov atom to the front so the video starts playing before fully downloaded.
  • -c:a aac -b:a 128k
    re-encodes audio at a transparent stereo bitrate.
End of example.
当用户要求提供命令时,返回:
  1. 完整的单行 FFmpeg 命令,放在
    sh
    代码块中,以便直接粘贴使用。
  2. 一个简短的项目符号列表,解释每个非简单参数和滤镜。
  3. 任何注意事项:播放器兼容性、预期运行成本、有损处理步骤,或相关参考文件中链接的已知 FFmpeg 特有问题。
仅当用户明确要求“仅提供命令”时,才省略说明部分。
当用户要求审查现有命令时,按以下方式组织发现:
  1. 正确性——会导致失败或错误输出的参数或滤镜顺序。
  2. 质量——CRF、preset、色彩空间、faststart 和音频码率。
  3. 性能——不必要的重新编码、运行缓慢的滤镜链、缺失的硬件加速。
  4. 可移植性——编解码器与容器不匹配、Apple HEVC 标签,以及消费级播放所需的 yuv420p。
例如,用户提出“压缩这个 MP4 以用于网页,同时保持视觉质量”时,输出如下:
sh
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

参考文件

  • references/glossary.md
    - flag and filter syntax, stream selectors,
    -map
    ,
    -c copy
    rules, input vs output seeking.
  • references/simple-editing.md
    - format conversion (MP4/MKV/MOV/AVI), resize and pad, time-based trim.
  • references/audio-processing.md
    - replace, extract, mix, crossfade, downsample, stereo-to-mono, format change.
  • references/advanced-editing.md
    - playback speed, fps, jump cuts, social-media cropping, drawtext overlays, subtitles, watermarks, vstack, intro/outro assembly.
  • references/asset-generation.md
    - image-to-video, slideshow with xfade, Ken Burns, GIFs, thumbnails, scene-change storyboards.
  • references/encoding-and-tuning.md
    - daily-use template, libx264/libx265/libvpx-vp9, faststart, CRF guidance, seeking, GPU encoders, ffprobe.
  • references/glossary.md
    ——参数和滤镜语法、流选择器、
    -map
    、
    -c copy
    规则、输入 seek 与输出 seek 的区别。
  • 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 指南、seek、GPU 编码器、ffprobe。

Source

来源

Recipes adapted from the Rendi FFmpeg cheatsheet. Sample URLs in the references point at
storage.rendi.dev
so commands can be run directly without local files.
配方改编自 Rendi FFmpeg cheatsheet。参考文件中的示例 URL 指向
storage.rendi.dev
,因此无需本地文件即可直接运行命令。