Synopsis

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

Description

FFmpeg is a fast and versatile multimedia converter capable of reading from any number of inputs (files, pipes, network streams, capture devices) specified via the -i option and writing to any number of outputs. Anything not recognized as an option is treated as an output URL.

Each input or output can contain multiple streams of different types (video, audio, subtitle, attachment, data). The container format limits the allowed stream types and count. By default, FFmpeg automatically selects which streams go to which output; the -map option overrides this behavior (see Stream Selection).

Input files are referenced by their index starting from 0. Streams within a file are referenced as file_index:stream_index. Options apply to the next specified file; global options (e.g., -loglevel) must be placed first.

Example: set output video bitrate to 64 kbit/s:

ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi

Detailed Description

The transcoding pipeline for each output follows this flow:

Input file → Demuxer → Encoded packets → Decoder → Decoded frames → Filters → Encoder → Encoded packets → Muxer → Output file

FFmpeg uses libavformat to read inputs and libavcodec to decode/encode. For stream copy (-c copy), the decode and encode steps are omitted, resulting in fast, lossless container or metadata changes.

Filtering

Filters process raw frames using libavfilter. Two types exist:

• Simple filtergraph: one input, one output (same type). Configured per-stream with -filter (or -vf/-af).
• Complex filtergraph: multiple inputs/outputs or different stream types. Configured with -filter_complex (or -lavfi).

Example of a simple video filter chain: input → deinterlace → scale → output. Some filters (e.g., fps, setpts) alter properties without touching frame content.

Stream Copy

Enable stream copy with -codec copy. The demuxer passes encoded packets directly to the muxer. This is fast and lossless but prevents filtering and may fail for some codecs.

Stream Selection

Stream selection can be automatic or manual via -map. Options -vn, -an, -sn, -dn disable streams of a given type.

Automatic Selection

If no -map is used, FFmpeg inspects the output format to determine allowed stream types. For each type, it picks one stream from all inputs following these criteria:

• Video: highest resolution
• Audio: most channels
• Subtitle: first subtitle stream that matches the default encoder type (text or image)

Data and attachment streams are never auto-selected.

Manual Selection

The -map option specifies exact input streams for an output. Unmapped complex filtergraph outputs are added to the first output file; tagged outputs must be mapped once and exactly once.

Examples

Assume three input files:

• A.avi: stream 0 video 640x360, stream 1 audio 2ch
• B.mp4: stream 0 video 1920x1080, stream 1 audio 2ch, stream 2 text subtitles, stream 3 audio 5.1ch, stream 4 text subtitles
• C.mkv: stream 0 video 1280x720, stream 1 audio 2ch, stream 2 image subtitles

Automatic selection:

ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov

out1.mkv gets video from B (highest res), audio from B (5.1ch), subtitles from B (text). out2.wav gets only B’s 5.1ch audio. out3.mov gets all audio streams from B (because -map 1:a) with copy codec.

Complex filtergraph with tagged output:

ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" -map '[outv1]' -an out1.mp4 out2.mkv -map '[outv2]' -map 1:a:0 out3.mkv

Here hue processes B’s video, splits in to two copies mapped to out1.mp4 and out3.mkv. The overlay filter uses A and C’s video; its unlabeled output goes to out1.mp4. aresample uses the first unused audio (A’s) and also goes to out1.mp4. out2.mkv is fully auto-selected. out3.mkv has the second hue copy and B’s first audio.

Options

Stream Specifiers

Stream specifiers are appended to an option after a colon. Examples:

• -codec:a:1 ac3 – second audio stream
• -b:a 128k – all audio streams
• v for video, a for audio, s for subtitle, d for data, t for attachment
• p:program_id – streams in a program
• #stream_id or i:stream_id – by stream ID (e.g., PID)
• m:key[:value] – by metadata tag
• u – streams with available configuration (codec defined, dimensions/sample rate known)

General Options

• -L – show license
• -h [arg] – help (long, full, decoder=, encoder=, filter=, etc.)
• -version, -buildconf, -formats, -codecs, -decoders, -encoders, -bsfs, -protocols, -filters, -pix_fmts, -sample_fmts, -layouts, -colors
• -sources device[,...] – list input sources
• -sinks device[,...] – list output sinks
• -loglevel [flags+]loglevel – set log level (quiet, panic, fatal, error, warning, info, verbose, debug, trace) and flags (repeat, level)
• -report – dump log to program-YYYYMMDD-HHMMSS.log
• -hide_banner – suppress copyright and build info
• -cpuflags flags – set CPU flags (for testing)

AVOptions

Options provided by libavformat, libavdevice, libavcodec. Use -help to list. Generic options apply to any container/codec/device; private options are specific. Per-stream AVOptions use a stream specifier.

Main Options

