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.