Examples

The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream selection methods.

They assume the following three input files.

input file 'A.avi'
      stream 0: video 640x360
      stream 1: audio 2 channels
input file 'B.mp4'
      stream 0: video 1920x1080
      stream 1: audio 2 channels
      stream 2: subtitles (text)
      stream 3: audio 5.1 channels
      stream 4: subtitles (text)
input file 'C.mkv'
      stream 0: video 1280x720
      stream 1: audio 2 channels
      stream 2: subtitles (image)

Example: automatic stream selection

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

There are three output files specified, and for the first two, no -map options are set, so ffmpeg will select streams for these two files automatically.

'out1.mkv' is a Matroska container file and accepts video, audio and subtitle streams, so ffmpeg will try to select one of each type.
For video, it will select stream 0 from 'B.mp4', which has the highest resolution among all the input video streams.
For audio, it will select stream 3 from 'B.mp4', since it has the greatest number of channels.
For subtitles, it will select stream 2 from 'B.mp4', which is the first subtitle stream from among 'A.avi' and 'B.mp4'.

'out2.wav' accepts only audio streams, so only stream 3 from 'B.mp4' is selected.

For 'out3.mov', since a -map option is set, no automatic stream selection will occur. The -map 1:a option will select all audio streams from the second input 'B.mp4'. No other streams will be included in this output file.

For the first two outputs, all included streams will be transcoded. The encoders chosen will be the default ones registered by each output format, which may not match the codec of the selected input streams.

For the third output, codec option for audio streams has been set to copy, so no decoding-filtering-encoding operations will occur, or can occur. Packets of selected streams shall be conveyed from the input file and muxed within the output file.

Example: automatic subtitles selection

ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv

Although 'out1.mkv' is a Matroska container file which accepts subtitle streams, only a video and audio stream shall be selected. The subtitle stream of 'C.mkv' is image-based and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation for the subtitles is expected to fail and hence the stream isn't selected. However, in 'out2.mkv', a subtitle encoder is specified in the command and so, the subtitle stream is selected, in addition to the video stream. The presence of -an disables audio stream selection for 'out2.mkv'.

Example: unlabeled filtergraph outputs

ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt

A filtergraph is setup here using the -filter_complex option and consists of a single video filter. The overlay filter requires exactly two video inputs, but none are specified, so the first two available video streams are used, those of 'A.avi' and 'C.mkv'. The output pad of the filter has no label and so is sent to the first output file 'out1.mp4'. Due to this, automatic selection of the video stream is skipped, which would have selected the stream in 'B.mp4'. The audio stream with most channels viz. stream 3 in 'B.mp4', is chosen automatically. No subtitle stream is chosen however, since the MP4 format has no default subtitle encoder registered, and the user hasn't specified a subtitle encoder.

The 2nd output file, 'out2.srt', only accepts text-based subtitle streams. So, even though the first subtitle stream available belongs to 'C.mkv', it is image-based and hence skipped. The selected stream, stream 2 in 'B.mp4', is the first text-based subtitle stream.

Example: labeled filtergraph outputs

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

The above command will fail, as the output pad labelled [outv] has been mapped twice. None of the output files shall be processed.

ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
       -an        out1.mp4 \
                  out2.mkv \
       -map 1:a:0 out3.mkv

This command above will also fail as the hue filter output has a label, [outv], and hasn't been mapped anywhere.

The command should be modified as follows,

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

The video stream from 'B.mp4' is sent to the hue filter, whose output is cloned once using the split filter, and both outputs labelled. Then a copy each is mapped to the first and third output files.

The overlay filter, requiring two video inputs, uses the first two unused video streams. Those are the streams from 'A.avi' and 'C.mkv'. The overlay output isn't labelled, so it is sent to the first output file 'out1.mp4', regardless of the presence of the -map option.

The aresample filter is sent the first unused audio stream, that of 'A.avi'. Since this filter output is also unlabelled, it too is mapped to the first output file. The presence of -an only suppresses automatic or manual stream selection of audio streams, not outputs sent from filtergraphs. Both these mapped streams shall be ordered before the mapped stream in 'out1.mp4'.

The video, audio and subtitle streams mapped to out2.mkv are entirely determined by automatic stream selection.

'out3.mkv' consists of the cloned video output from the hue filter and the first audio stream from 'B.mp4'.

Options

All the numerical options, if not specified otherwise, accept a string representing a number as input, which may be followed by one of the SI unit prefixes, for example: 'K', 'M', or 'G'.

If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted as a unit prefix for binary multiples, which are based on powers of 1024 instead of powers of 1000. Appending 'B' to the SI unit prefix multiplies the value by 8. This allows using, for example: 'KB', 'MiB', 'G' and 'B' as number suffixes.

Options which do not take arguments are boolean options, and set the corresponding value to true. They can be set to false by prefixing the option name with "no". For example using "-nofoo" will set the boolean option with name "foo" to false.