Ffmpeg Command Syntax

CRITICAL: FFmpeg Option Ordering Rules

The most common FFmpeg mistake is putting options in the wrong place. Options in FFmpeg are position-sensitive and apply to the NEXT file specified after them.

The Golden Rule

ffmpeg [global_options] {[input_options] -i input}... {[output_options] output}...

Key principle: Options are applied to the next file. They are reset between files.

---

Option Categories at a Glance

The full per-category catalog (every option, with descriptions) lives in `references/complete-option-reference.md`.

Global Options (Quick Subset)

ffmpeg -y -hide_banner -v warning -i input.mp4 output.mp4

Common global flags: -y, -n, -v/-loglevel, -stats, -progress, -report, -hide_banner, -filter_complex, -filter_complex_threads, -init_hw_device, -filter_hw_device.

Input Options (Quick Subset)

Placed immediately before the -i they apply to. They affect how the file is read/decoded.

Most-used: -ss, -t, -to, -itsoffset, -itsscale, -re, -readrate, -stream_loop, -hwaccel, -hwaccel_device, -hwaccel_output_format, -c:v/-c:a (as decoder), -r/-s/-pix_fmt (raw inputs), -accurate_seek, -thread_queue_size.

# Correct: Input options before their -i
ffmpeg -ss 00:01:00 -t 30 -i input.mp4 output.mp4

# Wrong: -ss after -i becomes an OUTPUT (slow) seek
ffmpeg -i input.mp4 -ss 00:01:00 output.mp4

Hardware acceleration must always go before -i:

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

Output Options (Quick Subset)

Placed after all inputs and before the output file they apply to. They affect how the file is encoded/written.

Most-used: -c:v/-c:a/-c:s (as encoder), -b:v/-b:a, -crf, -qp, -preset, -tune, -profile:v, -level, -r/-s/-aspect/-pix_fmt, -vf/-af, -map, -ss/-t/-to (output forms), -fs, -frames:v/-frames:a, -movflags, -metadata, -disposition, -shortest, -an/-vn/-sn.

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

---

Options That Switch Behavior by Position

Some options have completely different meanings depending on whether they appear before or after -i.

-ss (Seek/Start Time) - Position Critical

# BEFORE -i (INPUT): Fast keyframe seek, then decode to exact position with -accurate_seek (default)
ffmpeg -ss 00:01:00 -i input.mp4 -t 30 -c copy output.mp4

# AFTER -i (OUTPUT): Frame-accurate but slow - decodes everything, discards until target
ffmpeg -i input.mp4 -ss 00:01:00 -t 30 -c:v libx264 output.mp4

# BOTH (recommended): coarse seek + fine seek
ffmpeg -ss 00:00:55 -i input.mp4 -ss 00:00:05 -t 30 -c:v libx264 output.mp4

Note: -ss before -i resets timestamps to 0. Use -copyts to preserve originals.

-t and -to

# -t BEFORE -i: limits how much of input to READ
ffmpeg -t 60 -i input.mp4 -c copy output.mp4

# -t AFTER -i: limits output DURATION
ffmpeg -i input.mp4 -t 60 -c copy output.mp4

# -ss + -to: with timestamp reset, -to is relative to new zero
ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4  # 30s clip
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4  # also 30s clip

-r (Frame Rate)

# BEFORE -i: input frame rate (raw/image sequences)
ffmpeg -r 30 -i frame_%04d.png output.mp4

# AFTER -i: output frame rate (adds/drops frames)
ffmpeg -i input.mp4 -r 24 output.mp4

-s (Size)

# BEFORE -i: raw input size
ffmpeg -s 1920x1080 -pix_fmt yuv420p -i raw.yuv output.mp4

# AFTER -i: scales output (prefer -vf scale instead)
ffmpeg -i input.mp4 -s 1280x720 output.mp4

-c / -codec

# BEFORE -i: DECODER selection
ffmpeg -c:v h264_cuvid -i input.mp4 -c:v h264_nvenc output.mp4

# AFTER -i: ENCODER selection (common case)
ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4

---

Stream Specifiers (Quick Form)

Target specific streams with -option[:specifier]:

ffmpeg -i input.mkv -c:v libx264 -c:a aac -c:s mov_text output.mp4
ffmpeg -i a.mp4 -i b.mp4 -map 1:0 -c copy output.mp4

