fftools-common-opts.texi 12.6 KB
Newer Older
1 2 3 4 5
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
6
interpreted as a unit prefix for binary multiples, which are based on
7 8 9
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.
10

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

16
@anchor{Stream specifiers}
17 18
@section Stream specifiers
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 23
separated from it by a colon. E.g. @code{-codec:a:1 ac3} contains the
@code{a:1} stream specifier, which matches the second audio stream. Therefore, it
24 25
would select the ac3 codec for the second audio stream.

26
A stream specifier can match several streams, so that the option is applied to all
27 28 29
of them. E.g. the stream specifier in @code{-b:a 128k} matches all audio
streams.

30
An empty stream specifier matches all streams. For example, @code{-codec copy}
31 32 33 34 35 36 37 38
or @code{-codec: copy} would copy all the streams without reencoding.

Possible forms of stream specifiers are:
@table @option
@item @var{stream_index}
Matches the stream with this index. E.g. @code{-threads:1 4} would set the
thread count for the second stream to 4.
@item @var{stream_type}[:@var{stream_index}]
39 40 41 42
@var{stream_type} is one of following: 'v' or 'V' for video, 'a' for audio, 's'
for subtitle, 'd' for data, and 't' for attachments. 'v' matches all video
streams, 'V' only matches video streams which are not attached pictures, video
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 46
@item p:@var{program_id}[:@var{stream_index}] or p:@var{program_id}[:@var{stream_type}[:@var{stream_index}]] or
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 51 52 53
for subtitle, 'd' for data. If @var{stream_index} is also given, then it matches
stream number @var{stream_index} of this type in the program with the id @var{program_id}.
Otherwise, if only @var{stream_type} is given, it matches all
streams of this type in the program with the id @var{program_id}.
54 55 56 57 58
In the third version matches streams in the program with the id @var{program_id} with the metadata
tag @var{key} having the specified value. If
@var{value} is not given, matches streams that contain the given tag with any
value.

59 60
@item #@var{stream_id} or i:@var{stream_id}
Match the stream by stream id (e.g. PID in MPEG-TS container).
61 62 63 64
@item m:@var{key}[:@var{value}]
Matches streams with the metadata tag @var{key} having the specified value. If
@var{value} is not given, matches streams that contain the given tag with any
value.
65 66 67
@item u
Matches streams with usable configuration, the codec must be defined and the
essential information such as video dimension or audio sample rate must be present.
68

Michael Niedermayer's avatar
Michael Niedermayer committed
69
Note that in @command{ffmpeg}, matching by metadata will only work properly for
70
input files.
71
@end table
72

73 74
@section Generic options

75
These options are shared amongst the ff* tools.
76 77 78

@table @option

79 80 81
@item -L
Show license.

82 83
@item -h, -?, -help, --help [@var{arg}]
Show help. An optional parameter may be specified to print help about a specific
84 85
item. If no argument is specified, only basic (non advanced) tool
options are shown.
86 87 88

Possible values of @var{arg} are:
@table @option
89 90 91 92 93 94 95
@item long
Print advanced tool options in addition to the basic tool options.

@item full
Print complete list of options, including shared and private options
for encoders, decoders, demuxers, muxers, filters, etc.

96 97 98 99 100 101 102
@item decoder=@var{decoder_name}
Print detailed information about the decoder named @var{decoder_name}. Use the
@option{-decoders} option to get a list of all decoders.

@item encoder=@var{encoder_name}
Print detailed information about the encoder named @var{encoder_name}. Use the
@option{-encoders} option to get a list of all encoders.
103 104 105 106 107 108 109 110 111

@item demuxer=@var{demuxer_name}
Print detailed information about the demuxer named @var{demuxer_name}. Use the
@option{-formats} option to get a list of all demuxers and muxers.

@item muxer=@var{muxer_name}
Print detailed information about the muxer named @var{muxer_name}. Use the
@option{-formats} option to get a list of all muxers and demuxers.

112 113 114
@item filter=@var{filter_name}
Print detailed information about the filter name @var{filter_name}. Use the
@option{-filters} option to get a list of all filters.
115
@end table
116 117 118 119 120

@item -version
Show version.

@item -formats
121 122
Show available formats (including devices).

123 124 125 126 127 128
@item -demuxers
Show available demuxers.

@item -muxers
Show available muxers.

129 130
@item -devices
Show available devices.
131 132

@item -codecs
133
Show all codecs known to libavcodec.
134

135 136 137 138 139 140 141 142
Note that the term 'codec' is used throughout this documentation as a shortcut
for what is more correctly called a media bitstream format.

@item -decoders
Show available decoders.

@item -encoders
Show all available encoders.
143 144 145 146 147 148 149 150 151 152

@item -bsfs
Show available bitstream filters.

@item -protocols
Show available protocols.

@item -filters
Show available libavfilter filters.

153 154 155
@item -pix_fmts
Show available pixel formats.

156 157 158
@item -sample_fmts
Show available sample formats.

159 160 161
@item -layouts
Show channel names and standard channel layouts.

162 163 164
@item -colors
Show recognized color names.

165
@item -sources @var{device}[,@var{opt1}=@var{val1}[,@var{opt2}=@var{val2}]...]
166
Show autodetected sources of the input device.
167 168 169 170 171 172 173 174 175 176 177 178 179 180
Some devices may provide system-dependent source names that cannot be autodetected.
The returned list cannot be assumed to be always complete.
@example
ffmpeg -sources pulse,server=192.168.0.4
@end example

@item -sinks @var{device}[,@var{opt1}=@var{val1}[,@var{opt2}=@var{val2}]...]
Show autodetected sinks of the output device.
Some devices may provide system-dependent sink names that cannot be autodetected.
The returned list cannot be assumed to be always complete.
@example
ffmpeg -sinks pulse,server=192.168.0.4
@end example

