Libvorbisenc API Overview

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

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

workflow

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

Encode setup using libvorbisenc consists of three steps:

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

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

adjustable encoding parameters

input audio parameters

parameter description

sampling rate 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.

channels The number of channels encoded in each input sample. By default, stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such that the stereo relationship between the samples is taken into account when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET.

quality and VBR modes

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

parameter description

quality 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.

managed bitrate modes

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

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

parameter description

maximum bitrate The maximum allowed bitrate, set in bits per second. If the bitrate would otherwise rise such that oversized frames would underflow the bit-reservoir by consuming banked bits, bitrate management will force the encoder to use fewer bits per frame by encoding with a more aggressive psychoacoustic model.
This setting is a hard limit; the bitstream will never be allowed, under any circumstances, to increase above the specified bitrate over the average period set by the reservoir; it may momentarily rise over if inspected on a granularity much finer than the average period across the reservoir. Normally, the encoder will conserve bits gracefully by using more aggressive psychoacoustics to shrink a frame when forced to. However, if the encoder runs out of means of gracefully shrinking a frame, it will simply take the smallest frame it can otherwise generate and truncate it to the maximum allowed length. Note that this is not an error and although it will obviously adversely affect audio quality, a Vorbis decoder will be able to decode a truncated frame into audio.

average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top> average bitrate The average desired bitrate of a stream, set in bits per second. Ar valign=top>

parameter	description
sampling rate	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.
channels	The number of channels encoded in each input sample. By default, stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such that the stereo relationship between the samples is taken into account when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET.