ffmpeg-cli

FFmpeg CLI

Overview

Execute FFmpeg command-line operations to process video, audio, and image files. This skill provides comprehensive FFmpeg workflows for 13 common multimedia processing tasks, from basic format conversion to advanced video editing with transitions and overlays.

Prerequisites

Verify FFmpeg installation before proceeding:

ffmpeg -version

Minimum version: FFmpeg 4.3+ (for xfade transitions) Common installation:

• macOS: brew install ffmpeg
• Linux: apt-get install ffmpeg or yum install ffmpeg
• Windows: Download from ffmpeg.org

Official CLI Syntax

Command Structure

ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ...

Critical Rule: Options are positional. Input options apply ONLY to the next -i. Output options apply ONLY to the next output file. Misordering options causes silent misbehavior.

# CORRECT: -ss seeks input (fast), -t limits output duration
ffmpeg -y -ss 5 -i input.mp4 -t 10 -c:v libx264 output.mp4
#      ^   ^                   ^                    ^
#      |   input option        output options       output file
#      global option

# DIFFERENT BEHAVIOR: -ss after -i seeks output (slow but accurate)
ffmpeg -y -i input.mp4 -ss 5 -t 10 -c:v libx264 output.mp4

Stream Specifiers

Target specific streams with -option:stream_specifier:

Pattern	Meaning	Example
v	All video streams	-c:v libx264
a	All audio streams	-c:a aac
s	All subtitle streams	-c:s mov_text
v:0	First video stream	-b:v:0 2M
a:1	Second audio stream	-c:a:1 copy

Stream Mapping

# Without -map: auto-selects best video + best audio + first subtitle
ffmpeg -i input.mp4 output.mp4

# With -map: auto-selection DISABLED — must map ALL desired streams
ffmpeg -i input.mp4 -map 0:v -map 0:a output.mp4

# Multiple inputs: video from first, audio from second
ffmpeg -i video.mp4 -i audio.mp3 -map 0:v -map 1:a output.mp4

Gotcha: Using -map once disables auto-selection. Forgetting to map audio = silent output.

Seeking Behavior

Position	Speed	Accuracy	Use Case
-ss before -i	Fast (keyframe seek)	Approximate	Stream copy, rough cuts
-ss after -i	Slow (decode & discard)	Frame-exact	Precise editing
Both combined	Fast + Accurate	Best of both	Recommended for re-encode

# Fast seeking (good with -c copy)
ffmpeg -ss 30 -i input.mp4 -t 10 -c copy output.mp4

# Accurate seeking (re-encode required)
ffmpeg -i input.mp4 -ss 30 -t 10 -c:v libx264 -c:a aac output.mp4

# Combined: fast jump + fine-tune
ffmpeg -ss 29 -i input.mp4 -ss 1 -t 10 -c:v libx264 -c:a aac output.mp4

Stream Copy vs Re-encoding

	-c copy	Re-encode (-c:v libx264)
Speed	Very fast	Slow
Quality	Lossless (original)	Depends on settings
Filters	Cannot use	Required for filters
Cut accuracy	Keyframe only	Frame-exact

# Stream copy (fast, no quality loss, no filters)
ffmpeg -i input.mp4 -c copy output.mp4

# Re-encode video only (allows video filters, copies audio)
ffmpeg -i input.mp4 -vf "scale=1280:720" -c:v libx264 -c:a copy output.mp4

Common Patterns

Copy without re-encoding (fast):

ffmpeg -i input.mp4 -c copy output.mp4

Re-encode with quality control:

ffmpeg -i input.mp4 -c:v libx264 -crf 23 -c:a aac output.mp4

Apply video filter:

ffmpeg -i input.mp4 -vf "filter_name=param=value" -c:a copy output.mp4

Complex filter graph:

ffmpeg -i input1.mp4 -i input2.mp4 \
  -filter_complex "[0:v][1:v]filter_name[out]" \
  -map "[out]" -map 0:a output.mp4

Core Operations

1. Add Text to Video

Add text overlays with full control over font, size, color, position, and timing.

Basic text overlay:

ffmpeg -i input.mp4 \
  -vf "drawtext=fontfile=/path/to/font.ttf:text='Hello World':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=h-th-20" \
  -c:a copy output.mp4

Parameters:

