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

VP8

ffenc_wmv2

ffenc_mpeg4

jpegenc

pngenc

schroenc

x264enc

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

ffenc_aac

celtenc

speexenc

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.

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.

ZeroPointEleven/EncoderConsensus (last edited 2011-09-12 20:09:14 by mobile-166-203-142-031)