<ol>
<li>high-level initialization of a <tt>vorbis_info</tt> structure by
calling one of <a
-href="vorbis_encode_setup_vbr">vorbis_encode_setup_vbr()</a> or <a
-href="vorbis_encode_setup_managed">vorbis_encode_setup_managed()</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">vorbis_encode_ctl()</a><p>
+href="vorbis_encode_ctl
.html">vorbis_encode_ctl()</a><p>
<li>calling <a
-href="vorbis_encode_setup_init">vorbis_encode_setup_init()</a> to
+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">vorbis_encode_init_vbr</a> to set up 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">vorbis_encode_init</a> to set up a managed
+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>
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">vorbis_encode_ctl()</a> with <a
-href="vorbis_encode_ctl#OV_ECTL_COUPLE_SET">OV_ECTL_COUPLE_SET</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>
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).<p>
+(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
<td><b>description</b></td>
</tr>
<tr valign=top>
-<td>minimum bitrate</td>
-<td> </td>
+<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>
+<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>maximum bitrate</td>
+<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>
-
+<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>
+
+<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>
<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>
<h3>encoding model adjustments</h3>
-The <a href="vorbis_encode_ctl">vorbis_encode_ctl()</a> call provides
+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">vorbis_encode_setup_vbr()</a> or <a
-href="vorbis_encode_setup_managed">vorbis_encode_setup_managed()</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">vorbis_encode_ctl()</a> internally, and <a
-href="vorbis_encode_ctl">vorbis_encode_ctl()</a> can be used to adjust
+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">vorbis_encode_ctl()</a> can
+In Vorbis 1.1, <a href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> can
adjust the following additional parameters not described elsewhere:
<p>
<td><b>description</b></td>
</tr>
<tr valign=top>
-<td>management mode</td>
-<td> </td>
+<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> </td>
+<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> </td>
+<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> </td>
+<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>
projects / platform / upstream / libvorbis.git / commitdiff