From b469e989858394b53c4bf3048382d53412ed2179 Mon Sep 17 00:00:00 2001 From: Monty Date: Fri, 9 Jul 2004 08:34:39 +0000 Subject: [PATCH] Work in progress: documentation update for libvorbisenc svn path=/trunk/vorbis/; revision=7068 --- doc/vorbisenc/overview.html | 231 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 215 insertions(+), 16 deletions(-) diff --git a/doc/vorbisenc/overview.html b/doc/vorbisenc/overview.html index 3244c9c..1f00c54 100644 --- a/doc/vorbisenc/overview.html +++ b/doc/vorbisenc/overview.html @@ -9,50 +9,249 @@ - +

libvorbisenc documentation

libvorbisenc version 1.1.2.2 - 20001104

libvorbisenc release 1.1 - 20040709

Libvorbisenc API Overview

-

The current version of libvorbisenc is very simple. It contains an initialization function to set up the encoding engine properly. -It also contains a control function to be used in the future to tweak encoder settings. -

+

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: + +

    +
  1. 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)

    + +

  2. optional adjustment of the basic setup defaults using vorbis_encode_ctl()

    + +

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

+

- - + + - - + + - - + + + +
functionpurposeparameterdescription
vorbis_encode_initThis function takes a vorbis_info struct and encoding parameters and sets up a proper encoding environment..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. + +
vorbis_encode_init_vbrThis function takes a vorbis_info struct -and encoding parameters for VBR encoding.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. + +

+ + + + - - + +
parameterdescription
vorbis_encode_ctlFunction in progress, to be used in future versions of this API.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).

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parameterdescription
minimum bitrate
average bitrate + +
maximum bitrate + +
reservoir size + +
reservoir bias + +
average track damping + +
+ +

encoding model adjustments

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

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

+ + + + + + + + + + + + + + + + + + + + + + + + + +
parameterdescription
management mode
coupling
lowpass
impulse coding aggressiveness
+ +

- + - - + +

copyright © 2000 vorbis team

copyright © 2004 Vorbis team

Ogg Vorbis
team@vorbis.org

vorbisfile documentation

vorbisfile version 1.25 - 20000615

libvorbisenc documentation

libvorbisenc release 1.1 - 20040709
+ -- 2.7.4