avfilter/showvolume : add persistent max display
[ffmpeg.git] / doc / fftools-common-opts.texi
1 All the numerical options, if not specified otherwise, accept a string
2 representing a number as input, which may be followed by one of the SI
3 unit prefixes, for example: 'K', 'M', or 'G'.
4
5 If 'i' is appended to the SI unit prefix, the complete prefix will be
6 interpreted as a unit prefix for binary multiples, which are based on
7 powers of 1024 instead of powers of 1000. Appending 'B' to the SI unit
8 prefix multiplies the value by 8. This allows using, for example:
9 'KB', 'MiB', 'G' and 'B' as number suffixes.
10
11 Options which do not take arguments are boolean options, and set the
12 corresponding value to true. They can be set to false by prefixing
13 the option name with "no". For example using "-nofoo"
14 will set the boolean option with name "foo" to false.
15
16 @anchor{Stream specifiers}
17 @section Stream specifiers
18 Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers
19 are used to precisely specify which stream(s) a given option belongs to.
20
21 A stream specifier is a string generally appended to the option name and
22 separated from it by a colon. E.g. @code{-codec:a:1 ac3} contains the
23 @code{a:1} stream specifier, which matches the second audio stream. Therefore, it
24 would select the ac3 codec for the second audio stream.
25
26 A stream specifier can match several streams, so that the option is applied to all
27 of them. E.g. the stream specifier in @code{-b:a 128k} matches all audio
28 streams.
29
30 An empty stream specifier matches all streams. For example, @code{-codec copy}
31 or @code{-codec: copy} would copy all the streams without reencoding.
32
33 Possible forms of stream specifiers are:
34 @table @option
35 @item @var{stream_index}
36 Matches the stream with this index. E.g. @code{-threads:1 4} would set the
37 thread count for the second stream to 4.
38 @item @var{stream_type}[:@var{stream_index}]
39 @var{stream_type} is one of following: 'v' or 'V' for video, 'a' for audio, 's'
40 for subtitle, 'd' for data, and 't' for attachments. 'v' matches all video
41 streams, 'V' only matches video streams which are not attached pictures, video
42 thumbnails or cover arts.  If @var{stream_index} is given, then it matches
43 stream number @var{stream_index} of this type. Otherwise, it matches all
44 streams of this type.
45 @item p:@var{program_id}[:@var{stream_index}] or p:@var{program_id}[:@var{stream_type}[:@var{stream_index}]] or
46 p:@var{program_id}:m:@var{key}[:@var{value}]
47 In first version, if @var{stream_index} is given, then it matches the stream with number @var{stream_index}
48 in the program with the id @var{program_id}. Otherwise, it matches all streams in the
49 program. In the second version, @var{stream_type} is one of following: 'v' for video, 'a' for audio, 's'
50 for subtitle, 'd' for data. If @var{stream_index} is also given, then it matches
51 stream number @var{stream_index} of this type in the program with the id @var{program_id}.
52 Otherwise, if only @var{stream_type} is given, it matches all
53 streams of this type in the program with the id @var{program_id}.
54 In the third version matches streams in the program with the id @var{program_id} with the metadata
55 tag @var{key} having the specified value. If
56 @var{value} is not given, matches streams that contain the given tag with any
57 value.
58
59 @item #@var{stream_id} or i:@var{stream_id}
60 Match the stream by stream id (e.g. PID in MPEG-TS container).
61 @item m:@var{key}[:@var{value}]
62 Matches streams with the metadata tag @var{key} having the specified value. If
63 @var{value} is not given, matches streams that contain the given tag with any
64 value.
65 @item u
66 Matches streams with usable configuration, the codec must be defined and the
67 essential information such as video dimension or audio sample rate must be present.
68
69 Note that in @command{ffmpeg}, matching by metadata will only work properly for
70 input files.
71 @end table
72
73 @section Generic options
74
75 These options are shared amongst the ff* tools.
76
77 @table @option
78
79 @item -L
80 Show license.
81
82 @item -h, -?, -help, --help [@var{arg}]
83 Show help. An optional parameter may be specified to print help about a specific
84 item. If no argument is specified, only basic (non advanced) tool
85 options are shown.
86
87 Possible values of @var{arg} are:
88 @table @option
89 @item long
90 Print advanced tool options in addition to the basic tool options.
91
92 @item full
93 Print complete list of options, including shared and private options
94 for encoders, decoders, demuxers, muxers, filters, etc.
95
96 @item decoder=@var{decoder_name}
97 Print detailed information about the decoder named @var{decoder_name}. Use the
98 @option{-decoders} option to get a list of all decoders.
99
100 @item encoder=@var{encoder_name}
101 Print detailed information about the encoder named @var{encoder_name}. Use the
102 @option{-encoders} option to get a list of all encoders.
103
104 @item demuxer=@var{demuxer_name}
105 Print detailed information about the demuxer named @var{demuxer_name}. Use the
106 @option{-formats} option to get a list of all demuxers and muxers.
107
108 @item muxer=@var{muxer_name}
109 Print detailed information about the muxer named @var{muxer_name}. Use the
110 @option{-formats} option to get a list of all muxers and demuxers.
111
112 @item filter=@var{filter_name}
113 Print detailed information about the filter name @var{filter_name}. Use the
114 @option{-filters} option to get a list of all filters.
115 @end table
116
117 @item -version
118 Show version.
119
120 @item -formats
121 Show available formats (including devices).
122
123 @item -demuxers
124 Show available demuxers.
125
126 @item -muxers
127 Show available muxers.
128
129 @item -devices
130 Show available devices.
131
132 @item -codecs
133 Show all codecs known to libavcodec.
134
135 Note that the term 'codec' is used throughout this documentation as a shortcut
136 for what is more correctly called a media bitstream format.
137
138 @item -decoders
139 Show available decoders.
140
141 @item -encoders
142 Show all available encoders.
143
144 @item -bsfs
145 Show available bitstream filters.
146
147 @item -protocols
148 Show available protocols.
149
150 @item -filters
151 Show available libavfilter filters.
152
153 @item -pix_fmts
154 Show available pixel formats.
155
156 @item -sample_fmts
157 Show available sample formats.
158
159 @item -layouts
160 Show channel names and standard channel layouts.
161
162 @item -colors
163 Show recognized color names.
164
165 @item -sources @var{device}[,@var{opt1}=@var{val1}[,@var{opt2}=@var{val2}]...]
166 Show autodetected sources of the input device.
167 Some devices may provide system-dependent source names that cannot be autodetected.
168 The returned list cannot be assumed to be always complete.
169 @example
170 ffmpeg -sources pulse,server=192.168.0.4
171 @end example
172
173 @item -sinks @var{device}[,@var{opt1}=@var{val1}[,@var{opt2}=@var{val2}]...]
174 Show autodetected sinks of the output device.
175 Some devices may provide system-dependent sink names that cannot be autodetected.
176 The returned list cannot be assumed to be always complete.
177 @example
178 ffmpeg -sinks pulse,server=192.168.0.4
179 @end example
180
181 @item -loglevel [@var{flags}+]@var{loglevel} | -v [@var{flags}+]@var{loglevel}
182 Set logging level and flags used by the library.
183
184 The optional @var{flags} prefix can consist of the following values:
185 @table @samp
186 @item repeat
187 Indicates that repeated log output should not be compressed to the first line
188 and the "Last message repeated n times" line will be omitted.
189 @item level
190 Indicates that log output should add a @code{[level]} prefix to each message
191 line. This can be used as an alternative to log coloring, e.g. when dumping the
192 log to file.
193 @end table
194 Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single
195 flag without affecting other @var{flags} or changing @var{loglevel}. When
196 setting both @var{flags} and @var{loglevel}, a '+' separator is expected
197 between the last @var{flags} value and before @var{loglevel}.
198
199 @var{loglevel} is a string or a number containing one of the following values:
200 @table @samp
201 @item quiet, -8
202 Show nothing at all; be silent.
203 @item panic, 0
204 Only show fatal errors which could lead the process to crash, such as
205 an assertion failure. This is not currently used for anything.
206 @item fatal, 8
207 Only show fatal errors. These are errors after which the process absolutely
208 cannot continue.
209 @item error, 16
210 Show all errors, including ones which can be recovered from.
211 @item warning, 24
212 Show all warnings and errors. Any message related to possibly
213 incorrect or unexpected events will be shown.
214 @item info, 32
215 Show informative messages during processing. This is in addition to
216 warnings and errors. This is the default value.
217 @item verbose, 40
218 Same as @code{info}, except more verbose.
219 @item debug, 48
220 Show everything, including debugging information.
221 @item trace, 56
222 @end table
223
224 For example to enable repeated log output, add the @code{level} prefix, and set
225 @var{loglevel} to @code{verbose}:
226 @example
227 ffmpeg -loglevel repeat+level+verbose -i input output
228 @end example
229 Another example that enables repeated log output without affecting current
230 state of @code{level} prefix flag or @var{loglevel}:
231 @example
232 ffmpeg [...] -loglevel +repeat
233 @end example
234
235 By default the program logs to stderr. If coloring is supported by the
236 terminal, colors are used to mark errors and warnings. Log coloring
237 can be disabled setting the environment variable
238 @env{AV_LOG_FORCE_NOCOLOR} or @env{NO_COLOR}, or can be forced setting
239 the environment variable @env{AV_LOG_FORCE_COLOR}.
240 The use of the environment variable @env{NO_COLOR} is deprecated and
241 will be dropped in a future FFmpeg version.
242
243 @item -report
244 Dump full command line and console output to a file named
245 @code{@var{program}-@var{YYYYMMDD}-@var{HHMMSS}.log} in the current
246 directory.
247 This file can be useful for bug reports.
248 It also implies @code{-loglevel verbose}.
249
250 Setting the environment variable @env{FFREPORT} to any value has the
251 same effect. If the value is a ':'-separated key=value sequence, these
252 options will affect the report; option values must be escaped if they
253 contain special characters or the options delimiter ':' (see the
254 ``Quoting and escaping'' section in the ffmpeg-utils manual).
255
256 The following options are recognized:
257 @table @option
258 @item file
259 set the file name to use for the report; @code{%p} is expanded to the name
260 of the program, @code{%t} is expanded to a timestamp, @code{%%} is expanded
261 to a plain @code{%}
262 @item level
263 set the log verbosity level using a numerical value (see @code{-loglevel}).
264 @end table
265
266 For example, to output a report to a file named @file{ffreport.log}
267 using a log level of @code{32} (alias for log level @code{info}):
268
269 @example
270 FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
271 @end example
272
273 Errors in parsing the environment variable are not fatal, and will not
274 appear in the report.
275
276 @item -hide_banner
277 Suppress printing banner.
278
279 All FFmpeg tools will normally show a copyright notice, build options
280 and library versions. This option can be used to suppress printing
281 this information.
282
283 @item -cpuflags flags (@emph{global})
284 Allows setting and clearing cpu flags. This option is intended
285 for testing. Do not use it unless you know what you're doing.
286 @example
287 ffmpeg -cpuflags -sse+mmx ...
288 ffmpeg -cpuflags mmx ...
289 ffmpeg -cpuflags 0 ...
290 @end example
291 Possible flags for this option are:
292 @table @samp
293 @item x86
294 @table @samp
295 @item mmx
296 @item mmxext
297 @item sse
298 @item sse2
299 @item sse2slow
300 @item sse3
301 @item sse3slow
302 @item ssse3
303 @item atom
304 @item sse4.1
305 @item sse4.2
306 @item avx
307 @item avx2
308 @item xop
309 @item fma3
310 @item fma4
311 @item 3dnow
312 @item 3dnowext
313 @item bmi1
314 @item bmi2
315 @item cmov
316 @end table
317 @item ARM
318 @table @samp
319 @item armv5te
320 @item armv6
321 @item armv6t2
322 @item vfp
323 @item vfpv3
324 @item neon
325 @item setend
326 @end table
327 @item AArch64
328 @table @samp
329 @item armv8
330 @item vfp
331 @item neon
332 @end table
333 @item PowerPC
334 @table @samp
335 @item altivec
336 @end table
337 @item Specific Processors
338 @table @samp
339 @item pentium2
340 @item pentium3
341 @item pentium4
342 @item k6
343 @item k62
344 @item athlon
345 @item athlonxp
346 @item k8
347 @end table
348 @end table
349 @end table
350
351 @section AVOptions
352
353 These options are provided directly by the libavformat, libavdevice and
354 libavcodec libraries. To see the list of available AVOptions, use the
355 @option{-help} option. They are separated into two categories:
356 @table @option
357 @item generic
358 These options can be set for any container, codec or device. Generic options
359 are listed under AVFormatContext options for containers/devices and under
360 AVCodecContext options for codecs.
361 @item private
362 These options are specific to the given container, device or codec. Private
363 options are listed under their corresponding containers/devices/codecs.
364 @end table
365
366 For example to write an ID3v2.3 header instead of a default ID3v2.4 to
367 an MP3 file, use the @option{id3v2_version} private option of the MP3
368 muxer:
369 @example
370 ffmpeg -i input.flac -id3v2_version 3 out.mp3
371 @end example
372
373 All codec AVOptions are per-stream, and thus a stream specifier
374 should be attached to them.
375
376 Note: the @option{-nooption} syntax cannot be used for boolean
377 AVOptions, use @option{-option 0}/@option{-option 1}.
378
379 Note: the old undocumented way of specifying per-stream AVOptions by
380 prepending v/a/s to the options name is now obsolete and will be
381 removed soon.