git.sesse.net Git - ffmpeg/blob - doc/encoders.texi

   1 @chapter Encoders
   2 @c man begin ENCODERS
   3
   4 Encoders are configured elements in Libav which allow the encoding of
   5 multimedia streams.
   6
   7 When you configure your Libav 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 A description of some of the currently available encoders follows.
  21
  22 @section Audio Encoders
  23
  24 @subsection ac3 and ac3_fixed
  25
  26 AC-3 audio encoders.
  27
  28 These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366, as well as
  29 the undocumented RealAudio 3 (a.k.a. dnet).
  30
  31 The @var{ac3} encoder uses floating-point math, while the @var{ac3_fixed}
  32 encoder only uses fixed-point integer math. This does not mean that one is
  33 always faster, just that one or the other may be better suited to a
  34 particular system. The floating-point encoder will generally produce better
  35 quality audio for a given bitrate. The @var{ac3_fixed} encoder is not the
  36 default codec for any of the output formats, so it must be specified explicitly
  37 using the option @code{-acodec ac3_fixed} in order to use it.
  38
  39 @subheading AC-3 Metadata
  40
  41 The AC-3 metadata options are used to set parameters that describe the audio,
  42 but in most cases do not affect the audio encoding itself. Some of the options
  43 do directly affect or influence the decoding and playback of the resulting
  44 bitstream, while others are just for informational purposes. A few of the
  45 options will add bits to the output stream that could otherwise be used for
  46 audio data, and will thus affect the quality of the output. Those will be
  47 indicated accordingly with a note in the option list below.
  48
  49 These parameters are described in detail in several publicly-available
  50 documents.
  51 @itemize
  52 @item @uref{http://www.atsc.org/cms/standards/a_52-2010.pdf,A/52:2010 - Digital Audio Compression (AC-3) (E-AC-3) Standard}
  53 @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}
  54 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/18_Metadata.Guide.pdf,Dolby Metadata Guide}
  55 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/46_DDEncodingGuidelines.pdf,Dolby Digital Professional Encoding Guidelines}
  56 @end itemize
  57
  58 @subsubheading Metadata Control Options
  59
  60 @table @option
  61
  62 @item -per_frame_metadata @var{boolean}
  63 Allow Per-Frame Metadata. Specifies if the encoder should check for changing
  64 metadata for each frame.
  65 @table @option
  66 @item 0
  67 The metadata values set at initialization will be used for every frame in the
  68 stream. (default)
  69 @item 1
  70 Metadata values can be changed before encoding each frame.
  71 @end table
  72
  73 @end table
  74
  75 @subsubheading Downmix Levels
  76
  77 @table @option
  78
  79 @item -center_mixlev @var{level}
  80 Center Mix Level. The amount of gain the decoder should apply to the center
  81 channel when downmixing to stereo. This field will only be written to the
  82 bitstream if a center channel is present. The value is specified as a scale
  83 factor. There are 3 valid values:
  84 @table @option
  85 @item 0.707
  86 Apply -3dB gain
  87 @item 0.595
  88 Apply -4.5dB gain (default)
  89 @item 0.500
  90 Apply -6dB gain
  91 @end table
  92
  93 @item -surround_mixlev @var{level}
  94 Surround Mix Level. The amount of gain the decoder should apply to the surround
  95 channel(s) when downmixing to stereo. This field will only be written to the
  96 bitstream if one or more surround channels are present. The value is specified
  97 as a scale factor.  There are 3 valid values:
  98 @table @option
  99 @item 0.707
 100 Apply -3dB gain
 101 @item 0.500
 102 Apply -6dB gain (default)
 103 @item 0.000
 104 Silence Surround Channel(s)
 105 @end table
 106
 107 @end table
 108
 109 @subsubheading Audio Production Information
 110 Audio Production Information is optional information describing the mixing
 111 environment.  Either none or both of the fields are written to the bitstream.
 112
 113 @table @option
 114
 115 @item -mixing_level @var{number}
 116 Mixing Level. Specifies peak sound pressure level (SPL) in the production
 117 environment when the mix was mastered. Valid values are 80 to 111, or -1 for
 118 unknown or not indicated. The default value is -1, but that value cannot be
 119 used if the Audio Production Information is written to the bitstream. Therefore,
 120 if the @code{room_type} option is not the default value, the @code{mixing_level}
 121 option must not be -1.
 122
 123 @item -room_type @var{type}
 124 Room Type. Describes the equalization used during the final mixing session at
 125 the studio or on the dubbing stage. A large room is a dubbing stage with the
 126 industry standard X-curve equalization; a small room has flat equalization.
 127 This field will not be written to the bitstream if both the @code{mixing_level}
 128 option and the @code{room_type} option have the default values.
 129 @table @option
 130 @item 0
 131 @itemx notindicated
 132 Not Indicated (default)
 133 @item 1
 134 @itemx large
 135 Large Room
 136 @item 2
 137 @itemx small
 138 Small Room
 139 @end table
 140
 141 @end table
 142
 143 @subsubheading Other Metadata Options
 144
 145 @table @option
 146
 147 @item -copyright @var{boolean}
 148 Copyright Indicator. Specifies whether a copyright exists for this audio.
 149 @table @option
 150 @item 0
 151 @itemx off
 152 No Copyright Exists (default)
 153 @item 1
 154 @itemx on
 155 Copyright Exists
 156 @end table
 157
 158 @item -dialnorm @var{value}
 159 Dialogue Normalization. Indicates how far the average dialogue level of the
 160 program is below digital 100% full scale (0 dBFS). This parameter determines a
 161 level shift during audio reproduction that sets the average volume of the
 162 dialogue to a preset level. The goal is to match volume level between program
 163 sources. A value of -31dB will result in no volume level change, relative to
 164 the source volume, during audio reproduction. Valid values are whole numbers in
 165 the range -31 to -1, with -31 being the default.
 166
 167 @item -dsur_mode @var{mode}
 168 Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround
 169 (Pro Logic). This field will only be written to the bitstream if the audio
 170 stream is stereo. Using this option does @b{NOT} mean the encoder will actually
 171 apply Dolby Surround processing.
 172 @table @option
 173 @item 0
 174 @itemx notindicated
 175 Not Indicated (default)
 176 @item 1
 177 @itemx off
 178 Not Dolby Surround Encoded
 179 @item 2
 180 @itemx on
 181 Dolby Surround Encoded
 182 @end table
 183
 184 @item -original @var{boolean}
 185 Original Bit Stream Indicator. Specifies whether this audio is from the
 186 original source and not a copy.
 187 @table @option
 188 @item 0
 189 @itemx off
 190 Not Original Source
 191 @item 1
 192 @itemx on
 193 Original Source (default)
 194 @end table
 195
 196 @end table
 197
 198 @subsubheading Extended Bitstream Information
 199 The extended bitstream options are part of the Alternate Bit Stream Syntax as
 200 specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts.
 201 If any one parameter in a group is specified, all values in that group will be
 202 written to the bitstream.  Default values are used for those that are written
 203 but have not been specified.  If the mixing levels are written, the decoder
 204 will use these values instead of the ones specified in the @code{center_mixlev}
 205 and @code{surround_mixlev} options if it supports the Alternate Bit Stream
 206 Syntax.
 207
 208 @subsubheading Extended Bitstream Information - Part 1
 209
 210 @table @option
 211
 212 @item -dmix_mode @var{mode}
 213 Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt
 214 (Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode.
 215 @table @option
 216 @item 0
 217 @itemx notindicated
 218 Not Indicated (default)
 219 @item 1
 220 @itemx ltrt
 221 Lt/Rt Downmix Preferred
 222 @item 2
 223 @itemx loro
 224 Lo/Ro Downmix Preferred
 225 @end table
 226
 227 @item -ltrt_cmixlev @var{level}
 228 Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the
 229 center channel when downmixing to stereo in Lt/Rt mode.
 230 @table @option
 231 @item 1.414
 232 Apply +3dB gain
 233 @item 1.189
 234 Apply +1.5dB gain
 235 @item 1.000
 236 Apply 0dB gain
 237 @item 0.841
 238 Apply -1.5dB gain
 239 @item 0.707
 240 Apply -3.0dB gain
 241 @item 0.595
 242 Apply -4.5dB gain (default)
 243 @item 0.500
 244 Apply -6.0dB gain
 245 @item 0.000
 246 Silence Center Channel
 247 @end table
 248
 249 @item -ltrt_surmixlev @var{level}
 250 Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the
 251 surround channel(s) when downmixing to stereo in Lt/Rt mode.
 252 @table @option
 253 @item 0.841
 254 Apply -1.5dB gain
 255 @item 0.707
 256 Apply -3.0dB gain
 257 @item 0.595
 258 Apply -4.5dB gain
 259 @item 0.500
 260 Apply -6.0dB gain (default)
 261 @item 0.000
 262 Silence Surround Channel(s)
 263 @end table
 264
 265 @item -loro_cmixlev @var{level}
 266 Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the
 267 center channel when downmixing to stereo in Lo/Ro mode.
 268 @table @option
 269 @item 1.414
 270 Apply +3dB gain
 271 @item 1.189
 272 Apply +1.5dB gain
 273 @item 1.000
 274 Apply 0dB gain
 275 @item 0.841
 276 Apply -1.5dB gain
 277 @item 0.707
 278 Apply -3.0dB gain
 279 @item 0.595
 280 Apply -4.5dB gain (default)
 281 @item 0.500
 282 Apply -6.0dB gain
 283 @item 0.000
 284 Silence Center Channel
 285 @end table
 286
 287 @item -loro_surmixlev @var{level}
 288 Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the
 289 surround channel(s) when downmixing to stereo in Lo/Ro mode.
 290 @table @option
 291 @item 0.841
 292 Apply -1.5dB gain
 293 @item 0.707
 294 Apply -3.0dB gain
 295 @item 0.595
 296 Apply -4.5dB gain
 297 @item 0.500
 298 Apply -6.0dB gain (default)
 299 @item 0.000
 300 Silence Surround Channel(s)
 301 @end table
 302
 303 @end table
 304
 305 @subsubheading Extended Bitstream Information - Part 2
 306
 307 @table @option
 308
 309 @item -dsurex_mode @var{mode}
 310 Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX
 311 (7.1 matrixed to 5.1). Using this option does @b{NOT} mean the encoder will actually
 312 apply Dolby Surround EX processing.
 313 @table @option
 314 @item 0
 315 @itemx notindicated
 316 Not Indicated (default)
 317 @item 1
 318 @itemx on
 319 Dolby Surround EX On
 320 @item 2
 321 @itemx off
 322 Dolby Surround EX Off
 323 @end table
 324
 325 @item -dheadphone_mode @var{mode}
 326 Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone
 327 encoding (multi-channel matrixed to 2.0 for use with headphones). Using this
 328 option does @b{NOT} mean the encoder will actually apply Dolby Headphone
 329 processing.
 330 @table @option
 331 @item 0
 332 @itemx notindicated
 333 Not Indicated (default)
 334 @item 1
 335 @itemx on
 336 Dolby Headphone On
 337 @item 2
 338 @itemx off
 339 Dolby Headphone Off
 340 @end table
 341
 342 @item -ad_conv_type @var{type}
 343 A/D Converter Type. Indicates whether the audio has passed through HDCD A/D
 344 conversion.
 345 @table @option
 346 @item 0
 347 @itemx standard
 348 Standard A/D Converter (default)
 349 @item 1
 350 @itemx hdcd
 351 HDCD A/D Converter
 352 @end table
 353
 354 @end table
 355
 356 @subheading Other AC-3 Encoding Options
 357
 358 @table @option
 359
 360 @item -stereo_rematrixing @var{boolean}
 361 Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This
 362 is an optional AC-3 feature that increases quality by selectively encoding
 363 the left/right channels as mid/side. This option is enabled by default, and it
 364 is highly recommended that it be left as enabled except for testing purposes.
 365
 366 @end table
 367
 368 @c man end ENCODERS