ffmpeg-command-syntax

name

ffmpeg-command-syntax

description

Complete FFmpeg command syntax reference covering option ordering, input vs output options, stream specifiers, and position-sensitive options. PROACTIVELY activate for: (1) Command syntax questions, (2) Option placement issues, (3) Input vs output option confusion, (4) Stream specifier syntax, (5) -ss/-t/-to position questions, (6) Global vs per-file options, (7) Multiple input/output handling, (8) Option order errors. Provides: Correct option placement rules, input-only vs output-only options, position-sensitive option behavior, stream specifier syntax, common mistakes and fixes.

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

1. Global Options (First, Before Everything)

Global options affect the entire FFmpeg process and must come first, before any inputs:

Option	Description	Example
-y	Overwrite output without asking	ffmpeg -y -i in.mp4 out.mp4
-n	Never overwrite output	ffmpeg -n -i in.mp4 out.mp4
-v / -loglevel	Set logging verbosity	ffmpeg -v error -i in.mp4 out.mp4
-stats	Print encoding progress	ffmpeg -stats -i in.mp4 out.mp4
-progress	Send progress to file/URL	ffmpeg -progress - -i in.mp4 out.mp4
-report	Generate ffmpeg-*.log file	ffmpeg -report -i in.mp4 out.mp4
-hide_banner	Suppress copyright banner	ffmpeg -hide_banner -i in.mp4 out.mp4
-filter_complex	Complex filtergraph (global)	ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0][1]overlay" out.mp4
-filter_complex_threads	Filtergraph thread count	ffmpeg -filter_complex_threads 4 ...

# Correct: Global options first
ffmpeg -y -hide_banner -v warning -i input.mp4 output.mp4

# Wrong: Global option after -i
ffmpeg -i input.mp4 -y output.mp4  # -y works but is not idiomatic

2. Input Options (Before -i)

Input options affect how a file is read/decoded. They must be placed immediately before the -i for the file they apply to.

Input-Only Options

Option	Description	Placement
-ss (as input)	Seek position (fast, may be imprecise)	Before -i
-t (as input)	Limit input read duration	Before -i
-to (as input)	Read until timestamp	Before -i
-itsoffset	Time offset for input timestamps	Before -i
-itsscale	Input timestamp scale factor	Before -i
-re	Read input at native frame rate (streaming)	Before -i
-readrate	Read input at specified rate	Before -i
-stream_loop	Loop input N times (-1 = infinite)	Before -i
-hwaccel	Hardware acceleration method	Before -i
-hwaccel_device	Hardware device to use	Before -i
-hwaccel_output_format	Pixel format for hwaccel output	Before -i
-c:v (as decoder)	Video decoder selection	Before -i
-c:a (as decoder)	Audio decoder selection	Before -i
-r (as input)	Input frame rate (raw formats)	Before -i
-s (as input)	Input frame size (raw formats)	Before -i
-pix_fmt (as input)	Input pixel format (raw formats)

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

# Wrong: Input options after -i
ffmpeg -i input.mp4 -ss 00:01:00 output.mp4  # -ss is now an OUTPUT option (slower!)

Hardware Acceleration Input Options

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

# Correct: Different hwaccel per input
ffmpeg -hwaccel cuda -i input1.mp4 \
       -hwaccel vaapi -i input2.mp4 \
       -filter_complex "[0][1]overlay" output.mp4

# Wrong: hwaccel after -i (won't work)
ffmpeg -i input.mp4 -hwaccel cuda -c:v h264_nvenc output.mp4

3. Output Options (After Last -i, Before Output File)

Output options affect how a file is encoded/written. They must be placed after all inputs and before the output file they apply to.

Output-Only Options

Option	Description	Placement
-c:v (as encoder)	Video encoder selection	Before output
-c:a (as encoder)	Audio encoder selection	Before output
-c:s	Subtitle codec selection	Before output
-b:v	Video bitrate	Before output
-b:a	Audio bitrate	Before output
-crf	Constant Rate Factor (quality)	Before output
-preset	Encoding preset (speed/quality)	Before output
-tune	Encoding tuning profile	Before output
-profile:v	Video profile	Before output
-level	Codec level	Before output
-r (as output)	Output frame rate	Before output
-s (as output)	Output frame size	Before output
-aspect	Output aspect ratio	Before output
-pix_fmt (as output)	Output pixel format	Before output
-vf / -filter:v	Video filter chain	Before output
-af / -filter:a	Audio filter chain	Before output
-map	Stream mapping	Before output
-ss (as output)	Start time (accurate but slow)	Before output
-t (as output)	Output duration limit	Before output
-to (as output)

