libvorbisenc documentation |
Chris@1: libvorbisenc version 1.3.2 - 20101101 |
Chris@1:
Libvorbisenc is an encoding convenience library intended to Chris@1: encapsulate the elaborate setup that libvorbis requires for encoding. Chris@1: Libvorbisenc gives easy access to all high-level adjustments an Chris@1: application may require when encoding and also exposes some low-level Chris@1: tuning parameters to allow applications to make detailed adjustments Chris@1: to the encoding process.
Chris@1: Chris@1: All the libvorbisenc routines are declared in "vorbis/vorbisenc.h". Chris@1: Chris@1: Note: libvorbis and libvorbisenc always Chris@1: encode in a single pass. Thus, all possible encoding setups will work Chris@1: properly with live input and produce streams that decode properly when Chris@1: streamed. See the subsection titled "managed bitrate Chris@1: modes" for details on setting limits on bitrate usage when Vorbis Chris@1: streams are used in a limited-bandwidth environment. Chris@1: Chris@1:
Libvorbisenc is used only during encoder setup; its function Chris@1: is to automate initialization of a multitude of settings in a Chris@1: vorbis_info structure which libvorbis then uses as a reference Chris@1: during the encoding process. Libvorbisenc plays no part in the Chris@1: encoding process after setup. Chris@1: Chris@1:
Encode setup using libvorbisenc consists of three steps: Chris@1: Chris@1:
Chris@1: Chris@1:
Chris@1: Chris@1:
Chris@1: Chris@1:
Chris@1: Chris@1:
Chris@1:
| parameter | Chris@1:description | Chris@1:
| sampling rate | Chris@1:Chris@1: 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. Chris@1: Chris@1: | Chris@1:
| channels | Chris@1:Chris@1: Chris@1: The number of channels encoded in each input sample. By default, Chris@1: stereo input modes (two channels) are 'coupled' by Vorbis 1.1 such Chris@1: that the stereo relationship between the samples is taken into account Chris@1: when encoding. Stereo coupling my be disabled by using vorbis_encode_ctl() with OV_ECTL_COUPLE_SET. Chris@1: Chris@1: | Chris@1:
Chris@1:
| parameter | Chris@1:description | Chris@1:
| quality | Chris@1:Chris@1: 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. Chris@1: Chris@1: | Chris@1:
Chris@1: Chris@1: Beginning in libvorbis 1.1, bitrate management is implemented using a Chris@1: bit-reservoir algorithm. The encoder has a fixed-size Chris@1: reservoir used as a 'savings account' in encoding. When a frame is Chris@1: smaller than the target rate, the unused bits go into the reservoir so Chris@1: that they may be used by future frames. When a frame is larger than Chris@1: target bitrate, it draws 'banked' bits out of the reservoir. Encoding Chris@1: is managed so that the reservoir never goes negative (when a maximum Chris@1: bitrate is specified) or fills beyond a fixed limit (when a minimum Chris@1: bitrate is specified). An 'average bitrate' request is used as the Chris@1: set-point in a long-range bitrate tracker which adjusts the encoder's Chris@1: aggressiveness up or down depending on whether or not frames are coming Chris@1: in larger or smaller than the requested average point. Chris@1: Chris@1:
Chris@1:
| parameter | Chris@1:description | Chris@1:
| maximum bitrate | The maximum allowed bitrate, set in bits
Chris@1: per second. If the bitrate would otherwise rise such that oversized
Chris@1: frames would underflow the bit-reservoir by consuming banked bits,
Chris@1: bitrate management will force the encoder to use fewer bits per frame
Chris@1: by encoding with a more aggressive psychoacoustic model. This Chris@1: setting is a hard limit; the bitstream will never be allowed, under Chris@1: any circumstances, to increase above the specified bitrate over the Chris@1: average period set by the reservoir; it may momentarily rise over if Chris@1: inspected on a granularity much finer than the average period across Chris@1: the reservoir. Normally, the encoder will conserve bits gracefully by Chris@1: using more aggressive psychoacoustics to shrink a frame when forced Chris@1: to. However, if the encoder runs out of means of gracefully shrinking Chris@1: a frame, it will simply take the smallest frame it can otherwise Chris@1: generate and truncate it to the maximum allowed length. Note that Chris@1: this is not an error and although it will obviously adversely affect Chris@1: audio quality, a Vorbis decoder will be able to decode a truncated Chris@1: frame into audio. Chris@1: Chris@1: |
Chris@1:
| average bitrate | Chris@1: Chris@1:Chris@1: Chris@1: The average desired bitrate of a stream, set Chris@1: in bits per second. Average bitrate is tracked via a reservoir like Chris@1: minimum and maximum bitrate, however the averaging reservior does not Chris@1: impose a hard limit; it is used to nudge the bitrate toward the Chris@1: desired average by slowly adjusting the psychoacoustic aggressiveness. Chris@1: As such, the reservoir size does not affect the average bitrate Chris@1: behavior. Because this setting alone is not used to impose hard Chris@1: bitrate limits, the bitrate of a stream produced using only the Chris@1: average bitrate constraint will track the average over time Chris@1: but not necessarily adhere strictly to that average for any given Chris@1: period. Should a strict localized average be required, average Chris@1: bitrate should be used along with minimum bitrate and Chris@1: maximum bitrate. Chris@1: | Chris@1: Chris@1:
| minimum bitrate | Chris@1:
Chris@1: The minimum allowed bitrate, set in bits per second. If
Chris@1: the bitrate would otherwise fall such that undersized frames would
Chris@1: overflow the bit-reservoir with unused bits, bitrate management will
Chris@1: force the encoder to use more bits per frame by encoding with a less
Chris@1: aggressive psychoacoustic model. This setting is a hard limit; the Chris@1: bitstream will never be allowed, under any circumstances, to drop Chris@1: below the specified bitrate over the average period set by the Chris@1: reservoir; it may momentarily fall under if inspected on a granularity Chris@1: much finer than the average period across the reservoir. Normally, Chris@1: the encoder will fill out undersided frames with additional useful Chris@1: coding information by increasing the perceived quality of the stream. Chris@1: If the encoder runs out of useful ways to consume more bits, it will Chris@1: pad frames out with zeroes. Chris@1: |
Chris@1:
| reservoir size | The size of the minimum/maximum bitrate
Chris@1: tracking reservoir, set in bits. The reservoir is used as a 'bit
Chris@1: bank' to average out localized surges and dips in bitrate while
Chris@1: providing predictable, guaranteed buffering behavior for streams to be
Chris@1: used in situations with constrained transport bandwidth. The default
Chris@1: setting is two seconds of average bitrate. Chris@1: Chris@1: When a single frame is larger than the maximum allowed overall Chris@1: bitrate, the bits are 'borrowed' from the bitrate reservoir; if the Chris@1: reservoir contains insufficient bits to cover the defecit, the encoder Chris@1: must find some way to reduce the frame size. Chris@1: Chris@1: When a frame is under the minimum limit, the surplus bits are placed Chris@1: into the reservoir, banking them for future use. If the reservoir is Chris@1: already full of banked bits, the encoder is forced to find some way to Chris@1: make the frame larger. Chris@1: Chris@1: If the frame size is between the minimum and maximum rates (thus Chris@1: implying the minimum and maximum allowed rates are different), the Chris@1: reservoir gravitates toward a fill point configured by the Chris@1: reservoir bias setting described next. If the reservoir is Chris@1: fuller than the fill point (a 'surplus of surplus'), the encoder will Chris@1: consume a number bits from the reservoir equal to the number of the Chris@1: bits by which the frame exceeds minimum size. If the reservoir is Chris@1: emptier than the fillpoint (a 'surplus of defecit'), bits are returned Chris@1: to the reservoir equaling the current frame's number of bits under the Chris@1: maximum frame size. The idea of the fill point is to buffer against Chris@1: both underruns and overruns, by trying to hold the reservoir to a Chris@1: middle course. Chris@1: |
Chris@1:
| reservoir bias | Chris@1: Chris@1:
Chris@1:
Chris@1: Reservoir bias is a setting between 0.0 and 1.0 that biases bitrate
Chris@1: management toward smoothing bitrate spikes (0.0) or bitrate peaks
Chris@1: (1.0); the default setting is 0.1. Chris@1: Chris@1: Using settings toward 0.0 causes the bitrate manager to hoard bits in Chris@1: the bit reservoir such that there is a large pool of banked surplus to Chris@1: draw upon during short spikes in bitrate. As a result, the encoder Chris@1: will react less aggressively and less drastically to curtail framesize Chris@1: during brief surges in bitrate. Chris@1: Chris@1: Using settings toward 1.0 causes the bitrate manager to empty the bit Chris@1: reservoir such that there is a large buffer available to store surplus Chris@1: bits during sudden drops in bitrate. As a result, the encoder will Chris@1: react less aggressively and less drastically to support minimum frame Chris@1: sizes during drops in bitrate and will tend not to store any extra Chris@1: bits in the reservoir for future bitrate spikes. Chris@1: Chris@1: |
Chris@1:
| average track damping | Chris@1:
Chris@1:
Chris@1: A decimal value, in seconds, that controls how quickly the average
Chris@1: bitrate tracker is allowed to slew from enforcing minimum frame sizes
Chris@1: to maximum framesizes and vice versa. Default value is 1.5
Chris@1: seconds. Chris@1: Chris@1: When the 'average bitrate' setting is in use, the average bitrate Chris@1: tracker uses an unbounded reservoir to track overall bitrate-to-date Chris@1: in the stream. When bitrates are too low, the tracker will try to Chris@1: nudge bitrates up and when the bitrate is too high, nudge it down. Chris@1: The damping value regulates the maximum strength of the nudge; it Chris@1: describes, in seconds, how quickly the tracker may transition from an Chris@1: extreme nudge in one direction to an extreme nudge in the other. Chris@1: Chris@1: |
Chris@1:
Chris@1: Chris@1: In Vorbis 1.1, vorbis_encode_ctl() can Chris@1: adjust the following additional parameters not described elsewhere: Chris@1: Chris@1:
Chris@1:
| parameter | Chris@1:description | Chris@1:
| management mode | Configures whether or not bitrate Chris@1: management is in use or not. Normally, this value is set implicitly Chris@1: during encoding setup; however, the supported means of selecting a Chris@1: quality mode by bitrate (that is, requesting a true VBR stream, but Chris@1: doing so by asking for an approximate bitrate) is to use vorbis_encode_setup_managed() Chris@1: and then to explicitly turn off bitrate management by calling vorbis_encode_ctl() with OV_ECTL_RATEMANAGE2_SET Chris@1: | Chris@1:
| coupling | Stereo encoding (and in the future, surround Chris@1: encodings) are normally encoded assuming the channels form a stereo Chris@1: image and that lossy-stereo modelling is appropriate; this is called Chris@1: 'coupling'. Stereo coupling may be explicitly enabled or disabled. Chris@1: | Chris@1:
| lowpass | Sets the hard lowpass of a given encoding mode; Chris@1: this may be used to conserve a few bits in high-rate audio that has Chris@1: limited bandwidth, or in testing of the encoder's acoustic model. The Chris@1: encoder is generally already configured with ideal lowpasses (if any Chris@1: at all) for given modes; use of this parameter is strongly discouraged Chris@1: if the point is to try to 'improve' a given encoding mode for general Chris@1: encoding. Chris@1: | Chris@1:
| impulse coding aggressiveness | By default, libvorbis Chris@1: attempts to compromise between preventing wide bitrate swings and Chris@1: high-resolution impulse coding (which is required for the crispest Chris@1: possible attacks, but also requires a relatively large momentary Chris@1: bitrate increase). This parameter allows an application to tune the Chris@1: compromise or eliminate it; A value of 0.0 indicates normal behavior Chris@1: while a value of -15.0 requests maximum possible impulse Chris@1: resolution. | Chris@1:
copyright © 2000-2010 Xiph.Org |
Chris@1: Chris@1: |
libvorbisenc documentation |
Chris@1: libvorbisenc version 1.3.2 - 20101101 |
Chris@1: