| <html> |
| |
| <head> |
| <title>libvorbisenc - API Overview</title> |
| <link rel=stylesheet href="style.css" type="text/css"> |
| </head> |
| |
| <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff"> |
| <table border=0 width=100%> |
| <tr> |
| <td><p class=tiny>libvorbisenc documentation</p></td> |
| <td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td> |
| </tr> |
| </table> |
| |
| <h1>Libvorbisenc API Overview</h1> |
| |
| <p>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. <p> |
| |
| All the <b>libvorbisenc</b> routines are declared in "vorbis/vorbisenc.h". |
| |
| <em>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 <a href="#BBR">"managed bitrate |
| modes"</a> for details on setting limits on bitrate usage when Vorbis |
| streams are used in a limited-bandwidth environment.</em> |
| |
| <h2>workflow</h2> |
| |
| <p>Libvorbisenc is used only during encoder setup; its function |
| is to automate initialization of a multitude of settings in a |
| <tt>vorbis_info</tt> structure which libvorbis then uses as a reference |
| during the encoding process. Libvorbisenc plays no part in the |
| encoding process after setup. |
| |
| <p>Encode setup using libvorbisenc consists of three steps: |
| |
| <ol> |
| <li>high-level initialization of a <tt>vorbis_info</tt> structure by |
| calling one of <a |
| href="vorbis_encode_setup_vbr.html">vorbis_encode_setup_vbr()</a> or <a |
| href="vorbis_encode_setup_managed.html">vorbis_encode_setup_managed()</a> |
| with the basic input audio parameters (rate and channels) and the |
| basic desired encoded audio output parameters (VBR quality or ABR/CBR |
| bitrate)<p> |
| |
| <li>optional adjustment of the basic setup defaults using <a |
| href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a><p> |
| |
| <li>calling <a |
| href="vorbis_encode_setup_init.html">vorbis_encode_setup_init()</a> to |
| finalize the high-level setup into the detailed low-level reference |
| values needed by libvorbis to encode audio. The <tt>vorbis_info</tt> |
| structure is then ready to use for encoding by libvorbis.<p> |
| |
| </ol> |
| |
| These three steps can be collapsed into a single call by using <a |
| href="vorbis_encode_init_vbr.html">vorbis_encode_init_vbr</a> to set up a |
| quality-based VBR stream or <a |
| href="vorbis_encode_init.html">vorbis_encode_init</a> to set up a managed |
| bitrate (ABR or CBR) stream.<p> |
| |
| <h2>adjustable encoding parameters</h2> |
| |
| <h3>input audio parameters</h3> |
| |
| <p> |
| <table border=1 color=black width=50% cellspacing=0 cellpadding=7> |
| <tr bgcolor=#cccccc> |
| <td><b>parameter</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign=top> |
| <td>sampling rate</td> |
| <td> |
| 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. |
| |
| </td> |
| </tr> |
| <tr valign=top> |
| <td>channels</td> |
| <td> |
| |
| 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 <a |
| href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> with <a |
| href="vorbis_encode_ctl.html#OV_ECTL_COUPLE_SET">OV_ECTL_COUPLE_SET</a>. |
| |
| </td> |
| </tr> |
| </table> |
| |
| <h3>quality and VBR modes</h3> |
| |
| Vorbis is natively a VBR codec; a user requests a given constant |
| <em>quality</em> 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. |
| |
| <p> |
| <table border=1 color=black width=50% cellspacing=0 cellpadding=7> |
| <tr bgcolor=#cccccc> |
| <td><b>parameter</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign=top> |
| <td>quality</td> |
| <td> |
| 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. |
| |
| </td> |
| </tr> |
| </table> |
| |
| <a name="BBR"> |
| <h3>managed bitrate modes</h3> |
| |
| 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 <em>only</em> 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.<p> |
| |
| Beginning in libvorbis 1.1, bitrate management is implemented using a |
| <em>bit-reservoir</em> 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. |
| |
| <p> |
| <table border=1 color=black width=50% cellspacing=0 cellpadding=7> |
| <tr bgcolor=#cccccc> |
| <td><b>parameter</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign=top> |
| <td>maximum bitrate</td> <td> 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.<p> 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. |
| |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>average bitrate</td> |
| |
| <td> |
| |
| The average desired bitrate of a stream, set |
| in bits per second. Average bitrate is tracked via a reservoir like |
| minimum and maximum bitrate, however the averaging reservior does not |
| impose a hard limit; it is used to nudge the bitrate toward the |
| desired average by slowly adjusting the psychoacoustic aggressiveness. |
| As such, the reservoir size does not affect the average bitrate |
| behavior. Because this setting alone is not used to impose hard |
| bitrate limits, the bitrate of a stream produced using only the |
| <tt>average bitrate</tt> constraint will track the average over time |
| but not necessarily adhere strictly to that average for any given |
| period. Should a strict localized average be required, <tt>average |
| bitrate</tt> should be used along with <tt>minimum bitrate</tt> and |
| <tt>maximum bitrate</tt>. |
| </td> |
| |
| </tr> |
| |
| <tr valign=top> |
| <td>minimum bitrate</td> |
| <td> |
| The minimum allowed bitrate, set in bits per second. If |
| the bitrate would otherwise fall such that undersized frames would |
| overflow the bit-reservoir with unused bits, bitrate management will |
| force the encoder to use more bits per frame by encoding with a less |
| aggressive psychoacoustic model.<p> This setting is a hard limit; the |
| bitstream will never be allowed, under any circumstances, to drop |
| below the specified bitrate over the average period set by the |
| reservoir; it may momentarily fall under if inspected on a granularity |
| much finer than the average period across the reservoir. Normally, |
| the encoder will fill out undersided frames with additional useful |
| coding information by increasing the perceived quality of the stream. |
| If the encoder runs out of useful ways to consume more bits, it will |
| pad frames out with zeroes. |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>reservoir size</td> <td> The size of the minimum/maximum bitrate |
| tracking reservoir, set in bits. The reservoir is used as a 'bit |
| bank' to average out localized surges and dips in bitrate while |
| providing predictable, guaranteed buffering behavior for streams to be |
| used in situations with constrained transport bandwidth. The default |
| setting is two seconds of average bitrate.<p> |
| |
| When a single frame is larger than the maximum allowed overall |
| bitrate, the bits are 'borrowed' from the bitrate reservoir; if the |
| reservoir contains insufficient bits to cover the defecit, the encoder |
| must find some way to reduce the frame size. <p> |
| |
| When a frame is under the minimum limit, the surplus bits are placed |
| into the reservoir, banking them for future use. If the reservoir is |
| already full of banked bits, the encoder is forced to find some way to |
| make the frame larger.<p> |
| |
| If the frame size is between the minimum and maximum rates (thus |
| implying the minimum and maximum allowed rates are different), the |
| reservoir gravitates toward a fill point configured by the |
| <tt>reservoir bias</tt> setting described next. If the reservoir is |
| fuller than the fill point (a 'surplus of surplus'), the encoder will |
| consume a number bits from the reservoir equal to the number of the |
| bits by which the frame exceeds minimum size. If the reservoir is |
| emptier than the fillpoint (a 'surplus of defecit'), bits are returned |
| to the reservoir equaling the current frame's number of bits under the |
| maximum frame size. The idea of the fill point is to buffer against |
| both underruns and overruns, by trying to hold the reservoir to a |
| middle course. |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>reservoir bias</td> |
| |
| <td> |
| |
| Reservoir bias is a setting between 0.0 and 1.0 that biases bitrate |
| management toward smoothing bitrate spikes (0.0) or bitrate peaks |
| (1.0); the default setting is 0.1.<p> |
| |
| Using settings toward 0.0 causes the bitrate manager to hoard bits in |
| the bit reservoir such that there is a large pool of banked surplus to |
| draw upon during short spikes in bitrate. As a result, the encoder |
| will react less aggressively and less drastically to curtail framesize |
| during brief surges in bitrate.<p> |
| |
| Using settings toward 1.0 causes the bitrate manager to empty the bit |
| reservoir such that there is a large buffer available to store surplus |
| bits during sudden drops in bitrate. As a result, the encoder will |
| react less aggressively and less drastically to support minimum frame |
| sizes during drops in bitrate and will tend not to store any extra |
| bits in the reservoir for future bitrate spikes.<p> |
| |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>average track damping</td> |
| <td> |
| |
| A decimal value, in seconds, that controls how quickly the average |
| bitrate tracker is allowed to slew from enforcing minimum frame sizes |
| to maximum framesizes and vice versa. Default value is 1.5 |
| seconds.<p> |
| |
| When the 'average bitrate' setting is in use, the average bitrate |
| tracker uses an unbounded reservoir to track overall bitrate-to-date |
| in the stream. When bitrates are too low, the tracker will try to |
| nudge bitrates up and when the bitrate is too high, nudge it down. |
| The damping value regulates the maximum strength of the nudge; it |
| describes, in seconds, how quickly the tracker may transition from an |
| extreme nudge in one direction to an extreme nudge in the other.<p> |
| |
| </td> |
| </tr> |
| |
| </table> |
| |
| <h3>encoding model adjustments</h3> |
| |
| The <a href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> call provides |
| a generalized interface for making encoding setup adjustments to the |
| basic high-level setup provided by <a |
| href="vorbis_encode_setup_vbr.html">vorbis_encode_setup_vbr()</a> or <a |
| href="vorbis_encode_setup_managed.html">vorbis_encode_setup_managed()</a>. |
| In reality, these two calls use <a |
| href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> internally, and <a |
| href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> can be used to adjust |
| most of the parameters set by other calls.<p> |
| |
| In Vorbis 1.1, <a href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> can |
| adjust the following additional parameters not described elsewhere: |
| |
| <p> |
| <table border=1 color=black width=50% cellspacing=0 cellpadding=7> |
| <tr bgcolor=#cccccc> |
| <td><b>parameter</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign=top> |
| <td>management mode</td> <td> Configures whether or not bitrate |
| management is in use or not. Normally, this value is set implicitly |
| during encoding setup; however, the supported means of selecting a |
| quality mode by bitrate (that is, requesting a true VBR stream, but |
| doing so by asking for an approximate bitrate) is to use <a |
| href="vorbis_encode_setup_managed.html">vorbis_encode_setup_managed()</a> |
| and then to explicitly turn off bitrate management by calling <a |
| href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> with <a |
| href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_SET">OV_ECTL_RATEMANAGE2_SET</a> |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>coupling</td> <td> Stereo encoding (and in the future, surround |
| encodings) are normally encoded assuming the channels form a stereo |
| image and that lossy-stereo modelling is appropriate; this is called |
| 'coupling'. Stereo coupling may be explicitly enabled or disabled. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td>lowpass</td> <td> Sets the hard lowpass of a given encoding mode; |
| this may be used to conserve a few bits in high-rate audio that has |
| limited bandwidth, or in testing of the encoder's acoustic model. The |
| encoder is generally already configured with ideal lowpasses (if any |
| at all) for given modes; use of this parameter is strongly discouraged |
| if the point is to try to 'improve' a given encoding mode for general |
| encoding. |
| </td> |
| </tr> |
| |
| <tr valign=top> |
| <td>impulse coding aggressiveness</td> <td>By default, libvorbis |
| attempts to compromise between preventing wide bitrate swings and |
| high-resolution impulse coding (which is required for the crispest |
| possible attacks, but also requires a relatively large momentary |
| bitrate increase). This parameter allows an application to tune the |
| compromise or eliminate it; A value of 0.0 indicates normal behavior |
| while a value of -15.0 requests maximum possible impulse |
| resolution.</td> |
| </tr> |
| |
| </table> |
| |
| |
| <br><br> |
| <hr noshade> |
| <table border=0 width=100%> |
| <tr valign=top> |
| <td><p class=tiny>copyright © 2004 Vorbis team</p></td> |
| <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td> |
| </tr><tr> |
| <td><p class=tiny>libvorbisenc documentation</p></td> |
| <td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td> |
| </tr> |
| </table> |
| |
| </body> |
| |
| </html> |
| |