Merge commit 'd5eab59a5373b22aa52d6053a8e853e95a6e131e'
[ffmpeg.git] / doc / formats.texi
1 @chapter Format Options
2 @c man begin FORMAT OPTIONS
3
4 The libavformat library provides some generic global options, which
5 can be set on all the muxers and demuxers. In addition each muxer or
6 demuxer may support so-called private options, which are specific for
7 that component.
8
9 Options may be set by specifying -@var{option} @var{value} in the
10 FFmpeg tools, or by setting the value explicitly in the
11 @code{AVFormatContext} options or using the @file{libavutil/opt.h} API
12 for programmatic use.
13
14 The list of supported options follows:
15
16 @table @option
17 @item avioflags @var{flags} (@emph{input/output})
18 Possible values:
19 @table @samp
20 @item direct
21 Reduce buffering.
22 @end table
23
24 @item probesize @var{integer} (@emph{input})
25 Set probing size in bytes, i.e. the size of the data to analyze to get
26 stream information. A higher value will enable detecting more
27 information in case it is dispersed into the stream, but will increase
28 latency. Must be an integer not lesser than 32. It is 5000000 by default.
29
30 @item packetsize @var{integer} (@emph{output})
31 Set packet size.
32
33 @item fflags @var{flags} (@emph{input/output})
34 Set format flags.
35
36 Possible values:
37 @table @samp
38 @item ignidx
39 Ignore index.
40 @item fastseek
41 Enable fast, but inaccurate seeks for some formats.
42 @item genpts
43 Generate PTS.
44 @item nofillin
45 Do not fill in missing values that can be exactly calculated.
46 @item noparse
47 Disable AVParsers, this needs @code{+nofillin} too.
48 @item igndts
49 Ignore DTS.
50 @item discardcorrupt
51 Discard corrupted frames.
52 @item sortdts
53 Try to interleave output packets by DTS.
54 @item keepside
55 Do not merge side data.
56 @item latm
57 Enable RTP MP4A-LATM payload.
58 @item nobuffer
59 Reduce the latency introduced by optional buffering
60 @item bitexact
61 Only write platform-, build- and time-independent data.
62 This ensures that file and data checksums are reproducible and match between
63 platforms. Its primary use is for regression testing.
64 @end table
65
66 @item seek2any @var{integer} (@emph{input})
67 Allow seeking to non-keyframes on demuxer level when supported if set to 1.
68 Default is 0.
69
70 @item analyzeduration @var{integer} (@emph{input})
71 Specify how many microseconds are analyzed to probe the input. A
72 higher value will enable detecting more accurate information, but will
73 increase latency. It defaults to 5,000,000 microseconds = 5 seconds.
74
75 @item cryptokey @var{hexadecimal string} (@emph{input})
76 Set decryption key.
77
78 @item indexmem @var{integer} (@emph{input})
79 Set max memory used for timestamp index (per stream).
80
81 @item rtbufsize @var{integer} (@emph{input})
82 Set max memory used for buffering real-time frames.
83
84 @item fdebug @var{flags} (@emph{input/output})
85 Print specific debug info.
86
87 Possible values:
88 @table @samp
89 @item ts
90 @end table
91
92 @item max_delay @var{integer} (@emph{input/output})
93 Set maximum muxing or demuxing delay in microseconds.
94
95 @item fpsprobesize @var{integer} (@emph{input})
96 Set number of frames used to probe fps.
97
98 @item audio_preload @var{integer} (@emph{output})
99 Set microseconds by which audio packets should be interleaved earlier.
100
101 @item chunk_duration @var{integer} (@emph{output})
102 Set microseconds for each chunk.
103
104 @item chunk_size @var{integer} (@emph{output})
105 Set size in bytes for each chunk.
106
107 @item err_detect, f_err_detect @var{flags} (@emph{input})
108 Set error detection flags. @code{f_err_detect} is deprecated and
109 should be used only via the @command{ffmpeg} tool.
110
111 Possible values:
112 @table @samp
113 @item crccheck
114 Verify embedded CRCs.
115 @item bitstream
116 Detect bitstream specification deviations.
117 @item buffer
118 Detect improper bitstream length.
119 @item explode
120 Abort decoding on minor error detection.
121 @item careful
122 Consider things that violate the spec and have not been seen in the
123 wild as errors.
124 @item compliant
125 Consider all spec non compliancies as errors.
126 @item aggressive
127 Consider things that a sane encoder should not do as an error.
128 @end table
129
130 @item max_interleave_delta @var{integer} (@emph{output})
131 Set maximum buffering duration for interleaving. The duration is
132 expressed in microseconds, and defaults to 1000000 (1 second).
133
134 To ensure all the streams are interleaved correctly, libavformat will
135 wait until it has at least one packet for each stream before actually
136 writing any packets to the output file. When some streams are
137 "sparse" (i.e. there are large gaps between successive packets), this
138 can result in excessive buffering.
139
140 This field specifies the maximum difference between the timestamps of the
141 first and the last packet in the muxing queue, above which libavformat
142 will output a packet regardless of whether it has queued a packet for all
143 the streams.
144
145 If set to 0, libavformat will continue buffering packets until it has
146 a packet for each stream, regardless of the maximum timestamp
147 difference between the buffered packets.
148
149 @item use_wallclock_as_timestamps @var{integer} (@emph{input})
150 Use wallclock as timestamps.
151
152 @item avoid_negative_ts @var{integer} (@emph{output})
153
154 Possible values:
155 @table @samp
156 @item make_non_negative
157 Shift timestamps to make them non-negative.
158 Also note that this affects only leading negative timestamps, and not
159 non-monotonic negative timestamps.
160 @item make_zero
161 Shift timestamps so that the first timestamp is 0.
162 @item auto (default)
163 Enables shifting when required by the target format.
164 @item disabled
165 Disables shifting of timestamp.
166 @end table
167
168 When shifting is enabled, all output timestamps are shifted by the
169 same amount. Audio, video, and subtitles desynching and relative
170 timestamp differences are preserved compared to how they would have
171 been without shifting.
172
173 @item skip_initial_bytes @var{integer} (@emph{input})
174 Set number of bytes to skip before reading header and frames if set to 1.
175 Default is 0.
176
177 @item correct_ts_overflow @var{integer} (@emph{input})
178 Correct single timestamp overflows if set to 1. Default is 1.
179
180 @item flush_packets @var{integer} (@emph{output})
181 Flush the underlying I/O stream after each packet. Default 1 enables it, and
182 has the effect of reducing the latency; 0 disables it and may slightly
183 increase performance in some cases.
184
185 @item output_ts_offset @var{offset} (@emph{output})
186 Set the output time offset.
187
188 @var{offset} must be a time duration specification,
189 see @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
190
191 The offset is added by the muxer to the output timestamps.
192
193 Specifying a positive offset means that the corresponding streams are
194 delayed bt the time duration specified in @var{offset}. Default value
195 is @code{0} (meaning that no offset is applied).
196
197 @item format_whitelist @var{list} (@emph{input})
198 "," separated List of allowed demuxers. By default all are allowed.
199
200 @item dump_separator @var{string} (@emph{input})
201 Separator used to separate the fields printed on the command line about the
202 Stream parameters.
203 For example to separate the fields with newlines and indention:
204 @example
205 ffprobe -dump_separator "
206                           "  -i ~/videos/matrixbench_mpeg2.mpg
207 @end example
208 @end table
209
210 @c man end FORMAT OPTIONS
211
212 @anchor{Format stream specifiers}
213 @section Format stream specifiers
214
215 Format stream specifiers allow selection of one or more streams that
216 match specific properties.
217
218 Possible forms of stream specifiers are:
219 @table @option
220 @item @var{stream_index}
221 Matches the stream with this index.
222
223 @item @var{stream_type}[:@var{stream_index}]
224 @var{stream_type} is one of following: 'v' for video, 'a' for audio,
225 's' for subtitle, 'd' for data, and 't' for attachments. If
226 @var{stream_index} is given, then it matches the stream number
227 @var{stream_index} of this type. Otherwise, it matches all streams of
228 this type.
229
230 @item p:@var{program_id}[:@var{stream_index}]
231 If @var{stream_index} is given, then it matches the stream with number
232 @var{stream_index} in the program with the id
233 @var{program_id}. Otherwise, it matches all streams in the program.
234
235 @item #@var{stream_id}
236 Matches the stream by a format-specific ID.
237 @end table
238
239 The exact semantics of stream specifiers is defined by the
240 @code{avformat_match_stream_specifier()} function declared in the
241 @file{libavformat/avformat.h} header.
242
243 @ifclear config-writeonly
244 @include demuxers.texi
245 @end ifclear
246 @ifclear config-readonly
247 @include muxers.texi
248 @end ifclear
249 @include metadata.texi