ffmpeg Video skill for Codex

A good ffmpeg job starts from ffprobe, picks stream copy whenever no re-encode is needed, re-encodes once with a quality-based rate (CRF) when it is, produces files that play in browsers and on phones (yuv420p, +faststart, right codec tags), and is checked with ffprobe and a look at the output, not assumed from the command.

Probe first

ffprobe -v error -show_entries \
  format=duration,size,bit_rate:stream=index,codec_type,codec_name,profile,width,height,pix_fmt,r_frame_rate,channels,sample_rate \
  -of json in.mov

Note the codecs, pixel format (10-bit yuv420p10le and yuv422p do not play in many browsers), frame rate (variable frame rate from phones and screen recorders), rotation side data, audio channel layout, and subtitle or data streams that may not fit the target container.

Decide: copy or encode

Task	Approach
Change container only (MKV to MP4), codecs already compatible	-c copy (seconds, lossless)
Cut at rough points, speed matters	-ss before -i with -c copy; cuts snap to keyframes
Cut at exact frames	-ss before -i, re-encode video
Smaller file, wider compatibility, new resolution	Re-encode video (CRF), copy audio if it is AAC
Join files with identical codecs and parameters	concat demuxer, -c copy
Join files that differ	concat filter, re-encode (see references)

Core commands

# Universal MP4: H.264 + AAC, plays in every browser and phone
ffmpeg -i in.mov -c:v libx264 -crf 23 -preset medium -pix_fmt yuv420p \
  -c:a aac -b:a 128k -movflags +faststart out.mp4

# Downscale to 720p keeping aspect ratio (-2 keeps the width even)
ffmpeg -i in.mp4 -vf "scale=-2:720" -c:v libx264 -crf 23 -c:a copy out-720p.mp4

# HEVC for Apple devices (hvc1 tag is required for QuickTime/Safari playback)
ffmpeg -i in.mov -c:v libx265 -crf 26 -preset medium -tag:v hvc1 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -movflags +faststart out-hevc.mp4

# AV1 (smallest files, slower encode, modern players only)
ffmpeg -i in.mov -c:v libsvtav1 -crf 35 -preset 8 -pix_fmt yuv420p10le -c:a libopus -b:a 96k out.webm

# Trim, fast and lossless (starts on the keyframe at or before 00:01:05)
ffmpeg -ss 00:01:05 -i in.mp4 -t 30 -c copy clip.mp4

# Trim, frame-accurate (re-encodes)
ffmpeg -ss 00:01:05.200 -i in.mp4 -t 30 -c:v libx264 -crf 20 -c:a aac clip-exact.mp4

# Concatenate identical-format files
printf "file '%s'\n" part1.mp4 part2.mp4 part3.mp4 > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4

# Extract audio without re-encoding, or as MP3
ffmpeg -i in.mp4 -vn -c:a copy audio.m4a
ffmpeg -i in.mp4 -vn -c:a libmp3lame -q:a 2 audio.mp3

# Thumbnail at 10 s, and a poster sheet of 1 frame every 30 s
ffmpeg -ss 10 -i in.mp4 -frames:v 1 -q:v 2 thumb.jpg
ffmpeg -i in.mp4 -vf "fps=1/30,scale=320:-2,tile=4x3" -frames:v 1 sheet.jpg

CRF guide for libx264: 18 is visually lossless, 23 default, 28 small. Each +6 roughly halves the size. libx265 CRF about 4 to 6 higher gives similar quality; SVT-AV1 around 30 to 38. Use -preset slow when encode time does not matter.

Subtitles

# Soft subtitles (toggleable): MP4 needs mov_text, MKV takes SRT as-is
ffmpeg -i in.mp4 -i subs.srt -map 0 -map 1 -c copy -c:s mov_text \
  -metadata:s:s:0 language=eng out-subs.mp4

# Burned in (always visible; required for most social platforms)
ffmpeg -i in.mp4 -vf "subtitles=subs.srt:force_style='FontSize=22,Outline=2'" \
  -c:v libx264 -crf 20 -c:a copy out-burned.mp4

The subtitles filter needs ffmpeg built with libass. Check with ffmpeg -hide_banner -filters | grep subtitles; some package-manager builds omit it. Paths with colons or quotes must be escaped inside the filter string; copy the SRT to a simple name first. Generating the SRT from speech belongs to $speech-to-text.

Hardware encoders

Platform	Encoder	Rate control
macOS (Apple silicon)	h264_videotoolbox, hevc_videotoolbox	-b:v 6M or -q:v 60 (quality 1 to 100)
NVIDIA	h264_nvenc, hevc_nvenc, av1_nvenc	-cq 23 -preset p5
Intel/AMD on Linux	h264_vaapi, h264_qsv	Device setup flags required

Hardware encoders are much faster but larger at equal quality. Use them for previews and bulk screen recordings; use software encoders for final masters. List what your build has with ffmpeg -hide_banner -encoders | grep -E 'videotoolbox|nvenc|qsv|vaapi'.

Batch a folder

mkdir -p out
for f in in/*.mov; do
  base=$(basename "${f%.*}")
  [ -e "out/$base.mp4" ] && continue                     # rerun-safe
  ffmpeg -nostdin -hide_banner -loglevel error -i "$f" \
    -c:v libx264 -crf 23 -preset medium -pix_fmt yuv420p \
    -c:a aac -b:a 128k -movflags +faststart "out/$base.tmp.mp4" \
  && mv "out/$base.tmp.mp4" "out/$base.mp4" \
  || echo "FAILED $f" >> out/failures.txt
done

-nostdin stops ffmpeg from eating the loop’s input; the temp name means an interrupted encode never looks finished. Never pass -y against the input folder; write to out/.

Gotchas

• -ss after -i decodes and discards everything before the point: correct but slow. Before -i it seeks fast and, when re-encoding, is still frame-accurate in modern ffmpeg.
• -t is a duration, -to is a position; with -ss before -i, -to counts from the new start.
• Odd dimensions fail with libx264 (width not divisible by 2); use -2 in scale.
• Phone video with rotation metadata is auto-rotated on re-encode; with -c copy the metadata stays and players handle it.
• Variable frame rate screen recordings can drift audio after cutting; add -fps_mode cfr -r 30 when re-encoding if sync drifts.
• -map 0 copies every stream, including data streams MP4 cannot hold; map what you need (-map 0:v:0 -map 0:a:0) when muxing fails.
• 10-bit HDR sources need tone mapping to look right in SDR; see the references.
• Encoding needs no network, but installing ffmpeg does; ask before installing in a sandbox.

For more recipes (crop, pad to 9:16, speed changes, watermark, concat filter, HDR to SDR, HLS segments, two-pass target size), read references/filter-recipes.md when the core commands above do not cover the job.

Verification

ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height,pix_fmt -of compact out.mp4
ffmpeg -v error -i out.mp4 -f null - && echo "decodes cleanly"

• Duration matches the source (or the requested cut) within one frame or two.
• Codec, pixel format and resolution are what was asked for.
• Watch the first and last seconds and one point in the middle; check A/V sync.
• For delivery targets (browser, iPhone, a platform’s upload limits), test playback there.

Report

**Input:** demo.mov (ProRes 422, 3840x2160, 29.97 fps, 4:12, 6.1 GB)
**Output:** demo-1080p.mp4 (H.264 High, yuv420p, 1920x1080, AAC 128k, faststart, 182 MB)
**Command:** ffmpeg -i demo.mov -vf scale=-2:1080 -c:v libx264 -crf 22 -preset slow -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart demo-1080p.mp4
**Checks:** duration 4:12.13 both, decodes without errors, plays in Safari and Chrome