1@chapter Encoders 2@c man begin ENCODERS 3 4Encoders are configured elements in Libav which allow the encoding of 5multimedia streams. 6 7When you configure your Libav build, all the supported native encoders 8are enabled by default. Encoders requiring an external library must be enabled 9manually via the corresponding @code{--enable-lib} option. You can list all 10available encoders using the configure option @code{--list-encoders}. 11 12You can disable all the encoders with the configure option 13@code{--disable-encoders} and selectively enable / disable single encoders 14with the options @code{--enable-encoder=@var{ENCODER}} / 15@code{--disable-encoder=@var{ENCODER}}. 16 17The option @code{-codecs} of the av* tools will display the list of 18enabled encoders. 19 20@c man end ENCODERS 21 22@chapter Audio Encoders 23@c man begin AUDIO ENCODERS 24 25A description of some of the currently available audio encoders 26follows. 27 28@section ac3 and ac3_fixed 29 30AC-3 audio encoders. 31 32These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366, as well as 33the undocumented RealAudio 3 (a.k.a. dnet). 34 35The @var{ac3} encoder uses floating-point math, while the @var{ac3_fixed} 36encoder only uses fixed-point integer math. This does not mean that one is 37always faster, just that one or the other may be better suited to a 38particular system. The floating-point encoder will generally produce better 39quality audio for a given bitrate. The @var{ac3_fixed} encoder is not the 40default codec for any of the output formats, so it must be specified explicitly 41using the option @code{-acodec ac3_fixed} in order to use it. 42 43@subsection AC-3 Metadata 44 45The AC-3 metadata options are used to set parameters that describe the audio, 46but in most cases do not affect the audio encoding itself. Some of the options 47do directly affect or influence the decoding and playback of the resulting 48bitstream, while others are just for informational purposes. A few of the 49options will add bits to the output stream that could otherwise be used for 50audio data, and will thus affect the quality of the output. Those will be 51indicated accordingly with a note in the option list below. 52 53These parameters are described in detail in several publicly-available 54documents. 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} 67Allow Per-Frame Metadata. Specifies if the encoder should check for changing 68metadata for each frame. 69@table @option 70@item 0 71The metadata values set at initialization will be used for every frame in the 72stream. (default) 73@item 1 74Metadata 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} 84Center Mix Level. The amount of gain the decoder should apply to the center 85channel when downmixing to stereo. This field will only be written to the 86bitstream if a center channel is present. The value is specified as a scale 87factor. There are 3 valid values: 88@table @option 89@item 0.707 90Apply -3dB gain 91@item 0.595 92Apply -4.5dB gain (default) 93@item 0.500 94Apply -6dB gain 95@end table 96 97@item -surround_mixlev @var{level} 98Surround Mix Level. The amount of gain the decoder should apply to the surround 99channel(s) when downmixing to stereo. This field will only be written to the 100bitstream if one or more surround channels are present. The value is specified 101as a scale factor. There are 3 valid values: 102@table @option 103@item 0.707 104Apply -3dB gain 105@item 0.500 106Apply -6dB gain (default) 107@item 0.000 108Silence Surround Channel(s) 109@end table 110 111@end table 112 113@subsubsection Audio Production Information 114Audio Production Information is optional information describing the mixing 115environment. Either none or both of the fields are written to the bitstream. 116 117@table @option 118 119@item -mixing_level @var{number} 120Mixing Level. Specifies peak sound pressure level (SPL) in the production 121environment when the mix was mastered. Valid values are 80 to 111, or -1 for 122unknown or not indicated. The default value is -1, but that value cannot be 123used if the Audio Production Information is written to the bitstream. Therefore, 124if the @code{room_type} option is not the default value, the @code{mixing_level} 125option must not be -1. 126 127@item -room_type @var{type} 128Room Type. Describes the equalization used during the final mixing session at 129the studio or on the dubbing stage. A large room is a dubbing stage with the 130industry standard X-curve equalization; a small room has flat equalization. 131This field will not be written to the bitstream if both the @code{mixing_level} 132option and the @code{room_type} option have the default values. 133@table @option 134@item 0 135@itemx notindicated 136Not Indicated (default) 137@item 1 138@itemx large 139Large Room 140@item 2 141@itemx small 142Small Room 143@end table 144 145@end table 146 147@subsubsection Other Metadata Options 148 149@table @option 150 151@item -copyright @var{boolean} 152Copyright Indicator. Specifies whether a copyright exists for this audio. 153@table @option 154@item 0 155@itemx off 156No Copyright Exists (default) 157@item 1 158@itemx on 159Copyright Exists 160@end table 161 162@item -dialnorm @var{value} 163Dialogue Normalization. Indicates how far the average dialogue level of the 164program is below digital 100% full scale (0 dBFS). This parameter determines a 165level shift during audio reproduction that sets the average volume of the 166dialogue to a preset level. The goal is to match volume level between program 167sources. A value of -31dB will result in no volume level change, relative to 168the source volume, during audio reproduction. Valid values are whole numbers in 169the range -31 to -1, with -31 being the default. 170 171@item -dsur_mode @var{mode} 172Dolby 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 174stream is stereo. Using this option does @b{NOT} mean the encoder will actually 175apply Dolby Surround processing. 176@table @option 177@item 0 178@itemx notindicated 179Not Indicated (default) 180@item 1 181@itemx off 182Not Dolby Surround Encoded 183@item 2 184@itemx on 185Dolby Surround Encoded 186@end table 187 188@item -original @var{boolean} 189Original Bit Stream Indicator. Specifies whether this audio is from the 190original source and not a copy. 191@table @option 192@item 0 193@itemx off 194Not Original Source 195@item 1 196@itemx on 197Original Source (default) 198@end table 199 200@end table 201 202@subsection Extended Bitstream Information 203The extended bitstream options are part of the Alternate Bit Stream Syntax as 204specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts. 205If any one parameter in a group is specified, all values in that group will be 206written to the bitstream. Default values are used for those that are written 207but have not been specified. If the mixing levels are written, the decoder 208will use these values instead of the ones specified in the @code{center_mixlev} 209and @code{surround_mixlev} options if it supports the Alternate Bit Stream 210Syntax. 211 212@subsubsection Extended Bitstream Information - Part 1 213 214@table @option 215 216@item -dmix_mode @var{mode} 217Preferred 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 222Not Indicated (default) 223@item 1 224@itemx ltrt 225Lt/Rt Downmix Preferred 226@item 2 227@itemx loro 228Lo/Ro Downmix Preferred 229@end table 230 231@item -ltrt_cmixlev @var{level} 232Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the 233center channel when downmixing to stereo in Lt/Rt mode. 234@table @option 235@item 1.414 236Apply +3dB gain 237@item 1.189 238Apply +1.5dB gain 239@item 1.000 240Apply 0dB gain 241@item 0.841 242Apply -1.5dB gain 243@item 0.707 244Apply -3.0dB gain 245@item 0.595 246Apply -4.5dB gain (default) 247@item 0.500 248Apply -6.0dB gain 249@item 0.000 250Silence Center Channel 251@end table 252 253@item -ltrt_surmixlev @var{level} 254Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the 255surround channel(s) when downmixing to stereo in Lt/Rt mode. 256@table @option 257@item 0.841 258Apply -1.5dB gain 259@item 0.707 260Apply -3.0dB gain 261@item 0.595 262Apply -4.5dB gain 263@item 0.500 264Apply -6.0dB gain (default) 265@item 0.000 266Silence Surround Channel(s) 267@end table 268 269@item -loro_cmixlev @var{level} 270Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the 271center channel when downmixing to stereo in Lo/Ro mode. 272@table @option 273@item 1.414 274Apply +3dB gain 275@item 1.189 276Apply +1.5dB gain 277@item 1.000 278Apply 0dB gain 279@item 0.841 280Apply -1.5dB gain 281@item 0.707 282Apply -3.0dB gain 283@item 0.595 284Apply -4.5dB gain (default) 285@item 0.500 286Apply -6.0dB gain 287@item 0.000 288Silence Center Channel 289@end table 290 291@item -loro_surmixlev @var{level} 292Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the 293surround channel(s) when downmixing to stereo in Lo/Ro mode. 294@table @option 295@item 0.841 296Apply -1.5dB gain 297@item 0.707 298Apply -3.0dB gain 299@item 0.595 300Apply -4.5dB gain 301@item 0.500 302Apply -6.0dB gain (default) 303@item 0.000 304Silence 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} 314Dolby 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 316apply Dolby Surround EX processing. 317@table @option 318@item 0 319@itemx notindicated 320Not Indicated (default) 321@item 1 322@itemx on 323Dolby Surround EX Off 324@item 2 325@itemx off 326Dolby Surround EX On 327@end table 328 329@item -dheadphone_mode @var{mode} 330Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone 331encoding (multi-channel matrixed to 2.0 for use with headphones). Using this 332option does @b{NOT} mean the encoder will actually apply Dolby Headphone 333processing. 334@table @option 335@item 0 336@itemx notindicated 337Not Indicated (default) 338@item 1 339@itemx on 340Dolby Headphone Off 341@item 2 342@itemx off 343Dolby Headphone On 344@end table 345 346@item -ad_conv_type @var{type} 347A/D Converter Type. Indicates whether the audio has passed through HDCD A/D 348conversion. 349@table @option 350@item 0 351@itemx standard 352Standard A/D Converter (default) 353@item 1 354@itemx hdcd 355HDCD 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} 365Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This 366is an optional AC-3 feature that increases quality by selectively encoding 367the left/right channels as mid/side. This option is enabled by default, and it 368is highly recommended that it be left as enabled except for testing purposes. 369 370@end table 371 372@subheading Floating-Point-Only AC-3 Encoding Options 373 374These options are only valid for the floating-point encoder and do not exist 375for the fixed-point encoder due to the corresponding features not being 376implemented in fixed-point. 377 378@table @option 379 380@item -channel_coupling @var{boolean} 381Enables/Disables use of channel coupling, which is an optional AC-3 feature 382that increases quality by combining high frequency information from multiple 383channels into a single channel. The per-channel high frequency information is 384sent with less accuracy in both the frequency and time domains. This allows 385more bits to be used for lower frequencies while preserving enough information 386to reconstruct the high frequencies. This option is enabled by default for the 387floating-point encoder and should generally be left as enabled except for 388testing purposes or to increase encoding speed. 389@table @option 390@item -1 391@itemx auto 392Selected by Encoder (default) 393@item 0 394@itemx off 395Disable Channel Coupling 396@item 1 397@itemx on 398Enable Channel Coupling 399@end table 400 401@item -cpl_start_band @var{number} 402Coupling Start Band. Sets the channel coupling start band, from 1 to 15. If a 403value higher than the bandwidth is used, it will be reduced to 1 less than the 404coupling end band. If @var{auto} is used, the start band will be determined by 405the encoder based on the bit rate, sample rate, and channel layout. This option 406has no effect if channel coupling is disabled. 407@table @option 408@item -1 409@itemx auto 410Selected by Encoder (default) 411@end table 412 413@end table 414 415@c man end AUDIO ENCODERS 416