here are current docs

svn path=/branches/branch_beta3/vorbis/; revision=855

24 files changed, 411 insertions, 110 deletions

diff --git a/doc/vorbisfile/OggVorbis_File.html b/doc/vorbisfile/OggVorbis_File.html
index 84800cd8..6748deef 100644
--- a/doc/vorbisfile/OggVorbis_File.html
+++ b/doc/vorbisfile/OggVorbis_File.html
@@ -22,7 +22,8 @@ The OggVorbis_File structure defines an Ogg Vorbis file.
 <p>
 This structure is used in all vorbisfile routines.  Before it can be used, it must be initialized by <a href="ov_open.html">ov_open</a> or <a href="ov_open_callbacks.html">ov_open_callbacks</a>.
 <p>
-After use, the OggVorbis_File structure must be deallocated with a call to <a href="ov_clear.html">ov_clear()</a>.
+After use, the OggVorbis_File structure must be deallocated with a call to <a href="ov_clear.html">ov_clear()</a>.

+<p>Once a file or data source is passed to libvorbisfile, it is owned by vorbisfile.  The file should not be used by any other applications or functions outside the Vorbisfile API.
 <br><br>
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -58,7 +59,7 @@ After use, the OggVorbis_File structure must be deallocated with a call to <a hr
   vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
   vorbis_block     vb; /* local working space for packet->PCM decode */
 
-  ov_callbacks callbacks;
+  <a href="ov_callbacks.html">ov_callbacks</a> callbacks;
 
 } OggVorbis_File;</b></pre>
 	</td>
@@ -72,7 +73,9 @@ After use, the OggVorbis_File structure must be deallocated with a call to <a hr
 <dt><i>seekable</i></dt>
 <dd>Read-only int indicating whether file is seekable, i.e., 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>
+<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.</dd>
 </dl>
 
 <h3>Notes</h3>
diff --git a/doc/vorbisfile/chaining_example_c.html b/doc/vorbisfile/chaining_example_c.html
index ec0e1c21..6131693a 100644
--- a/doc/vorbisfile/chaining_example_c.html
+++ b/doc/vorbisfile/chaining_example_c.html
@@ -24,45 +24,44 @@ The example program source:
 	<td>
 <pre><b>
 
-#include "vorbis/codec.h"
-#include "vorbis/vorbisfile.h"
-#include "../lib/misc.h"
-
-int main(){
-  OggVorbis_File ov;
-  int i;
-
-  /* open the file/pipe on stdin */
-  if(ov_open(stdin,&ov,NULL,-1)==-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)){
-    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");
-  }
-
-  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));
-  }
-
-  ov_clear(&ov);
-  return 0;
-}
+#include <vorbis/codec.h>

+#include <vorbis/vorbisfile.h>

+

+int main(){

+  OggVorbis_File ov;

+  int i;

+

+  /* open the file/pipe on stdin */

+  if(ov_open(stdin,&ov,NULL,-1)<0){

+    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)){

+    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");

+  }

+

+  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));

+  }

+

+  ov_clear(&ov);

+  return 0;

+}

 
 </b></pre>
 	</td>
diff --git a/doc/vorbisfile/chainingexample.html b/doc/vorbisfile/chainingexample.html
index cf7a99db..f7c251b5 100644
--- a/doc/vorbisfile/chainingexample.html
+++ b/doc/vorbisfile/chainingexample.html
@@ -59,7 +59,7 @@ called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> struct
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-  if(ov_open(stdin,&ov,NULL,-1)==-1){
+  if(ov_open(stdin,&ov,NULL,-1)<0){

     printf("Could not open input as an OggVorbis file.\n\n");
     exit(1);
   }
diff --git a/doc/vorbisfile/datastructures.html b/doc/vorbisfile/datastructures.html
index ab60a7cb..955b9c7f 100644
--- a/doc/vorbisfile/datastructures.html
+++ b/doc/vorbisfile/datastructures.html
@@ -17,7 +17,9 @@
 <p>There are several data structures used to hold file and bitstream information during vorbisfile decoding.
 <p>
 All the <b>vorbisfile</b> specific data structures are declared in "vorbis/vorbisfile.h" or "vorbis/codec.h".
-<p>
+<p>

+<p>When using vorbisfile, we usually won't need 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>
diff --git a/doc/vorbisfile/example.html b/doc/vorbisfile/example.html
index a137786b..d0574849 100644
--- a/doc/vorbisfile/example.html
+++ b/doc/vorbisfile/example.html
@@ -140,20 +140,21 @@ Here's the read loop:
         <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;
-    }
-  }
+  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>
diff --git a/doc/vorbisfile/initialization.html b/doc/vorbisfile/initialization.html
index 004972f8..be09f651 100644
--- a/doc/vorbisfile/initialization.html
+++ b/doc/vorbisfile/initialization.html
@@ -1,20 +1,20 @@
 <html>
 
 <head>
