cannam@86: cannam@86: cannam@86: cannam@86: libvorbisenc - API Overview cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

libvorbisenc documentation

libvorbisenc version 1.3.2 - 20101101

cannam@86: cannam@86:

Libvorbisenc API Overview

cannam@86: cannam@86:

Libvorbisenc is an encoding convenience library intended to cannam@86: encapsulate the elaborate setup that libvorbis requires for encoding. cannam@86: Libvorbisenc gives easy access to all high-level adjustments an cannam@86: application may require when encoding and also exposes some low-level cannam@86: tuning parameters to allow applications to make detailed adjustments cannam@86: to the encoding process.

cannam@86: cannam@86: All the libvorbisenc routines are declared in "vorbis/vorbisenc.h". cannam@86: cannam@86: Note: libvorbis and libvorbisenc always cannam@86: encode in a single pass. Thus, all possible encoding setups will work cannam@86: properly with live input and produce streams that decode properly when cannam@86: streamed. See the subsection titled "managed bitrate cannam@86: modes" for details on setting limits on bitrate usage when Vorbis cannam@86: streams are used in a limited-bandwidth environment. cannam@86: cannam@86:

workflow

cannam@86: cannam@86:

Libvorbisenc is used only during encoder setup; its function cannam@86: is to automate initialization of a multitude of settings in a cannam@86: vorbis_info structure which libvorbis then uses as a reference cannam@86: during the encoding process. Libvorbisenc plays no part in the cannam@86: encoding process after setup. cannam@86: cannam@86:

Encode setup using libvorbisenc consists of three steps: cannam@86: cannam@86:

high-level initialization of a vorbis_info structure by cannam@86: calling one of vorbis_encode_setup_vbr() or vorbis_encode_setup_managed() cannam@86: with the basic input audio parameters (rate and channels) and the cannam@86: basic desired encoded audio output parameters (VBR quality or ABR/CBR cannam@86: bitrate)
cannam@86: cannam@86:
optional adjustment of the basic setup defaults using vorbis_encode_ctl()
cannam@86: cannam@86:
calling vorbis_encode_setup_init() to cannam@86: finalize the high-level setup into the detailed low-level reference cannam@86: values needed by libvorbis to encode audio. The vorbis_info cannam@86: structure is then ready to use for encoding by libvorbis.
cannam@86: cannam@86:

cannam@86: cannam@86: These three steps can be collapsed into a single call by using vorbis_encode_init_vbr to set up a cannam@86: quality-based VBR stream or vorbis_encode_init to set up a managed cannam@86: bitrate (ABR or CBR) stream.

cannam@86: cannam@86:

adjustable encoding parameters

cannam@86: cannam@86:

input audio parameters

cannam@86: cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
parameter description
sampling rate cannam@86: The sampling rate (in samples per second) of the input audio. Common examples are 8000 for telephony, 44100 for CD audio and 48000 for DAT. Note that a mono sample (one center value) and a stereo sample (one left value and one right value) both are a single sample. cannam@86: cannam@86:
channels cannam@86: cannam@86: The number of channels encoded in each input sample. By default, cannam@86: stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such cannam@86: that the stereo relationship between the samples is taken into account cannam@86: when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET. cannam@86: cannam@86:
cannam@86: cannam@86:

quality and VBR modes

cannam@86: cannam@86: Vorbis is natively a VBR codec; a user requests a given constant cannam@86: quality and the encoder keeps the encoding quality constant cannam@86: while allowing the bitrate to vary. 'Quality' modes (Variable BitRate) cannam@86: will always produce the most consistent encoding results as well as cannam@86: the highest quality for the amount of bits used. cannam@86: cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
parameter description
quality cannam@86: A decimal float value requesting a desired quality. Libvorbisenc 1.1 allows quality requests in the range of -0.1 (lowest quality, smallest files) through +1.0 (highest-quality, largest files). Quality -0.1 is intended as an ultra-low setting in which low bitrate is much more important than quality consistency. Quality settings 0.0 and above are intended to produce consistent results at all times. cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86:

managed bitrate modes

