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