# Correct: Output options before output file
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium output.mp4

# With multiple outputs - each needs its own options
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 output_h264.mp4 \
  -c:v libx265 -crf 28 output_h265.mp4

4. Options That Work as Both Input AND Output

Some options have different behavior depending on position:

-ss (Seek/Start Time) - Position Critical

# BEFORE -i (INPUT): Fast seek, may not be frame-accurate
# Seeks by keyframes, then decodes to precise position if -accurate_seek (default)
ffmpeg -ss 00:01:00 -i input.mp4 -t 30 -c copy output.mp4

# AFTER -i (OUTPUT): Frame-accurate but slower
# Decodes all frames from start, discards until seek point
ffmpeg -i input.mp4 -ss 00:01:00 -t 30 -c:v libx264 output.mp4

# BOTH (Recommended for accuracy + speed):
# Fast seek to near position, then accurate decode
ffmpeg -ss 00:00:55 -i input.mp4 -ss 00:00:05 -t 30 -c:v libx264 output.mp4

Important: When -ss is before -i, timestamps are reset to 0. Use -copyts to preserve original timestamps.

-t and -to (Duration/End Time)

# -t BEFORE -i: Limits how much of input to READ
ffmpeg -t 60 -i input.mp4 -c copy output.mp4  # Read first 60 seconds

# -t AFTER -i: Limits output DURATION
ffmpeg -i input.mp4 -t 60 -c copy output.mp4  # Output first 60 seconds

# -to: End timestamp (works with -ss timestamp reset)
# With -ss before -i, timestamps reset, so -to is relative to new zero
ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4  # 30 seconds from seek point

# To get 1:00 to 1:30, use -t instead, or -copyts with -to
ffmpeg -ss 00:01:00 -i input.mp4 -t 00:00:30 output.mp4  # Correct: 30 sec duration
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4  # Also correct

-r (Frame Rate)

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

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

-s (Size/Resolution)

# BEFORE -i: Input size (for raw formats)
ffmpeg -s 1920x1080 -pix_fmt yuv420p -i raw.yuv output.mp4

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

-c / -codec (Codec Selection)

# BEFORE -i: Selects DECODER (rarely needed)
ffmpeg -c:v h264_cuvid -i input.mp4 -c:v h264_nvenc output.mp4

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

---

Stream Specifiers

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

Syntax

-option[:stream_specifier] value

Stream Specifier Types

Specifier	Meaning	Example
:v	All video streams	-c:v libx264
:V	Video streams (not thumbnails/covers)	-c:V libx264
:a	All audio streams	-c:a aac
:s	All subtitle streams	-c:s mov_text
:d	All data streams	-c:d copy
:t	All attachment streams	...
:v:0	First video stream	-b:v:0 5M
:a:1	Second audio stream	-c:a:1 ac3
:0	First stream (any type)	-c:0 copy
:1	Second stream (any type)	-c:1 libx264
:#0x1234	Stream with specific PID	-c:#0x1234 copy
:i:0x100	Stream with specific ID	-c:i:0x100 copy
:m:key:value	Stream with matching metadata	-c:m:language:eng aac
:p:0	Streams in program 0	-c:p:0 copy
:u	Usable configuration streams	-c:u copy

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

---

Multiple Inputs and Outputs

Multiple Inputs

# Options apply to immediately following -i
ffmpeg \
  -ss 10 -i first.mp4 \      # Seek 10s in first input
  -ss 5 -i second.mp4 \      # Seek 5s in second input
  -filter_complex "[0:v][1:v]overlay" \
  output.mp4

Multiple Outputs

# Each output needs its own 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 \
  -c:v libvpx-vp9 -crf 30 output_vp9.webm

# Same codec, different resolutions
ffmpeg -i input.mp4 \
  -vf "scale=1920:1080" -c:v libx264 -crf 23 hd.mp4 \
  -vf "scale=1280:720" -c:v libx264 -crf 23 sd.mp4

# WRONG: Options don't carry over
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4
# out2.mp4 will NOT have libx264/crf 23 settings!

---

Common Mistakes and Fixes

Mistake 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: -hwaccel before -i
ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4

Mistake 2: Output Option Before -i

# WRONG: -c:v before -i tries to select decoder (may fail)
ffmpeg -c:v libx264 -i input.mp4 output.mp4

# CORRECT: -c:v after -i selects encoder
ffmpeg -i input.mp4 -c:v libx264 output.mp4