• fontfile - Path to TrueType font file (required)
• text - Text content (escape single quotes: don''t)
• fontsize - Font size in pixels (default: 16)
• fontcolor - Color name or hex value
• x, y - Position (numbers or expressions)
• enable - Time control: 'between(t,5,10)'

Position expressions:

• (w-text_w)/2 - center horizontally
• (h-text_h)/2 - center vertically
• 10 - 10px from left/top edge
• w-text_w-10 - 10px from right edge
• h-th-20 - 20px from bottom edge

Text with background box:

ffmpeg -i input.mp4 \
  -vf "drawtext=fontfile=/path/to/font.ttf:text='Subtitle':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=h-th-20:box=1:boxcolor=black@0.5:boxborderw=5" \
  -c:a copy output.mp4

Timed text (show from 5 to 10 seconds):

ffmpeg -i input.mp4 \
  -vf "drawtext=fontfile=/path/to/font.ttf:text='Limited':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2:enable='between(t,5,10)'" \
  -c:a copy output.mp4

2. Add Subtitles from SRT File

Burn subtitles from SRT file into video.

Method 1: Using subtitles filter (recommended):

ffmpeg -i input.mp4 -vf "subtitles=subtitle.srt" -c:a copy output.mp4

Method 2: Custom styling with drawtext (programmatic):

Parse SRT file and generate drawtext filter chain for each subtitle entry. Each entry becomes:

drawtext=fontfile=/path/to/font.ttf:text='subtitle text':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=h-th-50:box=1:boxcolor=black@0.5:boxborderw=5:enable='between(t,START_TIME,END_TIME)'

Combine all entries with commas:

ffmpeg -i input.mp4 -vf "drawtext=...,drawtext=...,drawtext=..." -c:a copy output.mp4

Custom subtitle styling:

ffmpeg -i input.mp4 \
  -vf "subtitles=subtitle.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&H00FFFFFF'" \
  -c:a copy output.mp4

3. Extract Audio from Video

Extract audio track in various formats.

Extract as MP3:

ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 192k -map 0:a:0 output.mp3

Extract as AAC:

ffmpeg -i input.mp4 -vn -c:a aac -b:a 192k -map 0:a:0 output.aac

Extract as WAV (lossless):

ffmpeg -i input.mp4 -vn -c:a pcm_s16le -map 0:a:0 output.wav

Copy audio without re-encoding:

ffmpeg -i input.mp4 -vn -c:a copy -map 0:a:0 output.m4a

Parameters:

• -vn - Remove video stream
• -c:a - Audio codec (libmp3lame, aac, copy)
• -b:a - Audio bitrate (128k, 192k, 320k)
• -map 0:a:0 - Select first audio stream

4. Convert Image to Video

Convert static image to video with specified duration.

Basic conversion:

ffmpeg -loop 1 -i image.png \
  -c:v libx264 -t 10 -pix_fmt yuv420p \
  output.mp4

With silent audio for compatibility:

ffmpeg -loop 1 -i image.png \
  -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=44100 \
  -c:v libx264 -c:a aac -t 10 -pix_fmt yuv420p -shortest \
  output.mp4

Custom dimensions:

ffmpeg -loop 1 -i image.png \
  -f lavfi -i anullsrc \
  -vf "scale=1920:1080" \
  -c:v libx264 -c:a aac -t 10 -pix_fmt yuv420p -shortest \
  output.mp4

Parameters:

• -loop 1 - Loop image input
• -t - Duration in seconds
• -pix_fmt yuv420p - Ensure compatibility
• anullsrc - Generate silent audio
• -shortest - Match shortest input duration

5. Merge/Concatenate Videos

Combine multiple videos into one.

Method 1: Concat demuxer (same codec/format):

# Create file list
echo "file 'video1.mp4'" > list.txt
echo "file 'video2.mp4'" >> list.txt

# Concatenate
ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4

Method 2: Concat filter (different formats):

ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 \
  -filter_complex "[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[outv][outa]" \
  -map "[outv]" -map "[outa]" output.mp4

Normalize before merging (different resolutions/framerates):

For each input video, apply normalization:

scale=1920:1080:force_original_aspect_ratio=decrease,
pad=1920:1080:(ow-iw)/2:(oh-ih)/2:color=black,
setsar=1,
fps=30,
setpts=PTS-STARTPTS

For audio:

aformat=sample_fmts=fltp:sample_rates=44100:channel_layouts=stereo,
asetpts=PTS-STARTPTS

Then concatenate normalized streams using concat protocol or concat filter.

