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