@chapter Encoders @c man begin ENCODERS Encoders are configured elements in Libav which allow the encoding of multimedia streams. When you configure your Libav build, all the supported native encoders are enabled by default. Encoders requiring an external library must be enabled manually via the corresponding @code{--enable-lib} option. You can list all available encoders using the configure option @code{--list-encoders}. You can disable all the encoders with the configure option @code{--disable-encoders} and selectively enable / disable single encoders with the options @code{--enable-encoder=@var{ENCODER}} / @code{--disable-encoder=@var{ENCODER}}. The option @code{-encoders} of the av* tools will display the list of enabled encoders. @c man end ENCODERS @chapter Audio Encoders @c man begin AUDIO ENCODERS A description of some of the currently available audio encoders follows. @section ac3 and ac3_fixed AC-3 audio encoders. These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366, as well as the undocumented RealAudio 3 (a.k.a. dnet). The @var{ac3} encoder uses floating-point math, while the @var{ac3_fixed} encoder only uses fixed-point integer math. This does not mean that one is always faster, just that one or the other may be better suited to a particular system. The floating-point encoder will generally produce better quality audio for a given bitrate. The @var{ac3_fixed} encoder is not the default codec for any of the output formats, so it must be specified explicitly using the option @code{-acodec ac3_fixed} in order to use it. @subsection AC-3 Metadata The AC-3 metadata options are used to set parameters that describe the audio, but in most cases do not affect the audio encoding itself. Some of the options do directly affect or influence the decoding and playback of the resulting bitstream, while others are just for informational purposes. A few of the options will add bits to the output stream that could otherwise be used for audio data, and will thus affect the quality of the output. Those will be indicated accordingly with a note in the option list below. These parameters are described in detail in several publicly-available documents. @itemize @item @uref{http://www.atsc.org/cms/standards/a_52-2010.pdf,A/52:2010 - Digital Audio Compression (AC-3) (E-AC-3) Standard} @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} @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/18_Metadata.Guide.pdf,Dolby Metadata Guide} @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/46_DDEncodingGuidelines.pdf,Dolby Digital Professional Encoding Guidelines} @end itemize @subsubsection Metadata Control Options @table @option @item -per_frame_metadata @var{boolean} Allow Per-Frame Metadata. Specifies if the encoder should check for changing metadata for each frame. @table @option @item 0 The metadata values set at initialization will be used for every frame in the stream. (default) @item 1 Metadata values can be changed before encoding each frame. @end table @end table @subsubsection Downmix Levels @table @option @item -center_mixlev @var{level} Center Mix Level. The amount of gain the decoder should apply to the center channel when downmixing to stereo. This field will only be written to the bitstream if a center channel is present. The value is specified as a scale factor. There are 3 valid values: @table @option @item 0.707 Apply -3dB gain @item 0.595 Apply -4.5dB gain (default) @item 0.500 Apply -6dB gain @end table @item -surround_mixlev @var{level} Surround Mix Level. The amount of gain the decoder should apply to the surround channel(s) when downmixing to stereo. This field will only be written to the bitstream if one or more surround channels are present. The value is specified as a scale factor. There are 3 valid values: @table @option @item 0.707 Apply -3dB gain @item 0.500 Apply -6dB gain (default) @item 0.000 Silence Surround Channel(s) @end table @end table @subsubsection Audio Production Information Audio Production Information is optional information describing the mixing environment. Either none or both of the fields are written to the bitstream. @table @option @item -mixing_level @var{number} Mixing Level. Specifies peak sound pressure level (SPL) in the production environment when the mix was mastered. Valid values are 80 to 111, or -1 for unknown or not indicated. The default value is -1, but that value cannot be used if the Audio Production Information is written to the bitstream. Therefore, if the @code{room_type} option is not the default value, the @code{mixing_level} option must not be -1. @item -room_type @var{type} Room Type. Describes the equalization used during the final mixing session at the studio or on the dubbing stage. A large room is a dubbing stage with the industry standard X-curve equalization; a small room has flat equalization. This field will not be written to the bitstream if both the @code{mixing_level} option and the @code{room_type} option have the default values. @table @option @item 0 @itemx notindicated Not Indicated (default) @item 1 @itemx large Large Room @item 2 @itemx small Small Room @end table @end table @subsubsection Other Metadata Options @table @option @item -copyright @var{boolean} Copyright Indicator. Specifies whether a copyright exists for this audio. @table @option @item 0 @itemx off No Copyright Exists (default) @item 1 @itemx on Copyright Exists @end table @item -dialnorm @var{value} Dialogue Normalization. Indicates how far the average dialogue level of the program is below digital 100% full scale (0 dBFS). This parameter determines a level shift during audio reproduction that sets the average volume of the dialogue to a preset level. The goal is to match volume level between program sources. A value of -31dB will result in no volume level change, relative to the source volume, during audio reproduction. Valid values are whole numbers in the range -31 to -1, with -31 being the default. @item -dsur_mode @var{mode} Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround (Pro Logic). This field will only be written to the bitstream if the audio stream is stereo. Using this option does @b{NOT} mean the encoder will actually apply Dolby Surround processing. @table @option @item 0 @itemx notindicated Not Indicated (default) @item 1 @itemx off Not Dolby Surround Encoded @item 2 @itemx on Dolby Surround Encoded @end table @item -original @var{boolean} Original Bit Stream Indicator. Specifies whether this audio is from the original source and not a copy. @table @option @item 0 @itemx off Not Original Source @item 1 @itemx on Original Source (default) @end table @end table @subsection Extended Bitstream Information The extended bitstream options are part of the Alternate Bit Stream Syntax as specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts. If any one parameter in a group is specified, all values in that group will be written to the bitstream. Default values are used for those that are written but have not been specified. If the mixing levels are written, the decoder will use these values instead of the ones specified in the @code{center_mixlev} and @code{surround_mixlev} options if it supports the Alternate Bit Stream Syntax. @subsubsection Extended Bitstream Information - Part 1 @table @option @item -dmix_mode @var{mode} Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt (Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode. @table @option @item 0 @itemx notindicated Not Indicated (default) @item 1 @itemx ltrt Lt/Rt Downmix Preferred @item 2 @itemx loro Lo/Ro Downmix Preferred @end table @item -ltrt_cmixlev @var{level} Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the center channel when downmixing to stereo in Lt/Rt mode. @table @option @item 1.414 Apply +3dB gain @item 1.189 Apply +1.5dB gain @item 1.000 Apply 0dB gain @item 0.841 Apply -1.5dB gain @item 0.707 Apply -3.0dB gain @item 0.595 Apply -4.5dB gain (default) @item 0.500 Apply -6.0dB gain @item 0.000 Silence Center Channel @end table @item -ltrt_surmixlev @var{level} Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the surround channel(s) when downmixing to stereo in Lt/Rt mode. @table @option @item 0.841 Apply -1.5dB gain @item 0.707 Apply -3.0dB gain @item 0.595 Apply -4.5dB gain @item 0.500 Apply -6.0dB gain (default) @item 0.000 Silence Surround Channel(s) @end table @item -loro_cmixlev @var{level} Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the center channel when downmixing to stereo in Lo/Ro mode. @table @option @item 1.414 Apply +3dB gain @item 1.189 Apply +1.5dB gain @item 1.000 Apply 0dB gain @item 0.841 Apply -1.5dB gain @item 0.707 Apply -3.0dB gain @item 0.595 Apply -4.5dB gain (default) @item 0.500 Apply -6.0dB gain @item 0.000 Silence Center Channel @end table @item -loro_surmixlev @var{level} Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the surround channel(s) when downmixing to stereo in Lo/Ro mode. @table @option @item 0.841 Apply -1.5dB gain @item 0.707 Apply -3.0dB gain @item 0.595 Apply -4.5dB gain @item 0.500 Apply -6.0dB gain (default) @item 0.000 Silence Surround Channel(s) @end table @end table @subsubsection Extended Bitstream Information - Part 2 @table @option @item -dsurex_mode @var{mode} Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX (7.1 matrixed to 5.1). Using this option does @b{NOT} mean the encoder will actually apply Dolby Surround EX processing. @table @option @item 0 @itemx notindicated Not Indicated (default) @item 1 @itemx on Dolby Surround EX Off @item 2 @itemx off Dolby Surround EX On @end table @item -dheadphone_mode @var{mode} Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone encoding (multi-channel matrixed to 2.0 for use with headphones). Using this option does @b{NOT} mean the encoder will actually apply Dolby Headphone processing. @table @option @item 0 @itemx notindicated Not Indicated (default) @item 1 @itemx on Dolby Headphone Off @item 2 @itemx off Dolby Headphone On @end table @item -ad_conv_type @var{type} A/D Converter Type. Indicates whether the audio has passed through HDCD A/D conversion. @table @option @item 0 @itemx standard Standard A/D Converter (default) @item 1 @itemx hdcd HDCD A/D Converter @end table @end table @subsection Other AC-3 Encoding Options @table @option @item -stereo_rematrixing @var{boolean} Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This is an optional AC-3 feature that increases quality by selectively encoding the left/right channels as mid/side. This option is enabled by default, and it is highly recommended that it be left as enabled except for testing purposes. @end table @subheading Floating-Point-Only AC-3 Encoding Options These options are only valid for the floating-point encoder and do not exist for the fixed-point encoder due to the corresponding features not being implemented in fixed-point. @table @option @item -channel_coupling @var{boolean} Enables/Disables use of channel coupling, which is an optional AC-3 feature that increases quality by combining high frequency information from multiple channels into a single channel. The per-channel high frequency information is sent with less accuracy in both the frequency and time domains. This allows more bits to be used for lower frequencies while preserving enough information to reconstruct the high frequencies. This option is enabled by default for the floating-point encoder and should generally be left as enabled except for testing purposes or to increase encoding speed. @table @option @item -1 @itemx auto Selected by Encoder (default) @item 0 @itemx off Disable Channel Coupling @item 1 @itemx on Enable Channel Coupling @end table @item -cpl_start_band @var{number} Coupling Start Band. Sets the channel coupling start band, from 1 to 15. If a value higher than the bandwidth is used, it will be reduced to 1 less than the coupling end band. If @var{auto} is used, the start band will be determined by the encoder based on the bit rate, sample rate, and channel layout. This option has no effect if channel coupling is disabled. @table @option @item -1 @itemx auto Selected by Encoder (default) @end table @end table @section libwavpack A wrapper providing WavPack encoding through libwavpack. Only lossless mode using 32-bit integer samples is supported currently. The @option{compression_level} option can be used to control speed vs. compression tradeoff, with the values mapped to libwavpack as follows: @table @option @item 0 Fast mode - corresponding to the wavpack @option{-f} option. @item 1 Normal (default) settings. @item 2 High quality - corresponding to the wavpack @option{-h} option. @item 3 Very high quality - corresponding to the wavpack @option{-hh} option. @item 4-8 Same as 3, but with extra processing enabled - corresponding to the wavpack @option{-x} option. I.e. 4 is the same as @option{-x2} and 8 is the same as @option{-x6}. @end table @c man end AUDIO ENCODERS @chapter Video Encoders @c man begin VIDEO ENCODERS @section libwebp libwebp WebP Image encoder wrapper libwebp is Google's official encoder for WebP images. It can encode in either lossy or lossless mode. Lossy images are essentially a wrapper around a VP8 frame. Lossless images are a separate codec developed by Google. @subsection Pixel Format Currently, libwebp only supports YUV420 for lossy and RGB for lossless due to limitations of the format and libwebp. Alpha is supported for either mode. Because of API limitations, if RGB is passed in when encoding lossy or YUV is passed in for encoding lossless, the pixel format will automatically be converted using functions from libwebp. This is not ideal and is done only for convenience. @subsection Options @table @option @item -lossless @var{boolean} Enables/Disables use of lossless mode. Default is 0. @item -compression_level @var{integer} For lossy, this is a quality/speed tradeoff. Higher values give better quality for a given size at the cost of increased encoding time. For lossless, this is a size/speed tradeoff. Higher values give smaller size at the cost of increased encoding time. More specifically, it controls the number of extra algorithms and compression tools used, and varies the combination of these tools. This maps to the @var{method} option in libwebp. The valid range is 0 to 6. Default is 4. @item -qscale @var{float} For lossy encoding, this controls image quality, 0 to 100. For lossless encoding, this controls the effort and time spent at compressing more. The default value is 75. Note that for usage via libavcodec, this option is called @var{global_quality} and must be multiplied by @var{FF_QP2LAMBDA}. @item -preset @var{type} Configuration preset. This does some automatic settings based on the general type of the image. @table @option @item none Do not use a preset. @item default Use the encoder default. @item picture Digital picture, like portrait, inner shot @item photo Outdoor photograph, with natural lighting @item drawing Hand or line drawing, with high-contrast details @item icon Small-sized colorful images @item text Text-like @end table @item lumi_aq Enable lumi masking adaptive quantization when set to 1. Default is 0 (disabled). @item variance_aq Enable variance adaptive quantization when set to 1. Default is 0 (disabled). When combined with @option{lumi_aq}, the resulting quality will not be better than any of the two specified individually. In other words, the resulting quality will be the worse one of the two effects. @item ssim Set structural similarity (SSIM) displaying method. Possible values: @table @samp @item off Disable displaying of SSIM information. @item avg Output average SSIM at the end of encoding to stdout. The format of showing the average SSIM is: @example Average SSIM: %f @end example For users who are not familiar with C, %f means a float number, or a decimal (e.g. 0.939232). @item frame Output both per-frame SSIM data during encoding and average SSIM at the end of encoding to stdout. The format of per-frame information is: @example SSIM: avg: %1.3f min: %1.3f max: %1.3f @end example For users who are not familiar with C, %1.3f means a float number rounded to 3 digits after the dot (e.g. 0.932). @end table @item ssim_acc Set SSIM accuracy. Valid options are integers within the range of 0-4, while 0 gives the most accurate result and 4 computes the fastest. @end table @section libx264 x264 H.264/MPEG-4 AVC encoder wrapper x264 supports an impressive number of features, including 8x8 and 4x4 adaptive spatial transform, adaptive B-frame placement, CAVLC/CABAC entropy coding, interlacing (MBAFF), lossless mode, psy optimizations for detail retention (adaptive quantization, psy-RD, psy-trellis). The Libav wrapper provides a mapping for most of them using global options that match those of the encoders and provides private options for the unique encoder options. Additionally an expert override is provided to directly pass a list of key=value tuples as accepted by x264_param_parse. @subsection Option Mapping The following options are supported by the x264 wrapper, the x264-equivalent options follow the Libav ones. @multitable { } { } { } @item b @tab bitrate @tab Libav @code{b} option is expressed in bits/s, x264 @code{bitrate} in kilobits/s. @item bf @tab bframes @tab Maximum number of B-frames. @item g @tab keyint @tab Maximum GOP size. @item qmin @tab qpmin @tab Minimum quantizer scale. @item qmax @tab qpmax @tab Maximum quantizer scale. @item qdiff @tab qpstep @tab Maximum difference between quantizer scales. @item qblur @tab qblur @tab Quantizer curve blur @item qcomp @tab qcomp @tab Quantizer curve compression factor @item refs @tab ref @tab Number of reference frames each P-frame can use. The range is from @var{0-16}. @item sc_threshold @tab scenecut @tab Sets the threshold for the scene change detection. @item trellis @tab trellis @tab Performs Trellis quantization to increase efficiency. Enabled by default. @item nr @tab nr @tab Noise reduction. @item me_range @tab merange @tab Maximum range of the motion search in pixels. @item subq @tab subme @tab Sub-pixel motion estimation method. @item b_strategy @tab b-adapt @tab Adaptive B-frame placement decision algorithm. Use only on first-pass. @item keyint_min @tab min-keyint @tab Minimum GOP size. @item coder @tab cabac @tab Set coder to @code{ac} to use CABAC. @item cmp @tab chroma-me @tab Set to @code{chroma} to use chroma motion estimation. @item threads @tab threads @tab Number of encoding threads. @item thread_type @tab sliced_threads @tab Set to @code{slice} to use sliced threading instead of frame threading. @item flags -cgop @tab open-gop @tab Set @code{-cgop} to use recovery points to close GOPs. @item rc_init_occupancy @tab vbv-init @tab Initial buffer occupancy. @end multitable @subsection Private Options @table @option @item -preset @var{string} Set the encoding preset (cf. x264 --fullhelp). @item -tune @var{string} Tune the encoding params (cf. x264 --fullhelp). @item -profile @var{string} Set profile restrictions (cf. x264 --fullhelp). @item -fastfirstpass @var{integer} Use fast settings when encoding first pass. @item -crf @var{float} Select the quality for constant quality mode. @item -crf_max @var{float} In CRF mode, prevents VBV from lowering quality beyond this point. @item -qp @var{integer} Constant quantization parameter rate control method. @item -aq-mode @var{integer} AQ method Possible values: @table @samp @item none @item variance Variance AQ (complexity mask). @item autovariance Auto-variance AQ (experimental). @end table @item -aq-strength @var{float} AQ strength, reduces blocking and blurring in flat and textured areas. @item -psy @var{integer} Use psychovisual optimizations. @item -psy-rd @var{string} Strength of psychovisual optimization, in <psy-rd>:<psy-trellis> format. @item -rc-lookahead @var{integer} Number of frames to look ahead for frametype and ratecontrol. @item -weightb @var{integer} Weighted prediction for B-frames. @item -weightp @var{integer} Weighted prediction analysis method. Possible values: @table @samp @item none @item simple @item smart @end table @item -ssim @var{integer} Calculate and print SSIM stats. @item -intra-refresh @var{integer} Use Periodic Intra Refresh instead of IDR frames. @item -bluray-compat @var{integer} Configure the encoder to be compatible with the bluray standard. It is a shorthand for setting "bluray-compat=1 force-cfr=1". @item -b-bias @var{integer} Influences how often B-frames are used. @item -b-pyramid @var{integer} Keep some B-frames as references. Possible values: @table @samp @item none @item strict Strictly hierarchical pyramid. @item normal Non-strict (not Blu-ray compatible). @end table @item -mixed-refs @var{integer} One reference per partition, as opposed to one reference per macroblock. @item -8x8dct @var{integer} High profile 8x8 transform. @item -fast-pskip @var{integer} @item -aud @var{integer} Use access unit delimiters. @item -mbtree @var{integer} Use macroblock tree ratecontrol. @item -deblock @var{string} Loop filter parameters, in <alpha:beta> form. @item -cplxblur @var{float} Reduce fluctuations in QP (before curve compression). @item -partitions @var{string} A comma-separated list of partitions to consider, possible values: p8x8, p4x4, b8x8, i8x8, i4x4, none, all. @item -direct-pred @var{integer} Direct MV prediction mode Possible values: @table @samp @item none @item spatial @item temporal @item auto @end table @item -slice-max-size @var{integer} Limit the size of each slice in bytes. @item -stats @var{string} Filename for 2 pass stats. @item -nal-hrd @var{integer} Signal HRD information (requires vbv-bufsize; cbr not allowed in .mp4). Possible values: @table @samp @item none @item vbr @item cbr @end table @item -x264-params @var{string} Override the x264 configuration using a :-separated list of key=value parameters. @example -x264-params level=30:bframes=0:weightp=0:cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 @end example @end table Encoding avpresets for common usages are provided so they can be used with the general presets system (e.g. passing the @code{-pre} option). @section ProRes Apple ProRes encoder. @subsection Private Options @table @option @item profile @var{integer} Select the ProRes profile to encode @table @samp @item proxy @item lt @item standard @item hq @item 4444 @end table @item quant_mat @var{integer} Select quantization matrix. @table @samp @item auto @item default @item proxy @item lt @item standard @item hq @end table If set to @var{auto}, the matrix matching the profile will be picked. If not set, the matrix providing the highest quality, @var{default}, will be picked. @item bits_per_mb @var{integer} How many bits to allot for coding one macroblock. Different profiles use between 200 and 2400 bits per macroblock, the maximum is 8000. @item mbs_per_slice @var{integer} Number of macroblocks in each slice (1-8); the default value (8) should be good in almost all situations. @item vendor @var{string} Override the 4-byte vendor ID. A custom vendor ID like @var{apl0} would claim the stream was produced by the Apple encoder. @item alpha_bits @var{integer} Specify number of bits for alpha component. Possible values are @var{0}, @var{8} and @var{16}. Use @var{0} to disable alpha plane coding. @end table @subsection Speed considerations In the default mode of operation the encoder has to honor frame constraints (i.e. not produc frames with size bigger than requested) while still making output picture as good as possible. A frame containing a lot of small details is harder to compress and the encoder would spend more time searching for appropriate quantizers for each slice. Setting a higher @option{bits_per_mb} limit will improve the speed. For the fastest encoding speed set the @option{qscale} parameter (4 is the recommended value) and do not set a size constraint. @section libkvazaar Kvazaar H.265/HEVC encoder. Requires the presence of the libkvazaar headers and library during configuration. You need to explicitly configure the build with @option{--enable-libkvazaar}. @subsection Options @table @option @item b Set target video bitrate in bit/s and enable rate control. @item kvazaar-params Set kvazaar parameters as a list of @var{name}=@var{value} pairs separated by commas (,). See kvazaar documentation for a list of options. @end table @section QSV encoders The family of Intel QuickSync Video encoders (MPEG-2, H.264 and HEVC) The ratecontrol method is selected as follows: @itemize @bullet @item When @option{global_quality} is specified, a quality-based mode is used. Specifically this means either @itemize @minus @item @var{CQP} - constant quantizer scale, when the @option{qscale} codec flag is also set (the @option{-qscale} avconv option). @item @var{LA_ICQ} - intelligent constant quality with lookahead, when the @option{la_depth} option is also set. @item @var{ICQ} -- intelligent constant quality otherwise. @end itemize @item Otherwise, a bitrate-based mode is used. For all of those, you should specify at least the desired average bitrate with the @option{b} option. @itemize @minus @item @var{LA} - VBR with lookahead, when the @option{la_depth} option is specified. @item @var{VCM} - video conferencing mode, when the @option{vcm} option is set. @item @var{CBR} - constant bitrate, when @option{maxrate} is specified and equal to the average bitrate. @item @var{VBR} - variable bitrate, when @option{maxrate} is specified, but is higher than the average bitrate. @item @var{AVBR} - average VBR mode, when @option{maxrate} is not specified. This mode is further configured by the @option{avbr_accuracy} and @option{avbr_convergence} options. @end itemize @end itemize Note that depending on your system, a different mode than the one you specified may be selected by the encoder. Set the verbosity level to @var{verbose} or higher to see the actual settings used by the QSV runtime. Additional libavcodec global options are mapped to MSDK options as follows: @itemize @item @option{g/gop_size} -> @option{GopPicSize} @item @option{bf/max_b_frames}+1 -> @option{GopRefDist} @item @option{rc_init_occupancy/rc_initial_buffer_occupancy} -> @option{InitialDelayInKB} @item @option{slices} -> @option{NumSlice} @item @option{refs} -> @option{NumRefFrame} @item @option{b_strategy/b_frame_strategy} -> @option{BRefType} @item @option{cgop/CLOSED_GOP} codec flag -> @option{GopOptFlag} @item For the @var{CQP} mode, the @option{i_qfactor/i_qoffset} and @option{b_qfactor/b_qoffset} set the difference between @var{QPP} and @var{QPI}, and @var{QPP} and @var{QPB} respectively. @item Setting the @option{coder} option to the value @var{vlc} will make the H.264 encoder use CAVLC instead of CABAC. @end itemize @c man end VIDEO ENCODERS