-<title>vorbisfile - Setup/Teardown</title>
+<title>libvorbisfile - 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><p class=tiny>libvorbisfile documentation</p></td>
 <td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
 </tr>
 </table>
 
 <h1>Setup/Teardown</h1>
-<p>In order to decode audio using vorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished.
+<p>In order to decode audio using libvorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished.
 <p>
 All the <b>vorbisfile</b> initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
 <p>
diff --git a/doc/vorbisfile/ov_bitrate.html b/doc/vorbisfile/ov_bitrate.html
index e48d9d37..ad402615 100644
--- a/doc/vorbisfile/ov_bitrate.html
+++ b/doc/vorbisfile/ov_bitrate.html
@@ -17,7 +17,8 @@
 
 <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.
+<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>
@@ -43,8 +44,8 @@ functions.</dd>
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
--1 indicates that the file is not seekable and the nominal, upper, and lower bounds are not set for the file.</li>
+<li>OV_EINVAL indicates that an invalid argument value was submitted.</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
diff --git a/doc/vorbisfile/ov_bitrate_instant.html b/doc/vorbisfile/ov_bitrate_instant.html
index 046ceb45..7f53b701 100644
--- a/doc/vorbisfile/ov_bitrate_instant.html
+++ b/doc/vorbisfile/ov_bitrate_instant.html
@@ -42,7 +42,8 @@ functions.
 <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><i>n</i> indicates the actual bitrate since the last call.</li>

+<li>OV_FALSE indicates that the call returned a 'false' status.  In this case, this error code is returned if playback is not in progress, and thus there is no instantaneous bitrate information to report.</li>
 </blockquote>
 <p>
 
diff --git a/doc/vorbisfile/ov_open.html b/doc/vorbisfile/ov_open.html
index 49135422..1a55527c 100644
--- a/doc/vorbisfile/ov_open.html
+++ b/doc/vorbisfile/ov_open.html
@@ -23,8 +23,9 @@ structure. It sets up all the related decoding structure.
 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 vorbisfile
-functions. Once this has been called, the same <tt>OggVorbis_File</tt>
+functions. Once this has been called, the same <a href="OggVorbis_File.html">OggVorbis_File</a>
 struct should be passed to all the vorbisfile functions.
+<p>Also, you should be aware that ov_open(), once successful, takes complete possession of the file resource.  After you have opened a file using ov_open(), you MUST close it using <a href="ov_clear.html">ov_clear()</a>, not fclose() or any other function.
 <p>
 It is often useful to call <tt>ov_open()</tt>
 simply to determine whether a given file is a vorbis bitstream. If the
@@ -33,7 +34,7 @@ call fails, then the file is not recognizable as such. When you use <tt>ov_open(
 </tt>for
 this, you should <tt>fclose()</tt> the file pointer if, and only if, the
 <tt>ov_open()</tt>
-call fails. If it succeeds, you must call <tt>ov_clear()</tt> to clear
+call fails. If it succeeds, you must call <a href="ov_clear.html">ov_clear()</a> to clear
 the decoder's buffers and close the file for you.
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -72,10 +73,15 @@ should contain the length (in bytes) of the buffer.  Used together with <tt>init
 <li>
 0 for success</li>
 
-<li>
--1 for failure</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>
-If the function fails, this was not recognizable as an OggVorbis file.
 <p>
 
 <h3>Notes</h3>
diff --git a/doc/vorbisfile/ov_open_callbacks.html b/doc/vorbisfile/ov_open_callbacks.html
index 32f8efff..9ac61bda 100644
--- a/doc/vorbisfile/ov_open_callbacks.html
+++ b/doc/vorbisfile/ov_open_callbacks.html
@@ -69,11 +69,15 @@ should contain the length (in bytes) of the buffer.  Used together with <tt>init
 <blockquote>
 <li>
 0 for success</li>
-
-<li>
--1 for failure</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>
-If the function fails, this was not recognizable as an OggVorbis file.
 <p>
 
 <h3>Notes</h3>
diff --git a/doc/vorbisfile/ov_pcm_seek.html b/doc/vorbisfile/ov_pcm_seek.html
index a39b4fbe..43e50157 100644
--- a/doc/vorbisfile/ov_pcm_seek.html
+++ b/doc/vorbisfile/ov_pcm_seek.html
@@ -50,8 +50,20 @@ functions.</dd>
 0 for success</li>
 
 <li>
-Nonzero for failure</li>
-</blockquote>
+nonzero indicates failure, described by several error codes:</li>

+<ul>

+<li>OV_ENOSEEK - Bitstream is not seekable.

+</li>

+<li>OV_EINVAL - Invalid argument value.

+</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 libvorbis/libvorbisfile, or the requested link is corrupt. 

+</li>

+</ul></blockquote>
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
diff --git a/doc/vorbisfile/ov_pcm_seek_page.html b/doc/vorbisfile/ov_pcm_seek_page.html
new file mode 100644
index 00000000..1f97db86
--- /dev/null
+++ b/doc/vorbisfile/ov_pcm_seek_page.html
@@ -0,0 +1,83 @@
+<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.25 - 20000615</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(OggVorbis_File *vf,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 vorbisfile
+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>
+<li>
+0 for success</li>
+
+<li>
+nonzero indicates failure, described by several error codes:</li>

+<ul>

+<li>OV_ENOSEEK - Bitstream is not seekable.

+</li>

+<li>OV_EINVAL - Invalid argument value.

+</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 libvorbis/libvorbisfile, or the requested link is corrupt. 

+</li>

+</ul></</blockquote>
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
+</tr><tr>
+<td><p class=tiny>vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+</tr>
+</table>
+
+
+</body>
+
+</html>
diff --git a/doc/vorbisfile/ov_pcm_total.html b/doc/vorbisfile/ov_pcm_total.html
index 5049e5ca..bb205c21 100644
--- a/doc/vorbisfile/ov_pcm_total.html
+++ b/doc/vorbisfile/ov_pcm_total.html
@@ -36,14 +36,13 @@ int64_t ov_pcm_total(OggVorbis_File *vf,int i);
 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
-<dd>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd>
+<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>
--1 if the bitstream is nonseekable.</li>
+<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=1 to n.</li>
diff --git a/doc/vorbisfile/ov_raw_seek.html b/doc/vorbisfile/ov_raw_seek.html
index 68fd97dc..dba16b4e 100644
--- a/doc/vorbisfile/ov_raw_seek.html
+++ b/doc/vorbisfile/ov_raw_seek.html
@@ -21,7 +21,7 @@
 <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 vorbisfile seek funtion to use.
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -48,7 +48,15 @@ struct should be passed to all the vorbisfile functions.</dd>
 <blockquote>
 <li>
 0 indicates success</li>
-<li>nonzero indicates failure.</li>
+<li>nonzero indicates failure, described by several error codes:</li>

+<ul>

+<li>OV_ENOSEEK - Bitstream is not seekable.

+</li>

+<li>OV_EINVAL - Invalid argument value.

+</li>

+<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt. 

+</li>

+</ul>
 </blockquote>
 <p>
 <br><br>
diff --git a/doc/vorbisfile/ov_raw_total.html b/doc/vorbisfile/ov_raw_total.html
index ff4362ee..9732a0dc 100644
--- a/doc/vorbisfile/ov_raw_total.html
+++ b/doc/vorbisfile/ov_raw_total.html
@@ -36,14 +36,13 @@ int64_t ov_raw_total(OggVorbis_File *vf,int i);
 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</b></dd>
+<dd><b>Link to the desired logical bitstream.  To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</b></dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
--1 if the bitstream is nonseekable.</li>
+<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>
 total length in compressed bytes of content if i=-1.</li>
 <li>length in compressed bytes of logical bitstream if i=1 to n.</li>
diff --git a/doc/vorbisfile/ov_read.html b/doc/vorbisfile/ov_read.html
index 083be1fa..ad53aaad 100644
--- a/doc/vorbisfile/ov_read.html
+++ b/doc/vorbisfile/ov_read.html
@@ -65,10 +65,15 @@ functions.</dd>
 <h3>Return Values</h3>
 <blockquote>
 <li>
--1 indicates an error or hole in data.</li>
+OV_HOLE indicates there was an interruption in the data. (one of: garbage between pages, loss of sync followed by recapture, or a corrupt page)</li>

+<li>
+OV_EBADLINK	indicates that an invalid stream section was supplied to libvorbisfile, 

+		or the requested link is corrupt. 

+</li>
+
 <li>
 0 indicates EOF</li>
-<li><i>n</i> indicates actual number of bytes read.  This may vary, but will be no longer than the parameter <tt>length</tt>.</li>
+<li><i>n</i> indicates actual number of bytes read.  Within a logical bitstream, the number should equal <tt>length</tt>.  At the end of a logical bitstream, the number of bytes read will equal the remaining number of bytes in the bitstream.</li>
 </blockquote>
 <p>
 <h3>Notes</h3>
diff --git a/doc/vorbisfile/ov_streams.html b/doc/vorbisfile/ov_streams.html
index a4162b61..ba4b31ef 100644
--- a/doc/vorbisfile/ov_streams.html
+++ b/doc/vorbisfile/ov_streams.html
@@ -1,7 +1,7 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>vorbisfile - function - ov_streams</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
diff --git a/doc/vorbisfile/ov_time_seek_page.html b/doc/vorbisfile/ov_time_seek_page.html
new file mode 100644
index 00000000..b3b96160
--- /dev/null
+++ b/doc/vorbisfile/ov_time_seek_page.html
@@ -0,0 +1,84 @@
+<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.25 - 20000615</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>For obvious reasons, this doesn't 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 seconds);
+</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>seconds</i></dt>
+<dd>Location to seek to within the file, specified in seconds.</dd>
+</dl>
+
+
+<h3>Return Values</h3>
+<blockquote>
+<li>
+0 for success</li>
+
+<li>
+nonzero indicates failure, described by several error codes:</li>

+<ul>

+<li>OV_ENOSEEK - Bitstream is not seekable.

+</li>

+<li>OV_EINVAL - Invalid argument value.

+</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 libvorbis/libvorbisfile, or the requested link is corrupt. 

+</li>

+</ul></blockquote>
+
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
+</tr><tr>
+<td><p class=tiny>vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+</tr>
+</table>
+
+
+</body>
+
+</html>
diff --git a/doc/vorbisfile/ov_time_total.html b/doc/vorbisfile/ov_time_total.html
index 16e1afa7..1fa81a57 100644
--- a/doc/vorbisfile/ov_time_total.html
+++ b/doc/vorbisfile/ov_time_total.html
@@ -39,14 +39,13 @@ double ov_time_total(OggVorbis_File *vf,int i);
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
 struct should be passed to all the vorbisfile functions.</dd>
 <dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the <a href="vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</b></dd>
+<dd><b>Link to the desired logical bitstream.  To retrieve the <a href="vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</b></dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
--1 if the bitstream is nonseekable.</li>
+<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>
 total length in seconds of content if i=-1.</li>
 <li>length in seconds of logical bitstream if i=1 to n.</li>
diff --git a/doc/vorbisfile/overview.html b/doc/vorbisfile/overview.html
index 778a58e3..99b384d2 100644
--- a/doc/vorbisfile/overview.html
+++ b/doc/vorbisfile/overview.html
@@ -1,7 +1,7 @@
 <html>
 
 <head>
-<title>libshout - API Overview</title>
+<title>libvorbisfile - API Overview</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
@@ -14,7 +14,8 @@
 </table>
 
 <h1>VorbisFile API Overview</h1>
-
+

+<p>The makeup of the vorbisfile API is relatively simple.  It revolves around a single file resource.  This resource is passed to the Vorbisfile API, 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>
diff --git a/doc/vorbisfile/seekexample.html b/doc/vorbisfile/seekexample.html
index c3f69da5..1c5e36b3 100644
--- a/doc/vorbisfile/seekexample.html
+++ b/doc/vorbisfile/seekexample.html
@@ -61,7 +61,7 @@ called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> struct
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-  if(ov_open(stdin,&ov,NULL,-1)==-1){
+  if(ov_open(stdin,&ov,NULL,-1)<0){
     printf("Could not open input as an OggVorbis file.\n\n");
     exit(1);
   }
diff --git a/doc/vorbisfile/seeking.html b/doc/vorbisfile/seeking.html
index 74a90583..6b5ac18b 100644
--- a/doc/vorbisfile/seeking.html
+++ b/doc/vorbisfile/seeking.html
@@ -18,6 +18,9 @@
 <p>

 All the <b>vorbisfile</b> seeking routines are declared in "vorbis/vorbisfile.h".

 <p>

+<p>Certain seeking functions are best suited to different situations.  When speed is important, page-level seeking should be used.

+

+</ul>

 

 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>

 <tr bgcolor=#cccccc>

@@ -33,8 +36,16 @@ All the <b>vorbisfile</b> seeking routines are declared in "vorbis/vorbisfile.h"
 	<td>This function seeks to a specific point in the bitstream, specified in pcm samples.</td>

 </tr>

 <tr valign=top>

+	<td><a href="ov_pcm_seek.html">ov_pcm_seek_page</a></td>

+	<td>This function seeks to the closest page preceding a point in the bitstream, 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 a specific time in the bitstream, specified in seconds.  The easiest and simplest seeking method.</td>

+	<td>This function seeks to a time in the bitstream, specified in seconds.  The easiest and simplest seeking method.</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 a time in the bitstream, specified in seconds.</td>

 </tr>

 </table>

 

diff --git a/doc/vorbisfile/seeking_example_c.html b/doc/vorbisfile/seeking_example_c.html
new file mode 100644
index 00000000..0ffcf821
--- /dev/null
+++ b/doc/vorbisfile/seeking_example_c.html
@@ -0,0 +1,83 @@
+<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.25 - 20000615</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"
+#include "../lib/misc.h"
+
+int main(){
+  OggVorbis_File ov;
+  int i;
+
+  /* open the file/pipe on stdin */
+  if(ov_open(stdin,&ov,NULL,-1)==-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 &copy; 2000 vorbis team</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
+</tr><tr>
+<td><p class=tiny>vorbisfile documentation</p></td>
+<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+</tr>
+</table>
+
+</body>
+
+</html>
diff --git a/doc/vorbisfile/vorbisfile_example_c.html b/doc/vorbisfile/vorbisfile_example_c.html
index 6db7418a..38068db0 100644
--- a/doc/vorbisfile/vorbisfile_example_c.html
+++ b/doc/vorbisfile/vorbisfile_example_c.html
@@ -62,21 +62,21 @@ int main(int argc, char **argv){
     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);
-    switch(ret){
-    case 0:
-      /* EOF */
-      eof=1;
-      break;
-    case -1:
-      break;
-    default:
-      fwrite(pcmout,1,ret,stdout);
-      break;
-    }
-  }
-  
+  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");