Handle videos without audio:

Check if video has audio using ffprobe. If missing, add silent audio:

ffmpeg -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=44100:duration=VIDEO_DURATION

Mix with video stream before normalization.

6. Mix Audio with Video

Combine video with background music or replace audio.

Basic audio mixing:

ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "[0:a]volume=1.0[a0];[1:a]volume=0.5[a1];[a0][a1]amix=inputs=2:duration=first[a]" \
  -map 0:v -map "[a]" -c:v copy output.mp4

Replace video audio:

ffmpeg -i video.mp4 -i new_audio.mp3 \
  -map 0:v -map 1:a -c:v copy -c:a aac -shortest output.mp4

Advanced mixing with fade effects:

ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "
    [1:a]afade=t=in:st=0:d=2,afade=t=out:st=28:d=2,volume=0.5[a1];
    [0:a]volume=1.0[a0];
    [a0][a1]amix=inputs=2:duration=first[a]
  " \
  -map 0:v -map "[a]" -c:v copy output.mp4

Partial mixing with time control:

Process audio with:

[1:a]atrim=duration=DURATION,asetpts=PTS-STARTPTS,volume=VOLUME,adelay=START_TIME*1000|START_TIME*1000[overlay]

Mix with main audio:

[0:a]volume=VIDEO_VOLUME[main];
[main][overlay]amix=inputs=2:duration=first[out]

Loop short audio:

[1:a]aloop=loop=-1:size=2e9,atrim=duration=VIDEO_DURATION[looped]

Parameters:

• volume - Volume multiplier (0.0-2.0)
• amix:duration - longest/shortest/first
• adelay - Delay in milliseconds
• afade - Fade in/out
• atrim - Trim audio duration
• aloop - Loop audio (-1 for infinite)

7. Apply Video Transitions

Apply transition effects between multiple videos (requires FFmpeg 4.3+).

Fade transition:

ffmpeg -i video1.mp4 -i video2.mp4 \
  -filter_complex "
    [0:v][1:v]xfade=transition=fade:duration=1:offset=5[v];
    [0:a][1:a]acrossfade=d=1[a]
  " \
  -map "[v]" -map "[a]" output.mp4

Multiple videos with transitions:

ffmpeg -i v1.mp4 -i v2.mp4 -i v3.mp4 \
  -filter_complex "
    [0:v][1:v]xfade=transition=fade:duration=1:offset=5[v01];
    [v01][2:v]xfade=transition=wipeleft:duration=1:offset=10[v];
    [0:a][1:a]acrossfade=d=1[a01];
    [a01][2:a]acrossfade=d=1[a]
  " \
  -map "[v]" -map "[a]" output.mp4

Available transitions:

• fade, fadeblack, fadewhite
• wipeleft, wiperight, wipeup, wipedown
• slideleft, slideright, slideup, slidedown
• circlecrop, rectcrop, distance
• dissolve, pixelize, radial

Normalize videos before transition:

When videos have different resolutions or framerates:

[0:v]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black,settb=AVTB[v0];
[1:v]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black,settb=AVTB[v1];
[v0][v1]xfade=transition=fade:duration=1:offset=5[v]

Fallback for FFmpeg < 4.3:

Use fade + concat instead:

# First video: fade out at end
[0:v]fade=t=out:st=5:d=1[v0];
# Second video: fade in at start
[1:v]fade=t=in:st=0:d=1[v1];
# Concatenate
[v0][0:a][v1][1:a]concat=n=2:v=1:a=1[outv][outa]

Parameters:

• transition - Transition type
• duration - Transition duration in seconds
• offset - When transition starts in first video
• acrossfade:d - Audio crossfade duration

8. Overlay Video/Image

Place one video or image on top of another.

Basic overlay (logo/watermark):

ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[1:v]scale=150:-1[logo];[0:v][logo]overlay=10:10" \
  -c:a copy output.mp4

Positioned overlays:

# Bottom-right corner
overlay=main_w-overlay_w-10:main_h-overlay_h-10

# Center
overlay=(main_w-overlay_w)/2:(main_h-overlay_h)/2

# Top-right
overlay=main_w-overlay_w-10:10

Overlay with opacity:

ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[1:v]scale=150:-1,colorchannelmixer=aa=0.5[logo];[0:v][logo]overlay=10:10" \
  -c:a copy output.mp4