Common specifiers: :v, :V, :a, :s, :d, :t, :v:0, :a:1, :0, :m:key:value, :p:0. Full table and per-stream examples in `references/stream-specifiers.md`.

---

Multiple Inputs and Outputs

# Per-input options
ffmpeg \
  -ss 10 -i first.mp4 \
  -ss 5 -i second.mp4 \
  -filter_complex "[0:v][1:v]overlay" output.mp4

# Per-output options (they RESET between outputs)
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 output_h264.mp4 \
  -c:v libx265 -crf 28 output_h265.mp4

# WRONG: second output silently gets no encoding options
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4

---

Common Mistakes and Fixes

1. Input option after -i

# WRONG: -hwaccel after -i has no effect
ffmpeg -i input.mp4 -hwaccel cuda -c:v h264_nvenc output.mp4
# CORRECT
ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4

2. Output option before -i

# WRONG: -c:v before -i tries to choose a decoder
ffmpeg -c:v libx264 -i input.mp4 output.mp4
# CORRECT
ffmpeg -i input.mp4 -c:v libx264 output.mp4

3. Expecting options to persist across outputs

# WRONG
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4
# CORRECT
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 out1.mp4 \
  -c:v libx264 -crf 23 out2.mp4

4. Wrong -ss position for accuracy

# Fast but may snap to keyframe
ffmpeg -ss 00:05:00 -i input.mp4 -t 30 -c copy output.mp4
# Accurate but slow
ffmpeg -i input.mp4 -ss 00:05:00 -t 30 -c:v libx264 output.mp4
# Fast AND accurate
ffmpeg -ss 00:04:55 -i input.mp4 -ss 5 -t 30 -c:v libx264 output.mp4

5. Mixing inputs and outputs

# WRONG
ffmpeg -i input1.mp4 -c:v libx264 output1.mp4 -i input2.mp4 output2.mp4
# CORRECT
ffmpeg -i input1.mp4 -i input2.mp4 \
  -map 0 -c:v libx264 output1.mp4 \
  -map 1 -c:v libx264 output2.mp4

6. -t vs -to with -ss timestamp reset

ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4         # 30s clip
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4 # 30s clip
ffmpeg -ss 00:01:00 -i input.mp4 -t 00:00:30 output.mp4          # 30s clip

7. -vf vs -filter_complex

# Single-input filter (per-output)
ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

# Multi-input filter (global)
ffmpeg -i video.mp4 -i overlay.png \
  -filter_complex "[0:v][1:v]overlay=10:10" output.mp4

# WRONG: -vf cannot reference multiple inputs
ffmpeg -i video.mp4 -i overlay.png -vf "overlay=10:10" output.mp4

---

Command Structure Examples

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

# With input seeking
ffmpeg -ss 60 -i input.mp4 -t 30 -c:v libx264 output.mp4

# Hardware acceleration
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
  -c:v h264_nvenc -preset p4 output.mp4

# Multiple inputs with filters
ffmpeg -i main.mp4 -i overlay.png \
  -filter_complex "[0:v][1:v]overlay=10:10[v]" \
  -map "[v]" -map 0:a -c:v libx264 -c:a copy output.mp4

# Real-time streaming
ffmpeg -re -i input.mp4 -c:v libx264 -f flv rtmp://server/live/stream

# Full structure
ffmpeg \
  -y -hide_banner \
  -hwaccel cuda -ss 10 -i input1.mp4 \
  -stream_loop -1 -i input2.mp4 \
  -filter_complex "[0:v][1:v]overlay[v]" \
  -map "[v]" -map 0:a \
  -c:v h264_nvenc -b:v 5M \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

---

Quick Placement Cheatsheet

---

Extended Reference Map

For exhaustive lookups, see the companion reference files:

• Complete option catalog (all global / input / output / color / threading / format flag tables): `references/complete-option-reference.md`
• Stream specifier syntax and examples: `references/stream-specifiers.md`
• Per-backend hardware device initialization (CUDA, VAAPI, QSV, Vulkan, D3D11VA, VideoToolbox): `references/hardware-device-init.md`
• Format/protocol/muxer options (HLS, DASH, segment, RTSP, RTMP, raw video, movflags, MPEG-TS, Matroska): `references/format-specific-options.md`
• Timestamps, bitstream filters, metadata, attachments, disposition: `references/timestamps-bitstream-metadata.md`

---

External References

