-map [-]input_file_id[:stream_specifier][:view_specifier][:?] | [linklabel] (output)
Create one or more streams in the output file. This option has two forms for specifying the data source(s): the first selects one or more streams from some input file (specified with -i), the second takes an output from some complex filtergraph (specified with -filter_complex).
In the first form, an output stream is created for every stream from the input file with the index input_file_id. If stream_specifier is given, only those streams that match the specifier are used (see the Stream specifiers section for the stream_specifier syntax).
A - character before the stream identifier creates a "negative" mapping. It disables matching streams from already created mappings.
An optional view_specifier may be given after the stream specifier, which for multiview video specifies the view to be used. The view specifier may have one of the following formats:
view:view_id
select a view by its ID; view_id may be set to ’all’ to use all the views interleaved into one stream;
vidx:view_idx
select a view by its index; i.e. 0 is the base view, 1 is the first non-base view, etc.
vpos:position
select a view by its display position; position may be left or right
The default for transcoding is to only use the base view, i.e. the equivalent of vidx:0. For streamcopy, view specifiers are not supported and all views are always copied.
A trailing ? after the stream index will allow the map to be optional: if the map matches no streams the map will be ignored instead of failing. Note the map will still fail if an invalid input file index is used; such as if the map refers to a non-existent input.
An alternative [linklabel] form will map outputs from complex filter graphs (see the -filter_complex option) to the output file. linklabel must correspond to a defined output link label in the graph.
This option may be specified multiple times, each adding more streams to the output file. Any given input stream may also be mapped any number of times as a source for different output streams, e.g. in order to use different encoding options and/or filters. The streams are created in the output in the same order in which the -map options are given on the commandline.
Using this option disables the default mappings for this output file.
Examples:
map everything
To map ALL streams from the first input file to output
ffmpeg -i INPUT -map 0 output
select specific stream
If you have two audio streams in the first input file, these streams are identified by 0:0 and 0:1. You can use -map to select which streams to place in an output file. For example:
ffmpeg -i INPUT -map 0:1 out.wav
will map the second input stream in INPUT to the (single) output stream in out.wav.
create multiple streams
To select the stream with index 2 from input file a.mov (specified by the identifier 0:2), and stream with index 6 from input b.mov (specified by the identifier 1:6), and copy them to the output file out.mov:
ffmpeg -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
create multiple streams 2
To select all video and the third audio stream from an input file:
ffmpeg -i INPUT -map 0:v -map 0:a:2 OUTPUT
negative map
To map all the streams except the second audio, use negative mappings
ffmpeg -i INPUT -map 0 -map -0:a:1 OUTPUT
optional map
To map the video and audio streams from the first input, and using the trailing ?, ignore the audio mapping if no audio streams exist in the first input:
ffmpeg -i INPUT -map 0:v -map 0:a? OUTPUT
map by language
To pick the English audio stream:
ffmpeg -i INPUT -map 0:m:language:eng OUTPUT
-ignore_unknown
Ignore input streams with unknown type instead of failing if copying such streams is attempted.
-copy_unknown
Allow input streams with unknown type to be copied instead of failing if copying such streams is attempted.
-map_metadata[:metadata_spec_out] infile[:metadata_spec_in] (output,per-metadata)
Set metadata information of the next output file from infile. Note that those are file indices (zero-based), not filenames. Optional metadata_spec_in/out parameters specify, which metadata to copy. A metadata specifier can have the following forms:
g
global metadata, i.e. metadata that applies to the whole file
s[:stream_spec]
per-stream metadata. stream_spec is a stream specifier as described in the Stream specifiers chapter. In an input metadata specifier, the first matching stream is copied from. In an output metadata specifier, all matching streams are copied to.
c:chapter_index
per-chapter metadata. chapter_index is the zero-based chapter index.
p:program_index
per-program metadata. program_index is the zero-based program index.
If metadata specifier is omitted, it defaults to global.
By default, global metadata is copied from the first input file, per-stream and per-chapter metadata is copied along with streams/chapters. These default mappings are disabled by creating any mapping of the relevant type. A negative file index can be used to create a dummy mapping that just disables automatic copying.
For example to copy metadata from the first stream of the input file to global metadata of the output file:
ffmpeg -i in.ogg -map_metadata 0:s:0 out.mp3
To do the reverse, i.e. copy global metadata to all audio streams:
ffmpeg -i in.mkv -map_metadata:s:a 0:g out.mkv
Note that simple 0 would work as well in this example, since global metadata is assumed by default.
-map_chapters input_file_index (output)
Copy chapters from input file with index input_file_index to the next output file. If no chapter mapping is specified, then chapters are copied from the first input file with at least one chapter. Use a negative file index to disable any chapter copying.
-benchmark (global)
Show benchmarking information at the end of an encode. Shows real, system and user time used and maximum memory consumption. Maximum memory consumption is not supported on all systems, it will usually display as 0 if not supported.
-benchmark_all (global)
Show benchmarking information during the encode. Shows real, system and user time used in various steps (audio/video encode/decode).
-timelimit duration (global)
Exit after ffmpeg has been running for duration seconds in CPU user time.
-dump (global)
Dump each input packet to stderr.
-hex (global)
When dumping packets, also dump the payload.
-readrate speed (input)
Limit input read speed.
Its value is a floating-point positive number which represents the maximum duration of media, in seconds, that should be ingested in one second of wallclock time. Default value is zero and represents no imposed limitation on speed of ingestion. Value 1 represents real-time speed and is equivalent to -re.
Mainly used to simulate a capture device or live input stream (e.g. when reading from a file). Should not be used with a low value when input is an actual capture device or live stream as it may cause packet loss.
It is useful for when flow speed of output packets is important, such as live streaming.
-re (input)
Read input at native frame rate. This is equivalent to setting -readrate 1.
-readrate_initial_burst seconds
Set an initial read burst time, in seconds, after which -re/-readrate will be enforced.
-vsync parameter (global)
-fps_mode[:stream_specifier] parameter (output,per-stream)
Set video sync method / framerate mode. vsync is applied to all output video streams but can be overridden for a stream by setting fps_mode. vsync is deprecated and will be removed in the future.
For compatibility reasons some of the values for vsync can be specified as numbers (shown in parentheses in the following table).
passthrough (0)
Each frame is passed with its timestamp from the demuxer to the muxer.
cfr (1)
Frames will be duplicated and dropped to achieve exactly the requested constant frame rate.
vfr (2)
Frames are passed through with their timestamp or dropped so as to prevent 2 frames from having the same timestamp.
auto (-1)
Chooses between cfr and vfr depending on muxer capabilities. This is the default method.
Note that the timestamps may be further modified by the muxer, after this. For example, in the case that the format option avoid_negative_ts is enabled.
With -map you can select from which stream the timestamps should be taken. You can leave either video or audio unchanged and sync the remaining stream(s) to the unchanged one.
-frame_drop_threshold parameter
Frame drop threshold, which specifies how much behind video frames can be before they are dropped. In frame rate units, so 1.0 is one frame. The default is -1.1. One possible usecase is to avoid framedrops in case of noisy timestamps or to increase frame drop precision in case of exact timestamps.
-apad parameters (output,per-stream)
Pad the output audio stream(s). This is the same as applying -af apad. Argument is a string of filter parameters composed the same as with the apad filter. -shortest must be set for this output for the option to take effect.
-copyts
Do not process input timestamps, but keep their values without trying to sanitize them. In particular, do not remove the initial start time offset value.
Note that, depending on the vsync option or on specific muxer processing (e.g. in case the format option avoid_negative_ts is enabled) the output timestamps may mismatch with the input timestamps even when this option is selected.
-start_at_zero
When used with copyts, shift input timestamps so they start at zero.
This means that using e.g. -ss 50 will make output timestamps start at 50 seconds, regardless of what timestamp the input file started at.
-copytb mode
Specify how to set the encoder timebase when stream copying. mode is an integer numeric value, and can assume one of the following values:
1
Use the demuxer timebase.
The time base is copied to the output encoder from the corresponding input demuxer. This is sometimes required to avoid non monotonically increasing timestamps when copying video streams with variable frame rate.
0
Use the decoder timebase.
The time base is copied to the output encoder from the corresponding input decoder.
-1
Try to make the choice automatically, in order to generate a sane output.
Default value is -1.
-enc_time_base[:stream_specifier] timebase (output,per-stream)
Set the encoder timebase. timebase can assume one of the following values:
0
Assign a default value according to the media type.
For video - use 1/framerate, for audio - use 1/samplerate.
demux
Use the timebase from the demuxer.
filter
Use the timebase from the filtergraph.
a positive number
Use the provided number as the timebase.
This field can be provided as a ratio of two integers (e.g. 1:24, 1:48000) or as a decimal number (e.g. 0.04166, 2.0833e-5)
Default value is 0.
-bitexact (input/output)
Enable bitexact mode for (de)muxer and (de/en)coder
-shortest (output)
Finish encoding when the shortest output stream ends.
Note that this option may require buffering frames, which introduces extra latency. The maximum amount of this latency may be controlled with the -shortest_buf_duration option.
-shortest_buf_duration duration (output)
The -shortest option may require buffering potentially large amounts of data when at least one of the streams is "sparse" (i.e. has large gaps between frames – this is typically the case for subtitles).
This option controls the maximum duration of buffered frames in seconds. Larger values may allow the -shortest option to produce more accurate results, but increase memory use and latency.
The default value is 10 seconds.
-dts_delta_threshold threshold
Timestamp discontinuity delta threshold, expressed as a decimal number of seconds.
The timestamp discontinuity correction enabled by this option is only applied to input formats accepting timestamp discontinuity (for which the AVFMT_TS_DISCONT flag is enabled), e.g. MPEG-TS and HLS, and is automatically disabled when employing the -copyts option (unless wrapping is detected).
If a timestamp discontinuity is detected whose absolute value is greater than threshold, ffmpeg will remove the discontinuity by decreasing/increasing the current DTS and PTS by the corresponding delta value.
The default value is 10.
-dts_error_threshold threshold
Timestamp error delta threshold, expressed as a decimal number of seconds.
The timestamp correction enabled by this option is only applied to input formats not accepting timestamp discontinuity (for which the AVFMT_TS_DISCONT flag is not enabled).
If a timestamp discontinuity is detected whose absolute value is greater than threshold, ffmpeg will drop the PTS/DTS timestamp value.
The default value is 3600*30 (30 hours), which is arbitrarily picked and quite conservative.
-muxdelay seconds (output)
Set the maximum demux-decode delay.
-muxpreload seconds (output)
Set the initial demux-decode delay.
-streamid output-stream-index:new-value (output)
Assign a new stream-id value to an output stream. This option should be specified prior to the output filename to which it applies. For the situation where multiple output files exist, a streamid may be reassigned to a different value.
For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for an output mpegts file:
ffmpeg -i inurl -streamid 0:33 -streamid 1:36 out.ts
-bsf[:stream_specifier] bitstream_filters (input/output,per-stream)
Apply bitstream filters to matching streams. The filters are applied to each packet as it is received from the demuxer (when used as an input option) or before it is sent to the muxer (when used as an output option).
bitstream_filters is a comma-separated list of bitstream filter specifications, each of the form
filter[=optname0=optval0:optname1=optval1:...]
Any of the ’,=:’ characters that are to be a part of an option value need to be escaped with a backslash.
Use the -bsfs option to get the list of bitstream filters.
E.g.
ffmpeg -bsf:v h264_mp4toannexb -i h264.mp4 -c:v copy -an out.h264
applies the h264_mp4toannexb bitstream filter (which converts MP4-encapsulated H.264 stream to Annex B) to the input video stream.
On the other hand,
ffmpeg -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
applies the mov2textsub bitstream filter (which extracts text from MOV subtitles) to the output subtitle stream. Note, however, that since both examples use -c copy, it matters little whether the filters are applied on input or output - that would change if transcoding was happening.
-tag[:stream_specifier] codec_tag (input/output,per-stream)
Force a tag/fourcc for matching streams.
-timecode hh:mm:ssSEPff
Specify Timecode for writing. SEP is ’:’ for non drop timecode and ’;’ (or ’.’) for drop.
ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
-filter_complex filtergraph (global)
Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or outputs. For simple graphs – those with one input and one output of the same type – see the -filter options. filtergraph is a description of the filtergraph, as described in the “Filtergraph syntax” section of the ffmpeg-filters manual. This option may be specified multiple times - each use creates a new complex filtergraph.
Inputs to a complex filtergraph may come from different source types, distinguished by the format of the corresponding link label:
To connect an input stream, use [file_index:stream_specifier] (i.e. the same syntax as -map). If stream_specifier matches multiple streams, the first one will be used. For multiview video, the stream specifier may be followed by the view specifier, see documentation for the -map option for its syntax.
To connect a loopback decoder use [dec:dec_idx], where dec_idx is the index of the loopback decoder to be connected to given input. For multiview video, the decoder index may be followed by the view specifier, see documentation for the -map option for its syntax.
To connect an output from another complex filtergraph, use its link label. E.g the following example:
ffmpeg -i input.mkv \
-filter_complex '[0:v]scale=size=hd1080,split=outputs=2[for_enc][orig_scaled]' \
-c:v libx264 -map '[for_enc]' output.mkv \
-dec 0:0 \
-filter_complex '[dec:0][orig_scaled]hstack[stacked]' \
-map '[stacked]' -c:v ffv1 comparison.mkv
reads an input video and
(line 2) uses a complex filtergraph with one input and two outputs to scale the video to 1920x1080 and duplicate the result to both outputs;
(line 3) encodes one scaled output with libx264 and writes the result to output.mkv;
(line 4) decodes this encoded stream with a loopback decoder;
(line 5) places the output of the loopback decoder (i.e. the libx264-encoded video) side by side with the scaled original input;
(line 6) combined video is then losslessly encoded and written into comparison.mkv.
Note that the two filtergraphs cannot be combined into one, because then there would be a cycle in the transcoding pipeline (filtergraph output goes to encoding, from there to decoding, then back to the same graph), and such cycles are not allowed.
An unlabeled input will be connected to the first unused input stream of the matching type.
Output link labels are referred to with -map. Unlabeled outputs are added to the first output file.
Note that with this option it is possible to use only lavfi sources without normal input files.
For example, to overlay an image over video
ffmpeg -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
'[out]' out.mkv
Here [0:v] refers to the first video stream in the first input file, which is linked to the first (main) input of the overlay filter. Similarly the first video stream in the second input is linked to the second (overlay) input of overlay.
Assuming there is only one video stream in each input file, we can omit input labels, so the above is equivalent to
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
'[out]' out.mkv
Furthermore we can omit the output label and the single output from the filter graph will be added to the output file automatically, so we can simply write
ffmpeg -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
As a special exception, you can use a bitmap subtitle stream as input: it will be converted into a video with the same size as the largest video in the file, or 720x576 if no video is present. Note that this is an experimental and temporary solution. It will be removed once libavfilter has proper support for subtitles.
For example, to hardcode subtitles on top of a DVB-T recording stored in MPEG-TS format, delaying the subtitles by 1 second:
ffmpeg -i input.ts -filter_complex \
'[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' \
-sn -map '#0x2dc' output.mkv
(0x2d0, 0x2dc and 0x2ef are the MPEG-TS PIDs of respectively the video, audio and subtitles streams; 0:0, 0:3 and 0:7 would have worked too)
To generate 5 seconds of pure red video using lavfi color source:
ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv
-filter_complex_threads nb_threads (global)
Defines how many threads are used to process a filter_complex graph. Similar to filter_threads but used for -filter_complex graphs only. The default is the number of available CPUs.
-lavfi filtergraph (global)
Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or outputs. Equivalent to -filter_complex.
-accurate_seek (input)
This option enables or disables accurate seeking in input files with the -ss option. It is enabled by default, so seeking is accurate when transcoding. Use -noaccurate_seek to disable it, which may be useful e.g. when copying some streams and transcoding the others.
-seek_timestamp (input)
This option enables or disables seeking by timestamp in input files with the -ss option. It is disabled by default. If enabled, the argument to the -ss option is considered an actual timestamp, and is not offset by the start time of the file. This matters only for files which do not start from timestamp 0, such as transport streams.
-thread_queue_size size (input/output)
For input, this option sets the maximum number of queued packets when reading from the file or device. With low latency / high rate live streams, packets may be discarded if they are not read in a timely manner; setting this value can force ffmpeg to use a separate input thread and read packets as soon as they arrive. By default ffmpeg only does this if multiple inputs are specified.
For output, this option specified the maximum number of packets that may be queued to each muxing thread.
-sdp_file file (global)
Print sdp information for an output stream to file. This allows dumping sdp information when at least one output isn’t an rtp stream. (Requires at least one of the output formats to be rtp).
-discard (input)
Allows discarding specific streams or frames from streams. Any input stream can be fully discarded, using value all whereas selective discarding of frames from a stream occurs at the demuxer and is not supported by all demuxers.
none
Discard no frame.
default
Default, which discards no frames.
noref
Discard all non-reference frames.
bidir
Discard all bidirectional frames.
nokey
Discard all frames excepts keyframes.
all
Discard all frames.
-abort_on flags (global)
Stop and abort on various conditions. The following flags are available:
empty_output
No packets were passed to the muxer, the output is empty.
empty_output_stream
No packets were passed to the muxer in some of the output streams.
-max_error_rate (global)
Set fraction of decoding frame failures across all inputs which when crossed ffmpeg will return exit code 69. Crossing this threshold does not terminate processing. Range is a floating-point number between 0 to 1. Default is 2/3.
-xerror (global)
Stop and exit on error
-max_muxing_queue_size packets (output,per-stream)
When transcoding audio and/or video streams, ffmpeg will not begin writing into the output until it has one packet for each such stream. While waiting for that to happen, packets for other streams are buffered. This option sets the size of this buffer, in packets, for the matching output stream.
The default value of this option should be high enough for most uses, so only touch this option if you are sure that you need it.
-muxing_queue_data_threshold bytes (output,per-stream)
This is a minimum threshold until which the muxing queue size is not taken into account. Defaults to 50 megabytes per stream, and is based on the overall size of packets passed to the muxer.
-auto_conversion_filters (global)
Enable automatically inserting format conversion filters in all filter graphs, including those defined by -vf, -af, -filter_complex and -lavfi. If filter format negotiation requires a conversion, the initialization of the filters will fail. Conversions can still be performed by inserting the relevant conversion filter (scale, aresample) in the graph. On by default, to explicitly disable it you need to specify -noauto_conversion_filters.
-bits_per_raw_sample[:stream_specifier] value (output,per-stream)
Declare the number of bits per raw sample in the given output stream to be value. Note that this option sets the information provided to the encoder/muxer, it does not change the stream to conform to this value. Setting values that do not match the stream properties may result in encoding failures or invalid output files.
-stats_enc_pre[:stream_specifier] path (output,per-stream)
-stats_enc_post[:stream_specifier] path (output,per-stream)
-stats_mux_pre[:stream_specifier] path (output,per-stream)
Write per-frame encoding information about the matching streams into the file given by path.
-stats_enc_pre writes information about raw video or audio frames right before they are sent for encoding, while -stats_enc_post writes information about encoded packets as they are received from the encoder. -stats_mux_pre writes information about packets just as they are about to be sent to the muxer. Every frame or packet produces one line in the specified file. The format of this line is controlled by -stats_enc_pre_fmt / -stats_enc_post_fmt / -stats_mux_pre_fmt.
When stats for multiple streams are written into a single file, the lines corresponding to different streams will be interleaved. The precise order of this interleaving is not specified and not guaranteed to remain stable between different invocations of the program, even with the same options.
-stats_enc_pre_fmt[:stream_specifier] format_spec (output,per-stream)
-stats_enc_post_fmt[:stream_specifier] format_spec (output,per-stream)
-stats_mux_pre_fmt[:stream_specifier] format_spec (output,per-stream)
Specify the format for the lines written with -stats_enc_pre / -stats_enc_post / -stats_mux_pre.
format_spec is a string that may contain directives of the form {fmt}. format_spec is backslash-escaped — use \{, \}, and \\ to write a literal {, }, or \, respectively, into the output.
The directives given with fmt may be one of the following:
fidx
Index of the output file.
sidx
Index of the output stream in the file.
n
Frame number. Pre-encoding: number of frames sent to the encoder so far. Post-encoding: number of packets received from the encoder so far. Muxing: number of packets submitted to the muxer for this stream so far.
ni
Input frame number. Index of the input frame (i.e. output by a decoder) that corresponds to this output frame or packet. -1 if unavailable.
tb
Timebase in which this frame/packet’s timestamps are expressed, as a rational number num/den. Note that encoder and muxer may use different timebases.
tbi
Timebase for ptsi, as a rational number num/den. Available when ptsi is available, 0/1 otherwise.
pts
Presentation timestamp of the frame or packet, as an integer. Should be multiplied by the timebase to compute presentation time.
ptsi
Presentation timestamp of the input frame (see ni), as an integer. Should be multiplied by tbi to compute presentation time. Printed as (2^63 - 1 = 9223372036854775807) when not available.
t
Presentation time of the frame or packet, as a decimal number. Equal to pts multiplied by tb.
ti
Presentation time of the input frame (see ni), as a decimal number. Equal to ptsi multiplied by tbi. Printed as inf when not available.
dts (packet)
Decoding timestamp of the packet, as an integer. Should be multiplied by the timebase to compute presentation time.
dt (packet)
Decoding time of the frame or packet, as a decimal number. Equal to dts multiplied by tb.
sn (frame,audio)
Number of audio samples sent to the encoder so far.
samp (frame,audio)
Number of audio samples in the frame.
size (packet)
Size of the encoded packet in bytes.
br (packet)
Current bitrate in bits per second.
abr (packet)
Average bitrate for the whole stream so far, in bits per second, -1 if it cannot be determined at this point.
key (packet)
Character ’K’ if the packet contains a keyframe, character ’N’ otherwise.
Directives tagged with packet may only be used with -stats_enc_post_fmt and -stats_mux_pre_fmt.
Directives tagged with frame may only be used with -stats_enc_pre_fmt.
Directives tagged with audio may only be used with audio streams.
The default format strings are:
pre-encoding
{fidx} {sidx} {n} {t}
post-encoding
{fidx} {sidx} {n} {t}
In the future, new items may be added to the end of the default formatting strings. Users who depend on the format staying exactly the same, should prescribe it manually.
Note that stats for different streams written into the same file may have different formats.
https://www.octfgroup.com/