• ZeroPointEleven
• EncoderConsensus

Right now, encoder controls in gstreamer are a mess. This page proposes a fix.

Current Properties

The below list shows a selection of basic properties from common video and audio encoder elements. The properties express a common core set of functionality, like setting bitrate/quality targets, but every encoder has invented its own different, incompatible version of these properties. This divergence makes life harder for gstreamer developers and hinders adoption, especially for GUI encoding and transcoding tools.

Read it and weep; it's actually astonishing how many different ways we have invented to do the same thing.

Video

Theoraenc

• bitrate : Compressed video bitrate (kbps)
  • Integer. Range: 0 - 16777215 Default: 0
  quality : Video quality
  • Integer. Range: 0 - 63 Default: 48
  keyframe-freq : Keyframe frequency
  • Integer. Range: 1 - 32768 Default: 64

  speed-level : Controls the amount of analysis performed when encoding. Higher values trade compression quality for speed. This property requires libtheora version >= 1.0, and the maximum value may vary based on encoder version.

  • Integer. Range: 0 - 2 Default: 1
  rate-buffer : Sets the size of the rate control buffer, in units of frames. The default value of 0 instructs the encoder to automatically select an appropriate value
  • Integer. Range: 0 - 1000 Default: 0
  cap-overflow : Enable capping of bit reservoir overflows
  • Boolean. Default: true
  cap-underflow : Enable capping of bit reservoir underflows
  • Boolean. Default: false
  multipass-cache-file: Multipass cache file
  • String. Default: null
  multipass-mode : Single pass or first/second pass

  • Enum "GstTheoraEncMultipassMode" Default: 0, "single-pass"

    • (0): single-pass - Single pass (1): first-pass - First pass (2): second-pass - Second pass

VP8

• bitrate : Bit rate (in bits/sec)
  • Integer. Range: 0 - 1000000000 Default: 0
  mode : Mode
  • Enum "GstVP8EncMode" Default: 0, "vbr" Current: 0, "vbr"
    • (0): vbr - Variable Bit Rate (VBR) mode (1): cbr - Constant Bit Rate (CBR) mode
  quality : Quality
  • Double. Range: 0 - 10 Default: 5
  max-keyframe-distance: Maximum distance between key frames
  • Integer. Range: 0 - 9999 Default: 60
  max-latency : Number of frames in encoder queue
  • Integer. Range: 0 - 25 Default: 10
  speed : Speed
  • Integer. Range: 0 - 2 Default: 0
  threads : Threads
  • Integer. Range: 1 - 64 Default: 1
  error-resilient : Encode streams that are error resilient
  • Boolean. Default: false
  multipass-mode : Multipass encode mode
  • Enum "GstVP8EncMultipassMode" Default: 0, "one-pass"
    • (0): one-pass - One pass encoding (default) (1): first-pass - First pass of multipass encoding (2): last-pass - Last pass of multipass encoding
  multipass-cache-file: Multipass cache file
  • String. Default: null

ffenc_wmv2

• bitrate : Target Video Bitrate
  • Unsigned Long. Range: 0 - 4294967295 Default: 300000
  gop-size : Number of frames within one GOP
  • Integer. Range: 0 - 2147483647 Default: 15

ffenc_mpeg4

• bitrate : Target Video Bitrate
  • Unsigned Long. Range: 0 - 4294967295 Default: 300000
  gop-size : Number of frames within one GOP
  • Integer. Range: 0 - 2147483647 Default: 15
  pass : Encoding pass/type
  • Enum "GstFFMpegEncPass" Default: 0, "cbr"
    • (0): cbr - Constant Bitrate Encoding (2): quant - Constant Quantizer (512): pass1 - VBR Encoding - Pass 1 (1024): pass2 - VBR Encoding - Pass 2
  multipass-cache-file: Filename for multipass cache file
  • String. Default: "stats.log"
  bitrate-tolerance : Number of bits the bitstream is allowed to diverge from the reference
  • Integer. Range: 0 - 100000000 Default: 8000000
  quantizer : Constant Quantizer
  • Float. Range: 0 - 30 Default: 0.01

jpegenc

• quality : Quality of encoding
  • Integer. Range: 0 - 100 Default: 85

pngenc

• compression-level : PNG compression level
  • Unsigned Integer. Range: 0 - 9 Default: 6

schroenc