Timed overlay (show from 5 to 15 seconds):

ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[1:v]scale=150:-1[logo];[0:v][logo]overlay=10:10:enable='between(t,5,15)'" \
  -c:a copy output.mp4

Picture-in-picture:

ffmpeg -i main.mp4 -i small.mp4 \
  -filter_complex "
    [1:v]scale=320:-1[pip];
    [0:v][pip]overlay=main_w-overlay_w-10:10[v]
  " \
  -map "[v]" -map 0:a -c:a copy output.mp4

Audio handling options:

# Use main video audio only
-map 0:a

# Use overlay video audio only
-map 1:a

# Mix both audio tracks
-filter_complex "...[v];[0:a]volume=1.0[a0];[1:a]volume=0.5[a1];[a0][a1]amix=inputs=2:duration=longest[a]"
-map "[v]" -map "[a]"

Parameters:

• scale - Resize overlay (width:height, -1 for auto)
• colorchannelmixer=aa - Opacity (0.0-1.0)
• overlay=x:y - Position
• enable - Time control
• eof_action=pass - Continue main after overlay ends

9. Separate Video and Audio

Split video into separate video (muted) and audio files.

Create muted video:

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

Extract audio:

ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 192k -map 0:a:0 audio.mp3

Both in one operation:

# Muted video
ffmpeg -i input.mp4 -an -c:v copy video_only.mp4

# Audio file
ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 192k -map 0:a:0 audio.mp3

Parameters:

• -an - Remove audio stream
• -vn - Remove video stream
• -c:v copy - Copy video without re-encoding
• -c:a - Audio codec (libmp3lame, aac, copy)

10. Apply Fade In/Out

Add fade in or fade out effects to video and/or audio.

Video fade in/out:

ffmpeg -i input.mp4 \
  -vf "fade=type=in:st=0:d=2,fade=type=out:st=28:d=2" \
  -c:a copy output.mp4

Audio fade in/out:

ffmpeg -i input.mp4 \
  -af "afade=type=in:st=0:d=2,afade=type=out:st=28:d=2" \
  -c:v copy output.mp4

Both video and audio fade:

ffmpeg -i input.mp4 \
  -vf "fade=type=in:st=0:d=2,fade=type=out:st=28:d=2" \
  -af "afade=type=in:st=0:d=2,afade=type=out:st=28:d=2" \
  output.mp4

Fade to/from white:

ffmpeg -i input.mp4 \
  -vf "fade=type=in:st=0:d=2:color=white" \
  -c:a copy output.mp4

Parameters:

• type - in or out
• st - Start time in seconds
• d - Duration in seconds
• color - Fade color (default: black)

11. Add Image Stamp/Watermark

Add logo, watermark, or stamp image to video.

Basic stamp:

ffmpeg -i video.mp4 -i stamp.png \
  -filter_complex "[1:v]scale=150:-1[stamp];[0:v][stamp]overlay=10:10" \
  -c:a copy output.mp4

Rotated stamp:

ffmpeg -i video.mp4 -i stamp.png \
  -filter_complex "
    [1:v]scale=150:-1,rotate=PI/4:fillcolor=none[stamp];
    [0:v][stamp]overlay=10:10
  " \
  -c:a copy output.mp4

Stamp with opacity:

ffmpeg -i video.mp4 -i stamp.png \
  -filter_complex "
    [1:v]scale=150:-1,colorchannelmixer=aa=0.5[stamp];
    [0:v][stamp]overlay=10:10
  " \
  -c:a copy output.mp4

Timed stamp (show from 5 to 15 seconds):

ffmpeg -i video.mp4 -i stamp.png \
  -filter_complex "
    [1:v]scale=150:-1[stamp];
    [0:v][stamp]overlay=10:10:enable='between(t,5,15)'
  " \
  -c:a copy output.mp4

Parameters:

• scale - Resize stamp (width:height, -1 for auto)
• rotate - Rotation angle in radians (PI/2 = 90°, PI/4 = 45°)
• colorchannelmixer=aa - Opacity (0.0-1.0)
• overlay=x:y - Position
• enable - Time control

12. Trim/Cut Video

Extract portion of video between specified times.

Fast cut (keyframe-accurate, input seeking):

ffmpeg -ss 5 -i input.mp4 -t 10 -c copy output.mp4

Accurate cut (frame-exact, output seeking + re-encode):

ffmpeg -i input.mp4 -ss 5 -t 10 -c:v libx264 -c:a aac output.mp4

