doc/encoders: reformat libmp3lame doc
[ffmpeg.git] / doc / encoders.texi
1 @chapter Encoders
2 @c man begin ENCODERS
3
4 Encoders are configured elements in FFmpeg which allow the encoding of
5 multimedia streams.
6
7 When you configure your FFmpeg build, all the supported native encoders
8 are enabled by default. Encoders requiring an external library must be enabled
9 manually via the corresponding @code{--enable-lib} option. You can list all
10 available encoders using the configure option @code{--list-encoders}.
11
12 You can disable all the encoders with the configure option
13 @code{--disable-encoders} and selectively enable / disable single encoders
14 with the options @code{--enable-encoder=@var{ENCODER}} /
15 @code{--disable-encoder=@var{ENCODER}}.
16
17 The option @code{-codecs} of the ff* tools will display the list of
18 enabled encoders.
19
20 @c man end ENCODERS
21
22 @chapter Audio Encoders
23 @c man begin AUDIO ENCODERS
24
25 A description of some of the currently available audio encoders
26 follows.
27
28 @section ac3 and ac3_fixed
29
30 AC-3 audio encoders.
31
32 These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366, as well as
33 the undocumented RealAudio 3 (a.k.a. dnet).
34
35 The @var{ac3} encoder uses floating-point math, while the @var{ac3_fixed}
36 encoder only uses fixed-point integer math. This does not mean that one is
37 always faster, just that one or the other may be better suited to a
38 particular system. The floating-point encoder will generally produce better
39 quality audio for a given bitrate. The @var{ac3_fixed} encoder is not the
40 default codec for any of the output formats, so it must be specified explicitly
41 using the option @code{-acodec ac3_fixed} in order to use it.
42
43 @subsection AC-3 Metadata
44
45 The AC-3 metadata options are used to set parameters that describe the audio,
46 but in most cases do not affect the audio encoding itself. Some of the options
47 do directly affect or influence the decoding and playback of the resulting
48 bitstream, while others are just for informational purposes. A few of the
49 options will add bits to the output stream that could otherwise be used for
50 audio data, and will thus affect the quality of the output. Those will be
51 indicated accordingly with a note in the option list below.
52
53 These parameters are described in detail in several publicly-available
54 documents.
55 @itemize
56 @item @uref{http://www.atsc.org/cms/standards/a_52-2010.pdf,A/52:2010 - Digital Audio Compression (AC-3) (E-AC-3) Standard}
57 @item @uref{http://www.atsc.org/cms/standards/a_54a_with_corr_1.pdf,A/54 - Guide to the Use of the ATSC Digital Television Standard}
58 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/18_Metadata.Guide.pdf,Dolby Metadata Guide}
59 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/46_DDEncodingGuidelines.pdf,Dolby Digital Professional Encoding Guidelines}
60 @end itemize
61
62 @subsubsection Metadata Control Options
63
64 @table @option
65
66 @item -per_frame_metadata @var{boolean}
67 Allow Per-Frame Metadata. Specifies if the encoder should check for changing
68 metadata for each frame.
69 @table @option
70 @item 0
71 The metadata values set at initialization will be used for every frame in the
72 stream. (default)
73 @item 1
74 Metadata values can be changed before encoding each frame.
75 @end table
76
77 @end table
78
79 @subsubsection Downmix Levels
80
81 @table @option
82
83 @item -center_mixlev @var{level}
84 Center Mix Level. The amount of gain the decoder should apply to the center
85 channel when downmixing to stereo. This field will only be written to the
86 bitstream if a center channel is present. The value is specified as a scale
87 factor. There are 3 valid values:
88 @table @option
89 @item 0.707
90 Apply -3dB gain
91 @item 0.595
92 Apply -4.5dB gain (default)
93 @item 0.500
94 Apply -6dB gain
95 @end table
96
97 @item -surround_mixlev @var{level}
98 Surround Mix Level. The amount of gain the decoder should apply to the surround
99 channel(s) when downmixing to stereo. This field will only be written to the
100 bitstream if one or more surround channels are present. The value is specified
101 as a scale factor.  There are 3 valid values:
102 @table @option
103 @item 0.707
104 Apply -3dB gain
105 @item 0.500
106 Apply -6dB gain (default)
107 @item 0.000
108 Silence Surround Channel(s)
109 @end table
110
111 @end table
112
113 @subsubsection Audio Production Information
114 Audio Production Information is optional information describing the mixing
115 environment.  Either none or both of the fields are written to the bitstream.
116
117 @table @option
118
119 @item -mixing_level @var{number}
120 Mixing Level. Specifies peak sound pressure level (SPL) in the production
121 environment when the mix was mastered. Valid values are 80 to 111, or -1 for
122 unknown or not indicated. The default value is -1, but that value cannot be
123 used if the Audio Production Information is written to the bitstream. Therefore,
124 if the @code{room_type} option is not the default value, the @code{mixing_level}
125 option must not be -1.
126
127 @item -room_type @var{type}
128 Room Type. Describes the equalization used during the final mixing session at
129 the studio or on the dubbing stage. A large room is a dubbing stage with the
130 industry standard X-curve equalization; a small room has flat equalization.
131 This field will not be written to the bitstream if both the @code{mixing_level}
132 option and the @code{room_type} option have the default values.
133 @table @option
134 @item 0
135 @itemx notindicated
136 Not Indicated (default)
137 @item 1
138 @itemx large
139 Large Room
140 @item 2
141 @itemx small
142 Small Room
143 @end table
144
145 @end table
146
147 @subsubsection Other Metadata Options
148
149 @table @option
150
151 @item -copyright @var{boolean}
152 Copyright Indicator. Specifies whether a copyright exists for this audio.
153 @table @option
154 @item 0
155 @itemx off
156 No Copyright Exists (default)
157 @item 1
158 @itemx on
159 Copyright Exists
160 @end table
161
162 @item -dialnorm @var{value}
163 Dialogue Normalization. Indicates how far the average dialogue level of the
164 program is below digital 100% full scale (0 dBFS). This parameter determines a
165 level shift during audio reproduction that sets the average volume of the
166 dialogue to a preset level. The goal is to match volume level between program
167 sources. A value of -31dB will result in no volume level change, relative to
168 the source volume, during audio reproduction. Valid values are whole numbers in
169 the range -31 to -1, with -31 being the default.
170
171 @item -dsur_mode @var{mode}
172 Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround
173 (Pro Logic). This field will only be written to the bitstream if the audio
174 stream is stereo. Using this option does @b{NOT} mean the encoder will actually
175 apply Dolby Surround processing.
176 @table @option
177 @item 0
178 @itemx notindicated
179 Not Indicated (default)
180 @item 1
181 @itemx off
182 Not Dolby Surround Encoded
183 @item 2
184 @itemx on
185 Dolby Surround Encoded
186 @end table
187
188 @item -original @var{boolean}
189 Original Bit Stream Indicator. Specifies whether this audio is from the
190 original source and not a copy.
191 @table @option
192 @item 0
193 @itemx off
194 Not Original Source
195 @item 1
196 @itemx on
197 Original Source (default)
198 @end table
199
200 @end table
201
202 @subsection Extended Bitstream Information
203 The extended bitstream options are part of the Alternate Bit Stream Syntax as
204 specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts.
205 If any one parameter in a group is specified, all values in that group will be
206 written to the bitstream.  Default values are used for those that are written
207 but have not been specified.  If the mixing levels are written, the decoder
208 will use these values instead of the ones specified in the @code{center_mixlev}
209 and @code{surround_mixlev} options if it supports the Alternate Bit Stream
210 Syntax.
211
212 @subsubsection Extended Bitstream Information - Part 1
213
214 @table @option
215
216 @item -dmix_mode @var{mode}
217 Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt
218 (Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode.
219 @table @option
220 @item 0
221 @itemx notindicated
222 Not Indicated (default)
223 @item 1
224 @itemx ltrt
225 Lt/Rt Downmix Preferred
226 @item 2
227 @itemx loro
228 Lo/Ro Downmix Preferred
229 @end table
230
231 @item -ltrt_cmixlev @var{level}
232 Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the
233 center channel when downmixing to stereo in Lt/Rt mode.
234 @table @option
235 @item 1.414
236 Apply +3dB gain
237 @item 1.189
238 Apply +1.5dB gain
239 @item 1.000
240 Apply 0dB gain
241 @item 0.841
242 Apply -1.5dB gain
243 @item 0.707
244 Apply -3.0dB gain
245 @item 0.595
246 Apply -4.5dB gain (default)
247 @item 0.500
248 Apply -6.0dB gain
249 @item 0.000
250 Silence Center Channel
251 @end table
252
253 @item -ltrt_surmixlev @var{level}
254 Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the
255 surround channel(s) when downmixing to stereo in Lt/Rt mode.
256 @table @option
257 @item 0.841
258 Apply -1.5dB gain
259 @item 0.707
260 Apply -3.0dB gain
261 @item 0.595
262 Apply -4.5dB gain
263 @item 0.500
264 Apply -6.0dB gain (default)
265 @item 0.000
266 Silence Surround Channel(s)
267 @end table
268
269 @item -loro_cmixlev @var{level}
270 Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the
271 center channel when downmixing to stereo in Lo/Ro mode.
272 @table @option
273 @item 1.414
274 Apply +3dB gain
275 @item 1.189
276 Apply +1.5dB gain
277 @item 1.000
278 Apply 0dB gain
279 @item 0.841
280 Apply -1.5dB gain
281 @item 0.707
282 Apply -3.0dB gain
283 @item 0.595
284 Apply -4.5dB gain (default)
285 @item 0.500
286 Apply -6.0dB gain
287 @item 0.000
288 Silence Center Channel
289 @end table
290
291 @item -loro_surmixlev @var{level}
292 Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the
293 surround channel(s) when downmixing to stereo in Lo/Ro mode.
294 @table @option
295 @item 0.841
296 Apply -1.5dB gain
297 @item 0.707
298 Apply -3.0dB gain
299 @item 0.595
300 Apply -4.5dB gain
301 @item 0.500
302 Apply -6.0dB gain (default)
303 @item 0.000
304 Silence Surround Channel(s)
305 @end table
306
307 @end table
308
309 @subsubsection Extended Bitstream Information - Part 2
310
311 @table @option
312
313 @item -dsurex_mode @var{mode}
314 Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX
315 (7.1 matrixed to 5.1). Using this option does @b{NOT} mean the encoder will actually
316 apply Dolby Surround EX processing.
317 @table @option
318 @item 0
319 @itemx notindicated
320 Not Indicated (default)
321 @item 1
322 @itemx on
323 Dolby Surround EX Off
324 @item 2
325 @itemx off
326 Dolby Surround EX On
327 @end table
328
329 @item -dheadphone_mode @var{mode}
330 Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone
331 encoding (multi-channel matrixed to 2.0 for use with headphones). Using this
332 option does @b{NOT} mean the encoder will actually apply Dolby Headphone
333 processing.
334 @table @option
335 @item 0
336 @itemx notindicated
337 Not Indicated (default)
338 @item 1
339 @itemx on
340 Dolby Headphone Off
341 @item 2
342 @itemx off
343 Dolby Headphone On
344 @end table
345
346 @item -ad_conv_type @var{type}
347 A/D Converter Type. Indicates whether the audio has passed through HDCD A/D
348 conversion.
349 @table @option
350 @item 0
351 @itemx standard
352 Standard A/D Converter (default)
353 @item 1
354 @itemx hdcd
355 HDCD A/D Converter
356 @end table
357
358 @end table
359
360 @subsection Other AC-3 Encoding Options
361
362 @table @option
363
364 @item -stereo_rematrixing @var{boolean}
365 Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This
366 is an optional AC-3 feature that increases quality by selectively encoding
367 the left/right channels as mid/side. This option is enabled by default, and it
368 is highly recommended that it be left as enabled except for testing purposes.
369
370 @end table
371
372 @subsection Floating-Point-Only AC-3 Encoding Options
373
374 These options are only valid for the floating-point encoder and do not exist
375 for the fixed-point encoder due to the corresponding features not being
376 implemented in fixed-point.
377
378 @table @option
379
380 @item -channel_coupling @var{boolean}
381 Enables/Disables use of channel coupling, which is an optional AC-3 feature
382 that increases quality by combining high frequency information from multiple
383 channels into a single channel. The per-channel high frequency information is
384 sent with less accuracy in both the frequency and time domains. This allows
385 more bits to be used for lower frequencies while preserving enough information
386 to reconstruct the high frequencies. This option is enabled by default for the
387 floating-point encoder and should generally be left as enabled except for
388 testing purposes or to increase encoding speed.
389 @table @option
390 @item -1
391 @itemx auto
392 Selected by Encoder (default)
393 @item 0
394 @itemx off
395 Disable Channel Coupling
396 @item 1
397 @itemx on
398 Enable Channel Coupling
399 @end table
400
401 @item -cpl_start_band @var{number}
402 Coupling Start Band. Sets the channel coupling start band, from 1 to 15. If a
403 value higher than the bandwidth is used, it will be reduced to 1 less than the
404 coupling end band. If @var{auto} is used, the start band will be determined by
405 the encoder based on the bit rate, sample rate, and channel layout. This option
406 has no effect if channel coupling is disabled.
407 @table @option
408 @item -1
409 @itemx auto
410 Selected by Encoder (default)
411 @end table
412
413 @end table
414
415 @section libmp3lame
416
417 LAME (Lame Ain't an MP3 Encoder) MP3 encoder wrapper.
418
419 Requires the presence of the libmp3lame headers and library during
420 configuration. You need to explicitly configure the build with
421 @code{--enable-libmp3lame}.
422
423 @subsection Options
424
425 The following options are supported by the libmp3lame wrapper. The
426 @command{lame}-equivalent of the options are listed in parentheses.
427
428 @table @option
429 @item b (@emph{-b})
430 Set bitrate expressed in bits/s for CBR. LAME @code{bitrate} is
431 expressed in kilobits/s.
432
433 @item q (@emph{-V})
434 Set constant quality setting for VBR. This option is valid only
435 using the @command{ffmpeg} command-line tool. For library interface
436 users, use @option{global_quality}.
437
438 @item compression_level (@emph{-q})
439 Set algorithm quality. Valid arguments are integers in the 0-9 range,
440 with 0 meaning highest quality but slowest, and 9 meaning fastest
441 while producing the worst quality.
442
443 @item reservoir
444 Enable use of bit reservoir when set to 1. Default value is 1. LAME
445 has this enabled by default, but can be overriden by use
446 @option{--nores} option.
447
448 @item joint_stereo (@emph{-m j})
449 Enable the encoder to use (on a frame by frame basis) either L/R
450 stereo or mid/side stereo. Default value is 1.
451
452 @end table
453
454 @section libopencore-amrnb
455
456 OpenCORE Adaptive Multi-Rate Narrowband encoder.
457
458 Requires the presence of the libopencore-amrnb headers and library during
459 configuration. You need to explicitly configure the build with
460 @code{--enable-libopencore-amrnb --enable-version3}.
461
462 This is a mono-only encoder. Officially it only supports 8000Hz sample rate,
463 but you can override it by setting @option{strict} to @samp{unofficial} or
464 lower.
465
466 @subsection Options
467
468 @table @option
469
470 @item b
471 Set bitrate in bits per second. Only the following bitrates are supported,
472 otherwise libavcodec will round to the nearest valid bitrate.
473
474 @table @option
475 @item 4750
476 @item 5150
477 @item 5900
478 @item 6700
479 @item 7400
480 @item 7950
481 @item 10200
482 @item 12200
483 @end table
484
485 @item dtx
486 Allow discontinuous transmission (generate comfort noise) when set to 1. The
487 default value is 0 (disabled).
488
489 @end table
490
491 @section libtwolame
492
493 TwoLAME MP2 encoder wrapper.
494
495 Requires the presence of the libtwolame headers and library during
496 configuration. You need to explicitly configure the build with
497 @code{--enable-libtwolame}.
498
499 @subsection Options Mapping
500
501 The following options are supported by the libtwolame wrapper. The
502 TwoLAME-equivalent options follow the FFmpeg ones and are in
503 parentheses.
504
505 @table @option
506 @item b
507 (b) Set bitrate in bits/s. Note that FFmpeg @code{b} option is
508 expressed in bits/s, twolame @code{b} in kilobits/s. The default
509 value is 128k.
510
511 @item q
512 (V) Set quality for experimental VBR support. Maximum value range is
513 from -50 to 50, useful range is from -10 to 10.
514
515 @item mode
516 (mode) Set MPEG mode. Possible values:
517
518 @table @samp
519 @item auto
520 Choose mode automatically based on the input. This is the default.
521 @item stereo
522 Stereo
523 @item joint_stereo
524 Joint stereo
525 @item dual_channel
526 Dual channel
527 @item mono
528 Mono
529 @end table
530
531 @item psymodel
532 (psyc-mode) Set psychoacoustic model to use in encoding. The argument
533 must be an integer between -1 and 4, inclusive. The higher the value,
534 the better the quality. The default value is 3.
535
536 @item energy_levels
537 (energy) Enable energy levels extensions when set to 1. The default
538 value is 0 (disabled).
539
540 @item error_protection
541 (protect) Enable CRC error protection when set to 1. The default value
542 is 0 (disabled).
543
544 @item copyright
545 (copyright) Set MPEG audio copyright flag when set to 1. The default
546 value is 0 (disabled).
547
548 @item original
549 (original) Set MPEG audio original flag when set to 1. The default
550 value is 0 (disabled).
551
552 @end table
553
554 @section libvo-aacenc
555
556 VisualOn AAC encoder.
557
558 Requires the presence of the libvo-aacenc headers and library during
559 configuration. You need to explicitly configure the build with
560 @code{--enable-libvo-aacenc --enable-version3}.
561
562 @subsection Options
563
564 The VisualOn AAC encoder only support encoding AAC-LC and up to 2
565 channels. It is also CBR-only. It is considered to be worse than the
566 native experimental FFmpeg AAC encoder.
567
568 @table @option
569
570 @item b
571 Bitrate.
572
573 @end table
574
575 @section libvo-amrwbenc
576
577 VisualOn Adaptive Multi-Rate Wideband encoder.
578
579 Requires the presence of the libvo-amrwbenc headers and library during
580 configuration. You need to explicitly configure the build with
581 @code{--enable-libvo-amrwbenc --enable-version3}.
582
583 This is a mono-only encoder. Officially it only supports 16000Hz sample
584 rate, but you can override it by setting @option{strict} to
585 @samp{unofficial} or lower.
586
587 @subsection Options
588
589 @table @option
590
591 @item b
592 Set bitrate in bits/s. Only the following bitrates are supported, otherwise
593 libavcodec will round to the nearest valid bitrate.
594
595 @table @samp
596 @item 6600
597 @item 8850
598 @item 12650
599 @item 14250
600 @item 15850
601 @item 18250
602 @item 19850
603 @item 23050
604 @item 23850
605 @end table
606
607 @item dtx
608 Allow discontinuous transmission (generate comfort noise) when set to 1. The
609 default value is 0 (disabled).
610
611 @end table
612
613 @section libopus
614
615 libopus Opus Interactive Audio Codec encoder wrapper.
616
617 Requires the presence of the libopus headers and library during
618 configuration. You need to explicitly configure the build with
619 @code{--enable-libopus}.
620
621 @subsection Option Mapping
622
623 Most libopus options are modeled after the @command{opusenc} utility from
624 opus-tools. The following is an option mapping chart describing options
625 supported by the libopus wrapper, and their @command{opusenc}-equivalent
626 in parentheses.
627
628 @table @option
629
630 @item b (@emph{bitrate})
631 Set the bit rate in bits/s.  FFmpeg's @option{b} option is
632 expressed in bits/s, while @command{opusenc}'s @option{bitrate} in
633 kilobits/s.
634
635 @item vbr (@emph{vbr}, @emph{hard-cbr}, and @emph{cvbr})
636 Set VBR mode. The FFmpeg @option{vbr} option has the following
637 valid arguments, with the their @command{opusenc} equivalent options
638 in parentheses:
639
640 @table @samp
641 @item off (@emph{hard-cbr})
642 Use constant bit rate encoding.
643
644 @item on (@emph{vbr})
645 Use variable bit rate encoding (the default).
646
647 @item constrained (@emph{cvbr})
648 Use constrained variable bit rate encoding.
649 @end table
650
651 @item compression_level (@emph{comp})
652 Set encoding algorithm complexity. Valid options are integers in
653 the 0-10 range. 0 gives the fastest encodes but lower quality, while 10
654 gives the highest quality but slowest encoding. The default is 10.
655
656 @item frame_duration (@emph{framesize})
657 Set maximum frame size, or duration of a frame in milliseconds. The
658 argument must be exactly the following: 2.5, 5, 10, 20, 40, 60. Smaller
659 frame sizes achieve lower latency but less quality at a given bitrate.
660 Sizes greater than 20ms are only interesting at fairly low bitrates.
661 The default of FFmpeg is 10ms, but is 20ms in @command{opusenc}.
662
663 @item packet_loss (@emph{expect-loss})
664 Set expected packet loss percentage. The default is 0.
665
666 @item application (N.A.)
667 Set intended application type. Valid options are listed below:
668
669 @table @samp
670 @item voip
671 Favor improved speech intelligibility.
672 @item audio
673 Favor faithfulness to the input (the default).
674 @item lowdelay
675 Restrict to only the lowest delay modes.
676 @end table
677
678 @item cutoff (N.A.)
679 Set cutoff bandwidth in Hz. The argument must be exactly one of the
680 following: 4000, 6000, 8000, 12000, or 20000, corresponding to
681 narrowband, mediumband, wideband, super wideband, and fullband
682 respectively. The default is 0 (cutoff disabled).
683
684 @end table
685
686 @section libwavpack
687
688 A wrapper providing WavPack encoding through libwavpack.
689
690 Only lossless mode using 32-bit integer samples is supported currently.
691 The @option{compression_level} option can be used to control speed vs.
692 compression tradeoff, with the values mapped to libwavpack as follows:
693
694 @table @option
695
696 @item 0
697 Fast mode - corresponding to the wavpack @option{-f} option.
698
699 @item 1
700 Normal (default) settings.
701
702 @item 2
703 High quality - corresponding to the wavpack @option{-h} option.
704
705 @item 3
706 Very high quality - corresponding to the wavpack @option{-hh} option.
707
708 @item 4-8
709 Same as 3, but with extra processing enabled - corresponding to the wavpack
710 @option{-x} option. I.e. 4 is the same as @option{-x2} and 8 is the same as
711 @option{-x6}.
712
713 @end table
714
715 @c man end AUDIO ENCODERS
716
717 @chapter Video Encoders
718 @c man begin VIDEO ENCODERS
719
720 A description of some of the currently available video encoders
721 follows.
722
723 @section libtheora
724
725 Theora format supported through libtheora.
726
727 Requires the presence of the libtheora headers and library during
728 configuration. You need to explicitly configure the build with
729 @code{--enable-libtheora}.
730
731 @subsection Options
732
733 The following global options are mapped to internal libtheora options
734 which affect the quality and the bitrate of the encoded stream.
735
736 @table @option
737 @item b
738 Set the video bitrate, only works if the @code{qscale} flag in
739 @option{flags} is not enabled.
740
741 @item flags
742 Used to enable constant quality mode encoding through the
743 @option{qscale} flag, and to enable the @code{pass1} and @code{pass2}
744 modes.
745
746 @item g
747 Set the GOP size.
748
749 @item global_quality
750 Set the global quality in lambda units, only works if the
751 @code{qscale} flag in @option{flags} is enabled. The value is clipped
752 in the [0 - 10*@code{FF_QP2LAMBDA}] range, and then multiplied for 6.3
753 to get a value in the native libtheora range [0-63]. A higher value
754 corresponds to a higher quality.
755
756 For example, to set maximum constant quality encoding with
757 @command{ffmpeg}:
758 @example
759 ffmpeg -i INPUT -flags:v qscale -global_quality:v "10*QP2LAMBDA" -codec:v libtheora OUTPUT.ogg
760 @end example
761 @end table
762
763 @section libvpx
764
765 VP8 format supported through libvpx.
766
767 Requires the presence of the libvpx headers and library during configuration.
768 You need to explicitly configure the build with @code{--enable-libvpx}.
769
770 @subsection Options
771
772 Mapping from FFmpeg to libvpx options with conversion notes in parentheses.
773
774 @table @option
775
776 @item threads
777 g_threads
778
779 @item profile
780 g_profile
781
782 @item vb
783 rc_target_bitrate
784
785 @item g
786 kf_max_dist
787
788 @item keyint_min
789 kf_min_dist
790
791 @item qmin
792 rc_min_quantizer
793
794 @item qmax
795 rc_max_quantizer
796
797 @item bufsize, vb
798 rc_buf_sz
799 @code{(bufsize * 1000 / vb)}
800
801 rc_buf_optimal_sz
802 @code{(bufsize * 1000 / vb * 5 / 6)}
803
804 @item rc_init_occupancy, vb
805 rc_buf_initial_sz
806 @code{(rc_init_occupancy * 1000 / vb)}
807
808 @item rc_buffer_aggressivity
809 rc_undershoot_pct
810
811 @item skip_threshold
812 rc_dropframe_thresh
813
814 @item qcomp
815 rc_2pass_vbr_bias_pct
816
817 @item maxrate, vb
818 rc_2pass_vbr_maxsection_pct
819 @code{(maxrate * 100 / vb)}
820
821 @item minrate, vb
822 rc_2pass_vbr_minsection_pct
823 @code{(minrate * 100 / vb)}
824
825 @item minrate, maxrate, vb
826 @code{VPX_CBR}
827 @code{(minrate == maxrate == vb)}
828
829 @item crf
830 @code{VPX_CQ}, @code{VP8E_SET_CQ_LEVEL}
831
832 @item quality
833 @table @option
834 @item @var{best}
835 @code{VPX_DL_BEST_QUALITY}
836 @item @var{good}
837 @code{VPX_DL_GOOD_QUALITY}
838 @item @var{realtime}
839 @code{VPX_DL_REALTIME}
840 @end table
841
842 @item speed
843 @code{VP8E_SET_CPUUSED}
844
845 @item nr
846 @code{VP8E_SET_NOISE_SENSITIVITY}
847
848 @item mb_threshold
849 @code{VP8E_SET_STATIC_THRESHOLD}
850
851 @item slices
852 @code{VP8E_SET_TOKEN_PARTITIONS}
853
854 @item max-intra-rate
855 @code{VP8E_SET_MAX_INTRA_BITRATE_PCT}
856
857 @item force_key_frames
858 @code{VPX_EFLAG_FORCE_KF}
859
860 @item Alternate reference frame related
861 @table @option
862 @item vp8flags altref
863 @code{VP8E_SET_ENABLEAUTOALTREF}
864 @item @var{arnr_max_frames}
865 @code{VP8E_SET_ARNR_MAXFRAMES}
866 @item @var{arnr_type}
867 @code{VP8E_SET_ARNR_TYPE}
868 @item @var{arnr_strength}
869 @code{VP8E_SET_ARNR_STRENGTH}
870 @item @var{rc_lookahead}
871 g_lag_in_frames
872 @end table
873
874 @item vp8flags error_resilient
875 g_error_resilient
876
877 @end table
878
879 For more information about libvpx see:
880 @url{http://www.webmproject.org/}
881
882 @section libx264
883
884 x264 H.264/MPEG-4 AVC encoder wrapper.
885
886 This encoder requires the presence of the libx264 headers and library
887 during configuration. You need to explicitly configure the build with
888 @code{--enable-libx264}.
889
890 libx264 supports an impressive number of features, including 8x8 and
891 4x4 adaptive spatial transform, adaptive B-frame placement, CAVLC/CABAC
892 entropy coding, interlacing (MBAFF), lossless mode, psy optimizations
893 for detail retention (adaptive quantization, psy-RD, psy-trellis).
894
895 Many libx264 encoder options are mapped to FFmpeg global codec
896 options, while unique encoder options are provided through private
897 options. Additionally the @option{x264opts} and @option{x264-params}
898 private options allows to pass a list of key=value tuples as accepted
899 by the libx264 @code{x264_param_parse} function.
900
901 The x264 project website is at
902 @url{http://www.videolan.org/developers/x264.html}.
903
904 @subsection Options
905
906 The following options are supported by the libx264 wrapper. The
907 @command{x264}-equivalent options or values are listed in parentheses
908 for easy migration.
909
910 To reduce the duplication of documentation, only the private options
911 and some others requiring special attention are documented here. For
912 the documentation of the undocumented generic options, see
913 @ref{codec-options,,the Codec Options chapter}.
914
915 To get a more accurate and extensive documentation of the libx264
916 options, invoke the command @command{x264 --full-help} or consult
917 the libx264 documentation.
918
919 @table @option
920 @item b (@emph{bitrate})
921 Set bitrate in bits/s. Note that FFmpeg's @option{b} option is
922 expressed in bits/s, while @command{x264}'s @option{bitrate} is in
923 kilobits/s.
924
925 @item bf (@emph{bframes})
926
927 @item g (@emph{keyint})
928
929 @item qmax (@emph{qpmax})
930
931 @item qmin (@emph{qpmin})
932
933 @item qdiff (@emph{qpstep})
934
935 @item qblur (@emph{qblur})
936
937 @item qcomp (@emph{qcomp})
938
939 @item refs (@emph{ref})
940
941 @item sc_threshold (@emph{scenecut})
942
943 @item trellis (@emph{trellis})
944
945 @item nr  (@emph{nr})
946
947 @item me_range (@emph{merange})
948
949 @item me_method (@emph{me})
950 Set motion estimation method. Possible values in the decreasing order
951 of speed:
952
953 @table @samp
954 @item dia (@emph{dia})
955 @item epzs (@emph{dia})
956 Diamond search with radius 1 (fastest). @samp{epzs} is an alias for
957 @samp{dia}.
958 @item hex (@emph{hex})
959 Hexagonal search with radius 2.
960 @item umh (@emph{umh})
961 Uneven multi-hexagon search.
962 @item esa (@emph{esa})
963 Exhaustive search.
964 @item tesa (@emph{tesa})
965 Hadamard exhaustive search (slowest).
966 @end table
967
968 @item subq (@emph{subme})
969
970 @item b_strategy (@emph{b-adapt})
971
972 @item keyint_min (@emph{min-keyint})
973
974 @item coder
975 Set entropy encoder. Possible values:
976
977 @table @samp
978 @item ac
979 Enable CABAC.
980
981 @item vlc
982 Enable CAVLC and disable CABAC. It generates the same effect as
983 @command{x264}'s @option{--no-cabac} option.
984 @end table
985
986 @item cmp
987 Set full pixel motion estimation comparation algorithm. Possible values:
988
989 @table @samp
990 @item chroma
991 Enable chroma in motion estimation.
992
993 @item sad
994 Ignore chroma in motion estimation. It generates the same effect as
995 @command{x264}'s @option{--no-chroma-me} option.
996 @end table
997
998 @item threads (@emph{threads})
999
1000 @item thread_type
1001 Set multithreading technique. Possible values:
1002
1003 @table @samp
1004 @item slice
1005 Slice-based multithreading. It generates the same effect as
1006 @command{x264}'s @option{--sliced-threads} option.
1007 @item frame
1008 Frame-based multithreading.
1009 @end table
1010
1011 @item flags
1012 Set encoding flags. It can be used to disable closed GOP and enable
1013 open GOP by setting it to @code{-cgop}. The result is similar to
1014 the behavior of @command{x264}'s @option{--open-gop} option.
1015
1016 @item rc_init_occupancy (@emph{vbv-init})
1017
1018 @item preset (@emph{preset})
1019 Set the encoding preset.
1020
1021 @item tune (@emph{tune})
1022 Set tuning of the encoding params.
1023
1024 @item profile (@emph{profile})
1025 Set profile restrictions.
1026
1027 @item fastfirstpass
1028 Enable fast settings when encoding first pass, when set to 1. When set
1029 to 0, it has the same effect of @command{x264}'s
1030 @option{--slow-firstpass} option.
1031
1032 @item crf (@emph{crf})
1033 Set the quality for constant quality mode.
1034
1035 @item crf_max (@emph{crf-max})
1036 In CRF mode, prevents VBV from lowering quality beyond this point.
1037
1038 @item qp (@emph{qp})
1039 Set constant quantization rate control method parameter.
1040
1041 @item aq-mode (@emph{aq-mode})
1042 Set AQ method. Possible values:
1043
1044 @table @samp
1045 @item none (@emph{0})
1046 Disabled.
1047
1048 @item variance (@emph{1})
1049 Variance AQ (complexity mask).
1050
1051 @item autovariance (@emph{2})
1052 Auto-variance AQ (experimental).
1053 @end table
1054
1055 @item aq-strength (@emph{aq-strength})
1056 Set AQ strength, reduce blocking and blurring in flat and textured areas.
1057
1058 @item psy
1059 Use psychovisual optimizations when set to 1. When set to 0, it has the
1060 same effect as @command{x264}'s @option{--no-psy} option.
1061
1062 @item psy-rd  (@emph{psy-rd})
1063 Set strength of psychovisual optimization, in
1064 @var{psy-rd}:@var{psy-trellis} format.
1065
1066 @item rc-lookahead (@emph{rc-lookahead})
1067 Set number of frames to look ahead for frametype and ratecontrol.
1068
1069 @item weightb
1070 Enable weighted prediction for B-frames when set to 1. When set to 0,
1071 it has the same effect as @command{x264}'s @option{--no-weightb} option.
1072
1073 @item weightp (@emph{weightp})
1074 Set weighted prediction method for P-frames. Possible values:
1075
1076 @table @samp
1077 @item none (@emph{0})
1078 Disabled
1079 @item simple (@emph{1})
1080 Enable only weighted refs
1081 @item smart (@emph{2})
1082 Enable both weighted refs and duplicates
1083 @end table
1084
1085 @item ssim (@emph{ssim})
1086 Enable calculation and printing SSIM stats after the encoding.
1087
1088 @item intra-refresh (@emph{intra-refresh})
1089 Enable the use of Periodic Intra Refresh instead of IDR frames when set
1090 to 1.
1091
1092 @item bluray-compat (@emph{bluray-compat})
1093 Configure the encoder to be compatible with the bluray standard.
1094 It is a shorthand for setting "bluray-compat=1 force-cfr=1".
1095
1096 @item b-bias (@emph{b-bias})
1097 Set the influence on how often B-frames are used.
1098
1099 @item b-pyramid (@emph{b-pyramid})
1100 Set method for keeping of some B-frames as references. Possible values:
1101
1102 @table @samp
1103 @item none (@emph{none})
1104 Disabled.
1105 @item strict (@emph{strict})
1106 Strictly hierarchical pyramid.
1107 @item normal (@emph{normal})
1108 Non-strict (not Blu-ray compatible).
1109 @end table
1110
1111 @item mixed-refs
1112 Enable the use of one reference per partition, as opposed to one
1113 reference per macroblock when set to 1. When set to 0, it has the
1114 same effect as @command{x264}'s @option{--no-mixed-refs} option.
1115
1116 @item 8x8dct
1117 Enable adaptive spatial transform (high profile 8x8 transform)
1118 when set to 1. When set to 0, it has the same effect as
1119 @command{x264}'s @option{--no-8x8dct} option.
1120
1121 @item fast-pskip
1122 Enable early SKIP detection on P-frames when set to 1. When set
1123 to 0, it has the same effect as @command{x264}'s
1124 @option{--no-fast-pskip} option.
1125
1126 @item aud (@emph{aud})
1127 Enable use of access unit delimiters when set to 1.
1128
1129 @item mbtree
1130 Enable use macroblock tree ratecontrol when set to 1. When set
1131 to 0, it has the same effect as @command{x264}'s
1132 @option{--no-mbtree} option.
1133
1134 @item deblock (@emph{deblock})
1135 Set loop filter parameters, in @var{alpha}:@var{beta} form.
1136
1137 @item cplxblur (@emph{cplxblur})
1138 Set fluctuations reduction in QP (before curve compression).
1139
1140 @item partitions (@emph{partitions})
1141 Set partitions to consider as a comma-separated list of. Possible
1142 values in the list:
1143
1144 @table @samp
1145 @item p8x8
1146 8x8 P-frame partition.
1147 @item p4x4
1148 4x4 P-frame partition.
1149 @item b8x8
1150 4x4 B-frame partition.
1151 @item i8x8
1152 8x8 I-frame partition.
1153 @item i4x4
1154 4x4 I-frame partition.
1155 (Enabling @samp{p4x4} requires @samp{p8x8} to be enabled. Enabling
1156 @samp{i8x8} requires adaptive spatial transform (@option{8x8dct}
1157 option) to be enabled.)
1158 @item none (@emph{none})
1159 Do not consider any partitions.
1160 @item all (@emph{all})
1161 Consider every partition.
1162 @end table
1163
1164 @item direct-pred (@emph{direct})
1165 Set direct MV prediction mode. Possible values:
1166
1167 @table @samp
1168 @item none (@emph{none})
1169 Disable MV prediction.
1170 @item spatial (@emph{spatial})
1171 Enable spatial predicting.
1172 @item temporal (@emph{temporal})
1173 Enable temporal predicting.
1174 @item auto (@emph{auto})
1175 Automatically decided.
1176 @end table
1177
1178 @item slice-max-size (@emph{slice-max-size})
1179 Set the limit of the size of each slice in bytes. If not specified
1180 but RTP payload size (@option{ps}) is specified, that is used.
1181
1182 @item stats (@emph{stats})
1183 Set the file name for multi-pass stats.
1184
1185 @item nal-hrd (@emph{nal-hrd})
1186 Set signal HRD information (requires @option{vbv-bufsize} to be set).
1187 Possible values:
1188
1189 @table @samp
1190 @item none (@emph{none})
1191 Disable HRD information signaling.
1192 @item vbr (@emph{vbr})
1193 Variable bit rate.
1194 @item cbr (@emph{cbr})
1195 Constant bit rate (not allowed in MP4 container).
1196 @end table
1197
1198 @item x264opts (N.A.)
1199 Set any x264 option, see @command{x264 --fullhelp} for a list.
1200
1201 Argument is a list of @var{key}=@var{value} couples separated by
1202 ":". In @var{filter} and @var{psy-rd} options that use ":" as a separator
1203 themselves, use "," instead. They accept it as well since long ago but this
1204 is kept undocumented for some reason.
1205
1206 For example to specify libx264 encoding options with @command{ffmpeg}:
1207 @example
1208 ffmpeg -i foo.mpg -vcodec libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
1209 @end example
1210
1211 @item x264-params (N.A.)
1212 Override the x264 configuration using a :-separated list of key=value
1213 parameters.
1214
1215 This option is functionally the same as the @option{x264opts}, but is
1216 duplicated for compability with the Libav fork.
1217
1218 For example to specify libx264 encoding options with @command{ffmpeg}:
1219 @example
1220 ffmpeg -i INPUT -c:v libx264 -x264-params level=30:bframes=0:weightp=0:\
1221 cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:\
1222 no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 OUTPUT
1223 @end example
1224 @end table
1225
1226 Encoding ffpresets for common usages are provided so they can be used with the
1227 general presets system (e.g. passing the @option{pre} option).
1228
1229 @section libxvid
1230
1231 Xvid MPEG-4 Part 2 encoder wrapper.
1232
1233 This encoder requires the presence of the libxvidcore headers and library
1234 during configuration. You need to explicitly configure the build with
1235 @code{--enable-libxvid --enable-gpl}.
1236
1237 The native @code{mpeg4} encoder supports the MPEG-4 Part 2 format, so
1238 users can encode to this format without this library.
1239
1240 @subsection Options
1241
1242 The following options are supported by the libxvid wrapper. Some of
1243 the following options are listed but are not documented, and
1244 correspond to shared codec options. See @ref{codec-options,,the Codec
1245 Options chapter} for their documentation. The other shared options
1246 which are not listed have no effect for the libxvid encoder.
1247
1248 @table @option
1249 @item b
1250
1251 @item g
1252
1253 @item qmin
1254
1255 @item qmax
1256
1257 @item mpeg_quant
1258
1259 @item threads
1260
1261 @item bf
1262
1263 @item b_qfactor
1264
1265 @item b_qoffset
1266
1267 @item flags
1268 Set specific encoding flags. Possible values:
1269
1270 @table @samp
1271
1272 @item mv4
1273 Use four motion vector by macroblock.
1274
1275 @item aic
1276 Enable high quality AC prediction.
1277
1278 @item gray
1279 Only encode grayscale.
1280
1281 @item gmc
1282 Enable the use of global motion compensation (GMC).
1283
1284 @item qpel
1285 Enable quarter-pixel motion compensation.
1286
1287 @item cgop
1288 Enable closed GOP.
1289
1290 @item global_header
1291 Place global headers in extradata instead of every keyframe.
1292
1293 @end table
1294
1295 @item trellis
1296
1297 @item me_method
1298 Set motion estimation method. Possible values in decreasing order of
1299 speed and increasing order of quality:
1300
1301 @table @samp
1302 @item zero
1303 Use no motion estimation (default).
1304
1305 @item phods
1306 @item x1
1307 @item log
1308 Enable advanced diamond zonal search for 16x16 blocks and half-pixel
1309 refinement for 16x16 blocks. @samp{x1} and @samp{log} are aliases for
1310 @samp{phods}.
1311
1312 @item epzs
1313 Enable all of the things described above, plus advanced diamond zonal
1314 search for 8x8 blocks, half-pixel refinement for 8x8 blocks, and motion
1315 estimation on chroma planes.
1316
1317 @item full
1318 Enable all of the things described above, plus extended 16x16 and 8x8
1319 blocks search.
1320 @end table
1321
1322 @item mbd
1323 Set macroblock decision algorithm. Possible values in the increasing
1324 order of quality:
1325
1326 @table @samp
1327 @item simple
1328 Use macroblock comparing function algorithm (default).
1329
1330 @item bits
1331 Enable rate distortion-based half pixel and quarter pixel refinement for
1332 16x16 blocks.
1333
1334 @item rd
1335 Enable all of the things described above, plus rate distortion-based
1336 half pixel and quarter pixel refinement for 8x8 blocks, and rate
1337 distortion-based search using square pattern.
1338 @end table
1339
1340 @item lumi_aq
1341 Enable lumi masking adaptive quantization when set to 1. Default is 0
1342 (disabled).
1343
1344 @item variance_aq
1345 Enable variance adaptive quantization when set to 1. Default is 0
1346 (disabled).
1347
1348 When combined with @option{lumi_aq}, the resulting quality will not
1349 be better than any of the two specified individually. In other
1350 words, the resulting quality will be the worse one of the two
1351 effects.
1352
1353 @item ssim
1354 Set structural similarity (SSIM) displaying method. Possible values:
1355
1356 @table @samp
1357 @item off
1358 Disable displaying of SSIM information.
1359
1360 @item avg
1361 Output average SSIM at the end of encoding to stdout. The format of
1362 showing the average SSIM is:
1363
1364 @example
1365 Average SSIM: %f
1366 @end example
1367
1368 For users who are not familiar with C, %f means a float number, or
1369 a decimal (e.g. 0.939232).
1370
1371 @item frame
1372 Output both per-frame SSIM data during encoding and average SSIM at
1373 the end of encoding to stdout. The format of per-frame information
1374 is:
1375
1376 @example
1377        SSIM: avg: %1.3f min: %1.3f max: %1.3f
1378 @end example
1379
1380 For users who are not familiar with C, %1.3f means a float number
1381 rounded to 3 digits after the dot (e.g. 0.932).
1382
1383 @end table
1384
1385 @item ssim_acc
1386 Set SSIM accuracy. Valid options are integers within the range of
1387 0-4, while 0 gives the most accurate result and 4 computes the
1388 fastest.
1389
1390 @end table
1391
1392 @section png
1393
1394 PNG image encoder.
1395
1396 @subsection Private options
1397
1398 @table @option
1399 @item dpi @var{integer}
1400 Set physical density of pixels, in dots per inch, unset by default
1401 @item dpm @var{integer}
1402 Set physical density of pixels, in dots per meter, unset by default
1403 @end table
1404
1405 @section ProRes
1406
1407 Apple ProRes encoder.
1408
1409 FFmpeg contains 2 ProRes encoders, the prores-aw and prores-ks encoder.
1410 The used encoder can be choosen with the @code{-vcodec} option.
1411
1412 @subsection Private Options for prores-ks
1413
1414 @table @option
1415 @item profile @var{integer}
1416 Select the ProRes profile to encode
1417 @table @samp
1418 @item proxy
1419 @item lt
1420 @item standard
1421 @item hq
1422 @item 4444
1423 @end table
1424
1425 @item quant_mat @var{integer}
1426 Select quantization matrix.
1427 @table @samp
1428 @item auto
1429 @item default
1430 @item proxy
1431 @item lt
1432 @item standard
1433 @item hq
1434 @end table
1435 If set to @var{auto}, the matrix matching the profile will be picked.
1436 If not set, the matrix providing the highest quality, @var{default}, will be
1437 picked.
1438
1439 @item bits_per_mb @var{integer}
1440 How many bits to allot for coding one macroblock. Different profiles use
1441 between 200 and 2400 bits per macroblock, the maximum is 8000.
1442
1443 @item mbs_per_slice @var{integer}
1444 Number of macroblocks in each slice (1-8); the default value (8)
1445 should be good in almost all situations.
1446
1447 @item vendor @var{string}
1448 Override the 4-byte vendor ID.
1449 A custom vendor ID like @var{apl0} would claim the stream was produced by
1450 the Apple encoder.
1451
1452 @item alpha_bits @var{integer}
1453 Specify number of bits for alpha component.
1454 Possible values are @var{0}, @var{8} and @var{16}.
1455 Use @var{0} to disable alpha plane coding.
1456
1457 @end table
1458
1459 @subsection Speed considerations
1460
1461 In the default mode of operation the encoder has to honor frame constraints
1462 (i.e. not produc frames with size bigger than requested) while still making
1463 output picture as good as possible.
1464 A frame containing a lot of small details is harder to compress and the encoder
1465 would spend more time searching for appropriate quantizers for each slice.
1466
1467 Setting a higher @option{bits_per_mb} limit will improve the speed.
1468
1469 For the fastest encoding speed set the @option{qscale} parameter (4 is the
1470 recommended value) and do not set a size constraint.
1471
1472 @c man end VIDEO ENCODERS