• -f fmt – force input/output format
• -i url – input
• -y – overwrite output
• -n – do not overwrite
• -stream_loop number – loop input (0=no loop, -1=infinite)
• -c[:stream_spec] codec – select encoder (output) or decoder (input); copy for stream copy
• -t duration – limit input/output duration (input: limit read; output: stop after duration)
• -to position – stop at position (mutually exclusive with -t)
• -fs limit_size – file size limit in bytes
• -ss position – seek to position (input: seek; output: discard until position)
• -sseof position – seek relative to end of file
• -itsoffset offset – add offset to input timestamps
• -itsscale scale – rescale input timestamps
• -timestamp date – set container recording timestamp
• -metadata[:spec] key=value – set metadata (global, stream, chapter, program)
• -disposition[:stream_spec] value – set stream disposition (default, dub, original, etc.)
• -program [title:...] st=stream[:st=stream...] – create program
• -target type – set VCD/SVCD/DVD/DV parameters automatically
• -dn – disable data recording
• -dframes number – number of data frames (deprecated, use -frames:d)
• -frames[:spec] framecount – stop after framecount frames
• -q[:spec] q – fixed quality scale (VBR)
• -filter[:spec] filtergraph – apply filtergraph to stream
• -filter_script[:spec] filename – read filtergraph from file
• -reinit_filter[:spec] integer – reinitialize filter when input parameters change
• -filter_threads nb_threads – threads for filter pipelines
• -pre[:spec] preset_name – apply preset
• -stats, -nostats – print encoding progress
• -stats_period time – update period (default 0.5s)
• -progress url – write progress info to URL
• -stdin, -nostdin – enable/disable interactive input
• -debug_ts – print timestamp info
• -attach filename – add attachment (e.g., font)
• -dump_attachment[:spec] filename – extract attachment stream

Video Options

• -vframes number – number of video frames (deprecated, use -frames:v)
• -r[:spec] fps – set frame rate (input: ignore timestamps; output: frame duplication/drop)
• -fpsmax[:spec] fps – maximum frame rate
• -s[:spec] size – frame size (input: shortcut for raw; output: adds scale filter)
• -aspect[:spec] aspect – display aspect ratio (e.g., 16:9)
• -vn – disable video
• -vcodec codec – video codec alias for -codec:v
• -pass[:spec] n – two-pass encoding (1 or 2)
• -passlogfile[:spec] prefix – log file prefix
• -vf filtergraph – alias for -filter:v
• -autorotate – auto-rotate based on metadata
• -autoscale – auto-scale to first frame resolution

Advanced Video Options

• -pix_fmt[:spec] format – set pixel format; prefix + to error if not supported
• -sws_flags flags – SwScaler flags
• -rc_override[:spec] override – rate control override per interval
• -ilme – force interlaced encoding (MPEG-2/4)
• -psnr – compute PSNR
• -vstats, -vstats_file file – dump video stats
• -vstats_version version – stats format version
• -top[:spec] n – field first (top=1, bottom=0, auto=-1)
• -dc precision – intra DC precision
• -vtag fourcc/tag – force video tag (alias -tag:v)
• -qphist – show QP histogram
• -force_key_frames[:spec] time[,time...] – force key frames at specified times or chapters
• -force_key_frames[:spec] expr:expr – force key frames based on expression (e.g., gte(t,n_forced*5))
• -force_key_frames[:spec] source – force when source was key frame
• -copyinkf[:spec] – copy non-key frames during stream copy
• -init_hw_device type[=name][:device[,key=value...]] – initialize hardware device (cuda, dxva2, vaapi, vdpau, qsv, opencl, vulkan)
• -filter_hw_device name – pass hardware device to filters
• -hwaccel[:spec] hwaccel – use hardware acceleration (none, auto, vdpau, dxva2, vaapi, qsv)
• -hwaccel_device[:spec] device – select device for hardware acceleration
• -hwaccels – list enabled hardware acceleration methods

Audio Options

• -aframes number – number of audio frames (deprecated)
• -ar[:spec] freq – set audio sample rate
• -aq q – audio quality (alias -q:a)
• -ac[:spec] channels – number of audio channels
• -an – disable audio
• -acodec codec – alias for -codec:a
• -sample_fmt[:spec] sample_fmt – set audio sample format
• -af filtergraph – alias for -filter:a

Advanced Audio Options

• -atag fourcc/tag – force audio tag (-tag:a)
• -guess_layout_max channels – maximum channels for guessing layout

Subtitle Options

• -scodec codec – subtitle codec (-codec:s)
• -sn – disable subtitles
• -sbsf bitstream_filter – deprecated, use -bsf
• -fix_sub_duration – adjust subtitle durations to avoid overlap
• -canvas_size size – canvas size for rendering subtitles

Advanced Options