Mistake 3: Expecting Options to Persist Across Outputs

# WRONG: Second output won't have the encoding settings
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4

# CORRECT: Repeat options for each output
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 out1.mp4 \
  -c:v libx264 -crf 23 out2.mp4

Mistake 4: Wrong -ss Position for Accuracy

# Fast but may be imprecise (seeks to keyframe)
ffmpeg -ss 00:05:00 -i input.mp4 -t 30 -c copy output.mp4

# Slow but frame-accurate (decodes everything)
ffmpeg -i input.mp4 -ss 00:05:00 -t 30 -c:v libx264 output.mp4

# BEST: Fast AND accurate (two-pass seek)
ffmpeg -ss 00:04:55 -i input.mp4 -ss 5 -t 30 -c:v libx264 output.mp4

Mistake 5: Mixing Input/Output Files

# WRONG: Mixing inputs and outputs
ffmpeg -i input1.mp4 -c:v libx264 output1.mp4 -i input2.mp4 output2.mp4

# CORRECT: All inputs first, then all outputs
ffmpeg -i input1.mp4 -i input2.mp4 \
  -map 0 -c:v libx264 output1.mp4 \
  -map 1 -c:v libx264 output2.mp4

Mistake 6: -t vs -to Confusion with -ss

# -ss before -i resets timestamps to 0
# -to 00:00:30 means 30 seconds from new timestamp 0
ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4  # 30 sec clip

# To end at original timestamp, use -copyts
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4  # 30 sec clip

# Or use -t for duration (unaffected by timestamp reset)
ffmpeg -ss 00:01:00 -i input.mp4 -t 00:00:30 output.mp4  # 30 sec clip

Mistake 7: Filter vs Global -filter_complex

# -vf is per-output, applies to single input
ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

# -filter_complex is GLOBAL, for multi-input operations
ffmpeg -i video.mp4 -i overlay.png \
  -filter_complex "[0:v][1:v]overlay=10:10" \
  output.mp4

# WRONG: Using -vf with multiple inputs
ffmpeg -i video.mp4 -i overlay.png -vf "overlay=10:10" output.mp4  # Error!

---

Command Structure Examples

Basic Transcode

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

With Input Seeking

ffmpeg -ss 60 -i input.mp4 -t 30 -c:v libx264 output.mp4
#      ^input opt ^input    ^output options    ^output

Hardware Acceleration

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
#      ^input options (must be before -i)        ^input
  -c:v h264_nvenc -preset p4 output.mp4
# ^output options            ^output

Multiple Inputs with Filters

ffmpeg -i main.mp4 -i overlay.png \
#      ^input1     ^input2
  -filter_complex "[0:v][1:v]overlay=10:10[v]" \
# ^global option
  -map "[v]" -map 0:a -c:v libx264 -c:a copy output.mp4
# ^output options                            ^output

Streaming with Real-time Read

ffmpeg -re -i input.mp4 -c:v libx264 -f flv rtmp://server/live/stream
#      ^input opt       ^output options      ^output

Complete Structure

ffmpeg \
  -y -hide_banner \                           # Global options
  -hwaccel cuda -ss 10 -i input1.mp4 \        # Input 1 options + input
  -stream_loop -1 -i input2.mp4 \             # Input 2 options + input
  -filter_complex "[0:v][1:v]overlay[v]" \    # Global filter
  -map "[v]" -map 0:a \                       # Output mapping
  -c:v h264_nvenc -b:v 5M \                   # Output video options
  -c:a aac -b:a 192k \                        # Output audio options
  -movflags +faststart \                      # Output muxer options
  output.mp4                                  # Output file

---

Quick Reference Card

Option Placement Cheatsheet

Option	Before -i	After -i	Notes
-ss	Fast seek	Accurate seek	Before = keyframe seek, After = decode all
-t	Input limit	Output limit	Limits read vs write
-to	Input end	Output end	Affected by timestamp reset
-r	Input FPS	Output FPS	For raw/output conversion
-s	Input size	Output size	For raw/scaling
-c:v	Decoder	Encoder	Before = decode, After = encode
-c:a	Decoder	Encoder	Before = decode, After = encode
-hwaccel	Required	N/A	Must be before -i
-re	Required	N/A	Must be before -i
-itsoffset	Required	N/A	Must be before -i
-stream_loop	Required	N/A	Must be before -i
-vf	N/A	Required	Output filter only
-af	N/A	Required	Output filter only
-map	N/A	Required	Output option only
-crf	N/A	Required	Output option only
-preset	N/A	Required	Output option only