cannam@86: cannam@86: Although the Vorbis codec is natively VBR, libvorbis includes cannam@86: infrastructure for 'managing' the bitrate of streams by setting cannam@86: minimum and maximum usage constraints, as well as functionality for cannam@86: nudging a stream toward a desired average value. These features cannam@86: should only be used when there is a requirement to limit cannam@86: bitrate in some way. Although the difference is usually slight, cannam@86: managed bitrate modes will always produce output inferior to VBR cannam@86: (given equal bitrate usage). Setting overly or impossibly tight cannam@86: bitrate management requirements can affect output quality dramatically cannam@86: for the worse.

cannam@86: cannam@86: Beginning in libvorbis 1.1, bitrate management is implemented using a cannam@86: bit-reservoir algorithm. The encoder has a fixed-size cannam@86: reservoir used as a 'savings account' in encoding. When a frame is cannam@86: smaller than the target rate, the unused bits go into the reservoir so cannam@86: that they may be used by future frames. When a frame is larger than cannam@86: target bitrate, it draws 'banked' bits out of the reservoir. Encoding cannam@86: is managed so that the reservoir never goes negative (when a maximum cannam@86: bitrate is specified) or fills beyond a fixed limit (when a minimum cannam@86: bitrate is specified). An 'average bitrate' request is used as the cannam@86: set-point in a long-range bitrate tracker which adjusts the encoder's cannam@86: aggressiveness up or down depending on whether or not frames are coming cannam@86: in larger or smaller than the requested average point. cannam@86: cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
parameter description
maximum bitrate The maximum allowed bitrate, set in bits cannam@86: per second. If the bitrate would otherwise rise such that oversized cannam@86: frames would underflow the bit-reservoir by consuming banked bits, cannam@86: bitrate management will force the encoder to use fewer bits per frame cannam@86: by encoding with a more aggressive psychoacoustic model.
This cannam@86: setting is a hard limit; the bitstream will never be allowed, under cannam@86: any circumstances, to increase above the specified bitrate over the cannam@86: average period set by the reservoir; it may momentarily rise over if cannam@86: inspected on a granularity much finer than the average period across cannam@86: the reservoir. Normally, the encoder will conserve bits gracefully by cannam@86: using more aggressive psychoacoustics to shrink a frame when forced cannam@86: to. However, if the encoder runs out of means of gracefully shrinking cannam@86: a frame, it will simply take the smallest frame it can otherwise cannam@86: generate and truncate it to the maximum allowed length. Note that cannam@86: this is not an error and although it will obviously adversely affect cannam@86: audio quality, a Vorbis decoder will be able to decode a truncated cannam@86: frame into audio. cannam@86: cannam@86:
average bitrate cannam@86: cannam@86: The average desired bitrate of a stream, set cannam@86: in bits per second. Average bitrate is tracked via a reservoir like cannam@86: minimum and maximum bitrate, however the averaging reservior does not cannam@86: impose a hard limit; it is used to nudge the bitrate toward the cannam@86: desired average by slowly adjusting the psychoacoustic aggressiveness. cannam@86: As such, the reservoir size does not affect the average bitrate cannam@86: behavior. Because this setting alone is not used to impose hard cannam@86: bitrate limits, the bitrate of a stream produced using only the cannam@86: average bitrate constraint will track the average over time cannam@86: but not necessarily adhere strictly to that average for any given cannam@86: period. Should a strict localized average be required, average cannam@86: bitrate should be used along with minimum bitrate and cannam@86: maximum bitrate. cannam@86:
minimum bitrate cannam@86: The minimum allowed bitrate, set in bits per second. If cannam@86: the bitrate would otherwise fall such that undersized frames would cannam@86: overflow the bit-reservoir with unused bits, bitrate management will cannam@86: force the encoder to use more bits per frame by encoding with a less cannam@86: aggressive psychoacoustic model.
This setting is a hard limit; the cannam@86: bitstream will never be allowed, under any circumstances, to drop cannam@86: below the specified bitrate over the average period set by the cannam@86: reservoir; it may momentarily fall under if inspected on a granularity cannam@86: much finer than the average period across the reservoir. Normally, cannam@86: the encoder will fill out undersided frames with additional useful cannam@86: coding information by increasing the perceived quality of the stream. cannam@86: If the encoder runs out of useful ways to consume more bits, it will cannam@86: pad frames out with zeroes. cannam@86:
reservoir size The size of the minimum/maximum bitrate cannam@86: tracking reservoir, set in bits. The reservoir is used as a 'bit cannam@86: bank' to average out localized surges and dips in bitrate while cannam@86: providing predictable, guaranteed buffering behavior for streams to be cannam@86: used in situations with constrained transport bandwidth. The default cannam@86: setting is two seconds of average bitrate.
cannam@86: cannam@86: When a single frame is larger than the maximum allowed overall cannam@86: bitrate, the bits are 'borrowed' from the bitrate reservoir; if the cannam@86: reservoir contains insufficient bits to cover the defecit, the encoder cannam@86: must find some way to reduce the frame size.
cannam@86: cannam@86: When a frame is under the minimum limit, the surplus bits are placed cannam@86: into the reservoir, banking them for future use. If the reservoir is cannam@86: already full of banked bits, the encoder is forced to find some way to cannam@86: make the frame larger.
cannam@86: cannam@86: If the frame size is between the minimum and maximum rates (thus cannam@86: implying the minimum and maximum allowed rates are different), the cannam@86: reservoir gravitates toward a fill point configured by the cannam@86: reservoir bias setting described next. If the reservoir is cannam@86: fuller than the fill point (a 'surplus of surplus'), the encoder will cannam@86: consume a number bits from the reservoir equal to the number of the cannam@86: bits by which the frame exceeds minimum size. If the reservoir is cannam@86: emptier than the fillpoint (a 'surplus of defecit'), bits are returned cannam@86: to the reservoir equaling the current frame's number of bits under the cannam@86: maximum frame size. The idea of the fill point is to buffer against cannam@86: both underruns and overruns, by trying to hold the reservoir to a cannam@86: middle course. cannam@86:
reservoir bias cannam@86: cannam@86: Reservoir bias is a setting between 0.0 and 1.0 that biases bitrate cannam@86: management toward smoothing bitrate spikes (0.0) or bitrate peaks cannam@86: (1.0); the default setting is 0.1.
cannam@86: cannam@86: Using settings toward 0.0 causes the bitrate manager to hoard bits in cannam@86: the bit reservoir such that there is a large pool of banked surplus to cannam@86: draw upon during short spikes in bitrate. As a result, the encoder cannam@86: will react less aggressively and less drastically to curtail framesize cannam@86: during brief surges in bitrate.
cannam@86: cannam@86: Using settings toward 1.0 causes the bitrate manager to empty the bit cannam@86: reservoir such that there is a large buffer available to store surplus cannam@86: bits during sudden drops in bitrate. As a result, the encoder will cannam@86: react less aggressively and less drastically to support minimum frame cannam@86: sizes during drops in bitrate and will tend not to store any extra cannam@86: bits in the reservoir for future bitrate spikes.
cannam@86: cannam@86:
average track damping cannam@86: cannam@86: A decimal value, in seconds, that controls how quickly the average cannam@86: bitrate tracker is allowed to slew from enforcing minimum frame sizes cannam@86: to maximum framesizes and vice versa. Default value is 1.5 cannam@86: seconds.
cannam@86: cannam@86: When the 'average bitrate' setting is in use, the average bitrate cannam@86: tracker uses an unbounded reservoir to track overall bitrate-to-date cannam@86: in the stream. When bitrates are too low, the tracker will try to cannam@86: nudge bitrates up and when the bitrate is too high, nudge it down. cannam@86: The damping value regulates the maximum strength of the nudge; it cannam@86: describes, in seconds, how quickly the tracker may transition from an cannam@86: extreme nudge in one direction to an extreme nudge in the other.
cannam@86: cannam@86:
cannam@86: cannam@86:

