diff options
Diffstat (limited to 'vorbis/doc/vorbisfile')
58 files changed, 5485 insertions, 0 deletions
diff --git a/vorbis/doc/vorbisfile/Makefile.am b/vorbis/doc/vorbisfile/Makefile.am new file mode 100644 index 0000000..fb27d44 --- /dev/null +++ b/vorbis/doc/vorbisfile/Makefile.am @@ -0,0 +1,25 @@ +## Process this file with automake to produce Makefile.in + +docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)/vorbisfile + +doc_DATA = OggVorbis_File.html callbacks.html chaining_example_c.html\ + chainingexample.html crosslap.html datastructures.html decoding.html\ + example.html exampleindex.html fileinfo.html index.html\ + initialization.html ov_bitrate.html ov_bitrate_instant.html\ + ov_callbacks.html ov_clear.html ov_comment.html ov_crosslap.html\ + ov_fopen.html\ + ov_info.html ov_open.html ov_open_callbacks.html ov_pcm_seek.html\ + ov_pcm_seek_lap.html ov_pcm_seek_page.html ov_pcm_seek_page_lap.html\ + ov_pcm_tell.html ov_pcm_total.html ov_raw_seek.html\ + ov_raw_seek_lap.html ov_raw_tell.html ov_raw_total.html ov_read.html\ + ov_read_float.html ov_read_filter.html\ + ov_seekable.html ov_serialnumber.html\ + ov_streams.html ov_test.html ov_test_callbacks.html ov_test_open.html\ + ov_time_seek.html ov_time_seek_lap.html ov_time_seek_page.html\ + ov_time_seek_page_lap.html ov_time_tell.html ov_time_total.html\ + overview.html reference.html seekexample.html seeking.html\ + seeking_example_c.html seeking_test_c.html seekingexample.html\ + style.css threads.html\ + vorbisfile_example_c.html + +EXTRA_DIST = $(doc_DATA) diff --git a/vorbis/doc/vorbisfile/OggVorbis_File.html b/vorbis/doc/vorbisfile/OggVorbis_File.html new file mode 100644 index 0000000..67f47d7 --- /dev/null +++ b/vorbis/doc/vorbisfile/OggVorbis_File.html @@ -0,0 +1,137 @@ +<html> + +<head> +<title>Vorbisfile - datatype - OggVorbis_File</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>OggVorbis_File</h1> + +<p><i>declared in "vorbis/vorbisfile.h"</i></p> + +<p> +The OggVorbis_File structure defines an Ogg Vorbis file. +<p> + +This structure is used in all libvorbisfile routines. Before it can +be used, it must be initialized by <a +href="ov_open.html">ov_open()</a>, <a +href="ov_fopen.html">ov_fopen()</a>, or <a +href="ov_open_callbacks.html">ov_open_callbacks()</a>. <em>Important +Note:</em> The use of <a href="ov_open.html">ov_open()</a> is +discouraged under Windows due to a peculiarity of Windows linking +convention; use <a href="ov_fopen.html">ov_fopen()</a> or <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. This +caution only applies to Windows; use of <a +href="ov_open.html">ov_open()</a> is appropriate for all other +platforms. See the <a href="ov_open.html">ov_open()</a> page for more +information. + +<p> +After use, the OggVorbis_File structure must be deallocated with a +call to <a href="ov_clear.html">ov_clear()</a>. + +<p> +Note that once a file handle is passed to a successful <a +href="ov_open.html">ov_open()</a> call, the handle is owned by +libvorbisfile and will be closed by libvorbisfile later during the +call to <a href="ov_clear.html">ov_clear()</a>. The handle should not +be used or closed outside of the libvorbisfile API. Similarly, files +opened by <a href="ov_fopen.html">ov_fopen()</a> will also be closed +internally by vorbisfile in <a href="ov_clear.html">ov_clear()</a>.<p> + +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> allows the +application to choose whether libvorbisfile will or will not close the +handle in <a href="ov_clear.html">ov_clear()</a>; see the <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> page for more information.<p> + +If a call to <a href="ov_open.html">ov_open()</a> or <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>, +libvorbisfile does <b>not</b> assume ownership of the handle and the +application is expected to close it if necessary. A failed <a +href="ov_fopen.html">ov_fopen()</a> call will internally close the +file handle if the open process fails.<p> + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b>typedef struct { + void *datasource; /* Pointer to a FILE *, etc. */ + int seekable; + ogg_int64_t offset; + ogg_int64_t end; + ogg_sync_state oy; + + /* If the FILE handle isn't seekable (eg, a pipe), only the current + stream appears */ + int links; + ogg_int64_t *offsets; + ogg_int64_t *dataoffsets; + long *serialnos; + ogg_int64_t *pcmlengths; + vorbis_info *vi; + vorbis_comment *vc; + + /* Decoding working state local storage */ + ogg_int64_t pcm_offset; + int ready_state; + long current_serialno; + int current_link; + + ogg_int64_t bittrack; + ogg_int64_t samptrack; + + ogg_stream_state os; /* take physical pages, weld into a logical + stream of packets */ + vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */ + vorbis_block vb; /* local working space for packet->PCM decode */ + + <a href="ov_callbacks.html">ov_callbacks</a> callbacks; + +} OggVorbis_File;</b></pre> + </td> +</tr> +</table> + +<h3>Relevant Struct Members</h3> +<dl> +<dt><i>datasource</i></dt> + +<dd>Pointer to file or other ogg source. When using stdio based +file/stream access, this field contains a <tt>FILE</tt> pointer. When using +custom IO via callbacks, libvorbisfile treats this void pointer as a +black box only to be passed to the callback routines provided by the +application.</dd> + +<dt><i>seekable</i></dt> +<dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd> +<dt><i>links</i></dt> +<dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
+<dt><i>ov_callbacks</i></dt>
+<dd>Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via <a href="ov_open.html">ov_open()</a>, the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd> +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/callbacks.html b/vorbis/doc/vorbisfile/callbacks.html new file mode 100644 index 0000000..20ae55a --- /dev/null +++ b/vorbis/doc/vorbisfile/callbacks.html @@ -0,0 +1,121 @@ +<html> + +<head> +<title>Vorbisfile - Callbacks and non-stdio I/O</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Callbacks and non-stdio I/O</h1> + +Although stdio is convenient and nearly universally implemented as per +ANSI C, it is not suited to all or even most potential uses of Vorbis. +For additional flexibility, embedded applications may provide their +own I/O functions for use with Vorbisfile when stdio is unavailable or not +suitable. One common example is decoding a Vorbis stream from a +memory buffer.<p> + +Use custom I/O functions by populating an <a +href="ov_callbacks.html">ov_callbacks</a> structure and calling <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the +typical <a href="ov_open.html">ov_open()</a> or <a +href="ov_test.html">ov_test()</a>. Past the open call, use of +libvorbisfile is identical to using it with stdio. + +<h2>Read function</h2> + +The read-like function provided in the <tt>read_func</tt> field is +used to fetch the requested amount of data. It expects the fetch +operation to function similar to file-access, that is, a multiple read +operations will retrieve contiguous sequential pieces of data, +advancing a position cursor after each read.<p> + +The following behaviors are also expected:<p> +<ul> +<li>a return of '0' indicates end-of-data (if the by-thread errno is unset) +<li>short reads mean nothing special (short reads are not treated as error conditions) +<li>a return of zero with the by-thread errno set to nonzero indicates a read error +</ul> +<p> + +<h2>Seek function</h2> + +The seek-like function provided in the <tt>seek_func</tt> field is +used to request non-sequential data access by libvorbisfile, moving +the access cursor to the requested position. The seek function is +optional; if callbacks are only to handle non-seeking (streaming) data +or the application wishes to force streaming behavior, +<tt>seek_func</tt> and <tt>tell_func</tt> should be set to NULL. If +the seek function is non-NULL, libvorbisfile mandates the following +behavior: + +<ul> +<li>The seek function must always return -1 (failure) if the given +data abstraction is not seekable. It may choose to always return -1 +if the application desires libvorbisfile to treat the Vorbis data +strictly as a stream (which makes for a less expensive open +operation).<p> + +<li>If the seek function initially indicates seekability, it must +always succeed upon being given a valid seek request.<p> + +<li>The seek function must implement all of SEEK_SET, SEEK_CUR and +SEEK_END. The implementation of SEEK_END should set the access cursor +one past the last byte of accessible data, as would stdio +<tt>fseek()</tt><p> +</ul> + +<h2>Close function</h2> + +The close function should deallocate any access state used by the +passed in instance of the data access abstraction and invalidate the +instance handle. The close function is assumed to succeed; its return +code is not checked.<p> + +The <tt>close_func</tt> may be set to NULL to indicate that libvorbis +should not attempt to close the file/data handle in <a +href="ov_clear.html">ov_clear</a> but allow the application to handle +file/data access cleanup itself. For example, by passing the normal +stdio calls as callback functions, but passing a <tt>close_func</tt> +that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an +application may call <a href="ov_clear.html">ov_clear()</a> and then +later <tt>fclose()</tt> the file originally passed to libvorbisfile. + +<h2>Tell function</h2> + +The tell function is intended to mimic the +behavior of <tt>ftell()</tt> and must return the byte position of the +next data byte that would be read. If the data access cursor is at +the end of the 'file' (pointing to one past the last byte of data, as +it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell +function must return the data position (and thus the total file size), +not an error.<p> + +The tell function need not be provided if the data IO abstraction is +not seekable, or the application wishes to force streaming +behavior. In this case, the <tt>tell_func</tt> and <tt>seek_func</tt> +fields should be set to NULL.<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/chaining_example_c.html b/vorbis/doc/vorbisfile/chaining_example_c.html new file mode 100644 index 0000000..e40689c --- /dev/null +++ b/vorbis/doc/vorbisfile/chaining_example_c.html @@ -0,0 +1,90 @@ +<html> + +<head> +<title>vorbisfile - chaining_example.c</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>chaining_example.c</h1> + +<p> +The example program source: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre width="80"><b> + +<font color="#A020F0">#include <vorbis/codec.h></font> +<font color="#A020F0">#include <vorbis/vorbisfile.h></font> + +<strong><font color="#4169E1"><a name="main"></a>int main()</font></strong>{ + OggVorbis_File ov; + int i; + +<font color="#A020F0">#ifdef _WIN32</font> <font color="#B22222">/* We need to set stdin to binary mode on windows. */</font> + _setmode( _fileno( stdin ), _O_BINARY ); +<font color="#A020F0">#endif</font> + + <font color="#B22222">/* open the file/pipe on stdin */</font> + <font color="#4169E1">if</font>(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)<0){ + printf(<font color="#666666">"Could not open input as an OggVorbis file.\n\n"</font>); + exit(1); + } + + <font color="#B22222">/* print details about each logical bitstream in the input */</font> + <font color="#4169E1">if</font>(ov_seekable(&ov)){ + printf(<font color="#666666">"Input bitstream contained %ld logical bitstream section(s).\n"</font>, + ov_streams(&ov)); + printf(<font color="#666666">"Total bitstream playing time: %ld seconds\n\n"</font>, + (long)ov_time_total(&ov,-1)); + + }<font color="#4169E1">else</font>{ + printf(<font color="#666666">"Standard input was not seekable.\n"</font> + <font color="#666666">"First logical bitstream information:\n\n"</font>); + } + + <font color="#4169E1">for</font>(i=0;i<ov_streams(&ov);i++){ + vorbis_info *vi=ov_info(&ov,i); + printf(<font color="#666666">"\tlogical bitstream section %d information:\n"</font>,i+1); + printf(<font color="#666666">"\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n"</font>, + vi->rate,vi->channels,ov_bitrate(&ov,i)/1000, + ov_serialnumber(&ov,i)); + printf(<font color="#666666">"\t\tcompressed length: %ld bytes "</font>,(long)(ov_raw_total(&ov,i))); + printf(<font color="#666666">" play time: %lds\n"</font>,(long)ov_time_total(&ov,i)); + } + + ov_clear(&ov); + <font color="#4169E1">return</font> 0; +} + +</b></pre> + </td> +</tr> +</table> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/chainingexample.html b/vorbis/doc/vorbisfile/chainingexample.html new file mode 100644 index 0000000..9e0440d --- /dev/null +++ b/vorbis/doc/vorbisfile/chainingexample.html @@ -0,0 +1,175 @@ +<html> + +<head> +<title>vorbisfile - Example Code</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Chaining Example Code</h1> + +<p> +The following is a run-through of the chaining example program supplied +with vorbisfile - <a href="chaining_example_c.html">chaining_example.c</a>. +This program demonstrates how to work with a chained bitstream. + +<p> +First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" +#include "../lib/misc.h" +</b></pre> + </td> +</tr> +</table> + +<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a other helpful variables to track our progress within the file. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int main(){ + OggVorbis_File ov; + int i; +</b></pre> + </td> +</tr> +</table> + +<p>This example takes its input on stdin which is in 'text' mode by default under Windows; this will corrupt the input data unless set to binary mode. This applies only to Windows. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif +</b></pre> + </td> +</tr> +</table> + +<p>We call <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to +initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> +structure. <a href="ov_open_callbacks.html">ov_open_callbacks()</a> +also checks to ensure that we're reading Vorbis format and not +something else. The OV_CALLBACKS_NOCLOSE callbacks instruct +libvorbisfile not to close stdin later during cleanup.<p> + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)<0){ + printf("Could not open input as an OggVorbis file.\n\n"); + exit(1); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +First we check to make sure the stream is seekable using <a href="ov_seekable.html">ov_seekable</a>. + +<p>Then we're going to find the number of logical bitstreams in the physical bitstream using <a href="ov_streams.html">ov_streams</a>. + +<p>We use <a href="ov_time_total.html">ov_time_total</a> to determine the total length of the physical bitstream. We specify that we want the entire bitstream by using the argument <tt>-1</tt>. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + if(ov_seekable(&ov)){ + printf("Input bitstream contained %ld logical bitstream section(s).\n", + ov_streams(&ov)); + printf("Total bitstream playing time: %ld seconds\n\n", + (long)ov_time_total(&ov,-1)); + + }else{ + printf("Standard input was not seekable.\n" + "First logical bitstream information:\n\n"); + } + +</b></pre> + </td> +</tr> +</table> + +<p>Now we're going to iterate through each logical bitstream and print information about that bitstream. + +<p>We use <a href="ov_info.html">ov_info</a> to pull out the <a href="../libvorbis/vorbis_info.html">vorbis_info</a> struct for each logical bitstream. This struct contains bitstream-specific info. + +<p><a href="ov_serialnumber.html">ov_serialnumber</a> retrieves the unique serial number for the logical bistream. <a href="ov_raw_total.html">ov_raw_total</a> gives the total compressed bytes for the logical bitstream, and <a href="ov_time_total.html">ov_time_total</a> gives the total time in the logical bitstream. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + for(i=0;i<ov_streams(&ov);i++){ + vorbis_info *vi=ov_info(&ov,i); + printf("\tlogical bitstream section %d information:\n",i+1); + printf("\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n", + vi->rate,vi->channels,ov_bitrate(&ov,i)/1000, + ov_serialnumber(&ov,i)); + printf("\t\tcompressed length: %ld bytes ",(long)(ov_raw_total(&ov,i))); + printf(" play time: %lds\n",(long)ov_time_total(&ov,i)); + } +</b></pre> + </td> +</tr> +</table> +<p> +When we're done with the entire physical bitstream, we need to call <a href="ov_clear.html">ov_clear()</a> to release the bitstream. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + ov_clear(&ov); + return 0; +} +</b></pre> + </td> +</tr> +</table> + +<p> +The full source for chaining_example.c can be found with the vorbis +distribution in <a href="chaining_example_c.html">chaining_example.c</a>. + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/crosslap.html b/vorbis/doc/vorbisfile/crosslap.html new file mode 100644 index 0000000..9d28b0b --- /dev/null +++ b/vorbis/doc/vorbisfile/crosslap.html @@ -0,0 +1,121 @@ +<html> + +<head> +<title>Vorbisfile - Sample Crosslapping</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>What is Crosslapping?</h1> + +<p>Crosslapping blends two samples together using a window function, +such that any sudden discontinuities between the samples that may +cause clicks or thumps are eliminated or blended away. The technique +is nearly identical to how Vorbis internally splices together frames +of audio data during normal decode. API functions are provided to <a +href="ov_crosslap.html">crosslap transitions between seperate +streams</a>, or to crosslap when <a href="seeking.html">seeking within +a single stream</a>. + +<h1>Why Crosslap?</h1> +<h2>The source of boundary clicks</h2> + +<p>Vorbis is a lossy compression format such that any compressed +signal is at best a close approximation of the original. The +approximation may be very good (ie, indistingushable to the human +ear), but it is an approximation nonetheless. Even if a sample or set +of samples is contructed carefully such that transitions from one to +another match perfectly in the original, the compression process +introduces minute amplitude and phase errors. It's an unavoidable +result of such high compression rates. + +<p>If an application transitions instantly from one sample to another, +any tiny discrepancy introduced in the lossy compression process +becomes audible as a stairstep discontinuity. Even if the discrepancy +in a normal lapped frame is only .1dB (usually far below the +threshhold of perception), that's a sudden cliff of 380 steps in a 16 +bit sample (when there's a boundary with no lapping). + +<h2>I thought Vorbis was gapless</h2> + +<p>It is. Vorbis introduces no extra samples at the beginning or end +of a stream, nor does it remove any samples. Gapless encoding +eliminates 99% of the click, pop or outright blown speaker that would +occur if boundaries had gaps or made no effort to align +transitions. However, gapless encoding is not enough to entirely +eliminate stairstep discontinuities all the time for exactly the +reasons described above. + +<p>Frame lapping, like Vorbis performs internally during continuous +playback, is necessary to eliminate that last epsilon of trouble. + +<h1>Easiest Crosslap</h1> + +The easiest way to perform crosslapping in Vorbis is to use the +lapping functions with no other extra effort. These functions behave +identically to when lapping isn't used except to provide +at-least-very-good lapping results. Crosslapping will not introduce +any samples into or remove any samples from the decoded audio; the +only difference is that the transition is lapped. Lapping occurs from +the current PCM position (either in the old stream, or at the position +prior to calling a lapping seek) forward into the next +half-short-block of audio data to be read from the new stream or +position. + +<p>Ideally, vorbisfile internally reads an extra frame of audio from +the old stream/position to perform lapping into the new +stream/position. However, automagic crosslapping works properly even +if the old stream/position is at EOF. In this case, the synthetic +post-extrapolation generated by the encoder to pad out the last block +with appropriate data (and avoid encoding a stairstep, which is +inefficient) is used for crosslapping purposes. Although this is +synthetic data, the result is still usually completely unnoticable +even in careful listening (and always preferable to a click or pop). + +<p>Vorbisfile will lap between streams of differing numbers of +channels. Any extra channels from the old stream are ignored; playback +of these channels simply ends. Extra channels in the new stream are +lapped from silence. Vorbisfile will also lap between streams links +of differing sample rates. In this case, the sample rates are ignored +(no implicit resampling is done to match playback). It is up to the +application developer to decide if this behavior makes any sense in a +given context; in practical use, these default behaviors perform +sensibly. + +<h1>Best Crosslap</h1> + +<p>To acheive the best possible crosslapping results, avoid the case +where synthetic extrapolation data is used for crosslapping. That is, +design loops and samples such that a little bit of data is left over +in sample A when seeking to sample B. Normally, the end of sample A +and the beginning of B would overlap exactly; this allows +crosslapping to perform exactly as it would within vorbis when +stitching audio frames together into continuous decoded audio. + +<p>The optimal amount of overlap is half a short-block, and this +varies by compression mode. Each encoder will vary in exact block +size selection; for vorbis 1.0, for -q0 through -q10 and 44kHz or +greater, a half-short block is 64 samples. + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/datastructures.html b/vorbis/doc/vorbisfile/datastructures.html new file mode 100644 index 0000000..00f8f8d --- /dev/null +++ b/vorbis/doc/vorbisfile/datastructures.html @@ -0,0 +1,61 @@ +<html> + +<head> +<title>Vorbisfile - Base Data Structures</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Base Data Structures</h1> +<p>There are several data structures used to hold file and bitstream information during libvorbisfile decoding. These structures are declared in "vorbis/vorbisfile.h" and "vorbis/codec.h". +<p> +<p>When using libvorbisfile, it's not necessary to know about most of the contents of these data structures, but it may be helpful to understand what they contain. +<br><br> + +<table border=1 color=black width=50% cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td><b>datatype</b></td> + <td><b>purpose</b></td> +</tr> +<tr valign=top> + <td><a href="OggVorbis_File.html">OggVorbis_File</a></td> + <td>This structure represents the basic file information. It contains + a pointer to the physical file or bitstream and various information about that bitstream.</td> +</tr> +<tr valign=top> +<td><a href="../libvorbis/vorbis_comment.html">vorbis_comment</a></td> + <td>This structure contains the file comments. It contains + a pointer to unlimited user comments, information about the number of comments, and a vendor description.</td> +</tr> +<tr valign=top> +<td><a href="../libvorbis/vorbis_info.html">vorbis_info</a></td> + <td>This structure contains encoder-related information about the bitstream. It includes encoder info, channel info, and bitrate limits.</td> +</tr> +<tr valign=top> +<td><a href="ov_callbacks.html">ov_callbacks</a></td> + <td>This structure contains pointers to the application-specified file manipulation routines set for use by <a href="ov_open_callbacks.html">ov_open_callbacks()</a>. See also the <a href="callbacks.html">provided document on using application-provided callbacks instead of stdio</a>.</td> +</tr> +</table> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/decoding.html b/vorbis/doc/vorbisfile/decoding.html new file mode 100644 index 0000000..f394376 --- /dev/null +++ b/vorbis/doc/vorbisfile/decoding.html @@ -0,0 +1,92 @@ +<html> + +<head> +<title>Vorbisfile - Decoding</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Decoding</h1> + +<p> +All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h". +<p> + +After <a href="initialization.html">initialization</a>, decoding audio +is as simple as calling <a href="ov_read.html">ov_read()</a> (or the +similar functions <a href="ov_read_float.html">ov_read_float()</a> and +<a href="ov_read_filter.html">ov_read_filter</a>). This function works +similarly to reading from a normal file using <tt>read()</tt>.<p> + +However, a few differences are worth noting: + +<h2>multiple stream links</h2> + +A Vorbis stream may consist of multiple sections (called links) that +encode differing numbers of channels or sample rates. It is vitally +important to pay attention to the link numbers returned by <a +href="ov_read.html">ov_read</a> and handle audio changes that may +occur at link boundaries. Such multi-section files do exist in the +wild and are not merely a specification curiosity. + +<h2>returned data amount</h2> + +<a href="ov_read.html">ov_read</a> does not attempt to completely fill +a large, passed in data buffer; it merely guarantees that the passed +back data does not overflow the passed in buffer size. Large buffers +may be filled by iteratively looping over calls to <a +href="ov_read.html">ov_read</a> (incrementing the buffer pointer) +until the original buffer is filled. + +<h2>file cursor position</h2> + +Vorbis files do not necessarily start at a sample number or time offset +of zero. Do not be surprised if a file begins at a positive offset of +several minutes or hours, such as would happen if a large stream (such +as a concert recording) is chopped into multiple seperate files. + +<p> +<table border=1 color=black width=50% cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td><b>function</b></td> + <td><b>purpose</b></td> +</tr> +<tr valign=top> + <td><a href="ov_read.html">ov_read</a></td> + <td>This function makes up the main chunk of a decode loop. It takes an +OggVorbis_File structure, which must have been initialized by a previous +call to <a href="ov_open.html"><tt>ov_open()</tt></a>, <a href="ov_fopen.html"><tt>ov_fopen()</tt></a>, +or <a href="ov_open_callbacks.html"><tt>ov_open_callbacks()</tt></a>.</td> +</tr> +<tr valign=top> + <td><a href="ov_read_float.html">ov_read_float</a></td> + <td>This function decodes to floats instead of integer samples.</td> +</tr> +<tr valign=top> + <td><a href="ov_read_filter.html">ov_read_filter</a></td> + <td>This function works like <a href="ov_read.html">ov_read</a>, but passes the PCM data through the provided filter before converting to integer sample data.</td> +</tr> +</table> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/example.html b/vorbis/doc/vorbisfile/example.html new file mode 100644 index 0000000..e0c4fa3 --- /dev/null +++ b/vorbis/doc/vorbisfile/example.html @@ -0,0 +1,208 @@ +<html> + +<head> +<title>Vorbisfile - Example Code</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Decoding Example Code</h1> + +<p> +The following is a run-through of the decoding example program supplied +with libvorbisfile, <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>. +This program takes a vorbis bitstream from stdin and writes raw pcm to stdout. + +<p> +First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#include <stdio.h> +#include <stdlib.h> +#include <math.h> +#include "vorbis/codec.h" +#include "vorbisfile.h" +</b></pre> + </td> +</tr> +</table> +<p> +We also have to make a concession to Windows users here. If we are using windows for decoding, we must declare these libraries so that we can set stdin/stdout to binary. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#ifdef _WIN32 +#include <io.h> +#include <fcntl.h> +#endif +</b></pre> + </td> +</tr> +</table> +<p> +Next, a buffer for the pcm audio output is declared. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +char pcmout[4096]; +</b></pre> + </td> +</tr> +</table> + +<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a few other helpful variables to track out progress within the file. +Also, we make our final concession to Windows users by setting the stdin and stdout to binary mode. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int main(int argc, char **argv){ + OggVorbis_File vf; + int eof=0; + int current_section; + +#ifdef _WIN32 + _setmode( _fileno( stdin ), _O_BINARY ); + _setmode( _fileno( stdout ), _O_BINARY ); +#endif +</b></pre> + </td> +</tr> +</table> + +<p>We call <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to +initialize the <b>OggVorbis_File</b> structure with default values. +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks +to ensure that we're reading Vorbis format and not something else. The +OV_CALLBACKS_NOCLOSE callbacks instruct libvorbisfile not to close +stdin later during cleanup. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + if(ov_open_callbacks(stdin, &vf, NULL, 0, OV_CALLBACKS_NOCLOSE) < 0) { + fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n"); + exit(1); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +We're going to pull the channel and bitrate info from the file using <a href="ov_info.html">ov_info()</a> and show them to the user. +We also want to pull out and show the user a comment attached to the file using <a href="ov_comment.html">ov_comment()</a>. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + { + char **ptr=ov_comment(&vf,-1)->user_comments; + vorbis_info *vi=ov_info(&vf,-1); + while(*ptr){ + fprintf(stderr,"%s\n",*ptr); + ++ptr; + } + fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate); + fprintf(stderr,"\nDecoded length: %ld samples\n", + (long)ov_pcm_total(&vf,-1)); + fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +Here's the read loop: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + + while(!eof){ + long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section); + if (ret == 0) { + /* EOF */ + eof=1; + } else if (ret < 0) { + /* error in the stream. Not a problem, just reporting it in + case we (the app) cares. In this case, we don't. */ + } else { + /* we don't bother dealing with sample rate changes, etc, but + you'll have to*/ + fwrite(pcmout,1,ret,stdout); + } + } + + +</b></pre> + </td> +</tr> +</table> + +<p> +The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>. +Based on the value returned, we know if we're at the end of the file or have invalid data. If we have valid data, we write it to the pcm output. + +<p> +Now that we've finished playing, we can pack up and go home. It's important to call <a href="ov_clear.html">ov_clear()</a> when we're finished. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + + ov_clear(&vf); + + fprintf(stderr,"Done.\n"); + return(0); +} +</b></pre> + </td> +</tr> +</table> + +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/exampleindex.html b/vorbis/doc/vorbisfile/exampleindex.html new file mode 100644 index 0000000..9227b97 --- /dev/null +++ b/vorbis/doc/vorbisfile/exampleindex.html @@ -0,0 +1,39 @@ +<html> + +<head> +<title>vorbisfile - 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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>VorbisFile Example Code</h1> + +<p> +Three sample programs are included with the vorbisfile distribution. +<p> +<a href="example.html">vorbisfile decoding</a><br> +<a href="seekexample.html">vorbisfile seeking</a><br> +<a href="chainingexample.html">vorbisfile bitstream chaining</a><br> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/fileinfo.html b/vorbis/doc/vorbisfile/fileinfo.html new file mode 100644 index 0000000..c025dd6 --- /dev/null +++ b/vorbis/doc/vorbisfile/fileinfo.html @@ -0,0 +1,95 @@ +<html>
+
+<head>
+<title>Vorbisfile - File Information</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>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+
+<h1>File Information</h1>
+<p>Libvorbisfile contains many functions to get information about bitstream attributes and decoding status.
+<p>
+All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h".
+<p>
+
+<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+ <td><b>function</b></td>
+ <td><b>purpose</b></td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_bitrate.html">ov_bitrate</a></td>
+ <td>Returns the average bitrate of the current logical bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_bitrate_instant.html">ov_bitrate_instant</a></td>
+ <td>Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitream or no new information is available.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_streams.html">ov_streams</a></td>
+ <td>Gives the number of logical bitstreams within the current physical bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_seekable.html">ov_seekable</a></td>
+ <td>Indicates whether the bitstream is seekable.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_serialnumber.html">ov_serialnumber</a></td>
+ <td>Returns the unique serial number of the specified logical bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_raw_total.html">ov_raw_total</a></td>
+ <td>Returns the total (compressed) bytes in a physical or logical seekable bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_total.html">ov_pcm_total</a></td>
+ <td>Returns the total number of samples in a physical or logical seekable bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_total.html">ov_time_total</a></td>
+ <td>Returns the total time length in seconds of a physical or logical seekable bitstream.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_raw_tell.html">ov_raw_tell</a></td>
+ <td>Returns the byte location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_tell.html">ov_pcm_tell</a></td>
+ <td>Returns the sample location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_tell.html">ov_time_tell</a></td>
+ <td>Returns the time location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_info.html">ov_info</a></td>
+ <td>Returns the <a href="../libvorbis/vorbis_info.html">vorbis_info</a> struct for a specific bitstream section.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_comment.html">ov_comment</a></td>
+ <td>Returns attached <a href="../libvorbis/vorbis_comment.html">comments</a> for the current bitstream.</td>
+</tr>
+</table>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
+</tr><tr>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+
+</body>
+
+</html>
diff --git a/vorbis/doc/vorbisfile/index.html b/vorbis/doc/vorbisfile/index.html new file mode 100644 index 0000000..167e1c0 --- /dev/null +++ b/vorbis/doc/vorbisfile/index.html @@ -0,0 +1,49 @@ +<html> + +<head> +<title>Vorbisfile - 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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Vorbisfile Documentation</h1> + +<p> + +The Vorbisfile library provides a convenient high-level API for +decoding and basic manipulation of all Vorbis I audio streams. +Libvorbisfile is implemented as a layer on top of Xiph.Org's reference +libogg and libvorbis libraries.<p> + +Vorbisfile can be used along with any ANSI compliant stdio implementation +for file/stream access, or use custom stream i/o routines provided by +the embedded environment. Both uses are described in detail in this +documentation. + +<p> +<a href="overview.html">API overview</a><br> +<a href="reference.html">API reference</a><br> +<a href="exampleindex.html">Code Examples</a><br> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/initialization.html b/vorbis/doc/vorbisfile/initialization.html new file mode 100644 index 0000000..da83957 --- /dev/null +++ b/vorbis/doc/vorbisfile/initialization.html @@ -0,0 +1,118 @@ +<html> + +<head> +<title>Vorbisfile - Setup/Teardown</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<H1>Setup/Teardown</h1> <p>In order to decode audio using +libvorbisfile, a bitstream containing Vorbis audio must be properly +initialized before decoding and cleared when decoding is finished. +The simplest possible case is to use <a +href="ov_fopen.html">ov_fopen()</a> to open the file for access, check +it for Vorbis content, and prepare it for playback. A successful <a +href="../libvorbis/return.html">return code</a> from <a +href="ov_fopen.html">ov_fopen()</a> indicates the file is ready for use. +Once the file is no longer needed, <a +href="ov_clear.html">ov_clear()</a> is used to close the file and +deallocate decoding resources.<p> + +On systems other than Windows<a href="ov_open.html#winfoot">[a]</a>, an +application may also open a file itself using <tt>fopen()</tt>, then pass the +<tt>FILE *</tt> to libvorbisfile using <a +href="ov_open.html">ov_open()</a>. </b>Do not</b> call +<tt>fclose()</tt> on a file handle successfully submitted to <a +href="ov_open.html">ov_open()</a>; libvorbisfile does this in the <a +href="ov_clear.html">ov_clear()</a> call.<p> + +An application that requires more setup flexibility may open a data +stream using <a href="ov_open_callbacks.html">ov_open_callbacks()</a> +to change default libvorbis behavior or specify non-stdio data access +mechanisms.<p> + +<p> +All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h". +<p> + +<table border=1 color=black width=50% cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td><b>function</b></td> + <td><b>purpose</b></td> +</tr> +<tr valign=top> + <td><a href="ov_fopen.html">ov_fopen</a></td> + <td>Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be + used.</td> +</tr> +<tr valign=top> + <td><a href="ov_open.html">ov_open</a></td> + <td>Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be + used. <a href="#winfoot"><em>Do not use this call under Windows [a];</em></a> Use <a href="ov_fopen.html">ov_fopen()</a> or <a href="ov_open_callbacks.html">ov_open_callbacks()</a> instead.</td> +</tr> +<tr valign=top> + <td><a href="ov_open_callbacks.html">ov_open_callbacks</a></td> + <td>Initializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of <a href="ov_open.html">ov_open()</a> or <a href="ov_fopen.html">ov_fopen()</a> when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a <tt>FILE *</tt> under Windows.</td> +</tr> + +<tr valign=top> +<td><a href="ov_test.html">ov_test</a></td> + +<td>Partially opens a file just far enough to determine if the file +is an Ogg Vorbis file or not. A successful return indicates that the +file appears to be an Ogg Vorbis file, but the <a +href="OggVorbis_File.html">OggVorbis_File</a> struct is not yet fully +initialized for actual decoding. After a <a href="../libvorbis/return.html">successful return</a>, the file +may be closed using <a href="ov_clear.html">ov_clear()</a> or fully +opened for decoding using <a +href="ov_test_open.html">ov_test_open()</a>.<p> This call is intended to +be used as a less expensive file open test than a full <a +href="ov_open.html">ov_open()</a>.<p> +Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td> + +</tr> +<tr valign=top> +<td><a href="ov_test_callbacks.html">ov_test_callbacks</a></td> +<td>As above but allowing application-define I/O callbacks.<p> +Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td> + +</tr> +<tr valign=top> +<td><a href="ov_test_open.html">ov_test_open</a><td> +Finish opening a file after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.</td> +</tr> +<tr valign=top> + <td><a href="ov_clear.html">ov_clear</a></td> <td>Closes the + bitstream and cleans up loose ends. Must be called when + finished with the bitstream. After return, the <a + href="OggVorbis_File.html">OggVorbis_File</a> struct is + invalid and may not be used before being initialized again + before begin reinitialized. + +</td> +</tr> +</table> + +<br><br> +<hr noshade> + +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_bitrate.html b/vorbis/doc/vorbisfile/ov_bitrate.html new file mode 100644 index 0000000..eb3c4d7 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_bitrate.html @@ -0,0 +1,72 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_bitrate</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_bitrate</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This function returns the average bitrate for the specified logical bitstream. This may be different from the <a href=ov_info.html>ov_info->nominal_bitrate</a> value, as it is based on the actual average for this bitstream if the file is seekable. +<p>Nonseekable files will return the nominal bitrate setting or the average of the upper and lower bounds, if any of these values are set. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_bitrate(OggVorbis_File *vf,int i); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the bitrate for the entire bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>OV_EINVAL indicates that an invalid argument value was submitted or that the stream represented by <tt>vf</tt> is not open.</li> +<li>OV_FALSE means the call returned a 'false' status, which in this case most likely indicates that the file is nonseekable and the upper, lower, and nominal bitrates were unset. +<li><i>n</i> indicates the bitrate for the given logical bitstream or the entire + physical bitstream. If the file is open for random (seekable) access, it will + find the *actual* average bitrate. If the file is streaming (nonseekable), it + returns the nominal bitrate (if set) or else the average of the + upper/lower bounds (if set).</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_bitrate_instant.html b/vorbis/doc/vorbisfile/ov_bitrate_instant.html new file mode 100644 index 0000000..da44dcf --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_bitrate_instant.html @@ -0,0 +1,65 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_bitrate</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_bitrate_instant</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Used to find the most recent bitrate played back within the file. Will return 0 if the bitrate has not changed or it is the beginning of the file. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_bitrate_instant(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 indicates the beginning of the file or unchanged bitrate info.</li> +<li><i>n</i> indicates the actual bitrate since the last call.</li> +<li>OV_FALSE indicates that playback is not in progress, and thus there is no instantaneous bitrate information to report.</li> +<li>OV_EINVAL indicates that the stream represented by <tt>vf</tt> is not open.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_callbacks.html b/vorbis/doc/vorbisfile/ov_callbacks.html new file mode 100644 index 0000000..d1b64be --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_callbacks.html @@ -0,0 +1,117 @@ +<html> + +<head> +<title>Vorbisfile - datatype - ov_callbacks</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_callbacks</h1> + +<p><i>declared in "vorbis/codec.h"</i></p> + +<p> +The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location. + +<p> +The ov_callbacks structure does not need to be user-defined if you are +working with stdio-based file manipulation; the <a +href="ov_fopen.html">ov_fopen()</a> and <a +href="ov_open.html">ov_open()</a> calls internally provide default callbacks for +stdio. ov_callbacks are defined and passed to <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> when +implementing non-stdio based stream manipulation (such as playback +from a memory buffer) or when <a +href="ov_open.html#winfoot">ov_open()-style initialization from a <tt>FILE *</tt> is required under Windows [a]</a>. +<p> + +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b>typedef struct { + size_t (*read_func) (void *ptr, size_t size, size_t nmemb, void *datasource); + int (*seek_func) (void *datasource, ogg_int64_t offset, int whence); + int (*close_func) (void *datasource); + long (*tell_func) (void *datasource); +} ov_callbacks;</b></pre> + </td> +</tr> +</table> + +<h3>Relevant Struct Members</h3> +<dl> +<dt><i>read_func</i></dt> +<dd>Pointer to custom data reading function.</dd> +<dt><i>seek_func</i></dt> +<dd>Pointer to custom data seeking function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided seek callback should always return -1 (failure) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd> +<dt><i>close_func</i></dt> +<dd>Pointer to custom data source closure function. Set to NULL if libvorbisfile should not attempt to automatically close the file/data handle.</dd> +<dt><i>tell_func</i></dt> +<dd>Pointer to custom data location function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided tell callback should always return -1 (failure) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd> +</dl> + +<p> + +<h3>Predefined callbacks</h3> +The header vorbis/vorbisfile.h provides several predefined static ov_callbacks structures that may be passed to <a +href="ov_open_callbacks.html">ov_open_callbacks()</a>: +<dl> +<dt><tt>OV_CALLBACKS_DEFAULT</tt><dd> + +These callbacks provide the same behavior as used internally by <a +href="ov_fopen.html">ov_fopen()</a> and <a +href="ov_open.html">ov_open()</a>. + +<dt><tt>OV_CALLBACKS_NOCLOSE</tt><dd> + +The same as <tt>OV_CALLBACKS_DEFAULT</tt>, but with the +<tt>close_func</tt> field set to NULL. The most typical use would be +to use <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to +provide the same behavior as <a href="ov_open.html">ov_open()</a>, but +not close the file/data handle in <a +href="ov_clear.html">ov_clear()</a>. + +<dt><tt>OV_CALLBACKS_STREAMONLY</tt><dd> + +A set of callbacks that set <tt>seek_func</tt> and <tt>tell_func</tt> +to NULL, thus forcing strict streaming-only behavior regardless of +whether or not the input is actually seekable. + +<dt><tt>OV_CALLBACKS_STREAMONLY_NOCLOSE</tt><dd> + +The same as <tt>OV_CALLBACKS_STREAMONLY</tt>, but with +<tt>close_func</tt> also set to null, preventing libvorbisfile from +attempting to close the file/data handle in <a +href="ov_clear.html">ov_clear()</a>. + +</dl> +<p> + +<h3>Examples and usage</h3> + +See <a href="callbacks.html">the callbacks and non-stdio I/O document</a> for more +detailed information on required behavior of the various callback +functions.<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_clear.html b/vorbis/doc/vorbisfile/ov_clear.html new file mode 100644 index 0000000..e67107c --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_clear.html @@ -0,0 +1,64 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_clear</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_clear</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> After a bitstream has been opened using <a href="ov_fopen.html">ov_fopen()</a>/<a href="ov_open.html">ov_open()</a>/<a href="ov_open_callbacks.html">ov_open_callbacks()</a> and decoding is complete, the application must call <tt>ov_clear()</tt> to clear +the decoder's buffers. <tt>ov_clear()</tt> will also close the file unless it was opened using <a href="ov_open_callbacks.html">ov_open_callbacks()</a> with the <tt>close_func</tt> callback set to NULL.<p> + +<tt>ov_clear()</tt> must also be called after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_clear(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. After <tt>ov_clear</tt> has been called, the contents of this structure are deallocated, and it can no longer be used without being reinitialized by a call to <a href="ov_fopen.html">ov_fopen()</a>, <a href="ov_open.html">ov_open()</a> or <a href="ov_open_callbacks.html">ov_open_callbacks()</a>.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 for success</li> +</blockquote> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_comment.html b/vorbis/doc/vorbisfile/ov_comment.html new file mode 100644 index 0000000..9f1b499 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_comment.html @@ -0,0 +1,66 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_bitrate</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_comment</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns a pointer to the <a href="../libvorbis/vorbis_comment.html">vorbis_comment</a> struct for the specified bitstream. For nonseekable streams, returns the struct for the current bitstream. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +vorbis_comment *ov_comment(OggVorbis_File *vf,int link); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the <a href="../libvorbis/vorbis_comment.html">vorbis_comment</a> struct for the current bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>Returns the vorbis_comment struct for the specified bitstream.</li> +<li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li> +</blockquote> +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_crosslap.html b/vorbis/doc/vorbisfile/ov_crosslap.html new file mode 100644 index 0000000..0b2b102 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_crosslap.html @@ -0,0 +1,100 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_crosslap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_crosslap()</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>ov_crosslap overlaps and blends the boundary at a transition +between two separate streams represented by separate <a +href="OggVorbis_File.html">OggVorbis_File</a> structures. For lapping +transitions due to seeking within a single stream represented by a +single <a href="OggVorbis_File.html">OggVorbis_File</a> structure, +consider using the lapping versions of the <a +href="seeking.html">vorbisfile seeking functions</a> instead. + +<p>ov_crosslap is used between the last (usually ov_read) call on +the old stream and the first ov_read from the new stream. Any +desired positioning of the new stream must occur before the call to +ov_crosslap() as a seek dumps all prior lapping information from a +stream's decode state. Crosslapping does not introduce or remove any +extraneous samples; positioning works exactly as if ov_crosslap was not +called. + +<p>ov_crosslap will lap between streams of differing numbers of +channels. Any extra channels from the old stream are ignored; playback +of these channels simply ends. Extra channels in the new stream are +lapped from silence. ov_crosslap will also lap between streams links +of differing sample rates. In this case, the sample rates are ignored +(no implicit resampling is done to match playback). It is up to the +application developer to decide if this behavior makes any sense in a +given context; in practical use, these default behaviors perform +sensibly. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_crosslap(<a href="OggVorbis_File.html">OggVorbis_File</a> *old, <a href="OggVorbis_File.html">OggVorbis_File</a> *new); + +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>old</i></dt> +<dd>A pointer to the OggVorbis_File structure representing the origin stream from which to transition playback.</dd> + +<dt><i>new</i></dt> +<dd>A pointer to the OggVorbis_File structure representing the stream with which playback continues.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<dl> +<dt>OV_EINVAL</dt> + <dd>crosslap called with an OggVorbis_File structure that isn't open.</dd> +<dt>OV_EFAULT</dt> + <dd>internal error; implies a library bug or external heap corruption.</dd> +<dt>OV_EREAD</dt> + <dd> A read from media returned an error.</dd> +<dt>OV_EOF</dt> + <dd>indicates stream <tt>vf2</tt> is at end of file, or that <tt>vf1</tt> is at end of file immediately after a seek (making crosslap impossible as there's no preceding decode state to crosslap).</dd> +<dt><i>0</i></dt> + <dd>success.</dd> +</dl> +</blockquote> + + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_fopen.html b/vorbis/doc/vorbisfile/ov_fopen.html new file mode 100644 index 0000000..9a7b14b --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_fopen.html @@ -0,0 +1,124 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_fopen</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_fopen</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This is the simplest function used to open and initialize an OggVorbis_File +structure. It sets up all the related decoding structure. +<p>The first argument is a file path suitable +for passing to fopen(). <tt>vf</tt> should be a pointer to an empty +OggVorbis_File structure -- this is used for ALL the externally visible +libvorbisfile functions. Once this has been called, the same <a +href="OggVorbis_File.html">OggVorbis_File</a> struct should be passed +to all the libvorbisfile functions. +<p>The <tt>vf</tt> structure initialized using ov_fopen() must +eventually be cleaned using <a href="ov_clear.html">ov_clear()</a>. + +<p> +It is often useful to call <tt>ov_fopen()</tt> simply to determine +whether a given file is a Vorbis bitstream. If the <tt>ov_fopen()</tt> +call fails, then the file is either inaccessable (errno is set) or not +recognizable as Vorbis (errno unchanged). If the call succeeds but +the initialized <tt>vf</tt> structure will not be used, the +application is responsible for calling <a +href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and +close the file.<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_fopen(const char *path,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>path</i></dt> +<dd>Null terminated string containing a file path suitable for passing to <tt>fopen()</tt>. +</dd> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 indicates success</li> + +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<h3>Notes</h3> +<dl> + +<dt><b>[a] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call +<tt>ov_open_callbacks()</tt> +in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback +thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming +call, given that the full structure of the file is determined at this point, +which may require reading large parts of the file under certain circumstances +(determining all the logical bitstreams in one physical bitstream, for +example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[b] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[c] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> + +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_info.html b/vorbis/doc/vorbisfile/ov_info.html new file mode 100644 index 0000000..b94fa68 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_info.html @@ -0,0 +1,64 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_info</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_info</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the <a href="../libvorbis/vorbis_info.html">vorbis_info</a> struct for the specified bitstream. For nonseekable files, always returns the current vorbis_info struct. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +vorbis_info *ov_info(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,int link); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. </dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the <a href="../libvorbis/vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>Returns the vorbis_info struct for the specified bitstream. Returns vorbis_info for current bitstream if the file is nonseekable or i=-1.</li> +<li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li> +</blockquote> +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_open.html b/vorbis/doc/vorbisfile/ov_open.html new file mode 100644 index 0000000..d0311ce --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_open.html @@ -0,0 +1,183 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_open</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_open</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>ov_open is one of three initialization functions used to initialize +an OggVorbis_File structure and prepare a bitstream for playback. + +<p><em><b> WARNING for Windows developers: </b> Do not use ov_open() in +Windows applications; Windows linking places restrictions on +passing <tt>FILE *</tt> handles successfully, and ov_open() runs +afoul of these restrictions <a href="#winfoot">[a]</a>. See the <a +href="ov_open_callbacks.html">ov_open_callbacks() page </a> for +details on using <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. </em> + +<p>The first argument must be a file pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream). <tt>vf</tt> should be a pointer to the +OggVorbis_File structure -- this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <a href="OggVorbis_File.html">OggVorbis_File</a> +struct should be passed to all the libvorbisfile functions.<p> + +The <tt>vf</tt> structure initialized using ov_fopen() must eventually +be cleaned using <a href="ov_clear.html">ov_clear()</a>. Once a +<tt>FILE *</tt> handle is passed to ov_open() successfully, the +application MUST NOT <tt>fclose()</tt> or in any other way manipulate +that file handle. Vorbisfile will close the file in <a +href="ov_clear.html">ov_clear()</a>. If the application must be able +to close the <tt>FILE *</tt> handle itself, see <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> with the use of +<tt>OV_CALLBACKS_NOCLOSE</tt>. + +<p>It is often useful to call <tt>ov_open()</tt> simply to determine +whether a given file is a Vorbis bitstream. If the <tt>ov_open()</tt> +call fails, then the file is not recognizable as Vorbis. If the call +succeeds but the initialized <tt>vf</tt> structure will not be used, +the application is responsible for calling <a +href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and +close the file.<p> + +If [and only if] an <tt>ov_open()</tt> call fails, the application +must explicitly <tt>fclose()</tt> the <tt>FILE *</tt> pointer itself. + + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_open(FILE *f,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,char *initial,long ibytes); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>f</i></dt> +<dd>File pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream).</dd> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +<dt><i>initial</i></dt> +<dd>Typically set to NULL. This parameter is useful if some data has already been +read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt> +should be a pointer to a buffer containing the data read.</dd> +<dt><i>ibytes</i></dt> +<dd>Typically set to 0. This parameter is useful if some data has already been +read from the file and the stream is not seekable. In this case, <tt>ibytes</tt> +should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt></dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 indicates success</li> + +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<a name="notes"></a> +<h3>Notes</h3> +<dl> + +<a name="winfoot"></a> +<dt><b>[a] Windows and ov_open()</b><p> + +<dd>Under Windows, stdio file access is implemented in each of many +variants of crt.o, several of which are typically installed on any one +Windows machine. If libvorbisfile and the application using +libvorbisfile are not linked against the exact same +version/variant/build of crt.o (and they usually won't be, especially +using a prebuilt libvorbis DLL), <tt>FILE *</tt> handles cannot be +opened in the application and then passed to vorbisfile to be used +by stdio calls from vorbisfile's different version of CRT. For this +reason, using <a href="ov_open.html">ov_open()</a> under Windows +without careful, expert linking will typically cause a protection +fault. Windows programmers should use <a +href="ov_fopen.html">ov_fopen()</a> (which will only use libvorbis's +crt.o) or <a href="ov_open_callbacks.html">ov_open_callbacks()</a> +(which will only use the application's crt.o) instead.<p> + +This warning only applies to Windows and only applies to <a +href="ov_open.html">ov_open()</a>. It is perfectly safe to use <a +href="ov_open.html">ov_open()</a> on all other platforms.<p> + +For more information, see the following microsoft pages on <a +href="http://msdn2.microsoft.com/en-us/library/abx4dbyh(VS.80).aspx">C +runtime library linking</a> and a specific description of <a +href="http://msdn2.microsoft.com/en-us/library/ms235460(VS.80).aspx">restrictions +on passing CRT objects across DLL boundaries</a>. + +<p> + +<dt><b>[b] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call +<tt>ov_open()</tt> +in the main control thread--instead, call <tt>ov_open()</tt> in your decode/playback +thread. This is important because <tt>ov_open()</tt> may be a fairly time-consuming +call, given that the full structure of the file is determined at this point, +which may require reading large parts of the file under certain circumstances +(determining all the logical bitstreams in one physical bitstream, for +example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[c] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[d] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> + +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_open_callbacks.html b/vorbis/doc/vorbisfile/ov_open_callbacks.html new file mode 100644 index 0000000..6d59e0b --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_open_callbacks.html @@ -0,0 +1,147 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_open_callbacks</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_open_callbacks</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This is an alternative function used to open and initialize an +OggVorbis_File structure when using a data source other than a file, +when its necessary to modify default file access behavior, or to +initialize a Vorbis decode from a <tt>FILE *</tt> pointer under +Windows where <a href="ov_open.html">ov_open()</a> cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +<p>Once ov_open_callbacks() has been called, the same +<tt>OggVorbis_File</tt> struct should be passed to all the +libvorbisfile functions. Unlike <a +href="ov_fopen.html">ov_fopen()</a> and <a +href="ov_open.html">ov_open()</a>, ov_open_callbacks() may be used to +instruct vorbisfile to either automatically close or not to close the +file/data access handle in <a href="ov_clear.html">ov_clear()</a>. +Automatic closure is disabled by passing NULL as the close callback, +or using one of the predefined callback sets that specify a NULL close +callback. The application is responsible for closing a file when a +call to ov_open_callbacks() is unsuccessful.<p> + +See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for +information on designing and specifying custom callback functions.<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_open_callbacks(void *datasource, <a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *initial, long ibytes, <a href="ov_callbacks.html">ov_callbacks</a> callbacks); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>datasource</i></dt> +<dd>Pointer to a data structure allocated by the calling application, containing any state needed by the callbacks provided.</dd> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +<dt><i>initial</i></dt> +<dd>Typically set to NULL. This parameter is useful if some data has already been +read from the stream and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt> +should be a pointer to a buffer containing the data read.</dd> +<dt><i>ibytes</i></dt> +<dd>Typically set to 0. This parameter is useful if some data has already been +read from the stream and the stream is not seekable. In this case, <tt>ibytes</tt> +should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd> +<dt><i>callbacks</i></dt> +<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 for success</li> +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<h3>Notes</h3> +<dl> + +<dt><b>[a] Windows and use as an ov_open() substitute</b><p> Windows +applications should not use <a href="ov_open.html">ov_open()</a> due +to the likelihood of <a href="ov_open.html#winfoot">CRT linking +mismatches and runtime protection faults +[ov_open:a]</a>. ov_open_callbacks() is a safe substitute; specifically: + +<pre><tt>ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt> +</pre> + +... provides exactly the same functionality as <a +href="ov_open.html">ov_open()</a> but will always work correctly under +Windows, regardless of linking setup details.<p> + +<dt><b>[b] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call +<tt>ov_open_callbacks()</tt> +in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback +thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming +call, given that the full structure of the file is determined at this point, +which may require reading large parts of the file under certain circumstances +(determining all the logical bitstreams in one physical bitstream, for +example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[c] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[d] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> + +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_seek.html b/vorbis/doc/vorbisfile/ov_pcm_seek.html new file mode 100644 index 0000000..81b0c1c --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_seek.html @@ -0,0 +1,83 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_seek</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_seek</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the offset specified (in pcm samples) within the physical bitstream. This function only works for seekable streams. +<p>This also updates everything needed within the +decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from +the newly seeked to position. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_pcm_seek(OggVorbis_File *vf,ogg_int64_t pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in pcm samples to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_seek_lap.html b/vorbis/doc/vorbisfile/ov_pcm_seek_lap.html new file mode 100644 index 0000000..6310e42 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_seek_lap.html @@ -0,0 +1,103 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_seek_lap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_seek_lap</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the offset specified (in pcm samples) within the physical bitstream. This variant of <a +href="ov_pcm_seek.html">ov_pcm_seek</a> also automatically +crosslaps the transition from the previous playback position into the +new playback position in order to eliminate clicking and boundary +discontinuities. Otherwise, usage and behavior is identical to <a +href="ov_pcm_seek.html">ov_pcm_seek</a>. + +<p>ov_pcm_seek_lap also updates everything needed within the decoder, +so you can immediately call <a href="ov_read.html">ov_read()</a> and +get data from the newly seeked to position. + +<p>ov_pcm_seek_lap will lap between logical stream links of differing +numbers of channels. Any extra channels from the origin of the seek +are ignored; playback of these channels simply ends. Extra channels at +the destination are lapped from silence. ov_pcm_seek_lap will also +lap between logical stream links of differing sample rates. In this +case, the sample rates are ignored (no implicit resampling is done to +match playback). It is up to the application developer to decide if +this behavior makes any sense in a given context; in practical use, +these default behaviors perform sensibly. + +<p>This function only works for seekable streams. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_pcm_seek_lap(OggVorbis_File *vf,ogg_int64_t pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in pcm samples to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EOF - Indicates stream is at end of file immediately after a seek + (making crosslap impossible as there's no preceeding decode state to crosslap). + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_seek_page.html b/vorbis/doc/vorbisfile/ov_pcm_seek_page.html new file mode 100644 index 0000000..8f1959a --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_seek_page.html @@ -0,0 +1,84 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_seek_page</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_seek_page</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the closest page preceding the specified location (in pcm samples) within the physical bitstream. This function only works for seekable streams. +<p>This function is faster than <a href="ov_pcm_seek.html">ov_pcm_seek</a> because the function can begin decoding at a page boundary rather than seeking through any remaining samples before the specified location. However, it is less accurate. +<p>This also updates everything needed within the +decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from +the newly seeked to position. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_pcm_seek_page(OggVorbis_File *vf,ogg_int64_t pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in pcm samples to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_seek_page_lap.html b/vorbis/doc/vorbisfile/ov_pcm_seek_page_lap.html new file mode 100644 index 0000000..d9694e8 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_seek_page_lap.html @@ -0,0 +1,112 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_seek_page_lap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_seek_page_lap</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the closest page preceding the specified location (in pcm +samples) within the physical bitstream. This variant of <a +href="ov_pcm_seek_page.html">ov_pcm_seek_page</a> also automatically +crosslaps the transition from the previous playback position into the +new playback position in order to eliminate clicking and boundary +discontinuities. Otherwise, usage and behavior is identical to <a +href="ov_pcm_seek_page.html">ov_pcm_seek_page</a>. + +<p>This function is faster than <a +href="ov_pcm_seek_lap.html">ov_pcm_seek_lap</a> because the function +can begin decoding at a page boundary rather than seeking through any +remaining samples before the specified location. However, it is less +accurate. + +<p>ov_pcm_seek_page_lap also updates everything needed within the +decoder, so you can immediately call <a +href="ov_read.html">ov_read()</a> and get data from the newly seeked +to position. + +<p>ov_pcm_seek_page_lap will lap between logical stream links of +differing numbers of channels. Any extra channels from the origin of +the seek are ignored; playback of these channels simply ends. Extra +channels at the destination are lapped from silence. +ov_pcm_seek_page_lap will also lap between logical stream links of +differing sample rates. In this case, the sample rates are ignored +(no implicit resampling is done to match playback). It is up to the +application developer to decide if this behavior makes any sense in a +given context; in practical use, these default behaviors perform +sensibly. + +<p>This function only works for seekable streams. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_pcm_seek_page_lap(OggVorbis_File *vf,ogg_int64_t pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in pcm samples to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EOF - Indicates stream is at end of file immediately after a seek + (making crosslap impossible as there's no preceeding decode state to crosslap). + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_tell.html b/vorbis/doc/vorbisfile/ov_pcm_tell.html new file mode 100644 index 0000000..2d8ea83 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_tell.html @@ -0,0 +1,63 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_tell</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_tell</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the current offset in samples. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +ogg_int64_t ov_pcm_tell(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li><i>n</i> indicates the current offset in samples.</li> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_pcm_total.html b/vorbis/doc/vorbisfile/ov_pcm_total.html new file mode 100644 index 0000000..297a8e1 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_pcm_total.html @@ -0,0 +1,67 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_pcm_total</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_pcm_total</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the total pcm samples of the physical bitstream or a specified logical bitstream. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +ogg_int64_t ov_pcm_total(OggVorbis_File *vf,int i); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is unseekable.</li> +<li> +total length in pcm samples of content if i=-1.</li> +<li>length in pcm samples of logical bitstream if i=0 to n.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_raw_seek.html b/vorbis/doc/vorbisfile/ov_raw_seek.html new file mode 100644 index 0000000..04ed549 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_raw_seek.html @@ -0,0 +1,83 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_raw_seek</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_raw_seek</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the offset specified (in compressed raw bytes) within the physical bitstream. This function only works for seekable streams. +<p>This also updates everything needed within the +decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from +the newly seeked to position. +<p>When seek speed is a priority, this is the best seek funtion to use. +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_raw_seek(OggVorbis_File *vf,long pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in compressed bytes to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_raw_seek_lap.html b/vorbis/doc/vorbisfile/ov_raw_seek_lap.html new file mode 100644 index 0000000..8e8c24d --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_raw_seek_lap.html @@ -0,0 +1,110 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_raw_seek_lap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_raw_seek_lap</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Seeks to the offset specified (in compressed raw bytes) within the +physical bitstream. This variant of <a +href="ov_raw_seek.html">ov_raw_seek</a> also automatically crosslaps +the transition from the previous playback position into the new +playback position in order to eliminate clicking and boundary +discontinuities. Otherwise, usage and behavior is identical to <a +href="ov_raw_seek.html">ov_raw_seek</a>. + +<p>When seek speed is a priority, but crosslapping is still desired, +this is the best seek funtion to use. + +<p>ov_raw_seek_lap also updates everything needed within the decoder, +so you can immediately call <a href="ov_read.html">ov_read()</a> and +get data from the newly seeked to position. + +<p>ov_raw_seek_lap will lap between logical stream links of differing +numbers of channels. Any extra channels from the origin of the seek +are ignored; playback of these channels simply ends. Extra channels at +the destination are lapped from silence. ov_raw_seek_lap will also +lap between logical stream links of differing sample rates. In this +case, the sample rates are ignored (no implicit resampling is done to +match playback). It is up to the application developer to decide if +this behavior makes any sense in a given context; in practical use, +these default behaviors perform sensibly. + +<p>This function only works for seekable streams. + + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_raw_seek_lap(OggVorbis_File *vf,long pos); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>pos</i></dt> +<dd>Position in compressed bytes to seek to in the bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EOF - Indicates stream is at end of file immediately after a seek + (making crosslap impossible as there's no preceeding decode state to crosslap). + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_raw_tell.html b/vorbis/doc/vorbisfile/ov_raw_tell.html new file mode 100644 index 0000000..5f30eff --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_raw_tell.html @@ -0,0 +1,65 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_raw_tell</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_raw_tell</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the current offset in raw compressed bytes.</p> + +<p>Note that if you later use ov_raw_seek() to return to this point, you won't generally get back to exactly the same place, due to internal buffering. Also note that a read operation may not cause a change to the current raw offset - only a read that requires reading more data from the underlying data source will do that.</p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +ogg_int64_t ov_raw_tell(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li><i>n</i> indicates the current offset in bytes.</li> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_raw_total.html b/vorbis/doc/vorbisfile/ov_raw_total.html new file mode 100644 index 0000000..d9d8303 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_raw_total.html @@ -0,0 +1,68 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_raw_total</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_raw_total</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the total (compressed) bytes of the physical bitstream or a specified logical bitstream. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable</li> +<li><tt>n</tt> +total length in compressed bytes of content if i=-1.</li> +<li><tt>n</tt> length in compressed bytes of logical bitstream if i=0 to n.</li> +</blockquote> +<p> + + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_read.html b/vorbis/doc/vorbisfile/ov_read.html new file mode 100644 index 0000000..5461a84 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_read.html @@ -0,0 +1,148 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_read</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_read()</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> + This is the main function used to decode a Vorbis file within a + loop. It returns up to the specified number of bytes of decoded PCM audio + in the requested endianness, signedness, and word size. If the audio is + multichannel, the channels are interleaved in the output buffer. + If the passed in buffer is large, <tt>ov_read()</tt> will not fill + it; the passed in buffer size is treated as a <em>limit</em> and + not a request. + +<p>The output channels are in stream order and not remapped. Vorbis I +defines channel order as follows: + +<ul> +<li>one channel - the stream is monophonic +<li>two channels - the stream is stereo. channel order: left, right +<li>three channels - the stream is a 1d-surround encoding. channel order: left, +center, right +<li>four channels - the stream is quadraphonic surround. channel order: front left, +front right, rear left, rear right +<li>five channels - the stream is five-channel surround. channel order: front left, +center, front right, rear left, rear right +<li>six channels - the stream is 5.1 surround. channel order: front left, center, +front right, rear left, rear right, LFE +<li>seven channels - the stream is 6.1 surround. channel order: front left, center, +front right, side left, side right, rear center, LFE +<li>eight channels - the stream is 7.1 surround. channel order: front left, center, +front right, side left, side right, rear left, rear right, +LFE +<li>greater than eight channels - channel use and order is undefined +</ul> + +<p>Note that up to this point, the Vorbisfile API could more or less hide the + multiple logical bitstream nature of chaining from the toplevel + application if the toplevel application didn't particularly care. + However, when reading audio back, the application must be aware + that multiple bitstream sections do not necessarily use the same + number of channels or sampling rate. <p> <tt>ov_read()</tt> passes + back the index of the sequential logical bitstream currently being + decoded (in <tt>*bitstream</tt>) along with the PCM data in order + that the toplevel application can handle channel and/or sample + rate changes. This number will be incremented at chaining + boundaries even for non-seekable streams. For seekable streams, it + represents the actual chaining index within the physical bitstream. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>buffer</i></dt> +<dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd> +<dt><i>length</i></dt> +<dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd> +<dt><i>bigendianp</i></dt> +<dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b +ig endian. Typical value is 0.</dd> +<dt><i>word</i></dt> +<dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or +16-bit samples. Typical value is 2.</dd> +<dt><i>sgned</i></dt> +<dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd> +<dt><i>bitstream</i></dt> +<dd>A pointer to the number of the current logical bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<dl> +<dt>OV_HOLE</dt> + <dd>indicates there was an interruption in the data. + <br>(one of: garbage between pages, loss of sync followed by + recapture, or a corrupt page)</dd> +<dt>OV_EBADLINK</dt> + <dd>indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.</dd> +<dt>OV_EINVAL</dt> + <dd>indicates the initial file headers couldn't be read or + are corrupt, or that the initial open call for <i>vf</i> + failed.</dd> +<dt>0</dt> + <dd>indicates EOF</dd> +<dt><i>n</i></dt> + <dd>indicates actual number of bytes read. <tt>ov_read()</tt> will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than <tt>length</tt>. +</dl> +</blockquote> + +<h3>Notes</h3> +<p><b>Typical usage:</b> +<blockquote> +<tt>bytes_read = ov_read(&vf, +buffer, 4096,0,2,1,&current_section)</tt> +</blockquote> + +This reads up to 4096 bytes into a buffer, with signed 16-bit +little-endian samples. +</p> + + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_read_filter.html b/vorbis/doc/vorbisfile/ov_read_filter.html new file mode 100644 index 0000000..e3f2e84 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_read_filter.html @@ -0,0 +1,114 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_read_filter</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_read_filter()</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> + <tt>ov_read_filter()</tt> is a variant of <a + href="ov_read.html">ov_read()</a>, the main function used to decode + a Vorbis file within a loop. It passes the decoded floating point + PCM data to the filter specified in the function arguments before + converting the data to integer output samples. All other aspects of + its behavior are as with <a href="ov_read.html">ov_read()</a>. +<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_read_filter(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream, + void (*filter)(float **pcm,long channels,long samples,void *filter_param),void *filter_param); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>buffer</i></dt> +<dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd> +<dt><i>length</i></dt> +<dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd> +<dt><i>bigendianp</i></dt> +<dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b +ig endian. Typical value is 0.</dd> +<dt><i>word</i></dt> +<dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or +16-bit samples. Typical value is 2.</dd> +<dt><i>sgned</i></dt> +<dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd> +<dt><i>bitstream</i></dt> +<dd>A pointer to the number of the current logical bitstream.</dd> +<dt><i>filter</i></dt> +<dd>Filter function to process float PCM data prior to conversion to interleaved integer output.</dd> +<dt><i>filter_param</i></dt> +<dd>Data to pass through to the filter function.</dd> + +</dl> + + +<h3>Return Values</h3> +<blockquote> +<dl> +<dt>OV_HOLE</dt> + <dd>indicates there was an interruption in the data. + <br>(one of: garbage between pages, loss of sync followed by + recapture, or a corrupt page)</dd> +<dt>OV_EBADLINK</dt> + <dd>indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.</dd> +<dt>0</dt> + <dd>indicates EOF</dd> +<dt><i>n</i></dt> + <dd>indicates actual number of bytes read. <tt>ov_read()</tt> will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than <tt>length</tt>. +</dl> +</blockquote> + +<h3>Notes</h3> +<p><b>Typical usage:</b> +<blockquote> +<tt>bytes_read = ov_read_filter(&vf, +buffer, 4096,0,2,1,&current_section, filter, (void *)filter_data_ptr)</tt> +</blockquote> + +This reads up to 4096 bytes into a buffer, with signed 16-bit +little-endian samples. The decoded data is passed to the function <tt>filter</tt> before integer conversiona nd interleave. +</p> + + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_read_float.html b/vorbis/doc/vorbisfile/ov_read_float.html new file mode 100644 index 0000000..0c36eb0 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_read_float.html @@ -0,0 +1,105 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_read_float</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_read_float()</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> + This is the function used to decode a Vorbis file within a loop, but + returns samples in native float format instead of in integer formats. +</p><p> + For information on channel ordering and how ov_read_float() deals with the complex issues + of chaining, etc, refer to the documentation for <a href="ov_read.html">ov_read()</a>. +</p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_read_float(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, float ***pcm_channels, int samples, int *bitstream); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions.</dd> +<dt><i>pcm_channels</i></dt> +<dd>A pointer to an output buffer. The pointer will be set to the decoded output buffer.</dd> +<dt><i>samples</i></dt> +<dd>Maximum number of decoded samples to produce.</dd> +<dt><i>bitstream</i></dt> +<dd>A pointer to the number of the current logical bitstream.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<dl> +<dt>OV_HOLE</dt> + <dd>indicates there was an interruption in the data. + <br>(one of: garbage between pages, loss of sync followed by + recapture, or a corrupt page)</dd> +<dt>OV_EBADLINK</dt> + <dd>indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.</dd> +<dt>OV_EINVAL</dt> + <dd>indicates the initial file headers couldn't be read or + are corrupt, or that the initial open call for <i>vf</i> + failed.</dd> +<dt>0</dt> + <dd>indicates EOF</dd> +<dt><i>n</i></dt> + <dd>indicates actual number of samples read. <tt>ov_read_float()</tt> will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than <tt>length</tt>. +</dl> +</blockquote> + +<h3>Notes</h3> +<p><b>Typical usage:</b> +<blockquote> +<tt>float **pcm; +samples_read = ov_read_float(&vf,pcm, 1024, &current_section)</tt> +</blockquote> + +This decodes up to 1024 float samples. +</p> + +<br> +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2002 vorbis team</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + + +</body> + +</html> + + + diff --git a/vorbis/doc/vorbisfile/ov_seekable.html b/vorbis/doc/vorbisfile/ov_seekable.html new file mode 100644 index 0000000..59b6e97 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_seekable.html @@ -0,0 +1,63 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_seekable</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_seekable</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This indicates whether or not the bitstream is seekable. + + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_seekable(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 indicates that the file is not seekable.</li> +<li>nonzero indicates that the file is seekable.</li> +</blockquote> +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_serialnumber.html b/vorbis/doc/vorbisfile/ov_serialnumber.html new file mode 100644 index 0000000..1b64415 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_serialnumber.html @@ -0,0 +1,67 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_serialnumber</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_serialnumber</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the serialnumber of the specified logical bitstream link number within the overall physical bitstream. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_serialnumber(OggVorbis_File *vf,int i); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the serial number of the current bitstream, this parameter should be set to -1.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li> +-1 if the specified logical bitstream <i>i</i> does not exist.</li> + +<li>Returns the serial number of the logical bitstream <i>i</i> or the serial number of the current bitstream if the file is nonseekable.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_streams.html b/vorbis/doc/vorbisfile/ov_streams.html new file mode 100644 index 0000000..e455b07 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_streams.html @@ -0,0 +1,64 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_streams</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_streams</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the number of logical bitstreams within our physical bitstream. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +long ov_streams(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. </dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li> +1 indicates a single logical bitstream or an unseekable file.</li> +<li><i>n</i> indicates the number of logical bitstreams.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_test.html b/vorbis/doc/vorbisfile/ov_test.html new file mode 100644 index 0000000..cb11d01 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_test.html @@ -0,0 +1,104 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_test</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_test</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> +This partially opens a vorbis file to test for Vorbis-ness. It loads +the headers for the first chain and tests for seekability (but does +not seek). Use <a href="ov_test_open.html">ov_test_open()</a> to +finish opening the file or <a href="ov_clear.html">ov_clear</a> to +close/free it. Note that vorbisfile does <b>not</b> take ownership of +the file if the call fails; the calling applicaiton is responsible for +closing the file if this call returns an error. +<p> + +<p><em><b> WARNING for Windows developers: </b> Do not use ov_test() +in Windows applications; Windows linking places restrictions on +passing <tt>FILE *</tt> handles successfully, and ov_test() runs afoul +of these restrictions <a href="#winfoot">[a]</a> in exactly the same +way as <a href="ov_open.html">ov_open()</a>. See the <a +href="ov_test_callbacks.html">ov_test_callbacks() page </a> for +details on using <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> instead. </em> +<p> + +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_test(FILE *f,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,char *initial,long ibytes); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>f</i></dt> +<dd>File pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream).</dd> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +<dt><i>initial</i></dt> +<dd>Typically set to NULL. This parameter is useful if some data has already been +read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt> +should be a pointer to a buffer containing the data read.</dd> +<dt><i>ibytes</i></dt> +<dd>Typically set to 0. This parameter is useful if some data has already been +read from the file and the stream is not seekable. In this case, <tt>ibytes</tt> +should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt></dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 for success</li> + +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<h3>Notes</h3> + +All the <a href="ov_open.html#notes">notes from ov_open()</a> apply to ov_test(). + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_test_callbacks.html b/vorbis/doc/vorbisfile/ov_test_callbacks.html new file mode 100644 index 0000000..9abc84c --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_test_callbacks.html @@ -0,0 +1,111 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_test_callbacks</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_test_callbacks</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This is an alternative function used to open and test an OggVorbis_File +structure when using a data source other than a file, +when its necessary to modify default file access behavior, or to +test for Vorbis content from a <tt>FILE *</tt> pointer under +Windows where <a href="ov_open.html">ov_test()</a> cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +<p>Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions. +<p> +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_test_callbacks(void *datasource, <a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *initial, long ibytes, <a href="ov_callbacks.html">ov_callbacks</a> callbacks); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>f</i></dt> +<dd>File pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream).</dd> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +<dt><i>initial</i></dt> +<dd>Typically set to NULL. This parameter is useful if some data has already been +read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt> +should be a pointer to a buffer containing the data read.</dd> +<dt><i>ibytes</i></dt> +<dd>Typically set to 0. This parameter is useful if some data has already been +read from the file and the stream is not seekable. In this case, <tt>ibytes</tt> +should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd> +<dt><i>callbacks</i></dt> +<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 for success</li> +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<h3>Notes</h3> +<dl> + +<dt><b>[a] Windows and use as an ov_test() substitute</b><p> Windows +applications should not use <a href="ov_test.html">ov_test()</a> due +to the likelihood of <a href="ov_open.html#winfoot">CRT linking +mismatches and runtime protection faults +[ov_open:a]</a>. ov_test_callbacks() is a safe substitute; specifically: + +<pre><tt>ov_test_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt> +</pre> + +... provides exactly the same functionality as <a +href="ov_test.html">ov_test()</a> but will always work correctly under +Windows, regardless of linking setup details.<p> + +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_test_open.html b/vorbis/doc/vorbisfile/ov_test_open.html new file mode 100644 index 0000000..6fb8ae9 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_test_open.html @@ -0,0 +1,82 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_test_open</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_test_open</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p> +Finish opening a file partially opened with <a href="ov_test.html">ov_test()</a> +or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>. +<p> + +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_test_open(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same <tt>OggVorbis_File</tt> +struct should be passed to all the libvorbisfile functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li> +0 for success</li> + +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> + + + + + + + diff --git a/vorbis/doc/vorbisfile/ov_time_seek.html b/vorbis/doc/vorbisfile/ov_time_seek.html new file mode 100644 index 0000000..ec19ce3 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_seek.html @@ -0,0 +1,82 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_seek</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_seek</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>For seekable +streams, this seeks to the given time. For implementing seeking in a player, +this is the only function generally needed. This also updates everything needed within the +decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from +the newly seeked to position. This function does not work for unseekable streams. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_time_seek(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd> +<dt><i>pos</i></dt> +<dd>Location to seek to within the file, specified in seconds.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_time_seek_lap.html b/vorbis/doc/vorbisfile/ov_time_seek_lap.html new file mode 100644 index 0000000..f300f3b --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_seek_lap.html @@ -0,0 +1,105 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_seek_lap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_seek_lap</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>For seekable +streams, ov_time_seek_lap seeks to the given time. This variant of <a +href="ov_time_seek.html">ov_time_seek</a> also automatically +crosslaps the transition from the previous playback position into the +new playback position in order to eliminate clicking and boundary +discontinuities. Otherwise, usage and behavior is identical to <a +href="ov_time_seek.html">ov_time_seek</a>. + +<p>ov_time_seek_lap also updates everything needed within the decoder, +so you can immediately call <a href="ov_read.html">ov_read()</a> and +get data from the newly seeked to position. + +<p>ov_time_seek_lap will lap between logical stream links of differing +numbers of channels. Any extra channels from the origin of the seek +are ignored; playback of these channels simply ends. Extra channels at +the destination are lapped from silence. ov_time_seek_lap will also +lap between logical stream links of differing sample rates. In this +case, the sample rates are ignored (no implicit resampling is done to +match playback). It is up to the application developer to decide if +this behavior makes any sense in a given context; in practical use, +these default behaviors perform sensibly. + +<p> This function does not work for unseekable streams. + + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_time_seek_lap(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd> +<dt><i>pos</i></dt> +<dd>Location to seek to within the file, specified in seconds.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EOF - Indicates stream is at end of file immediately after a seek + (making crosslap impossible as there's no preceeding decode state to crosslap). + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_time_seek_page.html b/vorbis/doc/vorbisfile/ov_time_seek_page.html new file mode 100644 index 0000000..271d575 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_seek_page.html @@ -0,0 +1,83 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_seek_page</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_seek_page</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>For seekable +streams, this seeks to closest full page preceding the given time. This function is faster than <a href="ov_time_seek.html">ov_time_seek</a> because it doesn't seek through the last few samples to reach an exact time, but it is also less accurate. This should be used when speed is important. +<p>This function also updates everything needed within the +decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from +the newly seeked to position. +<p>This function does not work for unseekable streams. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_time_seek_page(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd> +<dt><i>pos</i></dt> +<dd>Location to seek to within the file, specified in seconds.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_time_seek_page_lap.html b/vorbis/doc/vorbisfile/ov_time_seek_page_lap.html new file mode 100644 index 0000000..3b1effa --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_seek_page_lap.html @@ -0,0 +1,112 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_seek_page_lap</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_seek_page_lap</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>For seekable streams, ov_time_seek_page_lap seeks to the closest +full page preceeding the given time. This variant of <a +href="ov_time_seek_page.html">ov_time_seek_page</a> also automatically +crosslaps the transition from the previous playback position into the +new playback position in order to eliminate clicking and boundary +discontinuities. Otherwise, usage and behavior is identical to <a +href="ov_time_seek_page.html">ov_time_seek_page</a>. + +<p>ov_time_seek_page_lap is faster than <a +href="ov_time_seek_lap.html">ov_time_seek_lap</a> because it doesn't +seek through the last few samples to reach an exact time, but it is +also less accurate. This should be used when speed is important, but +crosslapping is still desired. + +<p>ov_time_seek_page_lap also updates everything needed within the +decoder, so you can immediately call <a +href="ov_read.html">ov_read()</a> and get data from the newly seeked +to position. + +<p>ov_time_seek_page_lap will lap between logical stream links of +differing numbers of channels. Any extra channels from the origin of +the seek are ignored; playback of these channels simply ends. Extra +channels at the destination are lapped from silence. +ov_time_seek_page_lap will also lap between logical stream links of +differing sample rates. In this case, the sample rates are ignored +(no implicit resampling is done to match playback). It is up to the +application developer to decide if this behavior makes any sense in a +given context; in practical use, these default behaviors perform +sensibly. + +<p>This function does not work for unseekable streams. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_time_seek_page_lap(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd> +<dt><i>pos</i></dt> +<dd>Location to seek to within the file, specified in seconds.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<ul> +<li>0 for success</li> + +<li> +nonzero indicates failure, described by several error codes: + <ul> + <li>OV_ENOSEEK - Bitstream is not seekable. + </li> + <li>OV_EINVAL - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open. + </li> + <li>OV_EREAD - A read from media returned an error. + </li> + <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack + corruption. + </li> + <li>OV_EOF - Indicates stream is at end of file immediately after a seek + (making crosslap impossible as there's no preceeding decode state to crosslap). + </li> + <li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. + </li> + </ul></li> +</ul></blockquote> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_time_tell.html b/vorbis/doc/vorbisfile/ov_time_tell.html new file mode 100644 index 0000000..92d171c --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_tell.html @@ -0,0 +1,63 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_tell</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_tell</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>Returns the current decoding offset in seconds. + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +double ov_time_tell(OggVorbis_File *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li><i>n</i> indicates the current decoding time offset in seconds.</li> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li> +</blockquote> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/ov_time_total.html b/vorbis/doc/vorbisfile/ov_time_total.html new file mode 100644 index 0000000..3b34f93 --- /dev/null +++ b/vorbis/doc/vorbisfile/ov_time_total.html @@ -0,0 +1,67 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_time_total</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>ov_time_total</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + + +<p>Returns the total time in seconds of the physical bitstream or a specified logical bitstream. + + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +double ov_time_total(OggVorbis_File *vf,int i); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>vf</i></dt> +<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.</dd> +<dt><i>i</i></dt> +<dd>Link to the desired logical bitstream. To retrieve the time total for the entire physical bitstream, this parameter should be set to -1.</b></dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable.</li> +<li><tt>n</tt> total length in seconds of content if i=-1.</li> +<li><tt>n</tt> length in seconds of logical bitstream if i=0 to n.</li> +</blockquote> +<p> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/overview.html b/vorbis/doc/vorbisfile/overview.html new file mode 100644 index 0000000..1306495 --- /dev/null +++ b/vorbis/doc/vorbisfile/overview.html @@ -0,0 +1,61 @@ +<html> + +<head> +<title>Vorbisfile - 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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Vorbisfile API Overview</h1> + +<p>The makeup of the Vorbisfile libvorbisfile library API is relatively +simple. It revolves around a single file resource. This file resource is +passed to libvorbisfile, where it is opened, manipulated, and closed, +in the form of an <a href="OggVorbis_File.html">OggVorbis_File</a> +struct. +<p> +The Vorbisfile API consists of the following functional categories: +<p> +<ul> +<li><p><a href="datastructures.html">Base data structures</a> +<li><p><a href="initialization.html">Setup/Teardown</a> +<li><p><a href="decoding.html">Decoding</a> +<li><p><a href="seeking.html">Seeking</a> +<li><p><a href="fileinfo.html">File Information</a> +</ul> +<p> +In addition, the following subjects deserve attention additional to +the above general overview: +<p> +<ul> +<li><p><a href="threads.html">Threading and thread safety</a> +<li><p><a href="callbacks.html">Using [non stdio] custom stream I/O +via callbacks</a> +<li><p><a href="crosslap.html">Sample crosslapping</a> +</ul> +<p> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> + diff --git a/vorbis/doc/vorbisfile/reference.html b/vorbis/doc/vorbisfile/reference.html new file mode 100644 index 0000000..7c3c789 --- /dev/null +++ b/vorbis/doc/vorbisfile/reference.html @@ -0,0 +1,86 @@ +<html> + +<head> +<title>Vorbisfile API Reference</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Vorbisfile API Reference</h1> + +<p> +<b>Data Structures</b><br> +<a href="OggVorbis_File.html">OggVorbis_File</a><br> +<a href="ov_callbacks.html">ov_callbacks</a><br> +<br> +<b>Data Structures from <a href="../libvorbis/index.html">libvorbis</a></b><br> +<a href="../libvorbis/vorbis_comment.html">vorbis_comment</a><br> +<a href="../libvorbis/vorbis_info.html">vorbis_info</a><br> +<br> +<b>Setup/Teardown</b><br> +<a href="ov_fopen.html">ov_fopen()</a><br> +<a href="ov_open.html">ov_open()</a><br> +<a href="ov_open_callbacks.html">ov_open_callbacks()</a><br> +<a href="ov_clear.html">ov_clear()</a><br> +<a href="ov_test.html">ov_test()</a><br> +<a href="ov_test_callbacks.html">ov_test_callbacks()</a><br> +<a href="ov_test_open.html">ov_test_open()</a><br> +<br> +<b>Decoding</b><br> +<a href="ov_read.html">ov_read()</a><br> +<a href="ov_read_float.html">ov_read_float()</a><br> +<a href="ov_read_filter.html">ov_read_filter()</a><br> +<a href="ov_crosslap.html">ov_crosslap()</a><br> +<br> +<b>Seeking</b><br> +<a href="ov_raw_seek.html">ov_raw_seek()</a><br> +<a href="ov_pcm_seek.html">ov_pcm_seek()</a><br> +<a href="ov_time_seek.html">ov_time_seek()</a><br> +<a href="ov_pcm_seek_page.html">ov_pcm_seek_page()</a><br> +<a href="ov_time_seek_page.html">ov_time_seek_page()</a><p> +<a href="ov_raw_seek_lap.html">ov_raw_seek_lap()</a><br> +<a href="ov_pcm_seek_lap.html">ov_pcm_seek_lap()</a><br> +<a href="ov_time_seek_lap.html">ov_time_seek_lap()</a><br> +<a href="ov_pcm_seek_page_lap.html">ov_pcm_seek_page_lap()</a><br> +<a href="ov_time_seek_page_lap.html">ov_time_seek_page_lap()</a><br> +<br> +<b>File Information</b><br> +<a href="ov_bitrate.html">ov_bitrate()</a><br> +<a href="ov_bitrate_instant.html">ov_bitrate_instant()</a><br> +<a href="ov_streams.html">ov_streams()</a><br> +<a href="ov_seekable.html">ov_seekable()</a><br> +<a href="ov_serialnumber.html">ov_serialnumber()</a><br> +<a href="ov_raw_total.html">ov_raw_total()</a><br> +<a href="ov_pcm_total.html">ov_pcm_total()</a><br> +<a href="ov_time_total.html">ov_time_total()</a><br> +<a href="ov_raw_tell.html">ov_raw_tell()</a><br> +<a href="ov_pcm_tell.html">ov_pcm_tell()</a><br> +<a href="ov_time_tell.html">ov_time_tell()</a><br> +<a href="ov_info.html">ov_info()</a><br> +<a href="ov_comment.html">ov_comment()</a><br> +<br> +<b><a href="../libvorbis/return.html">Return Codes</a> (from <a href="../libvorbis/index.html">libvorbis</a>)</b><br> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/seekexample.html b/vorbis/doc/vorbisfile/seekexample.html new file mode 100644 index 0000000..897403d --- /dev/null +++ b/vorbis/doc/vorbisfile/seekexample.html @@ -0,0 +1,152 @@ +<html> + +<head> +<title>vorbisfile - Example Code</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Example Code: seeking</h1> + +<p> +The following is a run-through of the seeking example program supplied +with vorbisfile - <a href="seeking_test_c.html">seeking_test.c</a>. +This program tests the vorbisfile <a href="ov_time_seek.html">ov_time_seek</a> function by seeking to random points within the file. + +<p> +First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#include <stdlib.h> +#include <stdio.h> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" +</b></pre> + </td> +</tr> +</table> + +<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare other helpful variables to track our progress within the file. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int main(){ + OggVorbis_File ov; + int i; +</b></pre> + </td> +</tr> +</table> + +<p>This example takes its input on stdin which is in 'text' mode by default under Windows; this will corrupt the input data unless set to binary mode. This applies only to Windows. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif +</b></pre> + </td> +</tr> +</table> + +<p><a href="ov_open_callbacks.html">ov_open()</a> must be +called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> structure with default values. +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks to ensure that we're reading Vorbis format and not something else. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + if(ov_open_callbacks(stdin,&ov,NULL,-1, OV_CALLBACKS_NOCLOSE)<0){ + printf("Could not open input as an OggVorbis file.\n\n"); + exit(1); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +First we check to make sure the stream is seekable using <a href="ov_seekable.html">ov_seekable</a>. + +<p>Then we seek to 100 random spots in the bitstream using <a href="ov_time_seek.html">ov_time_seek</a> with randomly generated values. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + + /* print details about each logical bitstream in the input */ + if(ov_seekable(&ov)){ + double length=ov_time_total(&ov,-1); + printf("testing seeking to random places in %g seconds....\n",length); + for(i=0;i<100;i++){ + double val=(double)rand()/RAND_MAX*length; + ov_time_seek(&ov,val); + printf("\r\t%d [%gs]... ",i,val); + fflush(stdout); + } + + printf("\r \nOK.\n\n"); + }else{ + printf("Standard input was not seekable.\n"); + } + +</b></pre> + </td> +</tr> +</table> +<p> +When we're done seeking, we need to call <a href="ov_clear.html">ov_clear()</a> to release the bitstream. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + ov_clear(&ov); + return 0; +} +</b></pre> + </td> +</tr> +</table> + +<p> +The full source for seeking_test.c can be found with the vorbis +distribution in <a href="seeking_test_c.html">seeking_test.c</a>. + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/seeking.html b/vorbis/doc/vorbisfile/seeking.html new file mode 100644 index 0000000..17e4e82 --- /dev/null +++ b/vorbis/doc/vorbisfile/seeking.html @@ -0,0 +1,107 @@ +<html>
+
+<head>
+<title>Vorbisfile - Seeking</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>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+
+<h1>Seeking</h1>
+<p>Seeking functions allow you to specify a specific point in the stream to begin or continue decoding.
+<p>
+All libvorbisfile seeking routines are declared in "vorbis/vorbisfile.h".
+
+<p>Certain seeking functions are best suited to different situations.
+When speed is important and exact positioning isn't required,
+page-level seeking should be used. Note also that Vorbis files do not
+necessarily start at a sample number or time offset of zero. Do not
+be surprised if a file begins at a positive offset of several minutes
+or hours, such as would happen if a large stream (such as a concert
+recording) is chopped into multiple separate files. Requesting to
+seek to a position before the beginning of such a file will seek to
+the position where audio begins.
+
+<p>As of vorbisfile version 1.68, seeking also optionally provides
+automatic crosslapping to eliminate clicks and other discontinuity
+artifacts at seeking boundaries. This fetaure is of particular
+interest to player and game developers implementing dynamic music and
+audio engines, or others looking for smooth transitions within a
+single sample or across multiple samples.<p>
+
+<p>Naturally, seeking is available only within a seekable file or
+stream. Seeking functions will return <tt>OV_ENOSEEK</tt> on
+nonseekable files and streams.
+
+</ul>
+
+<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+ <td><b>function</b></td>
+ <td><b>purpose</b></td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_raw_seek.html">ov_raw_seek</a></td>
+ <td>This function seeks to a position specified in the compressed bitstream, specified in bytes.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_seek.html">ov_pcm_seek</a></td>
+ <td>This function seeks to a specific audio sample number, specified in pcm samples.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_seek_page.html">ov_pcm_seek_page</a></td>
+ <td>This function seeks to the closest page preceding the specified audio sample number, specified in pcm samples.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_seek.html">ov_time_seek</a></td>
+ <td>This function seeks to the specific time location in the bitstream, specified in seconds </td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_seek_page.html">ov_time_seek_page</a></td>
+ <td>This function seeks to the closest page preceding the specified time position in the bitstream</td>
+</tr>
+
+</tr>
+<tr valign=top>
+ <td><a href="ov_raw_seek_lap.html">ov_raw_seek_lap</a></td>
+ <td>This function seeks to a position specified in the compressed bitstream, specified in bytes. The boundary between the old and new playback positions is crosslapped to eliminate discontinuities. </td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_seek_lap.html">ov_pcm_seek_lap</a></td>
+ <td>This function seeks to a specific audio sample number, specified in pcm samples. The boundary between the old and new playback positions is crosslapped to eliminate discontinuities.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_pcm_seek_page_lap.html">ov_pcm_seek_page_lap</a></td>
+ <td>This function seeks to the closest page preceding the specified audio sample number, specified in pcm samples. The boundary between the old and new playback positions is crosslapped to eliminate discontinuities.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_seek_lap.html">ov_time_seek_lap</a></td>
+ <td>This function seeks to the specific time location in the bitstream, specified in seconds. The boundary between the old and new playback positions is crosslapped to eliminate discontinuities. </td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_seek_page_lap.html">ov_time_seek_page_lap</a></td>
+ <td>This function seeks to the closest page preceding the specified time position in the bitstream. The boundary between the old and new playback positions is crosslapped to eliminate discontinuities.</td>
+</tr>
+</table>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
+</tr><tr>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+
+</body>
+
+</html>
diff --git a/vorbis/doc/vorbisfile/seeking_example_c.html b/vorbis/doc/vorbisfile/seeking_example_c.html new file mode 100644 index 0000000..eb10a98 --- /dev/null +++ b/vorbis/doc/vorbisfile/seeking_example_c.html @@ -0,0 +1,86 @@ +<html> + +<head> +<title>vorbisfile - seeking_test.c</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>seeking_test.c</h1> + +<p> +The example program source: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + +#include <stdlib.h> +#include <stdio.h> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" + +int main(){ + OggVorbis_File ov; + int i; + +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif + + /* open the file/pipe on stdin */ + if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)==-1){ + printf("Could not open input as an OggVorbis file.\n\n"); + exit(1); + } + + /* print details about each logical bitstream in the input */ + if(ov_seekable(&ov)){ + double length=ov_time_total(&ov,-1); + printf("testing seeking to random places in %g seconds....\n",length); + for(i=0;i<100;i++){ + double val=(double)rand()/RAND_MAX*length; + ov_time_seek(&ov,val); + printf("\r\t%d [%gs]... ",i,val); + fflush(stdout); + } + + printf("\r \nOK.\n\n"); + }else{ + printf("Standard input was not seekable.\n"); + } + + ov_clear(&ov); + return 0; +} + +</b></pre> + </td> +</tr> +</table> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/seeking_test_c.html b/vorbis/doc/vorbisfile/seeking_test_c.html new file mode 100644 index 0000000..eb10a98 --- /dev/null +++ b/vorbis/doc/vorbisfile/seeking_test_c.html @@ -0,0 +1,86 @@ +<html> + +<head> +<title>vorbisfile - seeking_test.c</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>seeking_test.c</h1> + +<p> +The example program source: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + +#include <stdlib.h> +#include <stdio.h> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" + +int main(){ + OggVorbis_File ov; + int i; + +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif + + /* open the file/pipe on stdin */ + if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)==-1){ + printf("Could not open input as an OggVorbis file.\n\n"); + exit(1); + } + + /* print details about each logical bitstream in the input */ + if(ov_seekable(&ov)){ + double length=ov_time_total(&ov,-1); + printf("testing seeking to random places in %g seconds....\n",length); + for(i=0;i<100;i++){ + double val=(double)rand()/RAND_MAX*length; + ov_time_seek(&ov,val); + printf("\r\t%d [%gs]... ",i,val); + fflush(stdout); + } + + printf("\r \nOK.\n\n"); + }else{ + printf("Standard input was not seekable.\n"); + } + + ov_clear(&ov); + return 0; +} + +</b></pre> + </td> +</tr> +</table> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/seekingexample.html b/vorbis/doc/vorbisfile/seekingexample.html new file mode 100644 index 0000000..8263f02 --- /dev/null +++ b/vorbis/doc/vorbisfile/seekingexample.html @@ -0,0 +1,203 @@ +<html> + +<head> +<title>vorbisfile - Example Code</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>vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td> +</tr> +</table> + +<h1>Example Code</h1> + +<p> +The following is a run-through of the decoding example program supplied +with vorbisfile - <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>. +This program takes a vorbis bitstream from stdin and writes raw pcm to stdout. + +<p> +First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#include <stdio.h> +#include <stdlib.h> +#include <math.h> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" +</b></pre> + </td> +</tr> +</table> +<p> +We also have to make a concession to Windows users here. If we are using windows for decoding, we must declare these libraries so that we can set stdin/stdout to binary. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#ifdef _WIN32 +#include <io.h> +#include <fcntl.h> +#endif +</b></pre> + </td> +</tr> +</table> +<p> +Next, a buffer for the pcm audio output is declared. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +char pcmout[4096]; +</b></pre> + </td> +</tr> +</table> + +<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a few other helpful variables to track out progress within the file. +Also, we make our final concession to Windows users by setting the stdin and stdout to binary mode. +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int main(int argc, char **argv){ + OggVorbis_File vf; + int eof=0; + int current_section; + +#ifdef _WIN32 + _setmode( _fileno( stdin ), _O_BINARY ); +#endif +</b></pre> + </td> +</tr> +</table> + +<p><a href="ov_open_callbacks.html">ov_open_callbacks()</a> must be +called to initialize the <b>OggVorbis_File</b> structure with default values. +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks to ensure that we're reading Vorbis format and not something else. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + if(ov_open_callbacks(stdin, &vf, NULL, 0, OV_CALLBACKS_NOCLOSE) < 0) { + fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n"); + exit(1); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +We're going to pull the channel and bitrate info from the file using <a href="ov_info.html">ov_info()</a> and show them to the user. +We also want to pull out and show the user a comment attached to the file using <a href="ov_comment.html">ov_comment()</a>. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + { + char **ptr=ov_comment(&vf,-1)->user_comments; + vorbis_info *vi=ov_info(&vf,-1); + while(*ptr){ + fprintf(stderr,"%s\n",*ptr); + ++ptr; + } + fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate); + fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor); + } + +</b></pre> + </td> +</tr> +</table> + +<p> +Here's the read loop: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + + while(!eof){ + long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section); + switch(ret){ + case 0: + /* EOF */ + eof=1; + break; + case -1: + break; + default: + fwrite(pcmout,1,ret,stdout); + break; + } + } + +</b></pre> + </td> +</tr> +</table> + +<p> +The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>. +Based on the value returned, we know if we're at the end of the file or have invalid data. If we have valid data, we write it to the pcm output. + +<p> +Now that we've finished playing, we can pack up and go home. It's important to call <a href="ov_clear.html">ov_clear()</a> when we're finished. + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> + + ov_clear(&vf); + + fprintf(stderr,"Done.\n"); + return(0); +} +</b></pre> + </td> +</tr> +</table> + +<p> +The full source for vorbisfile_example.c can be found with the vorbis +distribution in <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>. + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000 vorbis team</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</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> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/style.css b/vorbis/doc/vorbisfile/style.css new file mode 100644 index 0000000..81cf417 --- /dev/null +++ b/vorbis/doc/vorbisfile/style.css @@ -0,0 +1,7 @@ +BODY { font-family: Helvetica, sans-serif } +TD { font-family: Helvetica, sans-serif } +P { font-family: Helvetica, sans-serif } +H1 { font-family: Helvetica, sans-serif } +H2 { font-family: Helvetica, sans-serif } +H4 { font-family: Helvetica, sans-serif } +P.tiny { font-size: 8pt } diff --git a/vorbis/doc/vorbisfile/threads.html b/vorbis/doc/vorbisfile/threads.html new file mode 100644 index 0000000..274e115 --- /dev/null +++ b/vorbis/doc/vorbisfile/threads.html @@ -0,0 +1,50 @@ +<html> + +<head> +<title>Vorbisfile - Thread Safety</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>Thread Safety</h1> + +Vorbisfile's libvorbisfile may be used safely in a threading environment +so long as thread access to individual <a +href="OggVorbis_File.html">OggVorbis_File</a> instances is serialized. +<ul> + +<li>Only one thread at a time may enter a function that takes a given <a +href="OggVorbis_File.html">OggVorbis_File</a> instance, even if the +functions involved appear to be read-only.<p> + +<li>Multiple threads may enter +libvorbisfile at a given time, so long as each thread's function calls +are using different <a href="OggVorbis_File.html">OggVorbis_File</a> +instances. <p> + +<li>Any one <a +href="OggVorbis_File.html">OggVorbis_File</a> instance may be used safely from multiple threads so long as only one thread at a time is making calls using that instance.<p> +</ul> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/vorbis/doc/vorbisfile/vorbisfile_example_c.html b/vorbis/doc/vorbisfile/vorbisfile_example_c.html new file mode 100644 index 0000000..f3ba1d6 --- /dev/null +++ b/vorbis/doc/vorbisfile/vorbisfile_example_c.html @@ -0,0 +1,106 @@ +<html> + +<head> +<title>vorbisfile - vorbisfile_example.c</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>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +<h1>vorbisfile_example.c</h1> + +<p> +The example program source: + +<br><br> +<table border=0 width=100% color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +#include <stdio.h> +#include <stdlib.h> +#include <math.h> +#include "vorbis/codec.h" +#include "vorbis/vorbisfile.h" + +#ifdef _WIN32 +#include <io.h> +#include <fcntl.h> +#endif + +char pcmout[4096]; + +int main(int argc, char **argv){ + OggVorbis_File vf; + int eof=0; + int current_section; + +#ifdef _WIN32 + _setmode( _fileno( stdin ), _O_BINARY ); + _setmode( _fileno( stdout ), _O_BINARY ); +#endif + + if(ov_open_callbacks(stdin, &vf, NULL, 0, OV_CALLBACKS_NOCLOSE) < 0) { + fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n"); + exit(1); + } + + { + char **ptr=ov_comment(&vf,-1)->user_comments; + vorbis_info *vi=ov_info(&vf,-1); + while(*ptr){ + fprintf(stderr,"%s\n",*ptr); + ++ptr; + } + fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate); + fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor); + } + + while(!eof){ + long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section); + if (ret == 0) { + /* EOF */ + eof=1; + } else if (ret < 0) { + /* error in the stream. Not a problem, just reporting it in + case we (the app) cares. In this case, we don't. */ + } else { + /* we don't bother dealing with sample rate changes, etc, but + you'll have to */ + fwrite(pcmout,1,ret,stdout); + } + } + + ov_clear(&vf); + + fprintf(stderr,"Done.\n"); + return(0); +} + +</b></pre> + </td> +</tr> +</table> + + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 2000-2010 Xiph.Org</p></td> +<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td> +</tr><tr> +<td><p class=tiny>Vorbisfile documentation</p></td> +<td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td> +</tr> +</table> + +</body> + +</html> |