Commit 1028f159 authored by Ralph Giles's avatar Ralph Giles
Browse files

Add rough reference documentation for the main encoding calls.

These are a bit rough in that the main calls are declared in codec.h,
and not vorbisenc.h as one might expect for the encoder. Nevertheless
I felt this was helpful to those trying to use the encoder since there
is no 'Programming with libvorbis' documenation at all.

The error return values listed don't entirely match what the code will
actually provide, but they're all good ones to check for anyway.

Note of the new pages have hyperlinked function or structure names.

svn path=/trunk/vorbis/; revision=16756
parent cd6c4cf7
......@@ -15,20 +15,46 @@
<h1>Vorbisenc API Reference</h1>
<h2>Data Structures</h2>
<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>
</p>
<br>
<b>Encoder Setup</b><br>
<h2>Encoder Setup</h2>
<p>
<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_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>
</p>
<h2>Encoding</h2>
<p>
<a href="vorbis_analysis_init.html">vorbis_analysis_init()</a><br>
<a href="vorbis_block_init.html">vorbis_block_init()</a><br>
</p>
<p>
<a href="vorbis_analysis_headerout.html">vorbis_analysis_headerout()</a><br>
</p>
<p>
<a href="vorbis_analysis_buffer.html">vorbis_analysis_buffer()</a><br>
<a href="vorbis_analysis_wrote.html">vorbis_analysis_wrote()</a><br>
<a href="vorbis_analysis_blockout.html">vorbis_analysis_blockout()</a><br>
</p>
<p>
<a href="vorbis_analysis.html">vorbis_analysis()</a><br>
<a href="vorbis_bitrate_addblock.html">vorbis_bitrate_addblock()</a><br>
<a href="vorbis_bitrate_flushpacket.html">vorbis_bitrate_flushpacket()</a><br>
</p>
<br>
<br>
......
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>Once the uncompressed audio data has been divided into blocks, this
function is called on each block. It looks up the encoding mode and
dispatches the block to the forward transform provided by that mode.
</p>
<p>When using a basic encoding mode, with no bitrate management,
an ogg_packet pointer can be given, and an the coded block is returned
directly through that structure and can be placed in the output stream.
</p>
<p>Otherwise, NULL should be passed for the ogg_packet pointer. In
that case, after the transform has been applied, the block must passed
to vorbis_bitrate_addblock() for further coding. This method works with
both basic and managed encoding modes, so it's recommended for new code.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_analysis(vorbis_block *vb,ogg_packet *op);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vb</i></dt>
<dd>Pointer to the vorbis_block to be encoded.</dd>
<dt><i>op</i></dt>
<dd>Optional pointer to an ogg_packet. This should normally NULL,
and the final output obtained by passing <i>vb</i> though the
vorbis_bitrate_*() interface to perform any further refinement.
However, when not using a bitrate managed encoding mode, it
is possible to skip that step by providing an ogg_packet pointer
here, obtaining the compressed data directly.</dd>
</dl>
<h3>Return Values</h3>
<ul>
<li>0 for success</li>
<li>negative values for failure:
<ul>
<li>OV_EINVAL - Invalid request; a non-NULL value was passed for <i>op</i> when the encoder is using a bitrate managed mode.</li>
<li>OV_EFAULT - Internal fault; indicates a bug or memory corruption.</li>
<li>OV_EIMPL - Unimplemented; not supported by this version of the library.</li>
</ul>
</li>
</ul>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis_blockout</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis_blockout</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This fuction examines the available encoder and tries to break it
into appropriate sized blocks. It should be called in a loop after
adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
until it returns zero (need more data) or an negative value (error).
</p>
<p>
Each block returned should be passed to vorbis_analysis() for transform
and coding.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vb</i></dt>
<dd>Pointer to a previously initialize vorbis_block object to store the
returned data.
</dl>
<h3>Return Values</h3>
<ul>
<li>1 for success when more blocks are available.</li>
<li>0 for success when this is the last block available from the current input.</li>
<li>negative values for failure:
<ul>
<li>OV_EINVAL - Invalid parameters.</li>
<li>OV_EFAULT - Internal fault; indicates a bug or memory corruption.</li>
<li>OV_EIMPL - Unimplemented; not supported by this version of the library.</li>
</ul>
</li>
</ul>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis_buffer</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis_buffer</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This fuction requests a buffer array for delivering audio to the
encoder for compression.</p>
<p>The Vorbis encoder expects the caller to write audio data as
non-interleaved floating point samples into its internal buffers.
</p>
<p>
The general procedure is to call this function with the number of samples
you have available. The encoder will arrange for that much internal storage
and return an array of buffer pointers, one for each channel of audio.
The caller must then write the audio samples into those buffers, as
float values, and finally call vorbis_analysis_wrote() to tell the
encoder the data is available for analysis.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern float **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vals</i></dt>
<dd>Number of samples to provide in the request buffer.</dd>
</dl>
<h3>Return Values</h3>
<p>Returns an array of floating point buffers which can accept data.
A (**float) where the first index is the channel, and the second is
the sample index.<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis_headerout</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis_headerout</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function creates and returns the three header packets needed
to configure a decoder to accept subsequent data. I should be called
after all encoder initialization and configuration is complete. The
output packets should be placed in order at the start of the compressed
vorbis stream, prior to the first data packet.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_analysis_headerout(vorbis_dsp_state *v,
vorbis_comment *vc,
ogg_packet *op,
ogg_packet *op_comm,
ogg_packet *op_code);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dd>Pointer to an initialized vorbis_dsp_state which holds the encoder configuration.</dd>
<dt><i>vc</i></dt>
<dd>Pointer to an initialized vorbis_comment structure which holds the metadata associated with the stream being encoded.</dd>
<dt><i>op</i></dt>
<dd>Pointer to an ogg_packet structure to be filled out with the stream identification header.</dd>
<dt><i>op_comm</i></dt>
<dd>Pointer to an ogg_packet structure to be filled out with the serialied vorbis_comment data.</dd>
<dt><i>op_code</i></dt>
<dd>Pointer to an ogg_packet structure to be filled out with the codebooks, mode descriptions, etc. which will be used encoding the stream.</dd>
</dl>
<h3>Return Values</h3>
<ul>
<li>0 for success</li>
<li>negative values for failure:
<ul>
<li>OV_EFAULT - Internal fault; indicates a bug or memory corruption.</li>
<li>OV_EIMPL - Unimplemented; not supported by this version of the library.</li>
</ul>
</li>
</ul>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis_init</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis_init</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function allocates and initializes the encoder's analysis state
inside a is vorbis_dsp_state, based on the configuration in a vorbis_info
struct.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i</dt>
<dd>Pointer to the vorbis_dsp_state structure to be initialized for encoding.</dd>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_analysis_wrote</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_analysis_wrote</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function tells the encoder new data is available for compression.
Call this after writing new audio into the buffer array returned by
vorbis_analysis_buffer().
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vals</i></dt>
<dd>Number of samples successfully written. This must be less than
or equal to the value passed to vorbis_analysis_buffer().</dd>
</dl>
<h3>Return Values</h3>
<ul>
<li>0 for success</li>
<li>negative values for failure:
<ul>
<li>OV_EINVAL - Invalid request; e.g. vals overflows the allocated space.</li>
<li>OV_EFAULT - Internal fault; indicates a bug or memory corruption.</li>
<li>OV_EIMPL - Unimplemented; not supported by this version of the library.</li>
</ul>
</li>
</ul>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_bitrate_addblock</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_bitrate_addblock</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This fuction submits a transformed block to the bitrate management
engine for final encoding. Packets are submitted and, depending on the
encoding mode, buffered and the packet boundaries adjusted and padded
to meet the target bitrate.</p>
<p>After calling vorbis_bitrate_addblock(), the passed vorbis_block
structure can be reused in another call to vorbis_analysis_blockout().
Call vorbis_bitrate_flushpacket() to obtain the final compressed data.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_bitrate_addblock(vorbis_block *vb);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_block to be submitted.</dd>
</dl>
<h3>Return Values</h3>
<ul>
<li>0 for success.</li>
<li>negative values for failure:
<ul>
<li>OV_EINVAL - Invalid parameters.</li>
<li>OV_EFAULT - Internal fault; indicates a bug or memory corruption.</li>
<li>OV_EIMPL - Unimplemented; not supported by this version of the library.</li>
</ul>
</li>
</ul>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2009 Xiph.Org</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 - 20091219</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libvorbisenc - function - vorbis_bitrate_flushpacket</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 - 20091219</p></td>
</tr>
</table>
<h1>vorbis_bitrate_flushpacket</h1>
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function returns the next available packet from the bitrate
management engine. It should be called in a loop after any calls to