---

Complete FFmpeg 8.0+ Option Reference

Global Options (Complete List)

Option	Description
-y	Overwrite output files without asking
-n	Never overwrite output files
-v level / -loglevel level	Set logging verbosity (quiet, panic, fatal, error, warning, info, verbose, debug, trace)
-stats	Print encoding progress statistics
-stats_period time	Set statistics output period
-progress url	Send progress info to URL/file
-stdin	Enable stdin interaction
-nostdin	Disable stdin interaction
-report	Generate ffmpeg-*.log debug file
-hide_banner	Suppress program banner
-max_alloc bytes	Maximum allocation size limit
-cpuflags flags	Set CPU flags mask
-cpucount count	Override CPU count detection
-max_error_rate ratio	Maximum decoding error ratio
-xerror	Exit on error
-abort_on flags	Conditions to abort (empty_output, empty_output_stream)
-filter_complex graph	Global complex filtergraph
-filter_complex_threads n	Filtergraph thread count
-filter_threads n	Set filter processing threads
-filter_buffered_frames n	Max buffered frames in filtergraph
-lavfi graph	Alias for -filter_complex
-filter_complex_script file	Read filtergraph from file
-sdp_file file

Input-Only Options (Complete List)

Option	Description
-i url	Input file URL
-f fmt	Force input format
-c:v decoder / -vcodec decoder	Video decoder
-c:a decoder / -acodec decoder	Audio decoder
-c:s decoder / -scodec decoder	Subtitle decoder
-ss position	Seek to position (fast, keyframe-based)
-sseof position	Seek relative to end of file (negative value)
-t duration	Limit input duration
-to position	Limit input to position
-itsoffset offset	Input timestamp offset
-itsscale scale	Input timestamp scale (per-stream)
-isync input_index	Assign input as sync source
-re	Read at native frame rate
-readrate speed	Read at specified rate
-readrate_initial_burst duration	Initial burst before rate limiting
-readrate_catchup speed	Catchup rate when behind
-stream_loop count	Loop input (-1 = infinite)
-hwaccel method	Hardware acceleration (none, auto, cuda, vaapi, qsv, d3d11va, dxva2, videotoolbox, vdpau, vulkan)
-hwaccel_device device	Hardware device path/name
-hwaccel_output_format format	Hardware output pixel format
-autorotate	Automatically rotate video (enabled by default)
-noautorotate	Disable automatic rotation

Output-Only Options (Complete List)

Option	Description
-f fmt	Force output format
-c:v encoder / -vcodec encoder	Video encoder (or copy)
-c:a encoder / -acodec encoder	Audio encoder (or copy)
-c:s encoder / -scodec encoder	Subtitle encoder (or copy)
-c:d codec / -dcodec codec	Data stream codec
-ss position	Start time (accurate, slow)
-t duration	Output duration limit
-to position	Output end position
-fs size	File size limit (bytes)
-frames:v count / -vframes count	Video frame count limit
-frames:a count / -aframes count	Audio frame count limit
-frames:d count / -dframes count	Data frame count limit
-r fps	Output frame rate
-fpsmax fps	Maximum output frame rate
-s size	Output frame size
-aspect ratio	Display aspect ratio
-pix_fmt format	Output pixel format
-sample_fmt format	Output sample format
-ar rate	Output audio sample rate
-ac channels	Output audio channel count
-channel_layout layout	Output audio channel layout

Video Color/HDR Options (Output)

Option	Description
-color_range range	Color range (tv/pc, limited/full, mpeg/jpeg)
-color_primaries primaries	Color primaries (bt709, bt2020, smpte170m, etc.)
-color_trc trc	Transfer characteristics (bt709, smpte2084/pq, arib-std-b67/hlg, etc.)
-colorspace space	Colorspace (bt709, bt2020nc, smpte170m, etc.)
-chroma_sample_location loc	Chroma sample location
-top n	Top field first (1) or bottom field first (0)
-bits_per_raw_sample n	Bits per raw sample
-dc precision	Intra DC precision
-qphist	Show QP histogram

Subtitle Options

Option	Description	Type
-sn	Disable subtitles	Input/Output
-scodec codec	Subtitle codec	Input/Output
-stag fourcc	Subtitle tag/fourcc	Output
-fix_sub_duration	Fix subtitle durations	Input
-canvas_size size	Subtitle canvas size	Input

FFmpeg 8.0+ Specific Options