encoding model adjustments

cannam@86: cannam@86: The vorbis_encode_ctl() call provides cannam@86: a generalized interface for making encoding setup adjustments to the cannam@86: basic high-level setup provided by vorbis_encode_setup_vbr() or vorbis_encode_setup_managed(). cannam@86: In reality, these two calls use vorbis_encode_ctl() internally, and vorbis_encode_ctl() can be used to adjust cannam@86: most of the parameters set by other calls.

cannam@86: cannam@86: In Vorbis 1.1, vorbis_encode_ctl() can cannam@86: adjust the following additional parameters not described elsewhere: cannam@86: cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

copyright © 2000-2010 Xiph.Org	Ogg Vorbis
libvorbisenc documentation	libvorbisenc version 1.3.2 - 20101101

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

parameter	description
management mode	Configures whether or not bitrate cannam@86: management is in use or not. Normally, this value is set implicitly cannam@86: during encoding setup; however, the supported means of selecting a cannam@86: quality mode by bitrate (that is, requesting a true VBR stream, but cannam@86: doing so by asking for an approximate bitrate) is to use vorbis_encode_setup_managed() cannam@86: and then to explicitly turn off bitrate management by calling vorbis_encode_ctl() with OV_ECTL_RATEMANAGE2_SET cannam@86:
coupling	Stereo encoding (and in the future, surround cannam@86: encodings) are normally encoded assuming the channels form a stereo cannam@86: image and that lossy-stereo modelling is appropriate; this is called cannam@86: 'coupling'. Stereo coupling may be explicitly enabled or disabled. cannam@86:
lowpass	Sets the hard lowpass of a given encoding mode; cannam@86: this may be used to conserve a few bits in high-rate audio that has cannam@86: limited bandwidth, or in testing of the encoder's acoustic model. The cannam@86: encoder is generally already configured with ideal lowpasses (if any cannam@86: at all) for given modes; use of this parameter is strongly discouraged cannam@86: if the point is to try to 'improve' a given encoding mode for general cannam@86: encoding. cannam@86:
impulse coding aggressiveness	By default, libvorbis cannam@86: attempts to compromise between preventing wide bitrate swings and cannam@86: high-resolution impulse coding (which is required for the crispest cannam@86: possible attacks, but also requires a relatively large momentary cannam@86: bitrate increase). This parameter allows an application to tune the cannam@86: compromise or eliminate it; A value of 0.0 indicates normal behavior cannam@86: while a value of -15.0 requests maximum possible impulse cannam@86: resolution.