• -map [-]input_file_id[:stream_spec][?][,sync_file_id[:stream_spec]] | [linklabel] – map streams to output; negative mapping removes streams; ? makes mapping optional; [linklabel] for complex filtergraph outputs
• -ignore_unknown – ignore unknown stream types
• -copy_unknown – copy unknown stream types
• -map_channel input_file_id.stream_spec.channel_id|-1[?][:output_file_id.stream_spec] – map audio channels
• -map_metadata[:spec_out] infile[:spec_in] – copy metadata from input file
• -map_chapters input_file_index – copy chapters from input
• -benchmark – show benchmark info at end
• -benchmark_all – show per-step benchmark
• -timelimit duration – exit after duration seconds of user CPU time
• -dump – dump input packets to stderr
• -hex – dump packets with payload
• -re – read input at native frame rate
• -vsync parameter – video sync method (0=passthrough, 1=cfr, 2=vfr, drop, -1=auto)
• -frame_drop_threshold threshold – threshold for dropping frames (default -1.1)
• -async samples_per_second – audio sync stretch/squeeze (deprecated, use aresample)
• -adrift_threshold time – minimum difference to trigger sample add/remove
• -apad – pad audio stream
• -copyts – preserve input timestamps (no cleaning)
• -start_at_zero – shift timestamps to start at zero when using -copyts
• -copytb mode – encoder timebase mode (1=demuxer, 0=decoder, -1=auto)
• -enc_time_base[:spec] timebase – set encoder timebase (0=default per type, -1=input, >0=value as ratio)
• -bitexact – enible bitexact mode
• -shortest – finish encoding when the shortest input ends
• -dts_delta_threshold – threshold for timestamp discontinuities
• -dts_error_threshold seconds – threshold for erroneous timestamps (default 30 hours)
• -muxdelay seconds – max demuxer-decode delay
• -muxpreload seconds – initial demuxer-decode delay
• -streamid output_stream_index:new_value – assign stream ID to output stream
• -bsf[:spec] bitstream_filters – apply bitstream filters (e.g., h264_mp4toannexb)
• -tag[:spec] codec_tag – force codec tag
• -timecode hh:mm:ssSEPff – set timecode
• -filter_complex filtergraph – define complex filtergraph (global)
• -filter_complex_threads nb_threads – threads for complex filtergraph
• -lavfi filtergraph – same as -filter_complex
• -filter_complex_script filename – read complex filtergraph from file
• -accurate_seek – enable accurate seeking (default on)
• -seek_timestamp – interpret -ss argument as a real timestamp
• -thread_queue_size size – max packets queued from thread
• -sdp_file file – write SDP info to file
• -discard – discard specific frames or whole stream (none, default, noref, bidir, nokey, all)
• -abort_on flag – abort on conditions (empty_output, empty_output_stream)
• -max_error_rate – maximum fraction of decode failures (default 2/3)
• -xerror – exit on error
• -max_muxing_queue_size packets – buffer size for muxing queue
• -muxing_queue_data_threshold bytes – minimum threshold for muxing queue size
• -auto_conversion_filters – enable automatic insertion of formmat conversion filters

Preset Files

Preset files contain option=value pairs (one per line, comments start with #). Two types:

• ffpreset files: used via vpre, apre, spre, fpre. Looked up in $FFMPEG_DATADIR, $HOME/.ffmpeg, and the data directory.
• avpreset files: used via pre. Encoder-specific options only. Looked up in $AVCONV_DATADIR, $HOME/.avconv, and data directory.

Examples

Video/Audio Grabbing

# Capture from OSS and V4L2
ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg

# Using ALSA (mono, card 1)
ffmpeg -f alsa -ac 1 -i hw:1 -f video4linux2 -i /dev/video0 /tmp/out.mpg

X11 Grabbing

# Grab entire display
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg

# With offset
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg

File Format Conversion

# Input from YUV files (numbered)
ffmpeg -i /tmp/test%d.y /tmp/out.mpg

# Raw YUV420P to AVI
ffmpeg -i /tmp/test.yuv /tmp/out.avi

# Output to raw YUV
ffmpeg -i mydivx.avi hugefile.yuv

# Combine audio and video
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg

# Audio conversion with sample rate change
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2

# Multiple outputs with different bitrates
ffmpeg -i /tmp/a.wav -map 0:a -b:a 64k /tmp/a.mp2 -map 0:a -b:a 128k /tmp/b.mp2

# DVD rip to AVI
ffmpeg -i snatch_1.vob -f avi -c:v mpeg4 -b:v 800k -g 300 -bf 2 -c:a libmp3lame -b:a 128k snatch.avi

# Extract frames from video
ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg

# Create video from image sequence
ffmpeg -f image2 -framerate 12 -i foo-%03d.jpeg -s WxH foo.avi

# Using glob pattern
ffmpeg -f image2 -pattern_type glob -framerate 12 -i 'foo-*.jpeg' -s WxH foo.avi

# Multiple streams reordered
ffmpeg -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut

# Force CBR video
ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v