Combined seeking (fast + accurate):

ffmpeg -ss 4 -i input.mp4 -ss 1 -t 10 -c:v libx264 -c:a aac output.mp4

Extract from 5 to 15 seconds:

ffmpeg -ss 5 -i input.mp4 -to 10 -c copy output.mp4

Time duration formats:

-ss 01:23:45.678   # HH:MM:SS.mmm
-ss 5:30            # MM:SS (5 min 30 sec)
-ss 90              # seconds (numeric)
-ss 5500ms          # milliseconds with suffix

Parameters:

• -ss before -i - Input seeking (fast, keyframe-accurate)
• -ss after -i - Output seeking (slow, frame-accurate)
• -to - End time (absolute when -ss is after -i, relative when before)
• -t - Duration (always relative from seek point)
• -c copy - Stream copy (fast, keyframe-accurate only)
• -c:v libx264 - Re-encode for frame-accurate cutting

Gotcha: -to behaves differently depending on -ss position. With input seeking (-ss before -i), -to becomes relative to the new start.

13. Probe Media Information

Query metadata and technical details of media files.

Complete metadata (JSON):

ffprobe -v quiet -print_format json -show_format -show_streams input.mp4

Quick info:

ffmpeg -i input.mp4 2>&1 | grep -E 'Duration|Stream'

Video resolution:

ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=s=x:p=0 input.mp4

Video duration:

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp4

Check if video has audio:

ffprobe -i input.mp4 -show_streams -select_streams a -loglevel error

Framerate:

ffprobe -v error -select_streams v:0 -show_entries stream=r_frame_rate -of default=noprint_wrappers=1:nokey=1 input.mp4

Codec information:

ffprobe -v error -select_streams v:0 -show_entries stream=codec_name -of default=noprint_wrappers=1:nokey=1 input.mp4

Advanced Patterns

Complex Filter Graphs

Multiple outputs from single input:

ffmpeg -i input.mp4 \
  -filter_complex "
    [0:v]split=2[v1][v2];
    [v1]scale=1920:1080[out1];
    [v2]scale=1280:720[out2]
  " \
  -map "[out1]" -c:v libx264 output_1080p.mp4 \
  -map "[out2]" -c:v libx264 output_720p.mp4

Side-by-side comparison:

ffmpeg -i left.mp4 -i right.mp4 \
  -filter_complex "
    [0:v]scale=640:480[left];
    [1:v]scale=640:480[right];
    [left][right]hstack[v]
  " \
  -map "[v]" output.mp4

Quality Control

CRF (Constant Rate Factor) — recommended for local files:

CRF	Quality	Use Case
0	Lossless	Archival
18	Visually lossless	Professional editing
23	Good (default)	General purpose
28	Acceptable	Web distribution
51	Worst	(not recommended)

ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac output.mp4

Constrained bitrate — recommended for streaming:

# Average bitrate with buffer control
ffmpeg -i input.mp4 -c:v libx264 -b:v 2M -maxrate 2.5M -bufsize 5M -c:a aac output.mp4

Gotcha: -b:v 2M = 2 Megabits/s (not bytes). FFmpeg uses bits/s. Use K, M, G suffixes.

Two-pass encoding (best quality at target bitrate):

# Pass 1 (analysis only — output to /dev/null)
ffmpeg -i input.mp4 -c:v libx264 -b:v 2M -pass 1 -f null /dev/null

# Pass 2 (actual encoding using analysis)
ffmpeg -i input.mp4 -c:v libx264 -b:v 2M -pass 2 -c:a aac output.mp4

Encoding presets (speed → quality tradeoff):

ultrafast > superfast > veryfast > faster > fast > medium > slow > slower > veryslow

Tunes (content-type optimization):

# Animation
ffmpeg -i input.mp4 -c:v libx264 -crf 20 -tune animation output.mp4

# Screen recording
ffmpeg -i input.mp4 -c:v libx264 -crf 18 -tune stillimage output.mp4

# Streaming (low latency)
ffmpeg -i input.mp4 -c:v libx264 -preset fast -tune zerolatency output.mp4

Audio codec options:

# AAC at 192kbps
-c:a aac -b:a 192k

# MP3 VBR high quality (~190kbps average)
-c:a libmp3lame -q:a 2

# MP3 CBR 192kbps
-c:a libmp3lame -b:a 192k

