[xiph-commits] r7450 - trunk/vorbis/doc/vorbisenc
xiphmont at motherfish-iii.xiph.org
xiphmont
Thu Aug 5 19:06:51 PDT 2004
Author: xiphmont
Date: Thu Aug 5 19:06:51 2004
New Revision: 7450
Added:
trunk/vorbis/doc/vorbisenc/changes.html
trunk/vorbis/doc/vorbisenc/examples.html
Modified:
trunk/vorbis/doc/vorbisenc/index.html
trunk/vorbis/doc/vorbisenc/overview.html
trunk/vorbis/doc/vorbisenc/reference.html
trunk/vorbis/doc/vorbisenc/vorbis_info.html
Log:
Incremental update to avoid losing ongoing work
Added: trunk/vorbis/doc/vorbisenc/changes.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/changes.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/changes.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -0,0 +1,104 @@
+<html>
+
+<head>
+<title>libvorbisenc - Documentation</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 changes 1.0 through 1.1</h1>
+
+This document describes API additions to libvorbisenc between release
+1.0 and 1.1.
+
+<h2>1.0.1</h2>
+
+The programming API and binary application ABI are unchanged and fully
+forward/backward compatible between release 1.0 and 1.0.1. Libvorbis,
+libvorbisenc and libvorbisfile must match versions amongst themselves,
+however.
+
+<h2>1.1</h2>
+
+The binary ABI from release 1.0.1 to 1.1 is backward compatible;
+applications linked against libvorbis/libvorbisenc 1.0 and 1.0.1 will
+continue to function correctly when upgrading the libvorbis and
+libvorbisenc dynamic libraries without re-linking. <p>
+
+Release 1.1 adds several possible requests to the libvorbisenc <a
+href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> call in order to
+reflect the shift to <a href="overview.html#BBR">bit-reservoir style
+bitrate management</a>. In addition, several <a
+href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a> requests are
+deprecated (but functional) as they are redered semantically obsolete
+by the <a href="overview.html#BBR">new bitrate management</a>.<p>
+
+<h3>Deprecated in 1.1</h3>
+
+These calls are still available to older codebases to preserve
+compatability; the fields of the <a
+href="ovectl_ratemanage_arg.html">ovectl_ratemanage_arg</a> argument
+are mapped as closely as possible to the fields of the new <a
+href="ovectl_ratemanage2_arg.html">ovectl_ratemanage2_arg</a>
+structure.
+
+<dl>
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE_GET">OV_ECTL_RATEMANAGE_GET</a>:<dd> Use <a
+href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_GET">OV_ECTL_RATEMANAGE2_GET</a>
+instead.
+
+
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE_SET">OV_ECTL_RATEMANAGE_SET</a>:<dd> Use <a
+href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_SET">OV_ECTL_RATEMANAGE2_SET</a>
+instead.
+
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE_AVG">OV_ECTL_RATEMANAGE_AVG</a>:<dd> Use <a
+href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_SET">OV_ECTL_RATEMANAGE2_SET</a>
+instead.
+
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE_HARD">OV_ECTL_RATEMANAGE_HARD</a>:<dd> Use <a
+href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_SET">OV_ECTL_RATEMANAGE2_SET</a>
+instead.
+</dl>
+
+<h3>Newly added in 1.1</h3>
+
+The following calls are added in 1.1 to semantically reflect movement
+to a <a href="overview.html#BBR">bit-reservoir-based bitrate
+management</a> scheme by introducing the <a
+href="ovectl_ratemanage2_arg.html">ovectl_ratemanage2_arg</a>
+structure in order to better represent the abilities of the bitrate
+manager.<p>
+
+<dl>
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_GET">OV_ECTL_RATEMANAGE2_GET</a><dd>
+
+Used to query the current state of bitrate management setup.
+
+<dt><a href="vorbis_encode_ctl.html#OV_ECTL_RATEMANAGE2_SET">OV_ECTL_RATEMANAGE2_SET</a><dd>
+
+Used to set or alter bitrate management settings.
+</dl>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright © 2000-2004 vorbis team</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at 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>
Added: trunk/vorbis/doc/vorbisenc/examples.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/examples.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/examples.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -0,0 +1,133 @@
+<html>
+
+<head>
+<title>libvorbisenc - Documentation</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 Setup Examples</h1>
+
+VBR is always the recommended mode for Vorbis encoding when
+there's no need to impose bitrate constraints. True VBR encoding will
+always produce the most consistent quality output as well as the
+highest quality for a the bits used.
+
+<p>The following code examples prepare a
+<a href="vorbis_info.html">vorbis_info</a> structure for encoding
+use with libvorbis.<p>
+
+<h2>Example: encoding using a VBR quality mode</h2>
+
+<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc><td><pre><b>
+ vorbis_info_init(&vi);
+
+ /*********************************************************************
+ Encoding using a VBR quality mode. The usable range is -.1
+ (lowest quality, smallest file) to 1.0 (highest quality, largest file).
+ Example quality mode .4: 44kHz stereo coupled, roughly 128kbps VBR
+ *********************************************************************/
+
+ ret = vorbis_encode_init_vbr(&vi,2,44100,.4);
+
+ /*********************************************************************
+ do not continue if setup failed; this can happen if we ask for a
+ mode that libVorbis does not support (eg, too low a quality mode, etc,
+ will return 'OV_EIMPL')
+ *********************************************************************/
+
+ if(ret) exit(1);
+</b></pre></td></tr></table>
+
+<h2>Example: encoding using average bitrate (ABR)</h2>
+
+<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc><td><pre><b>
+ vorbis_info_init(&vi);
+
+ /*********************************************************************
+ Encoding using an average bitrate mode (ABR).
+ example: 44kHz stereo coupled, average 128kbps ABR
+ *********************************************************************/
+
+ ret = vorbis_encode_init(&vi,2,44100,-1,128000,-1);
+
+ /*********************************************************************
+ do not continue if setup failed; this can happen if we ask for a
+ mode that libVorbis does not support (eg, too low a bitrate, etc,
+ will return 'OV_EIMPL')
+ *********************************************************************/
+
+ if(ret) exit(1);
+</b></pre></td></tr></table>
+
+<h2>Example: encoding using constant bitrate (CBR)</h2>
+
+<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc><td><pre><b>
+ vorbis_info_init(&vi);
+
+ /*********************************************************************
+ Encoding using a constant bitrate mode (CBR).
+ example: 44kHz stereo coupled, average 128kbps CBR
+ *********************************************************************/
+
+ ret = vorbis_encode_init(&vi,2,44100,128000,128000,128000);
+
+ /*********************************************************************
+ do not continue if setup failed; this can happen if we ask for a
+ mode that libVorbis does not support (eg, too low a bitrate, etc,
+ will return 'OV_EIMPL')
+ *********************************************************************/
+
+ if(ret) exit(1);
+</b></pre></td></tr></table>
+
+<h2>Example: encoding using VBR sleected by approximate bitrate</h2>
+
+<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc><td><pre><b>
+ vorbis_info_init(&vi);
+
+ /*********************************************************************
+ Encode using a quality mode, but select that quality mode by asking for
+ an approximate bitrate. This is not ABR, it is true VBR, but selected
+ using the bitrate interface, and then turning bitrate management off:
+ *********************************************************************/
+
+ ret = ( vorbis_encode_setup_managed(&vi,2,44100,-1,128000,-1) ||
+ vorbis_encode_ctl(&vi,OV_ECTL_RATEMANAGE2_SET,NULL) ||
+ vorbis_encode_setup_init(&vi));
+
+ /*********************************************************************
+ do not continue if setup failed; this can happen if we ask for a
+ mode that libVorbis does not support (eg, too low a bitrate, etc,
+ will return 'OV_EIMPL')
+ *********************************************************************/
+
+ if(ret) exit(1);
+</b></pre></td></tr></table>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright © 2000-2004 vorbis team</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at 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>
Modified: trunk/vorbis/doc/vorbisenc/index.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/index.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/index.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -21,6 +21,7 @@
<a href="overview.html">libvorbisenc api overview</a><br>
<a href="reference.html">libvorbisenc api reference</a><br>
<a href="changes.html">libvorbisenc api changes from 1.0 and 1.0.1</a><br>
+<a href="examples.html">libvorbisenc encode setup examples</a><br>
<br><br>
<hr noshade>
Modified: trunk/vorbis/doc/vorbisenc/overview.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/overview.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/overview.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -339,7 +339,6 @@
'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
Modified: trunk/vorbis/doc/vorbisenc/reference.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/reference.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/reference.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisenc documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.0</p></td>
+<td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
</tr>
</table>
@@ -18,21 +18,28 @@
<p>
<b>Data Structures</b><br>
<a href="vorbis_info.html">vorbis_info</a><br>
+<a href="ov_ectl_ratemanage_arg.html">ov_ectl_ratemanage_arg</a><br>
+<a href="ov_ectl_ratemanage2_arg.html">ov_ectl_ratemanage2_arg</a><br>
+
<br>
<b>Encoder Setup</b><br>
+<a href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a><br>
<a href="vorbis_encode_init.html">vorbis_encode_init()</a><br>
<a href="vorbis_encode_init_vbr.html">vorbis_encode_init_vbr()</a><br>
-<a href="vorbis_encode_ctl.html">vorbis_encode_ctl()</a><br>
+<a href="vorbis_encode_setup_init.html">vorbis_encode_setup_init()</a><br>
+<a href="vorbis_encode_setup_managed.html">vorbis_encode_setup_managed()</a><br>
+<a href="vorbis_encode_setup_vbr.html">vorbis_encode_setup_vbr()</a><br>
+
<br>
<br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
-<td><p class=tiny>copyright © 2003 vorbis team</p></td>
+<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 at vorbis.org">team at vorbis.org</a></p></td>
</tr><tr>
-<td><p class=tiny>vorbisenc documentation</p></td>
-<td align=right><p class=tiny>vorbisenc version 1.0</p></td>
+<td><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
+<td align=right><p class=tiny>vorbisenc version 1.1</p></td>
</tr>
</table>
Modified: trunk/vorbis/doc/vorbisenc/vorbis_info.html
===================================================================
--- trunk/vorbis/doc/vorbisenc/vorbis_info.html 2004-08-02 04:54:20 UTC (rev 7449)
+++ trunk/vorbis/doc/vorbisenc/vorbis_info.html 2004-08-02 06:59:25 UTC (rev 7450)
@@ -8,8 +8,8 @@
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>libvorbisenc documentation</p></td>
+<td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
</tr>
</table>
@@ -18,7 +18,7 @@
<p><i>declared in "vorbis/codec.h"</i></p>
<p>
-The vorbis_info structure contains information about a vorbis bitstream. Most of the information in this struct is more complex and in-depth than we need when using basic API calls.
+The vorbis_info structure contains information about a vorbis bitstream.
<p>
@@ -33,34 +33,10 @@
long bitrate_upper;
long bitrate_nominal;
long bitrate_lower;
+ long bitrate_window;
- long blocksizes[2];
+ void *codec_setup;
- int modes;
- int maps;
- int times;
- int floors;
- int residues;
- int books;
- int psys; /* encode only */
-
- vorbis_info_mode *mode_param[64];
- int map_type[64];
- vorbis_info_mapping *map_param[64];
- int time_type[64];
- vorbis_info_time *time_param[64];
- int floor_type[64];
- vorbis_info_floor *floor_param[64];
- int residue_type[64];
- vorbis_info_residue *residue_param[64];
- static_codebook *book_param[256];
- vorbis_info_psy *psy_param[64]; /* encode only */
-
- /* for block long/sort tuning; encode only */
- int envelopesa;
- double preecho_thresh;
- double preecho_clamp;
-
} vorbis_info;</b></pre>
</td>
</tr>
@@ -80,8 +56,10 @@
<dd>Specifies the average bitrate for a VBR bitstream. May be unset. If the bitrate_upper and bitrate_lower parameters match, the stream is fixed bitrate.</dd>
<dt><i>bitrate_lower</i></dt>
<dd>Specifies the lower limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_upper parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
-<dt><i>blocksizes[2]</i></dt>
-<dd>Contains the sizes of the long and short blocks for this particular bitstream. These are variable and can be set by the encoder. Vorbis only supports two sizes, long and short.</dd>
+<dt><i>bitrate_window</i></dt>
+<dd>Specifies the size of the bit reservoir in /
+lower limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_upper parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
+
</dl>
@@ -89,11 +67,11 @@
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
-<td><p class=tiny>copyright © 2000 vorbis team</p></td>
+<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 at vorbis.org">team at vorbis.org</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
</tr>
</table>
More information about the commits
mailing list