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 @c man end AUDIO ENCODERS
 416
 417 @chapter Video Encoders
 418 @c man begin VIDEO ENCODERS
 419
 420 A description of some of the currently available video encoders
 421 follows.
 422
 423 @section libvpx
 424
 425 VP8 format supported through libvpx.
 426
 427 Requires the presence of the libvpx headers and library during configuration.
 428 You need to explicitly configure the build with @code{--enable-libvpx}.
 429
 430 @subsection Options
 431
 432 Mapping from FFmpeg to libvpx options with conversion notes in parentheses.
 433
 434 @table @option
 435
 436 @item threads
 437 g_threads
 438
 439 @item profile
 440 g_profile
 441
 442 @item vb
 443 rc_target_bitrate
 444
 445 @item g
 446 kf_max_dist
 447
 448 @item keyint_min
 449 kf_min_dist
 450
 451 @item qmin
 452 rc_min_quantizer
 453
 454 @item qmax
 455 rc_max_quantizer
 456
 457 @item bufsize, vb
 458 rc_buf_sz
 459 @code{(bufsize * 1000 / vb)}
 460
 461 rc_buf_optimal_sz
 462 @code{(bufsize * 1000 / vb * 5 / 6)}
 463
 464 @item rc_init_occupancy, vb
 465 rc_buf_initial_sz
 466 @code{(rc_init_occupancy * 1000 / vb)}
 467
 468 @item rc_buffer_aggressivity
 469 rc_undershoot_pct
 470
 471 @item skip_threshold
 472 rc_dropframe_thresh
 473
 474 @item qcomp
 475 rc_2pass_vbr_bias_pct
 476
 477 @item maxrate, vb
 478 rc_2pass_vbr_maxsection_pct
 479 @code{(maxrate * 100 / vb)}
 480
 481 @item minrate, vb
 482 rc_2pass_vbr_minsection_pct
 483 @code{(minrate * 100 / vb)}
 484
 485 @item minrate, maxrate, vb
 486 @code{VPX_CBR}
 487 @code{(minrate == maxrate == vb)}
 488
 489 @item crf
 490 @code{VPX_CQ}, @code{VP8E_SET_CQ_LEVEL}
 491
 492 @item quality
 493 @table @option
 494 @item @var{best}
 495 @code{VPX_DL_BEST_QUALITY}
 496 @item @var{good}
 497 @code{VPX_DL_GOOD_QUALITY}
 498 @item @var{realtime}
 499 @code{VPX_DL_REALTIME}
 500 @end table
 501
 502 @item speed
 503 @code{VP8E_SET_CPUUSED}
 504
 505 @item nr
 506 @code{VP8E_SET_NOISE_SENSITIVITY}
 507
 508 @item mb_threshold
 509 @code{VP8E_SET_STATIC_THRESHOLD}
 510
 511 @item slices
 512 @code{VP8E_SET_TOKEN_PARTITIONS}
 513
 514 @item max-intra-rate
 515 @code{VP8E_SET_MAX_INTRA_BITRATE_PCT}
 516
 517 @item force_key_frames
 518 @code{VPX_EFLAG_FORCE_KF}
 519
 520 @item Alternate reference frame related
 521 @table @option
 522 @item vp8flags altref
 523 @code{VP8E_SET_ENABLEAUTOALTREF}
 524 @item @var{arnr_max_frames}
 525 @code{VP8E_SET_ARNR_MAXFRAMES}
 526 @item @var{arnr_type}
 527 @code{VP8E_SET_ARNR_TYPE}
 528 @item @var{arnr_strength}
 529 @code{VP8E_SET_ARNR_STRENGTH}
 530 @item @var{rc_lookahead}
 531 g_lag_in_frames
 532 @end table
 533
 534 @item vp8flags error_resilient
 535 g_error_resilient
 536
 537 @end table
 538
 539 For more information about libvpx see:
 540 @url{http://www.webmproject.org/}
 541
 542 @section libx264
 543
 544 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 format supported through
 545 libx264.
 546
 547 Requires the presence of the libx264 headers and library during
 548 configuration. You need to explicitly configure the build with
 549 @code{--enable-libx264}.
 550
 551 @subsection Options
 552
 553 @table @option
 554
 555 @item preset @var{preset_name}
 556 Set the encoding preset.
 557
 558 @item tune @var{tune_name}
 559 Tune the encoding params.
 560
 561 @item fastfirstpass @var{bool}
 562 Use fast settings when encoding first pass, default value is 1.
 563
 564 @item profile @var{profile_name}
 565 Set profile restrictions.
 566
 567 @item level @var{level}
 568 Specify level (as defined by Annex A).
 569 Deprecated in favor of @var{x264opts}.
 570
 571 @item passlogfile @var{filename}
 572 Specify filename for 2 pass stats.
 573 Deprecated in favor of @var{x264opts} (see @var{stats} libx264 option).
 574
 575 @item wpredp @var{wpred_type}
 576 Specify Weighted prediction for P-frames.
 577 Deprecated in favor of @var{x264opts} (see @var{weightp} libx264 option).
 578
 579 @item x264opts @var{options}
 580 Allow to set any x264 option, see x264 --fullhelp for a list.
 581
 582 @var{options} is a list of @var{key}=@var{value} couples separated by
 583 ":".
 584 @end table
 585
 586 For example to specify libx264 encoding options with @command{ffmpeg}:
 587 @example
 588 ffmpeg -i foo.mpg -vcodec libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
 589 @end example
 590
 591 For more information about libx264 and the supported options see:
 592 @url{http://www.videolan.org/developers/x264.html}
 593
 594 @c man end VIDEO ENCODERS