Gotcha: VBR (-q:a) and CBR (-b:a) are mutually exclusive for MP3. Don't use both.

Hardware Acceleration

macOS (VideoToolbox):

ffmpeg -hwaccel videotoolbox -i input.mp4 -c:v h264_videotoolbox output.mp4

Linux/NVIDIA (NVENC):

ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4

Auto-detect:

ffmpeg -hwaccel auto -i input.mp4 -c:v libx264 output.mp4

Common Issues and Solutions

Fix Corrupted Video

ffmpeg -i corrupted.mp4 -c copy fixed.mp4

Add Silent Audio to Video

ffmpeg -i video.mp4 -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=44100 \
  -c:v copy -c:a aac -shortest output.mp4

Ensure Even Dimensions (H.264 requirement)

ffmpeg -i input.mp4 -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:a copy output.mp4

Convert Variable to Constant Framerate

ffmpeg -i input.mp4 -vf fps=30 -c:v libx264 -c:a copy output.mp4

Rotate Video

# 90° clockwise
ffmpeg -i input.mp4 -vf "transpose=1" -c:a copy output.mp4

# 90° counter-clockwise
ffmpeg -i input.mp4 -vf "transpose=2" -c:a copy output.mp4

# 180°
ffmpeg -i input.mp4 -vf "transpose=2,transpose=2" -c:a copy output.mp4

Remove Metadata

ffmpeg -i input.mp4 -map_metadata -1 -c copy output.mp4

Best Practices

1. Test with short clips first before processing long videos
2. Use -c copy when possible to avoid re-encoding (faster, lossless)
3. Always specify codecs explicitly to avoid unexpected defaults
4. Ensure even dimensions for H.264: scale=trunc(iw/2)*2:trunc(ih/2)*2
5. Add -pix_fmt yuv420p for maximum compatibility
6. Use CRF (18-28) for quality control instead of fixed bitrate
7. Check FFmpeg version for filter compatibility: ffmpeg -version
8. Backup original files before batch processing
9. Use -y flag cautiously (overwrites without confirmation)
10. Normalize audio when mixing from different sources

Common Global Options

• -y - Overwrite output file without asking
• -n - Never overwrite output file
• -v quiet - Suppress output messages
• -stats - Show encoding statistics
• -threads 0 - Use all CPU cores

Reference Documentation

Official Syntax Reference

For authoritative FFmpeg syntax rules extracted from official documentation (ffmpeg.org), consult:

references/ffmpeg-syntax-reference.md

This includes:

• CLI grammar and option ordering rules
• Stream specifier syntax (all patterns)
• Stream mapping and auto-selection behavior
• Seeking behavior (input vs output seeking)
• Time duration, color, size, expression syntax
• Codec options with valid ranges (libx264, AAC, libmp3lame)
• Format options (concat demuxer, probing)
• Critical gotchas and common mistakes

Detailed Filter Reference

For comprehensive documentation on all FFmpeg filters, parameters, and advanced usage patterns, consult:

references/ffmpeg-filters.md

This includes:

• Video filters: drawtext, fade, xfade, scale, overlay, pad, rotate, etc.
• Audio filters: afade, amix, acrossfade, volume, aformat, etc.
• Filter graph syntax hierarchy and escaping rules
• Expression evaluation (variables, functions, constants)
• Performance tips and common pitfalls
• Version compatibility information

Common Recipes and Patterns

For frequently used command patterns and real-world examples, consult:

references/common-recipes.md

This includes:

• Text and subtitles recipes
• Audio processing workflows
• Video editing patterns
• Format conversion examples
• Quality optimization techniques
• Troubleshooting solutions
• Batch processing scripts

Access references when:

• Need accurate syntax rules → ffmpeg-syntax-reference.md
• Need filter parameters or escaping rules → ffmpeg-filters.md
• Need real-world command examples → common-recipes.md

Version Requirements

• FFmpeg 4.3+ - Required for xfade transitions
• FFmpeg 3.0+ - Most other filters
• Check version: ffmpeg -version
• Check filter availability: ffmpeg -filters | grep filter_name

Output Format Compatibility

Ensure H.264/AAC compatibility:

-c:v libx264 -c:a aac -pix_fmt yuv420p -movflags +faststart

Parameters:

• -pix_fmt yuv420p - Maximum playback compatibility
• -movflags +faststart - Enable web streaming (MP4)
• Even dimensions required for H.264