• FFmpeg Documentation
• FFmpeg Wiki - Seeking
• Stream Specifiers
• FFmpeg Formats Documentation
• FFmpeg Bitstream Filters

Complete FFmpeg 8.0+ Option Reference

Exhaustive option catalogs grouped by category. Use this for lookup; for the placement rules and common mistakes see the parent SKILL.md.

Global Options (Complete List)

Input-Only Options (Complete List)

Output-Only Options (Complete List)

Video Color/HDR Options (Output)

Subtitle Options

FFmpeg 8.0+ Specific Options

Threading Options

# Auto-detect threads for encoding
ffmpeg -i input.mp4 -c:v libx264 -threads 0 output.mp4

# Specific thread count
ffmpeg -i input.mp4 -c:v libx264 -threads 8 output.mp4

# Per-stream threading
ffmpeg -i input.mp4 -threads:v 8 -threads:a 2 -c:v libx264 -c:a aac output.mp4

# Filter threads
ffmpeg -filter_threads 4 -i input.mp4 -vf "scale=1920:1080" output.mp4

Format Flags (-fflags)

Format/Protocol/Muxer Options

These options belong to specific muxers/demuxers/protocols, not the main FFmpeg options. They are passed using -option value syntax but only work with their specific format. Unlike main options, they are not position-sensitive in the same way and only apply when the matching format is selected.

HLS Muxer (Output)

ffmpeg -i input.mp4 -c copy \
  -hls_time 10 \
  -hls_list_size 6 \
  -hls_segment_filename "seg_%03d.ts" \
  -hls_flags delete_segments \
  playlist.m3u8

Segment Muxer (Output)

ffmpeg -i input.mp4 -c copy \
  -f segment \
  -segment_time 60 \
  -segment_list playlist.txt \
  -segment_format mp4 \
  output_%03d.mp4

DASH Muxer (Output)

ffmpeg -i input.mp4 -c copy \
  -f dash \
  -seg_duration 4 \
  -init_seg_name "init_$RepresentationID$.m4s" \
  manifest.mpd

RTSP/RTMP Protocol (Input)

ffmpeg -rtsp_transport tcp -i "rtsp://server/stream" output.mp4
ffmpeg -rtmp_buffer 1000 -i "rtmp://server/live/stream" output.mp4

Raw Video Input

ffmpeg -f rawvideo -video_size 1920x1080 -pix_fmt yuv420p -framerate 30 \
  -i input.yuv output.mp4

MP4/MOV Muxer Flags (-movflags)

# Fast start (move moov atom to beginning for web)
ffmpeg -i input.mp4 -c copy -movflags +faststart output.mp4

# Fragmented MP4 (for DASH/streaming)
ffmpeg -i input.mp4 -c copy -movflags +frag_keyframe+empty_moov output.mp4

# Separate moov atom
ffmpeg -i input.mp4 -c copy -movflags +frag_keyframe+separate_moof output.mp4

# All common streaming flags
ffmpeg -i input.mp4 -c copy \
  -movflags +faststart+frag_keyframe+empty_moov+default_base_moof \
  output.mp4

MPEG-TS Muxer

# MPEG-TS with PCR
ffmpeg -i input.mp4 -c copy -mpegts_copyts 1 output.ts

# Set service info
ffmpeg -i input.mp4 -c copy \
  -mpegts_service_id 1 \
  -mpegts_service_type digital_tv \
  output.ts

Matroska/WebM Muxer

# Cue points at clusters
ffmpeg -i input.mp4 -c:v libvpx-vp9 -cues_to_front 1 output.webm

# Set cluster size
ffmpeg -i input.mp4 -c copy -cluster_size_limit 2M output.mkv

Hardware Acceleration Device Initialization

Per-backend syntax for -hwaccel, -init_hw_device, and -filter_hw_device. For an in-depth comparison of GPU pipelines, see the ffmpeg-hardware-acceleration skill.

CUDA (NVIDIA)

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

# Specify device
ffmpeg -hwaccel cuda -hwaccel_device 0 -i input.mp4 -c:v h264_nvenc output.mp4

# Full GPU pipeline (decode + filter + encode on GPU)
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
  -vf "scale_cuda=1920:1080" -c:v h264_nvenc output.mp4

# Initialize named device for filters
ffmpeg -init_hw_device cuda=gpu0:0 -filter_hw_device gpu0 \
  -i input.mp4 -vf "hwupload_cuda,scale_cuda=1920:1080,hwdownload" \
  -c:v libx264 output.mp4