181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
@item -loglevel [@var{flags}+]@var{loglevel} | -v [@var{flags}+]@var{loglevel}
Set logging level and flags used by the library.

The optional @var{flags} prefix can consist of the following values:
@table @samp
@item repeat
Indicates that repeated log output should not be compressed to the first line
and the "Last message repeated n times" line will be omitted.
@item level
Indicates that log output should add a @code{[level]} prefix to each message
line. This can be used as an alternative to log coloring, e.g. when dumping the
log to file.
@end table
Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single
flag without affecting other @var{flags} or changing @var{loglevel}. When
setting both @var{flags} and @var{loglevel}, a '+' separator is expected
between the last @var{flags} value and before @var{loglevel}.

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 213
Show all warnings and errors. Any message related to possibly
incorrect or unexpected events will be shown.
214
@item info, 32
215 216
Show informative messages during processing. This is in addition to
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 223
@end table

224 225 226 227 228 229 230 231 232 233 234
For example to enable repeated log output, add the @code{level} prefix, and set
@var{loglevel} to @code{verbose}:
@example
ffmpeg -loglevel repeat+level+verbose -i input output
@end example
Another example that enables repeated log output without affecting current
state of @code{level} prefix flag or @var{loglevel}:
@example
ffmpeg [...] -loglevel +repeat
@end example

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 239
@env{AV_LOG_FORCE_NOCOLOR} or @env{NO_COLOR}, or can be forced setting
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 244 245 246 247 248 249
@item -report
Dump full command line and console output to a file named
@code{@var{program}-@var{YYYYMMDD}-@var{HHMMSS}.log} in the current
directory.
This file can be useful for bug reports.
It also implies @code{-loglevel verbose}.

Lou Logan's avatar
Lou Logan committed
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
Lou Logan's avatar
Lou Logan committed
252
options will affect the report; option values must be escaped if they
253
contain special characters or the options delimiter ':' (see the
Lou Logan's avatar
Lou Logan committed
254 255 256
``Quoting and escaping'' section in the ffmpeg-utils manual).

The following options are recognized:
257 258 259 260 261
@table @option
@item file
set the file name to use for the report; @code{%p} is expanded to the name
of the program, @code{%t} is expanded to a timestamp, @code{%%} is expanded
to a plain @code{%}
262
@item level
Lou Logan's avatar
Lou Logan committed
263
set the log verbosity level using a numerical value (see @code{-loglevel}).
264 265
@end table

Lou Logan's avatar
Lou Logan committed
266 267 268 269 270 271 272
For example, to output a report to a file named @file{ffreport.log}
using a log level of @code{32} (alias for log level @code{info}):

@example
FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
@end example

273 274
Errors in parsing the environment variable are not fatal, and will not
appear in the report.
275

276 277 278 279 280 281 282
@item -hide_banner
Suppress printing banner.

All FFmpeg tools will normally show a copyright notice, build options
and library versions. This option can be used to suppress printing
this information.

283 284 285
@item -cpuflags flags (@emph{global})
Allows setting and clearing cpu flags. This option is intended
for testing. Do not use it unless you know what you're doing.
286 287 288 289 290
@example
ffmpeg -cpuflags -sse+mmx ...
ffmpeg -cpuflags mmx ...
ffmpeg -cpuflags 0 ...
@end example
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
Possible flags for this option are:
@table @samp
@item x86
@table @samp
@item mmx
@item mmxext
@item sse
@item sse2
@item sse2slow
@item sse3
@item sse3slow
@item ssse3
@item atom
@item sse4.1
@item sse4.2
@item avx
307
@item avx2
308
@item xop
309
@item fma3
310 311 312
@item fma4
@item 3dnow
@item 3dnowext
313 314
@item bmi1
@item bmi2
315 316 317 318 319 320 321 322 323 324
@item cmov
@end table
@item ARM
@table @samp
@item armv5te
@item armv6
@item armv6t2
@item vfp
@item vfpv3
@item neon
325
@item setend
326
@end table
327 328 329 330 331 332
@item AArch64
@table @samp
@item armv8
@item vfp
@item neon
@end table
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348
@item PowerPC
@table @samp
@item altivec
@end table
@item Specific Processors
@table @samp
@item pentium2
@item pentium3
@item pentium4
@item k6
@item k62
@item athlon
@item athlonxp
@item k8
@end table
@end table
349
@end table
350 351 352

@section AVOptions

353 354
These options are provided directly by the libavformat, libavdevice and
libavcodec libraries. To see the list of available AVOptions, use the
355 356 357
@option{-help} option. They are separated into two categories:
@table @option
@item generic
358 359
These options can be set for any container, codec or device. Generic options
are listed under AVFormatContext options for containers/devices and under
360
AVCodecContext options for codecs.
361
@item private
362 363
These options are specific to the given container, device or codec. Private
options are listed under their corresponding containers/devices/codecs.
364 365 366 367 368 369 370 371 372
@end table

For example to write an ID3v2.3 header instead of a default ID3v2.4 to
an MP3 file, use the @option{id3v2_version} private option of the MP3
muxer:
@example
ffmpeg -i input.flac -id3v2_version 3 out.mp3
@end example

373 374
All codec AVOptions are per-stream, and thus a stream specifier
should be attached to them.
375

376 377
Note: the @option{-nooption} syntax cannot be used for boolean
AVOptions, use @option{-option 0}/@option{-option 1}.
378

379 380 381
Note: the old undocumented way of specifying per-stream AVOptions by
prepending v/a/s to the options name is now obsolete and will be
removed soon.