ffmpeg

FFmpeg/FFprobe command reference for media operations — transcode, probe, extract, concat, filter, stream copy, HW accel. Use when an agent needs to manipulate audio/video files directly without a hig

SKILL.md

GitHub

ffmpeg

Direct media manipulation via ffmpeg and ffprobe. Use this skill for operations that don't need a full video editing pipeline (video-use) or composition framework (HyperFrames/Remotion).

Installed Build

ffmpeg 8.1.1 — Homebrew, Apple Silicon (aarch64)
Path: /opt/homebrew/bin/ffmpeg
HW accel: VideoToolbox (encode/decode), AudioToolbox
Codecs: libx264, libx265, libsvtav1, libvpx, libopus, libmp3lame, libdav1d
Scoring: libvmaf
TLS: openssl

Probe Before Act

Always ffprobe before processing. Never assume codec, resolution, framerate, or duration.

# JSON probe (agent-friendly)
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4

# Quick duration
ffprobe -v quiet -show_entries format=duration -of csv=p=0 input.mp4

# Stream summary
ffprobe -v quiet -show_entries stream=index,codec_type,codec_name,width,height,r_frame_rate,channels,sample_rate -of json input.mp4

Common Operations

Transcode

# H.264 (universal compatibility)
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k output.mp4

# H.265 (smaller files, good device support)
ffmpeg -i input.mp4 -c:v libx265 -crf 28 -preset medium -c:a aac -b:a 128k output.mp4

# AV1 (best compression, slower encode)
ffmpeg -i input.mp4 -c:v libsvtav1 -crf 30 -preset 6 -c:a libopus -b:a 128k output.webm

# VP9 + Opus (web)
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus -b:a 128k output.webm

HW-Accelerated (Apple Silicon)

# VideoToolbox H.264 encode (fast, lower quality control)
ffmpeg -i input.mp4 -c:v h264_videotoolbox -b:v 5M -c:a aac output.mp4

# VideoToolbox H.265 encode
ffmpeg -i input.mp4 -c:v hevc_videotoolbox -b:v 3M -c:a aac output.mp4

# HW decode + SW encode (best quality with fast decode)
ffmpeg -hwaccel videotoolbox -i input.mp4 -c:v libx264 -crf 23 -c:a aac output.mp4

Stream Copy (no re-encode)

# Trim without re-encoding
ffmpeg -ss 00:01:30 -to 00:03:00 -i input.mp4 -c copy trimmed.mp4

# Extract audio
ffmpeg -i input.mp4 -vn -c:a copy audio.aac
ffmpeg -i input.mp4 -vn -c:a libmp3lame -q:a 2 audio.mp3

# Strip audio
ffmpeg -i input.mp4 -an -c:v copy video_only.mp4

# Remux (change container)
ffmpeg -i input.mkv -c copy output.mp4

Extract

# Single frame at timestamp
ffmpeg -ss 00:00:05 -i input.mp4 -frames:v 1 frame.png

# Frame sequence (1 fps)
ffmpeg -i input.mp4 -vf "fps=1" frames/frame_%04d.png

# Thumbnail grid (4x4)
ffmpeg -i input.mp4 -vf "select='not(mod(n,100))',scale=320:-1,tile=4x4" -frames:v 1 grid.png

# GIF from segment
ffmpeg -ss 5 -t 3 -i input.mp4 -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" out.gif

Concat

# File list concat (same codec)
printf "file '%s'\n" clip1.mp4 clip2.mp4 clip3.mp4 > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4

# Re-encode concat (mixed codecs/resolutions)
ffmpeg -i clip1.mp4 -i clip2.mp4 -filter_complex "[0:v:0][0:a:0][1:v:0][1:a:0]concat=n=2:v=1:a=1[outv][outa]" -map "[outv]" -map "[outa]" output.mp4

Filters

# Scale
ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" -c:a copy output.mp4

# Overlay (picture-in-picture)
ffmpeg -i main.mp4 -i overlay.png -filter_complex "overlay=W-w-10:H-h-10" output.mp4

# Color correction (ASC CDL model)
ffmpeg -i input.mp4 -vf "eq=brightness=0.06:contrast=1.1:saturation=1.2" output.mp4

# Fade in/out
ffmpeg -i input.mp4 -vf "fade=t=in:st=0:d=1,fade=t=out:st=9:d=1" -af "afade=t=in:st=0:d=1,afade=t=out:st=9:d=1" output.mp4

# Speed change (2x)
ffmpeg -i input.mp4 -vf "setpts=0.5*PTS" -af "atempo=2.0" output.mp4

# Burn subtitles
ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontSize=24,PrimaryColour=&H00FFFFFF'" output.mp4

# Audio normalization (loudnorm two-pass)
ffmpeg -i input.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json -f null - 2>&1 | tail -12
# Then apply measured values in second pass

Audio

# WAV extraction (for processing)
ffmpeg -i input.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav

# Mix audio tracks
ffmpeg -i video.mp4 -i music.mp3 -filter_complex "[0:a][1:a]amix=inputs=2:duration=first:dropout_transition=2[a]" -map 0:v -map "[a]" -c:v copy output.mp4

# Volume adjustment
ffmpeg -i input.mp4 -af "volume=1.5" output.mp4

# Silence detection
ffmpeg -i input.mp4 -af "silencedetect=noise=-30dB:d=0.5" -f null - 2>&1 | grep silence

Batch / Scripting Patterns

# Process all MP4s in directory
for f in *.mp4; do ffmpeg -i "$f" -c:v libx264 -crf 23 -c:a aac "out/${f}"; done

# Parallel with xargs (4 jobs)
ls *.mp4 | xargs -P4 -I{} ffmpeg -i {} -c:v libx264 -crf 23 -c:a aac out/{}

Quality Guidelines

Use case Codec CRF/Bitrate Notes
Archive libx264 CRF 18 Visually lossless
Web delivery libx264 CRF 23 Good balance
Social media libx264 CRF 20-22 Platforms re-encode anyway
Transparent overlay VP9/WebM CRF 30 -pix_fmt yuva420p
Audio podcast libmp3lame -q:a 2 ~190kbps VBR
Voice-only libopus 64k Mono, 16kHz

Hard Rules

  1. Probe first. Never assume input properties.
  2. Stream copy when possible. If you're not changing the codec, use -c copy.
  3. Use -movflags +faststart on MP4 outputs for web delivery.
  4. 30ms audio fades at cut boundaries to prevent pops: afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03.
  5. Interleaved stream order for concat filter: [v0][a0][v1][a1], not [v0][v1][a0][a1].
  6. Never merge duplicate filters silently — two scale filters in a chain must be collapsed into one or separated by a split.
  7. Verify output after every operation: ffprobe the result, check duration, check file size > 0.
  8. Quote paths — filenames with spaces or special chars break unquoted.

VMAF Quality Scoring

# Compare transcoded output against original
ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi libvmaf -f null -

Relationship to Other Skills

Skill When to use instead
video-use Full editing pipeline: multi-take selection, EDL, color grade, overlays, subtitles
hyperframes HTML/CSS video compositions, animated overlays, captions
hyperframes-cli HyperFrames project lifecycle (init, lint, render)
cli-anything Building a full CLI harness around ffmpeg for a specific workflow

Use this ffmpeg skill for direct, one-off media operations that don't need the orchestration layer of video-use or the composition model of HyperFrames.