• rate-control : rate_control

  • Enum "SchroEncoderSettingEnum_rate_control" Default: 6, "constant_quality"

    • (0): constant_noise_threshold - constant_noise_threshold (1): constant_bitrate - constant_bitrate (2): low_delay - low_delay (3): lossless - lossless (4): constant_lambda - constant_lambda (5): constant_error - constant_error (6): constant_quality - constant_quality
  bitrate : bitrate
  • Integer. Range: 0 - 2147483647 Default: 0
  max-bitrate : max_bitrate
  • Integer. Range: 0 - 2147483647 Default: 13824000
  min-bitrate : min_bitrate
  • Integer. Range: 0 - 2147483647 Default: 13824000
  buffer-size : buffer_size
  • Integer. Range: 0 - 2147483647 Default: 0
  buffer-level : buffer_level
  • Integer. Range: 0 - 2147483647 Default: 0
  quality : quality
  • Double. Range: 0 - 10 Default: 5
  noise-threshold : noise_threshold
  • Double. Range: 0 - 100 Default: 25
  queue-depth : queue_depth
  • Integer. Range: 1 - 40 Default: 20

x264enc

• threads : Number of threads used by the codec (0 for automatic)
  • Unsigned Integer. Range: 0 - 4 Default: 0
  sliced-threads : Low latency but lower efficiency threading
  • Boolean. Default: false
  sync-lookahead : Number of buffer frames for threaded lookahead (-1 for automatic)
  • Integer. Range: -1 - 250 Default: -1
  pass : Encoding pass/type

  • Enum "GstX264EncPass" Default: 0, "cbr"

    • (0): cbr - Constant Bitrate Encoding (4): quant - Constant Quantizer (debugging only) (5): qual - Constant Quality (17): pass1 - VBR Encoding - Pass 1 (18): pass2 - VBR Encoding - Pass 2 (19): pass3 - VBR Encoding - Pass 3
  quantizer : Constant quantizer or quality to apply
  • Unsigned Integer. Range: 1 - 50 Default: 21
  multipass-cache-file: Filename for multipass cache file
  • String. Default: "x264.log"
  bitrate : Bitrate in kbit/sec
  • Unsigned Integer. Range: 1 - 102400 Default: 2048
  intra-refresh : Use Periodic Intra Refresh instead of IDR frames
  • Boolean. Default: false
  vbv-buf-capacity : Size of the VBV buffer in milliseconds
  • Unsigned Integer. Range: 0 - 10000 Default: 600
  key-int-max : Maximal distance between two key-frames (0 for automatic)
  • Unsigned Integer. Range: 0 - 2147483647 Default: 0
  qp-min : Minimum quantizer
  • Unsigned Integer. Range: 1 - 51 Default: 10
  qp-max : Maximum quantizer
  • Unsigned Integer. Range: 1 - 51 Default: 51
  noise-reduction : Noise reduction strength
  • Unsigned Integer. Range: 0 - 100000 Default: 0
  interlaced : Interlaced material
  • Boolean. Default: false
  speed-preset : Preset name for speed/quality tradeoff options (can affect decode compatibility - impose restrictions separately for your target decoder)

  • Enum "GstX264EncPreset" Default: 6, "medium"

    • (0): None - No preset (1): ultrafast - ultrafast (2): superfast - superfast (3): veryfast - veryfast (4): faster - faster (5): fast - fast (6): medium - medium (7): slow - slow (8): slower - slower (9): veryslow - veryslow (10): placebo - placebo

