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 av* 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 @subheading 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 @c man end AUDIO ENCODERS
 416
 417 @chapter Video Encoders
 418 @c man begin VIDEO ENCODERS
 419
 420 @section libx264
 421
 422 x264 H.264/MPEG-4 AVC encoder wrapper
 423
 424 x264 supports an impressive number of features, including 8x8 and 4x4 adaptive
 425 spatial transform, adaptive B-frame placement, CAVLC/CABAC entropy coding,
 426 interlacing (MBAFF), lossless mode, psy optimizations for detail retention
 427 (adaptive quantization, psy-RD, psy-trellis).
 428
 429 The Libav wrapper provides a mapping for most of them using global options
 430 that match those of the encoders and provides private options for the unique
 431 encoder options. Additionally an expert override is provided to directly pass
 432 a list of key=value tuples as accepted by x264_param_parse.
 433
 434 @subsection Option Mapping
 435
 436 The following options are supported by the x264 wrapper, the x264-equivalent
 437 options follow the Libav ones.
 438
 439 @multitable @columnfractions .2 .2
 440 @item b                 @tab bitrate
 441 Libav @code{b} option is expressed in bits/s, x264 @code{bitrate} in kilobits/s.
 442 @item bf                @tab bframes
 443 Maximum number of B-frames.
 444 @item g                 @tab keyint
 445 Maximum GOP size.
 446 @item qmin              @tab qpmin
 447 @item qmax              @tab qpmax
 448 @item qdiff             @tab qpstep
 449 @item qblur             @tab qblur
 450 @item qcomp             @tab qcomp
 451 @item refs              @tab ref
 452 @item sc_threshold      @tab scenecut
 453 @item trellis           @tab trellis
 454 @item nr                @tab nr
 455 Noise reduction.
 456 @item me_range          @tab merange
 457 @item me_method         @tab me
 458 @item subq              @tab subme
 459 @item b_strategy        @tab b-adapt
 460 @item keyint_min        @tab keyint-min
 461 @item coder             @tab cabac
 462 Set coder to @code{ac} to use CABAC.
 463 @item cmp               @tab chroma-me
 464 Set to @code{chroma} to use chroma motion estimation.
 465 @item threads           @tab threads
 466 @item thread_type       @tab sliced_threads
 467 Set to @code{slice} to use sliced threading instead of frame threading.
 468 @item flags -cgop       @tab open-gop
 469 Set @code{-cgop} to use recovery points to close GOPs.
 470 @item rc_init_occupancy @tab vbv-init
 471 Initial buffer occupancy.
 472 @end multitable
 473
 474 @subsection Private Options
 475 @table @option
 476 @item -preset @var{string}
 477 Set the encoding preset (cf. x264 --fullhelp).
 478 @item -tune @var{string}
 479 Tune the encoding params (cf. x264 --fullhelp).
 480 @item -profile @var{string}
 481 Set profile restrictions (cf. x264 --fullhelp).
 482 @item -fastfirstpass @var{integer}
 483 Use fast settings when encoding first pass.
 484 @item -crf @var{float}
 485 Select the quality for constant quality mode.
 486 @item -crf_max @var{float}
 487 In CRF mode, prevents VBV from lowering quality beyond this point.
 488 @item -qp @var{integer}
 489 Constant quantization parameter rate control method.
 490 @item -aq-mode @var{integer}
 491 AQ method
 492
 493 Possible values:
 494 @table @samp
 495 @item none
 496
 497 @item variance
 498 Variance AQ (complexity mask).
 499 @item autovariance
 500 Auto-variance AQ (experimental).
 501 @end table
 502 @item -aq-strength @var{float}
 503 AQ strength, reduces blocking and blurring in flat and textured areas.
 504 @item -psy @var{integer}
 505 Use psychovisual optimizations.
 506 @item -psy-rd @var{string}
 507 Strength of psychovisual optimization, in <psy-rd>:<psy-trellis> format.
 508 @item -rc-lookahead @var{integer}
 509 Number of frames to look ahead for frametype and ratecontrol.
 510 @item -weightb @var{integer}
 511 Weighted prediction for B-frames.
 512 @item -weightp @var{integer}
 513 Weighted prediction analysis method.
 514
 515 Possible values:
 516 @table @samp
 517 @item none
 518
 519 @item simple
 520
 521 @item smart
 522
 523 @end table
 524 @item -ssim @var{integer}
 525 Calculate and print SSIM stats.
 526 @item -intra-refresh @var{integer}
 527 Use Periodic Intra Refresh instead of IDR frames.
 528 @item -b-bias @var{integer}
 529 Influences how often B-frames are used.
 530 @item -b-pyramid @var{integer}
 531 Keep some B-frames as references.
 532
 533 Possible values:
 534 @table @samp
 535 @item none
 536
 537 @item strict
 538 Strictly hierarchical pyramid.
 539 @item normal
 540 Non-strict (not Blu-ray compatible).
 541 @end table
 542 @item -mixed-refs @var{integer}
 543 One reference per partition, as opposed to one reference per macroblock.
 544 @item -8x8dct @var{integer}
 545 High profile 8x8 transform.
 546 @item -fast-pskip @var{integer}
 547 @item -aud @var{integer}
 548 Use access unit delimiters.
 549 @item -mbtree @var{integer}
 550 Use macroblock tree ratecontrol.
 551 @item -deblock @var{string}
 552 Loop filter parameters, in <alpha:beta> form.
 553 @item -cplxblur @var{float}
 554 Reduce fluctuations in QP (before curve compression).
 555 @item -partitions @var{string}
 556 A comma-separated list of partitions to consider, possible values: p8x8, p4x4, b8x8, i8x8, i4x4, none, all.
 557 @item -direct-pred @var{integer}
 558 Direct MV prediction mode
 559
 560 Possible values:
 561 @table @samp
 562 @item none
 563
 564 @item spatial
 565
 566 @item temporal
 567
 568 @item auto
 569
 570 @end table
 571 @item -slice-max-size @var{integer}
 572 Limit the size of each slice in bytes.
 573 @item -stats @var{string}
 574 Filename for 2 pass stats.
 575 @item -nal-hrd @var{integer}
 576 Signal HRD information (requires vbv-bufsize; cbr not allowed in .mp4).
 577
 578 Possible values:
 579 @table @samp
 580 @item none
 581
 582 @item vbr
 583
 584 @item cbr
 585
 586 @end table
 587 @item -x264-params @var{string}
 588 Override the x264 configuration using a :-separated list of key=value parameters.
 589 @example
 590 -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
 591 @end example
 592 @end table
 593
 594 Encoding avpresets for common usages are provided so they can be used with the
 595 general presets system (e.g. passing the @code{-pre} option).
 596
 597 @c man end VIDEO ENCODERS