parameter	description
sampling rate	cannam@86: The sampling rate (in samples per second) of the input audio. Common examples are 8000 for telephony, 44100 for CD audio and 48000 for DAT. Note that a mono sample (one center value) and a stereo sample (one left value and one right value) both are a single sample. cannam@86: cannam@86:
channels	cannam@86: cannam@86: The number of channels encoded in each input sample. By default, cannam@86: stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such cannam@86: that the stereo relationship between the samples is taken into account cannam@86: when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET. cannam@86: cannam@86:

parameter	description
maximum bitrate	The maximum allowed bitrate, set in bits cannam@86: per second. If the bitrate would otherwise rise such that oversized cannam@86: frames would underflow the bit-reservoir by consuming banked bits, cannam@86: bitrate management will force the encoder to use fewer bits per frame cannam@86: by encoding with a more aggressive psychoacoustic model. This cannam@86: setting is a hard limit; the bitstream will never be allowed, under cannam@86: any circumstances, to increase above the specified bitrate over the cannam@86: average period set by the reservoir; it may momentarily rise over if cannam@86: inspected on a granularity much finer than the average period across cannam@86: the reservoir. Normally, the encoder will conserve bits gracefully by cannam@86: using more aggressive psychoacoustics to shrink a frame when forced cannam@86: to. However, if the encoder runs out of means of gracefully shrinking cannam@86: a frame, it will simply take the smallest frame it can otherwise cannam@86: generate and truncate it to the maximum allowed length. Note that cannam@86: this is not an error and although it will obviously adversely affect cannam@86: audio quality, a Vorbis decoder will be able to decode a truncated cannam@86: frame into audio. cannam@86: cannam@86:
average bitrate	cannam@86: cannam@86: The average desired bitrate of a stream, set cannam@86: in bits per second. Average bitrate is tracked via a reservoir like cannam@86: minimum and maximum bitrate, however the averaging reservior does not cannam@86: impose a hard limit; it is used to nudge the bitrate toward the cannam@86: desired average by slowly adjusting the psychoacoustic aggressiveness. cannam@86: As such, the reservoir size does not affect the average bitrate cannam@86: behavior. Because this setting alone is not used to impose hard cannam@86: bitrate limits, the bitrate of a stream produced using only the cannam@86: `average bitrate` constraint will track the average over time cannam@86: but not necessarily adhere strictly to that average for any given cannam@86: period. Should a strict localized average be required, `average cannam@86: bitrate` should be used along with `minimum bitrate` and cannam@86: `maximum bitrate`. cannam@86:
minimum bitrate	cannam@86: The minimum allowed bitrate, set in bits per second. If cannam@86: the bitrate would otherwise fall such that undersized frames would cannam@86: overflow the bit-reservoir with unused bits, bitrate management will cannam@86: force the encoder to use more bits per frame by encoding with a less cannam@86: aggressive psychoacoustic model. This setting is a hard limit; the cannam@86: bitstream will never be allowed, under any circumstances, to drop cannam@86: below the specified bitrate over the average period set by the cannam@86: reservoir; it may momentarily fall under if inspected on a granularity cannam@86: much finer than the average period across the reservoir. Normally, cannam@86: the encoder will fill out undersided frames with additional useful cannam@86: coding information by increasing the perceived quality of the stream. cannam@86: If the encoder runs out of useful ways to consume more bits, it will cannam@86: pad frames out with zeroes. cannam@86:
reservoir size	The size of the minimum/maximum bitrate cannam@86: tracking reservoir, set in bits. The reservoir is used as a 'bit cannam@86: bank' to average out localized surges and dips in bitrate while cannam@86: providing predictable, guaranteed buffering behavior for streams to be cannam@86: used in situations with constrained transport bandwidth. The default cannam@86: setting is two seconds of average bitrate. cannam@86: cannam@86: When a single frame is larger than the maximum allowed overall cannam@86: bitrate, the bits are 'borrowed' from the bitrate reservoir; if the cannam@86: reservoir contains insufficient bits to cover the defecit, the encoder cannam@86: must find some way to reduce the frame size. cannam@86: cannam@86: When a frame is under the minimum limit, the surplus bits are placed cannam@86: into the reservoir, banking them for future use. If the reservoir is cannam@86: already full of banked bits, the encoder is forced to find some way to cannam@86: make the frame larger. cannam@86: cannam@86: If the frame size is between the minimum and maximum rates (thus cannam@86: implying the minimum and maximum allowed rates are different), the cannam@86: reservoir gravitates toward a fill point configured by the cannam@86: `reservoir bias` setting described next. If the reservoir is cannam@86: fuller than the fill point (a 'surplus of surplus'), the encoder will cannam@86: consume a number bits from the reservoir equal to the number of the cannam@86: bits by which the frame exceeds minimum size. If the reservoir is cannam@86: emptier than the fillpoint (a 'surplus of defecit'), bits are returned cannam@86: to the reservoir equaling the current frame's number of bits under the cannam@86: maximum frame size. The idea of the fill point is to buffer against cannam@86: both underruns and overruns, by trying to hold the reservoir to a cannam@86: middle course. cannam@86:
reservoir bias	cannam@86: cannam@86: Reservoir bias is a setting between 0.0 and 1.0 that biases bitrate cannam@86: management toward smoothing bitrate spikes (0.0) or bitrate peaks cannam@86: (1.0); the default setting is 0.1. cannam@86: cannam@86: Using settings toward 0.0 causes the bitrate manager to hoard bits in cannam@86: the bit reservoir such that there is a large pool of banked surplus to cannam@86: draw upon during short spikes in bitrate. As a result, the encoder cannam@86: will react less aggressively and less drastically to curtail framesize cannam@86: during brief surges in bitrate. cannam@86: cannam@86: Using settings toward 1.0 causes the bitrate manager to empty the bit cannam@86: reservoir such that there is a large buffer available to store surplus cannam@86: bits during sudden drops in bitrate. As a result, the encoder will cannam@86: react less aggressively and less drastically to support minimum frame cannam@86: sizes during drops in bitrate and will tend not to store any extra cannam@86: bits in the reservoir for future bitrate spikes. cannam@86: cannam@86:
average track damping	cannam@86: cannam@86: A decimal value, in seconds, that controls how quickly the average cannam@86: bitrate tracker is allowed to slew from enforcing minimum frame sizes cannam@86: to maximum framesizes and vice versa. Default value is 1.5 cannam@86: seconds. cannam@86: cannam@86: When the 'average bitrate' setting is in use, the average bitrate cannam@86: tracker uses an unbounded reservoir to track overall bitrate-to-date cannam@86: in the stream. When bitrates are too low, the tracker will try to cannam@86: nudge bitrates up and when the bitrate is too high, nudge it down. cannam@86: The damping value regulates the maximum strength of the nudge; it cannam@86: describes, in seconds, how quickly the tracker may transition from an cannam@86: extreme nudge in one direction to an extreme nudge in the other. cannam@86: cannam@86: