ffmpeg

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.

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.