VAAPI (AMD/Intel Linux)

# Basic VAAPI
ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -i input.mp4 \
  -c:v h264_vaapi output.mp4

# VAAPI with output format
ffmpeg -hwaccel vaapi -hwaccel_output_format vaapi \
  -hwaccel_device /dev/dri/renderD128 -i input.mp4 \
  -vf "scale_vaapi=1920:1080" -c:v h264_vaapi output.mp4

# Using -vaapi_device shortcut
ffmpeg -vaapi_device /dev/dri/renderD128 -i input.mp4 \
  -vf "hwupload,scale_vaapi=1920:1080" -c:v h264_vaapi output.mp4

QSV (Intel)

# Basic QSV
ffmpeg -hwaccel qsv -i input.mp4 -c:v h264_qsv output.mp4

# QSV with device specification
ffmpeg -qsv_device /dev/dri/renderD128 -hwaccel qsv \
  -i input.mp4 -c:v h264_qsv output.mp4

# Full QSV pipeline
ffmpeg -hwaccel qsv -hwaccel_output_format qsv -i input.mp4 \
  -vf "scale_qsv=1920:1080" -c:v h264_qsv output.mp4

Vulkan (Cross-platform FFmpeg 7.1+/8.0+)

# Vulkan hardware acceleration
ffmpeg -init_hw_device vulkan=vk:0 -filter_hw_device vk \
  -i input.mp4 -vf "hwupload,scale_vulkan=1920:1080,hwdownload" \
  -c:v libx264 output.mp4

# Vulkan encoder (FFmpeg 8.0+)
ffmpeg -hwaccel vulkan -hwaccel_output_format vulkan -i input.mp4 \
  -c:v h264_vulkan output.mp4

D3D11VA (Windows)

# D3D11 hardware acceleration
ffmpeg -hwaccel d3d11va -i input.mp4 -c:v h264_nvenc output.mp4

# With specific adapter
ffmpeg -hwaccel d3d11va -hwaccel_device 0 -i input.mp4 \
  -c:v hevc_amf output.mp4

VideoToolbox (macOS)

# VideoToolbox decode + encode
ffmpeg -hwaccel videotoolbox -i input.mp4 \
  -c:v h264_videotoolbox output.mp4

# With ProRes
ffmpeg -i input.mov -c:v prores_videotoolbox output.mov

Stream Specifiers

Stream specifiers target specific streams for per-stream options. Appended with a colon after the option name.

Syntax

-option[:stream_specifier] value

Stream Specifier Types

Input Index Prefix

For multi-input commands, prefix with input index:

# Stream 0 from input 1
ffmpeg -i a.mp4 -i b.mp4 -map 1:0 -c copy output.mp4

# Video from input 0, audio from input 1
ffmpeg -i video.mp4 -i audio.mp3 -map 0:v -map 1:a output.mp4

# Second audio stream from third input
ffmpeg -i a.mp4 -i b.mp4 -i c.mp4 -map 2:a:1 output.mp4

Per-Stream Option Examples

# Different codecs per stream type
ffmpeg -i input.mkv -c:v libx264 -c:a aac -c:s mov_text output.mp4

# Different bitrates per stream index
ffmpeg -i input.mkv -map 0 \
  -c:v libx264 -b:v:0 5M \
  -c:a:0 aac -b:a:0 192k \
  -c:a:1 ac3 -b:a:1 384k \
  output.mkv

# Different settings for each audio stream
ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 \
  -c:a:0 ac3 -b:a:0 640k \
  -ac:a:1 2 -c:a:1 aac -b:a:1 128k \
  output.mp4

Timestamps, Bitstream Filters, Metadata, Attachments, Disposition

Reference for advanced packet-level and container-level options.

Advanced Timestamp Handling

# Copy timestamps exactly from input
ffmpeg -copyts -i input.mp4 -c copy output.mp4

# Shift timestamps to start at zero
ffmpeg -start_at_zero -i input.mp4 -c copy output.mp4

# Both: copy but start at zero
ffmpeg -copyts -start_at_zero -i input.mp4 -c copy output.mp4

# Offset input timestamps
ffmpeg -itsoffset 5 -i input.mp4 -c copy output.mp4  # Delay by 5 seconds

# Scale input timestamps (2x speed)
ffmpeg -itsscale 0.5 -i input.mp4 -c copy output.mp4

