FFmpeg Video Editor Agent Skill

You are an expert FFmpeg operator. Use this skill to answer any video/audio editing request by constructing correct ffmpeg command lines. Always probe input files first, then select the appropriate operation category below.

Probe Input Files

Run scripts/probe.sh <file> (make executable first with chmod +x scripts/*.sh if needed), or inspect manually:

ffprobe -v error -show_streams -show_format -of json input.mp4

Trim / Cut

# Fast stream-copy trim (no re-encode)
ffmpeg -ss 00:01:00 -to 00:02:30 -i input.mp4 -c copy out.mp4

# Precise trim (re-encode around keyframes)
ffmpeg -ss 00:01:00 -i input.mp4 -t 90 -c:v libx264 -crf 18 -c:a aac out.mp4

Transcode

# H.264 web-safe (pix_fmt ensures broad player compatibility)
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart out.mp4

# H.265 (smaller files)
ffmpeg -i input.mp4 -c:v libx265 -crf 28 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k out.mp4

# VP9 for web
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 33 -b:v 0 \
  -c:a libopus -b:a 128k out.webm

# AV1 (best compression)
ffmpeg -i input.mp4 -c:v libaom-av1 -crf 35 -cpu-used 4 \
  -c:a libopus -b:a 128k out.mkv

See references/CODECS.md for full codec comparison.

Concatenate Files

# Using helper script
scripts/concat.sh out.mp4 clip1.mp4 clip2.mp4 clip3.mp4

# Manual concat demuxer
printf "file 'a.mp4'\nfile 'b.mp4'\n" > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4

Scale / Resize

# Scale to 1920×1080, keep aspect ratio, pad to fill
ffmpeg -i in.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,\
pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black" out.mp4

# Scale by width only (auto height)
ffmpeg -i in.mp4 -vf "scale=1280:-2" out.mp4

Crop

# Crop 640×360 starting at (100,50)
ffmpeg -i in.mp4 -vf "crop=640:360:100:50" out.mp4

# Center crop to 1:1 square
ffmpeg -i in.mp4 -vf "crop=min(iw\,ih):min(iw\,ih)" out.mp4

Overlay / Watermark

# Overlay image (top-right, 10px margin)
ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[0:v][1:v] overlay=W-w-10:10" out.mp4

# PiP: small video on top of main
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "[1:v]scale=320:-2[small];[0:v][small]overlay=W-w-10:H-h-10" out.mp4

Draw Text / Titles

ffmpeg -i in.mp4 -vf \
  "drawtext=text='My Title':fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf\
:fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2\
:shadowx=2:shadowy=2" out.mp4

Burn Subtitles

# SRT subtitles (re-encode required)
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" out.mp4

# ASS/SSA subtitles (preserves styling)
ffmpeg -i video.mp4 -vf "ass=subs.ass" out.mp4

Speed Change

# 2× speed (video + audio)
ffmpeg -i in.mp4 -vf "setpts=0.5*PTS" -af "atempo=2.0" out.mp4

# 0.5× speed (half speed)
ffmpeg -i in.mp4 -vf "setpts=2.0*PTS" -af "atempo=0.5" out.mp4

# >4×: chain atempo (max 2.0 per filter)
ffmpeg -i in.mp4 -vf "setpts=0.25*PTS" -af "atempo=2.0,atempo=2.0" out.mp4

# <0.5×: chain atempo (min 0.5 per filter)
ffmpeg -i in.mp4 -vf "setpts=4.0*PTS" -af "atempo=0.5,atempo=0.5" out.mp4

Reverse

ffmpeg -i in.mp4 -vf "reverse" -af "areverse" out.mp4

Transitions (xfade)

# Dissolve between two clips (1s overlap at t=5)
ffmpeg -i a.mp4 -i b.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=dissolve:duration=1:offset=5[v];\
[0:a][1:a]acrossfade=d=1[a]" \
  -map "[v]" -map "[a]" out.mp4

See references/TRANSITIONS.md for all 40+ xfade transition types.

Audio: Volume & Normalization

# Adjust volume
ffmpeg -i in.mp4 -af "volume=1.5" out.mp4

# EBU R128 normalization (two-pass)
scripts/normalize-audio.sh in.mp4 out.mp4

# One-pass loudnorm
ffmpeg -i in.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" out.mp4

Audio: Fade In/Out

# Fade in 2s at start, fade out 3s before end (total 60s)
ffmpeg -i in.mp4 -af "afade=t=in:d=2,afade=t=out:st=57:d=3" out.mp4

Mix / Combine Audio

# Mix two audio streams
ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "[0:a][1:a]amix=inputs=2:duration=first:weights=1 0.3[a]" \
  -map 0:v -map "[a]" -c:v copy out.mp4

Color Grading

# Brightness/Contrast/Saturation
ffmpeg -i in.mp4 -vf "eq=brightness=0.05:contrast=1.2:saturation=1.3" out.mp4

# Hue shift
ffmpeg -i in.mp4 -vf "hue=h=30:s=1.1" out.mp4

# Apply 3D LUT (.cube)
ffmpeg -i in.mp4 -vf "lut3d=file=lut.cube" out.mp4

# Apply Hald CLUT PNG
ffmpeg -i in.mp4 -i lut.png \
  -filter_complex "[0:v][1:v]haldclut" out.mp4

Chroma Key / Green Screen

# chromakey (color + similarity + blend)
ffmpeg -i foreground.mp4 -i background.mp4 \
  -filter_complex "[0:v]chromakey=0x00FF00:0.3:0.2[fg];\
[1:v][fg]overlay" out.mp4

# colorkey (simpler, exact color)
ffmpeg -i in.mp4 -vf "colorkey=green:0.3:0.2" out.mp4

Frame Rate Conversion

# Convert to 30fps
ffmpeg -i in.mp4 -vf "fps=30" out.mp4

# Use motion interpolation (minterpolate)
ffmpeg -i in.mp4 -vf "minterpolate=fps=60:mi_mode=mci" out.mp4

Extract Frames / Create Slideshow

# Extract one frame per second as PNG
ffmpeg -i in.mp4 -vf "fps=1" frames/%04d.png

# Slideshow from images (3s per image, 30fps output)
ffmpeg -framerate 1/3 -i frames/%04d.png -c:v libx264 -r 30 out.mp4

Stacking / Grid Layout

# Side by side (hstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]hstack=inputs=2" out.mp4

# Top-bottom (vstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]vstack=inputs=2" out.mp4

# 2×2 grid (xstack)
ffmpeg -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
  -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0" out.mp4

Hardware-Accelerated Encoding

# NVIDIA NVENC H.264
ffmpeg -hwaccel cuda -i in.mp4 -c:v h264_nvenc -preset p4 -cq 23 out.mp4

# Apple VideoToolbox H.265
ffmpeg -i in.mp4 -c:v hevc_videotoolbox -q:v 60 out.mp4

# Intel QuickSync H.264
ffmpeg -hwaccel qsv -i in.mp4 -c:v h264_qsv -global_quality 23 out.mp4

See references/HARDWARE-ACCEL.md for full GPU encoding guide.

Encoding Presets (assets/preset-profiles.json)

When the task maps to a named use case below, read assets/preset-profiles.json and use the example field as the ready-made ffmpeg command.

Multi-Stream Filter Graph Pattern

ffmpeg \
  -i input_video.mp4 \
  -i overlay.png \
  -i audio_bed.mp3 \
  -filter_complex "
    [0:v]scale=1920:1080,setsar=1[base];
    [1:v]scale=200:-2,format=rgba,colorchannelmixer=aa=0.8[logo];
    [base][logo]overlay=W-w-20:20[composited];
    [0:a][2:a]amix=inputs=2:weights=1 0.2[audio_mix]
  " \
  -map "[composited]" -map "[audio_mix]" \
  -c:v libx264 -crf 18 -preset slow \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

Common Options Reference

Debugging Tips

# Dry-run: print filter graph without encoding
ffmpeg -i in.mp4 -vf "scale=1280:-2" -f null -

# Benchmark encode speed
ffmpeg -benchmark -i in.mp4 -c:v libx264 -f null -

# Show available encoders
ffmpeg -encoders | grep -E "^.V|^.A"

# Show filter options
ffmpeg -help filter=loudnorm