Option	Description	Type
-vaapi_device path	VAAPI device path	Input/Global
-qsv_device path	Intel QSV device	Input/Global
-vulkan_device device	Vulkan device selection	Input/Global
-fps_mode mode	Frame rate mode (replaces -vsync)	Output
-enc_stats_pre file	Pre-encoding stats output	Output
-enc_stats_post file	Post-encoding stats output	Output
-enc_stats_pre_fmt fmt	Pre-encoding stats format	Output
-enc_stats_post_fmt fmt	Post-encoding stats format	Output
-autoscale	Auto-scale to encoder (default)	Output
-noautoscale	Disable auto-scaling	Output
-bits_per_raw_sample n	Set bits per raw sample	Output

Threading Options

Option	Description	Type
-threads n	Encoding/decoding threads (0=auto)	Per-stream/Output
-thread_type type	Thread type (frame, slice)	Per-stream
-filter_threads n	Filter processing threads	Global
-filter_complex_threads n	Complex filtergraph threads	Global

# 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)

Flag	Description
+genpts	Generate PTS if missing
+igndts	Ignore DTS (use PTS only)
+ignidx	Ignore index
+discardcorrupt	Discard corrupted frames
+sortdts	Sort packets by DTS
+fastseek	Enable fast seeking
+nobuffer	Disable buffering
+flush_packets	Flush packets immediately
+bitexact	Bit-exact output
+shortest	Stop at shortest stream
+autobsf	Auto-insert bitstream filters

---

Format-Specific Options (Not Main 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.

HLS Muxer Options (Output)

ffmpeg -i input.mp4 -c copy \
  -hls_time 10 \               # Segment duration (seconds)
  -hls_list_size 6 \           # Playlist entries (0=all)
  -hls_segment_filename "seg_%03d.ts" \
  -hls_flags delete_segments \
  playlist.m3u8

Segment Muxer Options (Output)

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

DASH Muxer Options (Output)

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

RTSP/RTMP Protocol Options (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 Options

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

Important: These are NOT position-sensitive like main options. They are format/protocol parameters and only apply when using that specific format.

---

Hardware Acceleration Device Initialization

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

---

Advanced Timestamp Handling

Timestamp Options Explained

# 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

Mode	Description
make_non_negative	Shift timestamps to be non-negative
make_zero	Shift to start at exactly zero
auto	Auto-select based on format
disabled	Don't adjust timestamps

---

Muxer-Specific Options

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

Flag	Description
faststart	Move moov before mdat (web streaming)
frag_keyframe	Fragment at each keyframe
empty_moov	Empty initial moov (DASH)
separate_moof	Separate moof for each track
default_base_moof	Base offset at moof (DASH)
negative_cts_offsets	Allow negative CTS offsets
isml	IIS Smooth Streaming
omit_tfhd_offset	Omit offset in tfhd
disable_chpl	Disable chapter track
write_colr	Write colr atom
write_gama	Write gama atom

MPEG-TS Muxer Options

# 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 Options

# 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

---

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

Filter	Description
h264_mp4toannexb	Convert H.264 to AnnexB format
hevc_mp4toannexb	Convert HEVC to AnnexB format
aac_adtstoasc	Convert AAC ADTS to ASC
extract_extradata	Extract codec extradata
h264_redundant_pps	Add redundant PPS
h264_metadata	Modify H.264 metadata
hevc_metadata	Modify HEVC metadata
filter_units	Filter NAL units
dump_extra	Dump extradata to packets
prores_metadata	Modify ProRes metadata
vp9_superframe	VP9 superframe handling
av1_metadata	Modify AV1 metadata

---

Metadata Mapping (-map_metadata)

The -map_metadata option copies metadata between files with fine-grained control.

Syntax

-map_metadata[:metadata_spec_out] infile[:metadata_spec_in]

Metadata Specifiers

Specifier	Target
g	Global file metadata
s:stream_index	Stream metadata
s:v / s:a / s:s	All video/audio/subtitle streams
c:chapter_index	Chapter metadata
p:program_index	Program metadata

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 Attachments (-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 Attachments (-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

Value	Description
default	Default stream for playback
dub	Dubbed audio track
original	Original language
comment	Commentary track
lyrics	Lyrics track
karaoke	Karaoke version
forced	Forced subtitles
hearing_impaired	Subtitles for hearing impaired
visual_impaired	Audio for visually impaired
clean_effects	Clean audio effects
attached_pic	Attached picture (cover art)
captions	Closed captions
descriptions	Audio descriptions
metadata	Metadata stream
dependent	Dependent stream
still_image	Still image stream

---

References

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