meegoh264encoder

   /**
        *  MeegoGstH264Encoder:rate-control-mode
        *
        * Rate control mode
        * This parameter controls the type of bitrate control algorithm the encoder will use
        * The interface defines several modes in #MeegoGstH264EncoderRateControlMode
        * 
        */
   /**
        *  MeegoGstH264Encoder:bit-rate
        *
        * Bitrate in bits per second 
        * This property can be changed during the encoding process as opposed to
        * #MeegoGstH264Encoder:max-bitrate that is set only before the encoding begins
        * If set to 0 (default) encoder will choose a value based on frame size and
        * frame rate that fits in a valid standard level.
        */
   /**
        *  MeegoGstH264Encoder:max-bit-rate
        *
        * Maximum Bitrate in bits per second 
        * This property can NOT be changed during the encoding process as opposed to
        * #MeegoGstH264Encoder:bitrate 
        * It is used as a hint to the encoder to allow for a change of bitrate 
        * during the encoding process. The encoder will not allow (or ignore) a change
        * of bitrate to a value bigger than the one set by this property 
        * If set to 0 (default) encoder will choose a value based on frame size and
        * frame rate that fits in a valid standard level.
        */
  // In case of RC-mode = None

   /**
        *  MeegoGstH264Encoder:min-qp
        *
        * Minimum Quantization Parameter to be used during the encoding process
        * The value -1 is used as default value, so that the encoder decides
        * which value is more appropiate
        */
   /**
        *  MeegoGstH264Encoder:max-qp
        *
        * Maximum Quantization Parameter to be used during the encoding process 
        * The value -1 is used as default value, so that the encoder decides
        * which value is more appropiate
        */
   /**
        *  MeegoGstH264Encoder:intra-qp
        *
        * Quantization Parameter to be used during the encoding process of I frames
        * When used with a rate control algorithm diferent than "none" this parameter
        * is used only for the first I frame.
        */
   /**
        *  MeegoGstH264Encoder:inter-qp
        *
        * Quantization Parameter to be used during the encoding process of inter 
        * predicted frames (P and B).
        */
   /**
        *  MeegoGstH264Encoder:delay
        *
        * Maximum delay in miliseconds that the encoder will produce.
        * The delay is nothing else than a parameter for a simplified VBV model
        * This property is only used in case the rc-mode is Constant Bitrate mode. 
        * The buffer size used in this simplified VBV is equal to :
        *        (delay) x (bitrate) 
        */
   /**
        *  MeegoGstH264Encoder:rate-tol
        *
        * Maximum bitrate tolerance allowed
        * This property is only used in case the rc-mode is Variable Bitrate mode. 
        * The bitrate of the encoded sequence should be bounded in the region
        *  [ b*(1-tol), b*(1+tol)]
        * 
        * where:
        *  b   is the target bitrate specified in the property bitrate
        *  tol is the allowed tolerance as percentage
        *
        *   
        */
   /**
        *  MeegoGstH264Encoder:keyframe-period
        *
        * Number of seconds between two I frames
        * The actual number of frames between I-frames is keyframe-period * framerate
        * Every time this property is set an I frame is inserted and the cycle
        * starts. In this way an application can force the insertion of an I frames
        * A value of 0 will insert a single I frame at the begining of the stream.
        *
        * Other methods of inserting I frames on demand is by sending  the event
        * GstForceKeyUnit
        */
   /**
        *  MeegoGstH264Encoder:slice-size-mb
        *
        * Number of MacroBlocks in a single NAL Unit
        * A value of 0 is used as default and equal to one slice per frame
        * i.e:
        *   1 NAL Unit = 1 Access Unit 
        *
        * Application should estimate the size in bytes of the NAL Unit based one
        * the target bitrate and rate control algorithm.
        * (*NOTE: Maybe some encoders can implement also a slice-size-byte )
        */
   /**
        *  MeegoGstH264Encoder:intra-refresh
        *
        * Method for Intra-MB refresh on Inter predicted frames.
        * Different strategies can be followed, is up to the implementation 
        * decide which one it supports.
        * Two of the most common are:
        *       - Adaptative Intra Refresh : AIR 
        *   - Cyclic Intra Refresh: CIR          
    *
        *  see #MeegoGstH264EncoderIntraRefreshMode for more details
        *
        */
   /**
        *  MeegoGstH264Encoder:intra-refresh-rate
        *
        * Number of seconds it takes the intra refresh method to refresh the whole
        * frame.
        * Only meaningful in cyclic intra refresh modes or similar. It depends on 
        * the size of the kernel/pattern used to refresh the image.
        * 
        */
  g_object_interface_install_property (klass,
      g_param_spec_float (MEEGO_GST_H264_ENCODER_PROP_INTRA_REFRESH_RATE,
          "Frames until whole frame is refreshed ", "Number of frames until"
          " all MB's in a frame have been encoded as I-MB at least once\n"
          "\t\t\tOnly useful in intra refresh modes like cyclic",
          0, G_MAXUINT, ARG_INTRA_REFRESH_RATE_DEFAULT,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

Audio

The audio elements expose a variety of rate control options, with an emphasis on VBR, but very little else in the way of common functionality.

vorbisenc

• max-bitrate : Specify a maximum bitrate (in bps). Useful for streaming applications. (-1 == disabled)
  • Integer. Range: -1 - 250001 Default: -1
  bitrate : Attempt to encode at a bitrate averaging this (in bps). This uses the bitrate management engine, and is not recommended for most users. Quality is a better alternative. (-1 == disabled)
  • Integer. Range: -1 - 250001 Default: -1
  min-bitrate : Specify a minimum bitrate (in bps). Useful for encoding for a fixed-size channel. (-1 == disabled)
  • Integer. Range: -1 - 250001 Default: -1
  quality : Specify quality instead of specifying a particular bitrate.
  • Float. Range: -0.1 - 1 Default: 0.3
  managed : Enable bitrate management engine
  • Boolean. Default: false

ffenc_aac

• bitrate : Target Audio Bitrate
  • Unsigned Long. Range: 0 - 4294967295 Default: 128000

celtenc

• bitrate : Specify an encoding bit-rate (in bps).
  • Integer. Range: 10000 - 320000 Default: 64000
  framesize : The number of samples per frame
  • Integer. Range: 64 - 512 Default: 480
  cbr : Constant bit rate
  • Boolean. Default: true
  complexity : Complexity
  • Integer. Range: 0 - 10 Default: 9
  max-bitrate : Specify a maximum encoding bit rate (in bps) for variable bit rate encoding.
  • Integer. Range: 10000 - 320000 Default: 64000
  prediction : Controls the use of interframe prediction.

  • Enum "GstCeltEncPrediction" Default: 0, "idependent"

    • (0): idependent - Independent frames (1): short-term - Short term interframe prediction (2): long-term - Long term interframe prediction

speexenc

• quality : Encoding quality
  • Float. Range: 0 - 10 Default: 8
  bitrate : Specify an encoding bit-rate (in bps). (0 = automatic)
  • Integer. Range: 0 - 2147483647 Default: 0
  vbr : Enable variable bit-rate
  • Boolean. Default: false
  abr : Enable average bit-rate (0 = disabled)
  • Integer. Range: 0 - 2147483647 Default: 0
  complexity : Set encoding complexity
  • Integer. Range: 0 - 2147483647 Default: 3
  nframes : Number of frames per buffer
  • Integer. Range: 0 - 2147483647 Default: 1

Consensus Properties

The following set of properties represents a set of common encoder functionality: each property provides information used by at least 3 of the above encoders. It is not expected that every encoder provide all of these properties, or that encoders provide only these properties. Rather, if an encoder provides the functionality described by one of these consensus properties, it should conform to the consensus property and not invent its own incompatible property. For functionality not covered here, encoder developers are free to invent any kind of new property.

The consensus properties should be simple, clear, concise, and flexible. Where possible, their conventions have been chosen to match a plurality of the above encoders. Suggestions are welcome.

Property template

All properties are readable and writable.

• bitrate : Specify an encoding target bit-rate (in bps).

  • Unsigned Integer. Range: minimum rate - maximum rate Default: reasonable rate

  ignore-bitrate : Ignore the specified bitrate target

  • Boolean. Default: good default

  buffer-limit : Specify the minimum duration that a recipient must buffer when constrained to the target bitrate (in nanoseconds), zero for hard CBR

  • Unsigned Integer. Range: minimum buffer duration, 0 iff hard CBR is available - maximum buffer duration Default: reasonable buffer duration

  ignore-buffer-limit : Ignore the buffer limit (the recipient is not actually constrained to the target bitrate).

  • Boolean. Default: good default

  quality : Specify an encoding target quality

  • Numeric type. Range: minimum quality - maximum quality Default: reasonable default

  ignore-quality : Ignore the specified quality target

  • Boolean. Default: good default

  max-latency : Maximum latency between input and output (in nanoseconds)

  • Unsigned Integer. Range: minimum latency, 0 iff a no-latency mode is available - maximum helpful latency Default: good default

  complexity : Encoder speed/quality tradeoff. Higher values make better use of bits, but are slower to encode.

  • Integer. Range minimum complexity setting - maximum complexity setting Default: reasonable default

  threads : Number of threads used by the encoder (0 for automatic)

  • Unsigned Integer. Range: 0 - max reasonable number of threads Default: 0

  max-keyframe-distance: Maximum number of frames between keyframes (0 for unlimited)

  • Unsigned Integer. Range: 0 if unlimited is available, otherwise 1 - max keyframe distance Default: reasonable default

  multipass-cache-file: Multipass cache file. If null, multipass is disabled.
  • flags: readable, writable String. Default: null
  total-passes : The total number of passes that will be made if multipass is enabled

  • Unsigned Integer. Range: 1 - max number of passes Default: 1

  pass : The number of passes already completed

  • Unsigned Integer. Range: 0 - max number of passes - 1 Default: 0

Notes: If an encoder only provides one of ignore-bitrate and ignore-quality, then the encoder must act as if ignore-bitrate != ignore-quality.

If an encoder provides both ignore-quality and ignore-bitrate, then when ignore-quality == ignore-bitrate, the behavior is encoder-specific. For example, theoraenc can operate with both a bitrate ceiling and a quality floor, dropping frames when these constraints collide. This would be exposed as ignore-bitrate == ignore-quality == False. Basic encoder interfaces may want to fuse both options into a single toggle, if this kind of functionality is not needed.