# Handle negative timestamps
ffmpeg -i input.mp4 -avoid_negative_ts make_zero output.mp4

Timestamp Modes

Bitstream Filters (-bsf)

# Extract AnnexB NAL units for H.264
ffmpeg -i input.mp4 -c:v copy -bsf:v h264_mp4toannexb output.h264

# Add SEI recovery point for broadcast
ffmpeg -i input.mp4 -c:v copy -bsf:v h264_redundant_pps output.mp4

# HEVC HVC1 to HEV1
ffmpeg -i input.mp4 -c:v copy -bsf:v hevc_mp4toannexb output.hevc

# Insert ADTS headers for AAC
ffmpeg -i input.mp4 -c:a copy -bsf:a aac_adtstoasc output.aac

# Remove filler data
ffmpeg -i input.mp4 -c:v copy -bsf:v filter_units=remove_types=6 output.mp4

# Metadata injection
ffmpeg -i input.mp4 -c:v copy -bsf:v h264_metadata=level=4.1 output.mp4

Common Bitstream Filters

Metadata Mapping (-map_metadata)

Syntax

-map_metadata[:metadata_spec_out] infile[:metadata_spec_in]

Metadata Specifiers

Examples

# Copy all metadata from input to output
ffmpeg -i input.mp4 -map_metadata 0 -c copy output.mp4

# Copy global metadata only
ffmpeg -i input.mp4 -map_metadata:g 0:g -c copy output.mp4

# Strip all metadata
ffmpeg -i input.mp4 -map_metadata -1 -c copy output.mp4

# Copy metadata from second input file
ffmpeg -i video.mp4 -i metadata_source.mp4 -map 0 -map_metadata 1 -c copy output.mp4

# Copy stream metadata from input stream 0 to output stream 0
ffmpeg -i input.mp4 -map_metadata:s:0 0:s:0 -c copy output.mp4

# Copy chapter metadata
ffmpeg -i input.mp4 -map_metadata:c 0:c -map_chapters 0 -c copy output.mp4

# Copy all metadata, but set specific values
ffmpeg -i input.mp4 -map_metadata 0 -metadata title="New Title" -c copy output.mp4

Metadata Manipulation

# Add/modify metadata
ffmpeg -i input.mp4 -metadata title="Video Title" -metadata artist="Creator" output.mp4

# Set stream-specific metadata
ffmpeg -i input.mp4 -metadata:s:v:0 title="Main Video" -metadata:s:a:0 language=eng output.mp4

# Set chapter metadata
ffmpeg -i input.mp4 -metadata:c:0 title="Chapter 1" output.mp4

# Remove specific metadata (set to empty)
ffmpeg -i input.mp4 -metadata comment= -c copy output.mp4

Attachments

Adding (-attach)

# Attach font file (for subtitles)
ffmpeg -i input.mkv -attach DejaVuSans.ttf \
  -metadata:s:t:0 mimetype=application/x-truetype-font \
  -c copy output.mkv

# Attach cover art
ffmpeg -i input.mp4 -attach cover.jpg \
  -metadata:s:t:0 mimetype=image/jpeg \
  -c copy output.mkv

# Multiple attachments
ffmpeg -i input.mkv \
  -attach font1.ttf -metadata:s:t:0 mimetype=application/x-truetype-font \
  -attach font2.ttf -metadata:s:t:1 mimetype=application/x-truetype-font \
  -c copy output.mkv

Extracting (-dump_attachment)

# Extract first attachment to specific file
ffmpeg -dump_attachment:t:0 extracted_font.ttf -i input.mkv

# Extract all attachments (uses filename metadata)
ffmpeg -dump_attachment:t "" -i input.mkv

# Extract specific stream by index
ffmpeg -dump_attachment:3 attachment.bin -i input.mkv

Disposition Flags

# Set stream as default
ffmpeg -i input.mkv -c copy -disposition:a:0 default output.mkv

# Set as default and forced subtitle
ffmpeg -i input.mkv -c copy -disposition:s:0 default+forced output.mkv

# Clear all dispositions
ffmpeg -i input.mkv -c copy -disposition:a:1 0 output.mkv

# Multiple dispositions
ffmpeg -i input.mkv -c copy \
  -disposition:v:0 default \
  -disposition:a:0 default \
  -disposition:a:1 0 \
  output.mkv

Disposition Values