From 74f4b1bc3b627ba4c7e03498234d88cacdfbe97b Mon Sep 17 00:00:00 2001 From: Aki Date: Wed, 29 Sep 2021 22:52:49 +0200 Subject: Squashed 'vorbis/' content from commit d22c3ab5f git-subtree-dir: vorbis git-subtree-split: d22c3ab5f633460abc2532feee60ca0892134cbf --- doc/vorbisfile/Makefile.am | 25 ++++ doc/vorbisfile/OggVorbis_File.html | 137 ++++++++++++++++++++ doc/vorbisfile/callbacks.html | 121 +++++++++++++++++ doc/vorbisfile/chaining_example_c.html | 90 +++++++++++++ doc/vorbisfile/chainingexample.html | 175 +++++++++++++++++++++++++ doc/vorbisfile/crosslap.html | 121 +++++++++++++++++ doc/vorbisfile/datastructures.html | 61 +++++++++ doc/vorbisfile/decoding.html | 92 +++++++++++++ doc/vorbisfile/example.html | 208 ++++++++++++++++++++++++++++++ doc/vorbisfile/exampleindex.html | 39 ++++++ doc/vorbisfile/fileinfo.html | 95 ++++++++++++++ doc/vorbisfile/index.html | 49 +++++++ doc/vorbisfile/initialization.html | 118 +++++++++++++++++ doc/vorbisfile/ov_bitrate.html | 72 +++++++++++ doc/vorbisfile/ov_bitrate_instant.html | 65 ++++++++++ doc/vorbisfile/ov_callbacks.html | 117 +++++++++++++++++ doc/vorbisfile/ov_clear.html | 64 +++++++++ doc/vorbisfile/ov_comment.html | 66 ++++++++++ doc/vorbisfile/ov_crosslap.html | 100 ++++++++++++++ doc/vorbisfile/ov_fopen.html | 124 ++++++++++++++++++ doc/vorbisfile/ov_info.html | 64 +++++++++ doc/vorbisfile/ov_open.html | 183 ++++++++++++++++++++++++++ doc/vorbisfile/ov_open_callbacks.html | 147 +++++++++++++++++++++ doc/vorbisfile/ov_pcm_seek.html | 83 ++++++++++++ doc/vorbisfile/ov_pcm_seek_lap.html | 103 +++++++++++++++ doc/vorbisfile/ov_pcm_seek_page.html | 84 ++++++++++++ doc/vorbisfile/ov_pcm_seek_page_lap.html | 112 ++++++++++++++++ doc/vorbisfile/ov_pcm_tell.html | 63 +++++++++ doc/vorbisfile/ov_pcm_total.html | 67 ++++++++++ doc/vorbisfile/ov_raw_seek.html | 83 ++++++++++++ doc/vorbisfile/ov_raw_seek_lap.html | 110 ++++++++++++++++ doc/vorbisfile/ov_raw_tell.html | 65 ++++++++++ doc/vorbisfile/ov_raw_total.html | 68 ++++++++++ doc/vorbisfile/ov_read.html | 148 +++++++++++++++++++++ doc/vorbisfile/ov_read_filter.html | 114 ++++++++++++++++ doc/vorbisfile/ov_read_float.html | 105 +++++++++++++++ doc/vorbisfile/ov_seekable.html | 63 +++++++++ doc/vorbisfile/ov_serialnumber.html | 67 ++++++++++ doc/vorbisfile/ov_streams.html | 64 +++++++++ doc/vorbisfile/ov_test.html | 104 +++++++++++++++ doc/vorbisfile/ov_test_callbacks.html | 111 ++++++++++++++++ doc/vorbisfile/ov_test_open.html | 82 ++++++++++++ doc/vorbisfile/ov_time_seek.html | 82 ++++++++++++ doc/vorbisfile/ov_time_seek_lap.html | 105 +++++++++++++++ doc/vorbisfile/ov_time_seek_page.html | 83 ++++++++++++ doc/vorbisfile/ov_time_seek_page_lap.html | 112 ++++++++++++++++ doc/vorbisfile/ov_time_tell.html | 63 +++++++++ doc/vorbisfile/ov_time_total.html | 67 ++++++++++ doc/vorbisfile/overview.html | 61 +++++++++ doc/vorbisfile/reference.html | 86 ++++++++++++ doc/vorbisfile/seekexample.html | 152 ++++++++++++++++++++++ doc/vorbisfile/seeking.html | 107 +++++++++++++++ doc/vorbisfile/seeking_example_c.html | 86 ++++++++++++ doc/vorbisfile/seeking_test_c.html | 86 ++++++++++++ doc/vorbisfile/seekingexample.html | 203 +++++++++++++++++++++++++++++ doc/vorbisfile/style.css | 7 + doc/vorbisfile/threads.html | 50 +++++++ doc/vorbisfile/vorbisfile_example_c.html | 106 +++++++++++++++ 58 files changed, 5485 insertions(+) create mode 100644 doc/vorbisfile/Makefile.am create mode 100644 doc/vorbisfile/OggVorbis_File.html create mode 100644 doc/vorbisfile/callbacks.html create mode 100644 doc/vorbisfile/chaining_example_c.html create mode 100644 doc/vorbisfile/chainingexample.html create mode 100644 doc/vorbisfile/crosslap.html create mode 100644 doc/vorbisfile/datastructures.html create mode 100644 doc/vorbisfile/decoding.html create mode 100644 doc/vorbisfile/example.html create mode 100644 doc/vorbisfile/exampleindex.html create mode 100644 doc/vorbisfile/fileinfo.html create mode 100644 doc/vorbisfile/index.html create mode 100644 doc/vorbisfile/initialization.html create mode 100644 doc/vorbisfile/ov_bitrate.html create mode 100644 doc/vorbisfile/ov_bitrate_instant.html create mode 100644 doc/vorbisfile/ov_callbacks.html create mode 100644 doc/vorbisfile/ov_clear.html create mode 100644 doc/vorbisfile/ov_comment.html create mode 100644 doc/vorbisfile/ov_crosslap.html create mode 100644 doc/vorbisfile/ov_fopen.html create mode 100644 doc/vorbisfile/ov_info.html create mode 100644 doc/vorbisfile/ov_open.html create mode 100644 doc/vorbisfile/ov_open_callbacks.html create mode 100644 doc/vorbisfile/ov_pcm_seek.html create mode 100644 doc/vorbisfile/ov_pcm_seek_lap.html create mode 100644 doc/vorbisfile/ov_pcm_seek_page.html create mode 100644 doc/vorbisfile/ov_pcm_seek_page_lap.html create mode 100644 doc/vorbisfile/ov_pcm_tell.html create mode 100644 doc/vorbisfile/ov_pcm_total.html create mode 100644 doc/vorbisfile/ov_raw_seek.html create mode 100644 doc/vorbisfile/ov_raw_seek_lap.html create mode 100644 doc/vorbisfile/ov_raw_tell.html create mode 100644 doc/vorbisfile/ov_raw_total.html create mode 100644 doc/vorbisfile/ov_read.html create mode 100644 doc/vorbisfile/ov_read_filter.html create mode 100644 doc/vorbisfile/ov_read_float.html create mode 100644 doc/vorbisfile/ov_seekable.html create mode 100644 doc/vorbisfile/ov_serialnumber.html create mode 100644 doc/vorbisfile/ov_streams.html create mode 100644 doc/vorbisfile/ov_test.html create mode 100644 doc/vorbisfile/ov_test_callbacks.html create mode 100644 doc/vorbisfile/ov_test_open.html create mode 100644 doc/vorbisfile/ov_time_seek.html create mode 100644 doc/vorbisfile/ov_time_seek_lap.html create mode 100644 doc/vorbisfile/ov_time_seek_page.html create mode 100644 doc/vorbisfile/ov_time_seek_page_lap.html create mode 100644 doc/vorbisfile/ov_time_tell.html create mode 100644 doc/vorbisfile/ov_time_total.html create mode 100644 doc/vorbisfile/overview.html create mode 100644 doc/vorbisfile/reference.html create mode 100644 doc/vorbisfile/seekexample.html create mode 100644 doc/vorbisfile/seeking.html create mode 100644 doc/vorbisfile/seeking_example_c.html create mode 100644 doc/vorbisfile/seeking_test_c.html create mode 100644 doc/vorbisfile/seekingexample.html create mode 100644 doc/vorbisfile/style.css create mode 100644 doc/vorbisfile/threads.html create mode 100644 doc/vorbisfile/vorbisfile_example_c.html (limited to 'doc/vorbisfile') diff --git a/doc/vorbisfile/Makefile.am b/doc/vorbisfile/Makefile.am new file mode 100644 index 0000000..fb27d44 --- /dev/null +++ b/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/doc/vorbisfile/OggVorbis_File.html b/doc/vorbisfile/OggVorbis_File.html new file mode 100644 index 0000000..67f47d7 --- /dev/null +++ b/doc/vorbisfile/OggVorbis_File.html @@ -0,0 +1,137 @@ + + + +Vorbisfile - datatype - OggVorbis_File + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

OggVorbis_File

+ +

declared in "vorbis/vorbisfile.h"

+ +

+The OggVorbis_File structure defines an Ogg Vorbis file. +

+ +This structure is used in all libvorbisfile routines. Before it can +be used, it must be initialized by ov_open(), ov_fopen(), or ov_open_callbacks(). Important +Note: The use of ov_open() is +discouraged under Windows due to a peculiarity of Windows linking +convention; use ov_fopen() or ov_open_callbacks() instead. This +caution only applies to Windows; use of ov_open() is appropriate for all other +platforms. See the ov_open() page for more +information. + +

+After use, the OggVorbis_File structure must be deallocated with a +call to ov_clear(). + +

+Note that once a file handle is passed to a successful ov_open() call, the handle is owned by +libvorbisfile and will be closed by libvorbisfile later during the +call to ov_clear(). The handle should not +be used or closed outside of the libvorbisfile API. Similarly, files +opened by ov_fopen() will also be closed +internally by vorbisfile in ov_clear().

+ +ov_open_callbacks() allows the +application to choose whether libvorbisfile will or will not close the +handle in ov_clear(); see the ov_open_callbacks() page for more information.

+ +If a call to ov_open() or ov_open_callbacks() fails, +libvorbisfile does not assume ownership of the handle and the +application is expected to close it if necessary. A failed ov_fopen() call will internally close the +file handle if the open process fails.

+ +

+ + + + +
+
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 */
+
+  ov_callbacks callbacks;
+
+} OggVorbis_File;
+
+ +

Relevant Struct Members

+
+
datasource
+ +
Pointer to file or other ogg source. When using stdio based +file/stream access, this field contains a FILE 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.
+ +
seekable
+
Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.
+
links
+
Read-only int indicating the number of logical bitstreams within the physical bitstream.
+
ov_callbacks
+
Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via ov_open(), the callbacks will be filled in with stdio calls or wrappers to stdio calls.
+
+ +

+
+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/callbacks.html b/doc/vorbisfile/callbacks.html new file mode 100644 index 0000000..20ae55a --- /dev/null +++ b/doc/vorbisfile/callbacks.html @@ -0,0 +1,121 @@ + + + +Vorbisfile - Callbacks and non-stdio I/O + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Callbacks and non-stdio I/O

+ +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.

+ +Use custom I/O functions by populating an ov_callbacks structure and calling ov_open_callbacks() or ov_test_callbacks() rather than the +typical ov_open() or ov_test(). Past the open call, use of +libvorbisfile is identical to using it with stdio. + +

Read function

+ +The read-like function provided in the read_func 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.

+ +The following behaviors are also expected:

+

+

+ +

Seek function

+ +The seek-like function provided in the seek_func 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, +seek_func and tell_func should be set to NULL. If +the seek function is non-NULL, libvorbisfile mandates the following +behavior: + + + +

Close function

+ +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.

+ +The close_func may be set to NULL to indicate that libvorbis +should not attempt to close the file/data handle in ov_clear 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 close_func +that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an +application may call ov_clear() and then +later fclose() the file originally passed to libvorbisfile. + +

Tell function

+ +The tell function is intended to mimic the +behavior of ftell() 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 fseek(file,SEEK_END,0)), the tell +function must return the data position (and thus the total file size), +not an error.

+ +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 tell_func and seek_func +fields should be set to NULL.

+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/chaining_example_c.html b/doc/vorbisfile/chaining_example_c.html new file mode 100644 index 0000000..e40689c --- /dev/null +++ b/doc/vorbisfile/chaining_example_c.html @@ -0,0 +1,90 @@ + + + +vorbisfile - chaining_example.c + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

chaining_example.c

+ +

+The example program source: + +

+ + + + +
+

+
+#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 on windows. */
+  _setmode( _fileno( stdin ), _O_BINARY );
+#endif
+
+  /* open the file/pipe on stdin */
+  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);
+  }
+  
+  /* 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;
+}
+
+
+
+ + +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/chainingexample.html b/doc/vorbisfile/chainingexample.html new file mode 100644 index 0000000..9e0440d --- /dev/null +++ b/doc/vorbisfile/chainingexample.html @@ -0,0 +1,175 @@ + + + +vorbisfile - Example Code + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Chaining Example Code

+ +

+The following is a run-through of the chaining example program supplied +with vorbisfile - chaining_example.c. +This program demonstrates how to work with a chained bitstream. + +

+First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +

+ + + + +
+

+#include "vorbis/codec.h"
+#include "vorbis/vorbisfile.h"
+#include "../lib/misc.h"
+
+
+ +

Inside main(), we declare our primary OggVorbis_File structure. We also declare a other helpful variables to track our progress within the file. +

+ + + + +
+

+int main(){
+  OggVorbis_File ov;
+  int i;
+
+
+ +

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. +

+ + + + +
+

+#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */
+  _setmode( _fileno( stdin ), _O_BINARY );
+#endif
+
+
+ +

We call ov_open_callbacks() to +initialize the OggVorbis_File +structure. ov_open_callbacks() +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.

+ +

+ + + + +
+

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

+First we check to make sure the stream is seekable using ov_seekable. + +

Then we're going to find the number of logical bitstreams in the physical bitstream using ov_streams. + +

We use ov_time_total to determine the total length of the physical bitstream. We specify that we want the entire bitstream by using the argument -1. + +

+ + + + +
+

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

Now we're going to iterate through each logical bitstream and print information about that bitstream. + +

We use ov_info to pull out the vorbis_info struct for each logical bitstream. This struct contains bitstream-specific info. + +

ov_serialnumber retrieves the unique serial number for the logical bistream. ov_raw_total gives the total compressed bytes for the logical bitstream, and ov_time_total gives the total time in the logical bitstream. + +

+ + + + +
+

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

+When we're done with the entire physical bitstream, we need to call ov_clear() to release the bitstream. + +

+ + + + +
+

+  ov_clear(&ov);
+  return 0;
+}
+
+
+ +

+The full source for chaining_example.c can be found with the vorbis +distribution in chaining_example.c. + +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/crosslap.html b/doc/vorbisfile/crosslap.html new file mode 100644 index 0000000..9d28b0b --- /dev/null +++ b/doc/vorbisfile/crosslap.html @@ -0,0 +1,121 @@ + + + +Vorbisfile - Sample Crosslapping + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

What is Crosslapping?

+ +

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 crosslap transitions between seperate +streams, or to crosslap when seeking within +a single stream. + +

Why Crosslap?

+

The source of boundary clicks

+ +

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. + +

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

I thought Vorbis was gapless

+ +

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. + +

Frame lapping, like Vorbis performs internally during continuous +playback, is necessary to eliminate that last epsilon of trouble. + +

Easiest Crosslap

+ +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. + +

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

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. + +

Best Crosslap

+ +

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. + +

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. + +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/datastructures.html b/doc/vorbisfile/datastructures.html new file mode 100644 index 0000000..00f8f8d --- /dev/null +++ b/doc/vorbisfile/datastructures.html @@ -0,0 +1,61 @@ + + + +Vorbisfile - Base Data Structures + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Base Data Structures

+

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". +

+

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. +

+ + + + + + + + + + + + + + + + + + + + + + +
datatypepurpose
OggVorbis_FileThis structure represents the basic file information. It contains + a pointer to the physical file or bitstream and various information about that bitstream.
vorbis_commentThis structure contains the file comments. It contains + a pointer to unlimited user comments, information about the number of comments, and a vendor description.
vorbis_infoThis structure contains encoder-related information about the bitstream. It includes encoder info, channel info, and bitrate limits.
ov_callbacksThis structure contains pointers to the application-specified file manipulation routines set for use by ov_open_callbacks(). See also the provided document on using application-provided callbacks instead of stdio.
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/decoding.html b/doc/vorbisfile/decoding.html new file mode 100644 index 0000000..f394376 --- /dev/null +++ b/doc/vorbisfile/decoding.html @@ -0,0 +1,92 @@ + + + +Vorbisfile - Decoding + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Decoding

+ +

+All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h". +

+ +After initialization, decoding audio +is as simple as calling ov_read() (or the +similar functions ov_read_float() and +ov_read_filter). This function works +similarly to reading from a normal file using read().

+ +However, a few differences are worth noting: + +

multiple stream links

+ +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 ov_read 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. + +

returned data amount

+ +ov_read 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 ov_read (incrementing the buffer pointer) +until the original buffer is filled. + +

file cursor position

+ +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. + +

+ + + + + + + + + + + + + + + + + +
functionpurpose
ov_readThis 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 ov_open(), ov_fopen(), +or ov_open_callbacks().
ov_read_floatThis function decodes to floats instead of integer samples.
ov_read_filterThis function works like ov_read, but passes the PCM data through the provided filter before converting to integer sample data.
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/example.html b/doc/vorbisfile/example.html new file mode 100644 index 0000000..e0c4fa3 --- /dev/null +++ b/doc/vorbisfile/example.html @@ -0,0 +1,208 @@ + + + +Vorbisfile - Example Code + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Decoding Example Code

+ +

+The following is a run-through of the decoding example program supplied +with libvorbisfile, vorbisfile_example.c. +This program takes a vorbis bitstream from stdin and writes raw pcm to stdout. + +

+First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included. + +

+ + + + +
+

+#include <stdio.h>
+#include <stdlib.h>
+#include <math.h>
+#include "vorbis/codec.h"
+#include "vorbisfile.h"
+
+
+

+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. +

+ + + + +
+

+#ifdef _WIN32
+#include <io.h>
+#include <fcntl.h>
+#endif
+
+
+

+Next, a buffer for the pcm audio output is declared. + +

+ + + + +
+

+char pcmout[4096];
+
+
+ +

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. +

+ + + + +
+

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

We call ov_open_callbacks() to +initialize the OggVorbis_File structure with default values. +ov_open_callbacks() 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. + +

+ + + + +
+

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

+We're going to pull the channel and bitrate info from the file using ov_info() and show them to the user. +We also want to pull out and show the user a comment attached to the file using ov_comment(). + +

+ + + + +
+

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

+Here's the read loop: + +

+ + + + +
+

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

+The code is reading blocks of data using ov_read(). +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. + +

+Now that we've finished playing, we can pack up and go home. It's important to call ov_clear() when we're finished. + +

+ + + + +
+

+
+  ov_clear(&vf);
+    
+  fprintf(stderr,"Done.\n");
+  return(0);
+}
+
+
+ +

+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/exampleindex.html b/doc/vorbisfile/exampleindex.html new file mode 100644 index 0000000..9227b97 --- /dev/null +++ b/doc/vorbisfile/exampleindex.html @@ -0,0 +1,39 @@ + + + +vorbisfile - Documentation + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

VorbisFile Example Code

+ +

+Three sample programs are included with the vorbisfile distribution. +

+vorbisfile decoding
+vorbisfile seeking
+vorbisfile bitstream chaining
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/fileinfo.html b/doc/vorbisfile/fileinfo.html new file mode 100644 index 0000000..c025dd6 --- /dev/null +++ b/doc/vorbisfile/fileinfo.html @@ -0,0 +1,95 @@ + + + +Vorbisfile - File Information + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

File Information

+

Libvorbisfile contains many functions to get information about bitstream attributes and decoding status. +

+All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h". +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
functionpurpose
ov_bitrateReturns the average bitrate of the current logical bitstream.
ov_bitrate_instantReturns 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.
ov_streamsGives the number of logical bitstreams within the current physical bitstream.
ov_seekableIndicates whether the bitstream is seekable.
ov_serialnumberReturns the unique serial number of the specified logical bitstream.
ov_raw_totalReturns the total (compressed) bytes in a physical or logical seekable bitstream.
ov_pcm_totalReturns the total number of samples in a physical or logical seekable bitstream.
ov_time_totalReturns the total time length in seconds of a physical or logical seekable bitstream.
ov_raw_tellReturns the byte location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.
ov_pcm_tellReturns the sample location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.
ov_time_tellReturns the time location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.
ov_infoReturns the vorbis_info struct for a specific bitstream section.
ov_commentReturns attached comments for the current bitstream.
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/index.html b/doc/vorbisfile/index.html new file mode 100644 index 0000000..167e1c0 --- /dev/null +++ b/doc/vorbisfile/index.html @@ -0,0 +1,49 @@ + + + +Vorbisfile - Documentation + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Vorbisfile Documentation

+ +

+ +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.

+ +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. + +

+API overview
+API reference
+Code Examples
+ +

+

+ + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/initialization.html b/doc/vorbisfile/initialization.html new file mode 100644 index 0000000..da83957 --- /dev/null +++ b/doc/vorbisfile/initialization.html @@ -0,0 +1,118 @@ + + + +Vorbisfile - Setup/Teardown + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

Setup/Teardown

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 ov_fopen() to open the file for access, check +it for Vorbis content, and prepare it for playback. A successful return code from ov_fopen() indicates the file is ready for use. +Once the file is no longer needed, ov_clear() is used to close the file and +deallocate decoding resources.

+ +On systems other than Windows[a], an +application may also open a file itself using fopen(), then pass the +FILE * to libvorbisfile using ov_open(). Do not call +fclose() on a file handle successfully submitted to ov_open(); libvorbisfile does this in the ov_clear() call.

+ +An application that requires more setup flexibility may open a data +stream using ov_open_callbacks() +to change default libvorbis behavior or specify non-stdio data access +mechanisms.

+ +

+All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h". +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
functionpurpose
ov_fopenOpens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be + used.
ov_openInitializes 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. Do not use this call under Windows [a]; Use ov_fopen() or ov_open_callbacks() instead.
ov_open_callbacksInitializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of ov_open() or ov_fopen() when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a FILE * under Windows.
ov_testPartially 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 OggVorbis_File struct is not yet fully +initialized for actual decoding. After a successful return, the file +may be closed using ov_clear() or fully +opened for decoding using ov_test_open().

This call is intended to +be used as a less expensive file open test than a full ov_open().

+Note that libvorbisfile owns the passed in file resource is it returns success; do not fclose() files owned by libvorbisfile.

ov_test_callbacksAs above but allowing application-define I/O callbacks.

+Note that libvorbisfile owns the passed in file resource is it returns success; do not fclose() files owned by libvorbisfile.

ov_test_open +Finish opening a file after a successful call to ov_test() or ov_test_callbacks().
ov_clear Closes the + bitstream and cleans up loose ends. Must be called when + finished with the bitstream. After return, the OggVorbis_File struct is + invalid and may not be used before being initialized again + before begin reinitialized. + +
+ +

+

+ + + + + + + + + +

copyright © 2000-2010 Xiph.Org

Ogg Vorbis

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ + + + diff --git a/doc/vorbisfile/ov_bitrate.html b/doc/vorbisfile/ov_bitrate.html new file mode 100644 index 0000000..eb3c4d7 --- /dev/null +++ b/doc/vorbisfile/ov_bitrate.html @@ -0,0 +1,72 @@ + + + +Vorbisfile - function - ov_bitrate + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

ov_bitrate

+ +

declared in "vorbis/vorbisfile.h";

+ +

This function returns the average bitrate for the specified logical bitstream. This may be different from the ov_info->nominal_bitrate value, as it is based on the actual average for this bitstream if the file is seekable. +

Nonseekable files will return the nominal bitrate setting or the average of the upper and lower bounds, if any of these values are set. +

+ +

+ + + + +
+

+long ov_bitrate(OggVorbis_File *vf,int i);
+
+
+ +

Parameters

+
+
vf
+
A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
+
i
+
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.
+
+ + +

Return Values

+
+
  • OV_EINVAL indicates that an invalid argument value was submitted or that the stream represented by vf is not open.
    • +
  • 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. +
  • n 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).
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_bitrate_instant.html b/doc/vorbisfile/ov_bitrate_instant.html new file mode 100644 index 0000000..da44dcf --- /dev/null +++ b/doc/vorbisfile/ov_bitrate_instant.html @@ -0,0 +1,65 @@ + + + +Vorbisfile - function - ov_bitrate + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_bitrate_instant

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    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. + +

    + + + + +
    +
    
+long ov_bitrate_instant(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. +
    + + +

    Return Values

    +
    +
  • 0 indicates the beginning of the file or unchanged bitrate info.
    • +
  • n indicates the actual bitrate since the last call.
    • +
  • OV_FALSE indicates that playback is not in progress, and thus there is no instantaneous bitrate information to report.
    • +
  • OV_EINVAL indicates that the stream represented by vf is not open.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_callbacks.html b/doc/vorbisfile/ov_callbacks.html new file mode 100644 index 0000000..d1b64be --- /dev/null +++ b/doc/vorbisfile/ov_callbacks.html @@ -0,0 +1,117 @@ + + + +Vorbisfile - datatype - ov_callbacks + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_callbacks

    + +

    declared in "vorbis/codec.h"

    + +

    +The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location. + +

    +The ov_callbacks structure does not need to be user-defined if you are +working with stdio-based file manipulation; the ov_fopen() and ov_open() calls internally provide default callbacks for +stdio. ov_callbacks are defined and passed to ov_open_callbacks() when +implementing non-stdio based stream manipulation (such as playback +from a memory buffer) or when ov_open()-style initialization from a FILE * is required under Windows [a]. +

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

    Relevant Struct Members

    +
    +
    read_func
    +
    Pointer to custom data reading function.
    +
    seek_func
    +
    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 seek_func and tell_func fields should be set to NULL.
    +
    close_func
    +
    Pointer to custom data source closure function. Set to NULL if libvorbisfile should not attempt to automatically close the file/data handle.
    +
    tell_func
    +
    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 seek_func and tell_func fields should be set to NULL.
    +
    + +

    + +

    Predefined callbacks

    +The header vorbis/vorbisfile.h provides several predefined static ov_callbacks structures that may be passed to ov_open_callbacks(): +
    +
    OV_CALLBACKS_DEFAULT
    + +These callbacks provide the same behavior as used internally by ov_fopen() and ov_open(). + +
    OV_CALLBACKS_NOCLOSE
    + +The same as OV_CALLBACKS_DEFAULT, but with the +close_func field set to NULL. The most typical use would be +to use ov_open_callbacks() to +provide the same behavior as ov_open(), but +not close the file/data handle in ov_clear(). + +
    OV_CALLBACKS_STREAMONLY
    + +A set of callbacks that set seek_func and tell_func +to NULL, thus forcing strict streaming-only behavior regardless of +whether or not the input is actually seekable. + +
    OV_CALLBACKS_STREAMONLY_NOCLOSE
    + +The same as OV_CALLBACKS_STREAMONLY, but with +close_func also set to null, preventing libvorbisfile from +attempting to close the file/data handle in ov_clear(). + +
    +

    + +

    Examples and usage

    + +See the callbacks and non-stdio I/O document for more +detailed information on required behavior of the various callback +functions.

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_clear.html b/doc/vorbisfile/ov_clear.html new file mode 100644 index 0000000..e67107c --- /dev/null +++ b/doc/vorbisfile/ov_clear.html @@ -0,0 +1,64 @@ + + + +Vorbisfile - function - ov_clear + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_clear

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    After a bitstream has been opened using ov_fopen()/ov_open()/ov_open_callbacks() and decoding is complete, the application must call ov_clear() to clear +the decoder's buffers. ov_clear() will also close the file unless it was opened using ov_open_callbacks() with the close_func callback set to NULL.

    + +ov_clear() must also be called after a successful call to ov_test() or ov_test_callbacks().

    + +

    + + + + +
    +
    
+int ov_clear(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. After ov_clear has been called, the contents of this structure are deallocated, and it can no longer be used without being reinitialized by a call to ov_fopen(), ov_open() or ov_open_callbacks().
    +
    + + +

    Return Values

    +
    +
  • 0 for success
    • +
    + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_comment.html b/doc/vorbisfile/ov_comment.html new file mode 100644 index 0000000..9f1b499 --- /dev/null +++ b/doc/vorbisfile/ov_comment.html @@ -0,0 +1,66 @@ + + + +Vorbisfile - function - ov_bitrate + + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_comment

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns a pointer to the vorbis_comment struct for the specified bitstream. For nonseekable streams, returns the struct for the current bitstream. +

    + +

    + + + + +
    +
    
+vorbis_comment *ov_comment(OggVorbis_File *vf,int link);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the vorbis_comment struct for the current bitstream, this parameter should be set to -1.
    +
    + + +

    Return Values

    +
    +
  • Returns the vorbis_comment struct for the specified bitstream.
    • +
  • NULL if the specified bitstream does not exist or the file has been initialized improperly.
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_crosslap.html b/doc/vorbisfile/ov_crosslap.html new file mode 100644 index 0000000..0b2b102 --- /dev/null +++ b/doc/vorbisfile/ov_crosslap.html @@ -0,0 +1,100 @@ + + + +Vorbisfile - function - ov_crosslap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_crosslap()

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    ov_crosslap overlaps and blends the boundary at a transition +between two separate streams represented by separate OggVorbis_File structures. For lapping +transitions due to seeking within a single stream represented by a +single OggVorbis_File structure, +consider using the lapping versions of the vorbisfile seeking functions instead. + +

    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. + +

    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. + +

    + + + + +
    +
    
+long ov_crosslap(OggVorbis_File *old, OggVorbis_File *new);
+
+
    +
    + +

    Parameters

    +
    +
    old
    +
    A pointer to the OggVorbis_File structure representing the origin stream from which to transition playback.
    + +
    new
    +
    A pointer to the OggVorbis_File structure representing the stream with which playback continues.
    +
    + + +

    Return Values

    +
    +
    +
    OV_EINVAL
    +
    crosslap called with an OggVorbis_File structure that isn't open.
    +
    OV_EFAULT
    +
    internal error; implies a library bug or external heap corruption.
    +
    OV_EREAD
    +
    A read from media returned an error.
    +
    OV_EOF
    +
    indicates stream vf2 is at end of file, or that vf1 is at end of file immediately after a seek (making crosslap impossible as there's no preceding decode state to crosslap).
    +
    0
    +
    success.
    +
    +
    + + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_fopen.html b/doc/vorbisfile/ov_fopen.html new file mode 100644 index 0000000..9a7b14b --- /dev/null +++ b/doc/vorbisfile/ov_fopen.html @@ -0,0 +1,124 @@ + + + +Vorbisfile - function - ov_fopen + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_fopen

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    This is the simplest function used to open and initialize an OggVorbis_File +structure. It sets up all the related decoding structure. +

    The first argument is a file path suitable +for passing to fopen(). vf 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 OggVorbis_File struct should be passed +to all the libvorbisfile functions. +

    The vf structure initialized using ov_fopen() must +eventually be cleaned using ov_clear(). + +

    +It is often useful to call ov_fopen() simply to determine +whether a given file is a Vorbis bitstream. If the ov_fopen() +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 vf structure will not be used, the +application is responsible for calling ov_clear() to clear the decoder's buffers and +close the file.

    + +

    + + + + +
    +
    
+int ov_fopen(const char *path,OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    path
    +
    Null terminated string containing a file path suitable for passing to fopen(). +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    + + +

    Return Values

    +
    +
  • 0 indicates success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    Notes

    +
    + +
    [a] Threaded decode

    +

    If your decoder is threaded, it is recommended that you NOT call +ov_open_callbacks() +in the main control thread--instead, call ov_open_callbacks() in your decode/playback +thread. This is important because ov_open_callbacks() 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 Thread Safety for other information on using libvorbisfile with threads. +

    + +

    [b] Mixed media streams

    +

    +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.

    + +

    [c] Faster testing for Vorbis files

    +

    ov_test() and ov_test_callbacks() provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.

    + +

    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_info.html b/doc/vorbisfile/ov_info.html new file mode 100644 index 0000000..b94fa68 --- /dev/null +++ b/doc/vorbisfile/ov_info.html @@ -0,0 +1,64 @@ + + + +Vorbisfile - function - ov_info + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_info

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the vorbis_info struct for the specified bitstream. For nonseekable files, always returns the current vorbis_info struct. + +

    + + + + +
    +
    
+vorbis_info *ov_info(OggVorbis_File *vf,int link);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the vorbis_info struct for the current bitstream, this parameter should be set to -1.
    +
    + + +

    Return Values

    +
    +
  • Returns the vorbis_info struct for the specified bitstream. Returns vorbis_info for current bitstream if the file is nonseekable or i=-1.
    • +
  • NULL if the specified bitstream does not exist or the file has been initialized improperly.
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_open.html b/doc/vorbisfile/ov_open.html new file mode 100644 index 0000000..d0311ce --- /dev/null +++ b/doc/vorbisfile/ov_open.html @@ -0,0 +1,183 @@ + + + +Vorbisfile - function - ov_open + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_open

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    ov_open is one of three initialization functions used to initialize +an OggVorbis_File structure and prepare a bitstream for playback. + +

    WARNING for Windows developers: Do not use ov_open() in +Windows applications; Windows linking places restrictions on +passing FILE * handles successfully, and ov_open() runs +afoul of these restrictions [a]. See the ov_open_callbacks() page for +details on using ov_open_callbacks() instead. + +

    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). vf 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 OggVorbis_File +struct should be passed to all the libvorbisfile functions.

    + +The vf structure initialized using ov_fopen() must eventually +be cleaned using ov_clear(). Once a +FILE * handle is passed to ov_open() successfully, the +application MUST NOT fclose() or in any other way manipulate +that file handle. Vorbisfile will close the file in ov_clear(). If the application must be able +to close the FILE * handle itself, see ov_open_callbacks() with the use of +OV_CALLBACKS_NOCLOSE. + +

    It is often useful to call ov_open() simply to determine +whether a given file is a Vorbis bitstream. If the ov_open() +call fails, then the file is not recognizable as Vorbis. If the call +succeeds but the initialized vf structure will not be used, +the application is responsible for calling ov_clear() to clear the decoder's buffers and +close the file.

    + +If [and only if] an ov_open() call fails, the application +must explicitly fclose() the FILE * pointer itself. + + +

    + + + + +
    +
    
+int ov_open(FILE *f,OggVorbis_File *vf,char *initial,long ibytes);
+
    +
    + +

    Parameters

    +
    +
    f
    +
    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).
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    initial
    +
    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 ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
    +
    ibytes
    +
    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, ibytes +should contain the length (in bytes) of the buffer. Used together with initial
    +
    + + +

    Return Values

    +
    +
  • 0 indicates success
    • + +
  • less than zero for failure:
    • + +
    +

    + + +

    Notes

    +
    + + +
    [a] Windows and ov_open()

    + +

    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), FILE * 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 ov_open() under Windows +without careful, expert linking will typically cause a protection +fault. Windows programmers should use ov_fopen() (which will only use libvorbis's +crt.o) or ov_open_callbacks() +(which will only use the application's crt.o) instead.

    + +This warning only applies to Windows and only applies to ov_open(). It is perfectly safe to use ov_open() on all other platforms.

    + +For more information, see the following microsoft pages on C +runtime library linking and a specific description of restrictions +on passing CRT objects across DLL boundaries. + +

    + +

    [b] Threaded decode

    +

    If your decoder is threaded, it is recommended that you NOT call +ov_open() +in the main control thread--instead, call ov_open() in your decode/playback +thread. This is important because ov_open() 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 Thread Safety for other information on using libvorbisfile with threads. +

    + +

    [c] Mixed media streams

    +

    +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.

    + +

    [d] Faster testing for Vorbis files

    +

    ov_test() and ov_test_callbacks() provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.

    + +

    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_open_callbacks.html b/doc/vorbisfile/ov_open_callbacks.html new file mode 100644 index 0000000..6d59e0b --- /dev/null +++ b/doc/vorbisfile/ov_open_callbacks.html @@ -0,0 +1,147 @@ + + + +Vorbisfile - function - ov_open_callbacks + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_open_callbacks

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    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 FILE * pointer under +Windows where ov_open() cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +

    Once ov_open_callbacks() has been called, the same +OggVorbis_File struct should be passed to all the +libvorbisfile functions. Unlike ov_fopen() and ov_open(), ov_open_callbacks() may be used to +instruct vorbisfile to either automatically close or not to close the +file/data access handle in ov_clear(). +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.

    + +See also Callbacks and Non-stdio I/O for +information on designing and specifying custom callback functions.

    + +

    + + + + +
    +
    
+int ov_open_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks);
+
    +
    + +

    Parameters

    +
    +
    datasource
    +
    Pointer to a data structure allocated by the calling application, containing any state needed by the callbacks provided.
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    initial
    +
    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 ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
    +
    ibytes
    +
    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, ibytes +should contain the length (in bytes) of the buffer. Used together with initial.
    +
    callbacks
    +
    A completed ov_callbacks struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see ov_callbacks for details.
    +
    + + +

    Return Values

    +
    +
  • 0 for success
    • +
  • less than zero for failure:
    • + +
    +

    + +

    Notes

    +
    + +
    [a] Windows and use as an ov_open() substitute

    Windows +applications should not use ov_open() due +to the likelihood of CRT linking +mismatches and runtime protection faults +[ov_open:a]. ov_open_callbacks() is a safe substitute; specifically: + +

    ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);
+
    + +... provides exactly the same functionality as ov_open() but will always work correctly under +Windows, regardless of linking setup details.

    + +

    [b] Threaded decode

    +

    If your decoder is threaded, it is recommended that you NOT call +ov_open_callbacks() +in the main control thread--instead, call ov_open_callbacks() in your decode/playback +thread. This is important because ov_open_callbacks() 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 Thread Safety for other information on using libvorbisfile with threads. +

    + +

    [c] Mixed media streams

    +

    +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.

    + +

    [d] Faster testing for Vorbis files

    +

    ov_test() and ov_test_callbacks() provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.

    + +

    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_seek.html b/doc/vorbisfile/ov_pcm_seek.html new file mode 100644 index 0000000..81b0c1c --- /dev/null +++ b/doc/vorbisfile/ov_pcm_seek.html @@ -0,0 +1,83 @@ + + + +Vorbisfile - function - ov_pcm_seek + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_seek

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the offset specified (in pcm samples) within the physical bitstream. This function only works for seekable streams. +

    This also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from +the newly seeked to position. +

    + +

    + + + + +
    +
    
+int ov_pcm_seek(OggVorbis_File *vf,ogg_int64_t pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in pcm samples to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_seek_lap.html b/doc/vorbisfile/ov_pcm_seek_lap.html new file mode 100644 index 0000000..6310e42 --- /dev/null +++ b/doc/vorbisfile/ov_pcm_seek_lap.html @@ -0,0 +1,103 @@ + + + +Vorbisfile - function - ov_pcm_seek_lap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_seek_lap

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the offset specified (in pcm samples) within the physical bitstream. This variant of ov_pcm_seek 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 ov_pcm_seek. + +

    ov_pcm_seek_lap also updates everything needed within the decoder, +so you can immediately call ov_read() and +get data from the newly seeked to position. + +

    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. + +

    This function only works for seekable streams. + +

    + + + + +
    +
    
+int ov_pcm_seek_lap(OggVorbis_File *vf,ogg_int64_t pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in pcm samples to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_seek_page.html b/doc/vorbisfile/ov_pcm_seek_page.html new file mode 100644 index 0000000..8f1959a --- /dev/null +++ b/doc/vorbisfile/ov_pcm_seek_page.html @@ -0,0 +1,84 @@ + + + +Vorbisfile - function - ov_pcm_seek_page + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_seek_page

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the closest page preceding the specified location (in pcm samples) within the physical bitstream. This function only works for seekable streams. +

    This function is faster than ov_pcm_seek 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. +

    This also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from +the newly seeked to position. +

    + +

    + + + + +
    +
    
+int ov_pcm_seek_page(OggVorbis_File *vf,ogg_int64_t pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in pcm samples to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_seek_page_lap.html b/doc/vorbisfile/ov_pcm_seek_page_lap.html new file mode 100644 index 0000000..d9694e8 --- /dev/null +++ b/doc/vorbisfile/ov_pcm_seek_page_lap.html @@ -0,0 +1,112 @@ + + + +Vorbisfile - function - ov_pcm_seek_page_lap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_seek_page_lap

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the closest page preceding the specified location (in pcm +samples) within the physical bitstream. This variant of ov_pcm_seek_page 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 ov_pcm_seek_page. + +

    This function is faster than ov_pcm_seek_lap 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. + +

    ov_pcm_seek_page_lap also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from the newly seeked +to position. + +

    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. + +

    This function only works for seekable streams. + +

    + + + + +
    +
    
+int ov_pcm_seek_page_lap(OggVorbis_File *vf,ogg_int64_t pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in pcm samples to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_tell.html b/doc/vorbisfile/ov_pcm_tell.html new file mode 100644 index 0000000..2d8ea83 --- /dev/null +++ b/doc/vorbisfile/ov_pcm_tell.html @@ -0,0 +1,63 @@ + + + +Vorbisfile - function - ov_pcm_tell + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_tell

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the current offset in samples. + +

    + + + + +
    +
    
+ogg_int64_t ov_pcm_tell(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    + + +

    Return Values

    +
    +
  • n indicates the current offset in samples.
    • +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_pcm_total.html b/doc/vorbisfile/ov_pcm_total.html new file mode 100644 index 0000000..297a8e1 --- /dev/null +++ b/doc/vorbisfile/ov_pcm_total.html @@ -0,0 +1,67 @@ + + + +Vorbisfile - function - ov_pcm_total + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_pcm_total

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the total pcm samples of the physical bitstream or a specified logical bitstream. + +

    + + + + +
    +
    
+ogg_int64_t ov_pcm_total(OggVorbis_File *vf,int i);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    Link to the desired logical bitstream. To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.
    +
    + + +

    Return Values

    +
    +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is unseekable.
    • +
  • +total length in pcm samples of content if i=-1.
    • +
  • length in pcm samples of logical bitstream if i=0 to n.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_raw_seek.html b/doc/vorbisfile/ov_raw_seek.html new file mode 100644 index 0000000..04ed549 --- /dev/null +++ b/doc/vorbisfile/ov_raw_seek.html @@ -0,0 +1,83 @@ + + + +Vorbisfile - function - ov_raw_seek + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_raw_seek

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the offset specified (in compressed raw bytes) within the physical bitstream. This function only works for seekable streams. +

    This also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from +the newly seeked to position. +

    When seek speed is a priority, this is the best seek funtion to use. +

    + + + + +
    +
    
+int ov_raw_seek(OggVorbis_File *vf,long pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in compressed bytes to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_raw_seek_lap.html b/doc/vorbisfile/ov_raw_seek_lap.html new file mode 100644 index 0000000..8e8c24d --- /dev/null +++ b/doc/vorbisfile/ov_raw_seek_lap.html @@ -0,0 +1,110 @@ + + + +Vorbisfile - function - ov_raw_seek_lap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_raw_seek_lap

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Seeks to the offset specified (in compressed raw bytes) within the +physical bitstream. This variant of ov_raw_seek 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 ov_raw_seek. + +

    When seek speed is a priority, but crosslapping is still desired, +this is the best seek funtion to use. + +

    ov_raw_seek_lap also updates everything needed within the decoder, +so you can immediately call ov_read() and +get data from the newly seeked to position. + +

    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. + +

    This function only works for seekable streams. + + +

    + + + + +
    +
    
+int ov_raw_seek_lap(OggVorbis_File *vf,long pos);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    pos
    +
    Position in compressed bytes to seek to in the bitstream.
    +
    + + +

    Return Values

    +
    +
    + +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_raw_tell.html b/doc/vorbisfile/ov_raw_tell.html new file mode 100644 index 0000000..5f30eff --- /dev/null +++ b/doc/vorbisfile/ov_raw_tell.html @@ -0,0 +1,65 @@ + + + +Vorbisfile - function - ov_raw_tell + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_raw_tell

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the current offset in raw compressed bytes.

    + +

    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.

    + +

    + + + + +
    +
    
+ogg_int64_t ov_raw_tell(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    + + +

    Return Values

    +
    +
  • n indicates the current offset in bytes.
    • +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_raw_total.html b/doc/vorbisfile/ov_raw_total.html new file mode 100644 index 0000000..d9d8303 --- /dev/null +++ b/doc/vorbisfile/ov_raw_total.html @@ -0,0 +1,68 @@ + + + +Vorbisfile - function - ov_raw_total + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_raw_total

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the total (compressed) bytes of the physical bitstream or a specified logical bitstream. + +

    + + + + +
    +
    
+ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    Link to the desired logical bitstream. To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.
    +
    + + +

    Return Values

    +
    +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable
    • +
  • n +total length in compressed bytes of content if i=-1.
    • +
  • n length in compressed bytes of logical bitstream if i=0 to n.
    • +
    +

    + + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_read.html b/doc/vorbisfile/ov_read.html new file mode 100644 index 0000000..5461a84 --- /dev/null +++ b/doc/vorbisfile/ov_read.html @@ -0,0 +1,148 @@ + + + +Vorbisfile - function - ov_read + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_read()

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    + 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, ov_read() will not fill + it; the passed in buffer size is treated as a limit and + not a request. + +

    The output channels are in stream order and not remapped. Vorbis I +defines channel order as follows: + +

    + +

    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.

    ov_read() passes + back the index of the sequential logical bitstream currently being + decoded (in *bitstream) 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. +

    + +

    + + + + +
    +
    
+long ov_read(OggVorbis_File *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    buffer
    +
    A pointer to an output buffer. The decoded output is inserted into this buffer.
    +
    length
    +
    Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.
    +
    bigendianp
    +
    Specifies big or little endian byte packing. 0 for little endian, 1 for b +ig endian. Typical value is 0.
    +
    word
    +
    Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or +16-bit samples. Typical value is 2.
    +
    sgned
    +
    Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.
    +
    bitstream
    +
    A pointer to the number of the current logical bitstream.
    +
    + + +

    Return Values

    +
    +
    +
    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)
    +
    OV_EBADLINK
    +
    indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.
    +
    OV_EINVAL
    +
    indicates the initial file headers couldn't be read or + are corrupt, or that the initial open call for vf + failed.
    +
    0
    +
    indicates EOF
    +
    n
    +
    indicates actual number of bytes read. ov_read() will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than length. +
    +
    + +

    Notes

    +

    Typical usage: +

    +bytes_read = ov_read(&vf, +buffer, 4096,0,2,1,&current_section) +
    + +This reads up to 4096 bytes into a buffer, with signed 16-bit +little-endian samples. +

    + + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_read_filter.html b/doc/vorbisfile/ov_read_filter.html new file mode 100644 index 0000000..e3f2e84 --- /dev/null +++ b/doc/vorbisfile/ov_read_filter.html @@ -0,0 +1,114 @@ + + + +Vorbisfile - function - ov_read_filter + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_read_filter()

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    + ov_read_filter() is a variant of ov_read(), 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 ov_read(). +

    + +

    + + + + +
    +
    
+long ov_read_filter(OggVorbis_File *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);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    buffer
    +
    A pointer to an output buffer. The decoded output is inserted into this buffer.
    +
    length
    +
    Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.
    +
    bigendianp
    +
    Specifies big or little endian byte packing. 0 for little endian, 1 for b +ig endian. Typical value is 0.
    +
    word
    +
    Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or +16-bit samples. Typical value is 2.
    +
    sgned
    +
    Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.
    +
    bitstream
    +
    A pointer to the number of the current logical bitstream.
    +
    filter
    +
    Filter function to process float PCM data prior to conversion to interleaved integer output.
    +
    filter_param
    +
    Data to pass through to the filter function.
    + +
    + + +

    Return Values

    +
    +
    +
    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)
    +
    OV_EBADLINK
    +
    indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.
    +
    0
    +
    indicates EOF
    +
    n
    +
    indicates actual number of bytes read. ov_read() will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than length. +
    +
    + +

    Notes

    +

    Typical usage: +

    +bytes_read = ov_read_filter(&vf, +buffer, 4096,0,2,1,&current_section, filter, (void *)filter_data_ptr) +
    + +This reads up to 4096 bytes into a buffer, with signed 16-bit +little-endian samples. The decoded data is passed to the function filter before integer conversiona nd interleave. +

    + + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_read_float.html b/doc/vorbisfile/ov_read_float.html new file mode 100644 index 0000000..0c36eb0 --- /dev/null +++ b/doc/vorbisfile/ov_read_float.html @@ -0,0 +1,105 @@ + + + +Vorbisfile - function - ov_read_float + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_read_float()

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    + 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. +

    + For information on channel ordering and how ov_read_float() deals with the complex issues + of chaining, etc, refer to the documentation for ov_read(). +

    + +

    + + + + +
    +
    
+long ov_read_float(OggVorbis_File *vf, float ***pcm_channels, int samples, int *bitstream);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions.
    +
    pcm_channels
    +
    A pointer to an output buffer. The pointer will be set to the decoded output buffer.
    +
    samples
    +
    Maximum number of decoded samples to produce.
    +
    bitstream
    +
    A pointer to the number of the current logical bitstream.
    +
    + + +

    Return Values

    +
    +
    +
    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)
    +
    OV_EBADLINK
    +
    indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.
    +
    OV_EINVAL
    +
    indicates the initial file headers couldn't be read or + are corrupt, or that the initial open call for vf + failed.
    +
    0
    +
    indicates EOF
    +
    n
    +
    indicates actual number of samples read. ov_read_float() will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than length. +
    +
    + +

    Notes

    +

    Typical usage: +

    +float **pcm; +samples_read = ov_read_float(&vf,pcm, 1024, &current_section) +
    + +This decodes up to 1024 float samples. +

    + +
    +

    +
    + + + + + + + + +

    copyright © 2002 vorbis team

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + + + + + diff --git a/doc/vorbisfile/ov_seekable.html b/doc/vorbisfile/ov_seekable.html new file mode 100644 index 0000000..59b6e97 --- /dev/null +++ b/doc/vorbisfile/ov_seekable.html @@ -0,0 +1,63 @@ + + + +Vorbisfile - function - ov_seekable + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_seekable

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    This indicates whether or not the bitstream is seekable. + + +

    + + + + +
    +
    
+long ov_seekable(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    + + +

    Return Values

    +
    +
  • 0 indicates that the file is not seekable.
    • +
  • nonzero indicates that the file is seekable.
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_serialnumber.html b/doc/vorbisfile/ov_serialnumber.html new file mode 100644 index 0000000..1b64415 --- /dev/null +++ b/doc/vorbisfile/ov_serialnumber.html @@ -0,0 +1,67 @@ + + + +Vorbisfile - function - ov_serialnumber + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_serialnumber

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the serialnumber of the specified logical bitstream link number within the overall physical bitstream. + +

    + + + + +
    +
    
+long ov_serialnumber(OggVorbis_File *vf,int i);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    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.
    +
    + + +

    Return Values

    +
    +
  • +-1 if the specified logical bitstream i does not exist.
    • + +
  • Returns the serial number of the logical bitstream i or the serial number of the current bitstream if the file is nonseekable.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_streams.html b/doc/vorbisfile/ov_streams.html new file mode 100644 index 0000000..e455b07 --- /dev/null +++ b/doc/vorbisfile/ov_streams.html @@ -0,0 +1,64 @@ + + + +Vorbisfile - function - ov_streams + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_streams

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the number of logical bitstreams within our physical bitstream. + +

    + + + + +
    +
    
+long ov_streams(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    + + +

    Return Values

    +
    +
  • +1 indicates a single logical bitstream or an unseekable file.
    • +
  • n indicates the number of logical bitstreams.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_test.html b/doc/vorbisfile/ov_test.html new file mode 100644 index 0000000..cb11d01 --- /dev/null +++ b/doc/vorbisfile/ov_test.html @@ -0,0 +1,104 @@ + + + +Vorbisfile - function - ov_test + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_test

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    +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 ov_test_open() to +finish opening the file or ov_clear to +close/free it. Note that vorbisfile does not take ownership of +the file if the call fails; the calling applicaiton is responsible for +closing the file if this call returns an error. +

    + +

    WARNING for Windows developers: Do not use ov_test() +in Windows applications; Windows linking places restrictions on +passing FILE * handles successfully, and ov_test() runs afoul +of these restrictions [a] in exactly the same +way as ov_open(). See the ov_test_callbacks() page for +details on using ov_test_callbacks() instead. +

    + + + + + +
    +
    
+int ov_test(FILE *f,OggVorbis_File *vf,char *initial,long ibytes);
+
    +
    + +

    Parameters

    +
    +
    f
    +
    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).
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    initial
    +
    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 ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
    +
    ibytes
    +
    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, ibytes +should contain the length (in bytes) of the buffer. Used together with initial
    +
    + + +

    Return Values

    +
    +
  • 0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    Notes

    + +All the notes from ov_open() apply to ov_test(). + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_test_callbacks.html b/doc/vorbisfile/ov_test_callbacks.html new file mode 100644 index 0000000..9abc84c --- /dev/null +++ b/doc/vorbisfile/ov_test_callbacks.html @@ -0,0 +1,111 @@ + + + +Vorbisfile - function - ov_test_callbacks + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_test_callbacks

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    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 FILE * pointer under +Windows where ov_test() cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +

    Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions. +

    +

    + + + + +
    +
    
+int ov_test_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks);
+
    +
    + +

    Parameters

    +
    +
    f
    +
    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).
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    initial
    +
    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 ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
    +
    ibytes
    +
    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, ibytes +should contain the length (in bytes) of the buffer. Used together with initial.
    +
    callbacks
    +
    A completed ov_callbacks struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see ov_callbacks for details.
    +
    + + +

    Return Values

    +
    +
  • 0 for success
    • +
  • less than zero for failure:
    • + +
    +

    + +

    Notes

    +
    + +
    [a] Windows and use as an ov_test() substitute

    Windows +applications should not use ov_test() due +to the likelihood of CRT linking +mismatches and runtime protection faults +[ov_open:a]. ov_test_callbacks() is a safe substitute; specifically: + +

    ov_test_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);
+
    + +... provides exactly the same functionality as ov_test() but will always work correctly under +Windows, regardless of linking setup details.

    + +

    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_test_open.html b/doc/vorbisfile/ov_test_open.html new file mode 100644 index 0000000..6fb8ae9 --- /dev/null +++ b/doc/vorbisfile/ov_test_open.html @@ -0,0 +1,82 @@ + + + +Vorbisfile - function - ov_test_open + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_test_open

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    +Finish opening a file partially opened with ov_test() +or ov_test_callbacks(). +

    + + + + + +
    +
    
+int ov_test_open(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + + + + + + + + diff --git a/doc/vorbisfile/ov_time_seek.html b/doc/vorbisfile/ov_time_seek.html new file mode 100644 index 0000000..ec19ce3 --- /dev/null +++ b/doc/vorbisfile/ov_time_seek.html @@ -0,0 +1,82 @@ + + + +Vorbisfile - function - ov_time_seek + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_seek

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    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 ov_read() and get data from +the newly seeked to position. This function does not work for unseekable streams. + +

    + + + + +
    +
    
+int ov_time_seek(OggVorbis_File *vf, double s);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    Pointer to our already opened and initialized OggVorbis_File structure.
    +
    pos
    +
    Location to seek to within the file, specified in seconds.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_time_seek_lap.html b/doc/vorbisfile/ov_time_seek_lap.html new file mode 100644 index 0000000..f300f3b --- /dev/null +++ b/doc/vorbisfile/ov_time_seek_lap.html @@ -0,0 +1,105 @@ + + + +Vorbisfile - function - ov_time_seek_lap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_seek_lap

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    For seekable +streams, ov_time_seek_lap seeks to the given time. This variant of ov_time_seek 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 ov_time_seek. + +

    ov_time_seek_lap also updates everything needed within the decoder, +so you can immediately call ov_read() and +get data from the newly seeked to position. + +

    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. + +

    This function does not work for unseekable streams. + + +

    + + + + +
    +
    
+int ov_time_seek_lap(OggVorbis_File *vf, double s);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    Pointer to our already opened and initialized OggVorbis_File structure.
    +
    pos
    +
    Location to seek to within the file, specified in seconds.
    +
    + + +

    Return Values

    +
    +
    + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_time_seek_page.html b/doc/vorbisfile/ov_time_seek_page.html new file mode 100644 index 0000000..271d575 --- /dev/null +++ b/doc/vorbisfile/ov_time_seek_page.html @@ -0,0 +1,83 @@ + + + +Vorbisfile - function - ov_time_seek_page + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_seek_page

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    For seekable +streams, this seeks to closest full page preceding the given time. This function is faster than ov_time_seek 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. +

    This function also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from +the newly seeked to position. +

    This function does not work for unseekable streams. + +

    + + + + +
    +
    
+int ov_time_seek_page(OggVorbis_File *vf, double s);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    Pointer to our already opened and initialized OggVorbis_File structure.
    +
    pos
    +
    Location to seek to within the file, specified in seconds.
    +
    + + +

    Return Values

    +
    +
    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_time_seek_page_lap.html b/doc/vorbisfile/ov_time_seek_page_lap.html new file mode 100644 index 0000000..3b1effa --- /dev/null +++ b/doc/vorbisfile/ov_time_seek_page_lap.html @@ -0,0 +1,112 @@ + + + +Vorbisfile - function - ov_time_seek_page_lap + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_seek_page_lap

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    For seekable streams, ov_time_seek_page_lap seeks to the closest +full page preceeding the given time. This variant of ov_time_seek_page 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 ov_time_seek_page. + +

    ov_time_seek_page_lap is faster than ov_time_seek_lap 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. + +

    ov_time_seek_page_lap also updates everything needed within the +decoder, so you can immediately call ov_read() and get data from the newly seeked +to position. + +

    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. + +

    This function does not work for unseekable streams. + +

    + + + + +
    +
    
+int ov_time_seek_page_lap(OggVorbis_File *vf, double s);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    Pointer to our already opened and initialized OggVorbis_File structure.
    +
    pos
    +
    Location to seek to within the file, specified in seconds.
    +
    + + +

    Return Values

    +
    +
    + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_time_tell.html b/doc/vorbisfile/ov_time_tell.html new file mode 100644 index 0000000..92d171c --- /dev/null +++ b/doc/vorbisfile/ov_time_tell.html @@ -0,0 +1,63 @@ + + + +Vorbisfile - function - ov_time_tell + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_tell

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    Returns the current decoding offset in seconds. + +

    + + + + +
    +
    
+double ov_time_tell(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    + + +

    Return Values

    +
    +
  • n indicates the current decoding time offset in seconds.
    • +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.
    • +
    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/ov_time_total.html b/doc/vorbisfile/ov_time_total.html new file mode 100644 index 0000000..3b34f93 --- /dev/null +++ b/doc/vorbisfile/ov_time_total.html @@ -0,0 +1,67 @@ + + + +Vorbisfile - function - ov_time_total + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    ov_time_total

    + +

    declared in "vorbis/vorbisfile.h";

    + + +

    Returns the total time in seconds of the physical bitstream or a specified logical bitstream. + + +

    + + + + +
    +
    
+double ov_time_total(OggVorbis_File *vf,int i);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions.
    +
    i
    +
    Link to the desired logical bitstream. To retrieve the time total for the entire physical bitstream, this parameter should be set to -1.
    +
    + + +

    Return Values

    +
    +
  • OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable.
    • +
  • n total length in seconds of content if i=-1.
    • +
  • n length in seconds of logical bitstream if i=0 to n.
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/overview.html b/doc/vorbisfile/overview.html new file mode 100644 index 0000000..1306495 --- /dev/null +++ b/doc/vorbisfile/overview.html @@ -0,0 +1,61 @@ + + + +Vorbisfile - API Overview + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    Vorbisfile API Overview

    + +

    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 OggVorbis_File +struct. +

    +The Vorbisfile API consists of the following functional categories: +

    +

    +

    +In addition, the following subjects deserve attention additional to +the above general overview: +

    +

    +

    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + + diff --git a/doc/vorbisfile/reference.html b/doc/vorbisfile/reference.html new file mode 100644 index 0000000..7c3c789 --- /dev/null +++ b/doc/vorbisfile/reference.html @@ -0,0 +1,86 @@ + + + +Vorbisfile API Reference + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    Vorbisfile API Reference

    + +

    +Data Structures
    +OggVorbis_File
    +ov_callbacks
    +
    +Data Structures from libvorbis
    +vorbis_comment
    +vorbis_info
    +
    +Setup/Teardown
    +ov_fopen()
    +ov_open()
    +ov_open_callbacks()
    +ov_clear()
    +ov_test()
    +ov_test_callbacks()
    +ov_test_open()
    +
    +Decoding
    +ov_read()
    +ov_read_float()
    +ov_read_filter()
    +ov_crosslap()
    +
    +Seeking
    +ov_raw_seek()
    +ov_pcm_seek()
    +ov_time_seek()
    +ov_pcm_seek_page()
    +ov_time_seek_page()

    +ov_raw_seek_lap()
    +ov_pcm_seek_lap()
    +ov_time_seek_lap()
    +ov_pcm_seek_page_lap()
    +ov_time_seek_page_lap()
    +
    +File Information
    +ov_bitrate()
    +ov_bitrate_instant()
    +ov_streams()
    +ov_seekable()
    +ov_serialnumber()
    +ov_raw_total()
    +ov_pcm_total()
    +ov_time_total()
    +ov_raw_tell()
    +ov_pcm_tell()
    +ov_time_tell()
    +ov_info()
    +ov_comment()
    +
    +Return Codes (from libvorbis)
    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/seekexample.html b/doc/vorbisfile/seekexample.html new file mode 100644 index 0000000..897403d --- /dev/null +++ b/doc/vorbisfile/seekexample.html @@ -0,0 +1,152 @@ + + + +vorbisfile - Example Code + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    Example Code: seeking

    + +

    +The following is a run-through of the seeking example program supplied +with vorbisfile - seeking_test.c. +This program tests the vorbisfile ov_time_seek function by seeking to random points within the file. + +

    +First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +

    + + + + +
    +
    
+#include <stdlib.h>
+#include <stdio.h>
+#include "vorbis/codec.h"
+#include "vorbis/vorbisfile.h"
+
    +
    + +

    Inside main(), we declare our primary OggVorbis_File structure. We also declare other helpful variables to track our progress within the file. +

    + + + + +
    +
    
+int main(){
+  OggVorbis_File ov;
+  int i;
+
    +
    + +

    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. +

    + + + + +
    +
    
+#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */
+  _setmode( _fileno( stdin ), _O_BINARY );
+#endif
+
    +
    + +

    ov_open() must be +called to initialize the OggVorbis_File structure with default values. +ov_open_callbacks() also checks to ensure that we're reading Vorbis format and not something else. + +

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

    +First we check to make sure the stream is seekable using ov_seekable. + +

    Then we seek to 100 random spots in the bitstream using ov_time_seek with randomly generated values. + +

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

    +When we're done seeking, we need to call ov_clear() to release the bitstream. + +

    + + + + +
    +
    
+  ov_clear(&ov);
+  return 0;
+}
+
    +
    + +

    +The full source for seeking_test.c can be found with the vorbis +distribution in seeking_test.c. + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/seeking.html b/doc/vorbisfile/seeking.html new file mode 100644 index 0000000..17e4e82 --- /dev/null +++ b/doc/vorbisfile/seeking.html @@ -0,0 +1,107 @@ + + + +Vorbisfile - Seeking + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    Seeking

    +

    Seeking functions allow you to specify a specific point in the stream to begin or continue decoding. +

    +All libvorbisfile seeking routines are declared in "vorbis/vorbisfile.h". + +

    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. + +

    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.

    + +

    Naturally, seeking is available only within a seekable file or +stream. Seeking functions will return OV_ENOSEEK on +nonseekable files and streams. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    functionpurpose
    ov_raw_seekThis function seeks to a position specified in the compressed bitstream, specified in bytes.
    ov_pcm_seekThis function seeks to a specific audio sample number, specified in pcm samples.
    ov_pcm_seek_pageThis function seeks to the closest page preceding the specified audio sample number, specified in pcm samples.
    ov_time_seekThis function seeks to the specific time location in the bitstream, specified in seconds
    ov_time_seek_pageThis function seeks to the closest page preceding the specified time position in the bitstream
    ov_raw_seek_lapThis 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.
    ov_pcm_seek_lapThis 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.
    ov_pcm_seek_page_lapThis 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.
    ov_time_seek_lapThis 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.
    ov_time_seek_page_lapThis 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.
    + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/seeking_example_c.html b/doc/vorbisfile/seeking_example_c.html new file mode 100644 index 0000000..eb10a98 --- /dev/null +++ b/doc/vorbisfile/seeking_example_c.html @@ -0,0 +1,86 @@ + + + +vorbisfile - seeking_test.c + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    seeking_test.c

    + +

    +The example program source: + +

    + + + + +
    +
    
+
+#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;
+}
+
+
    +
    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/seeking_test_c.html b/doc/vorbisfile/seeking_test_c.html new file mode 100644 index 0000000..eb10a98 --- /dev/null +++ b/doc/vorbisfile/seeking_test_c.html @@ -0,0 +1,86 @@ + + + +vorbisfile - seeking_test.c + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    seeking_test.c

    + +

    +The example program source: + +

    + + + + +
    +
    
+
+#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;
+}
+
+
    +
    + + +

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/seekingexample.html b/doc/vorbisfile/seekingexample.html new file mode 100644 index 0000000..8263f02 --- /dev/null +++ b/doc/vorbisfile/seekingexample.html @@ -0,0 +1,203 @@ + + + +vorbisfile - Example Code + + + + + + + + + +

    vorbisfile documentation

    vorbisfile version 1.25 - 20000615

    + +

    Example Code

    + +

    +The following is a run-through of the decoding example program supplied +with vorbisfile - vorbisfile_example.c. +This program takes a vorbis bitstream from stdin and writes raw pcm to stdout. + +

    +First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included. + +

    + + + + +
    +
    
+#include <stdio.h>
+#include <stdlib.h>
+#include <math.h>
+#include "vorbis/codec.h"
+#include "vorbis/vorbisfile.h"
+
    +
    +

    +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. +

    + + + + +
    +
    
+#ifdef _WIN32
+#include <io.h>
+#include <fcntl.h>
+#endif
+
    +
    +

    +Next, a buffer for the pcm audio output is declared. + +

    + + + + +
    +
    
+char pcmout[4096];
+
    +
    + +

    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. +

    + + + + +
    +
    
+int main(int argc, char **argv){
+  OggVorbis_File vf;
+  int eof=0;
+  int current_section;
+
+#ifdef _WIN32
+  _setmode( _fileno( stdin ), _O_BINARY );
+#endif
+
    +
    + +

    ov_open_callbacks() must be +called to initialize the OggVorbis_File structure with default values. +ov_open_callbacks() also checks to ensure that we're reading Vorbis format and not something else. + +

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

    +We're going to pull the channel and bitrate info from the file using ov_info() and show them to the user. +We also want to pull out and show the user a comment attached to the file using ov_comment(). + +

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

    +Here's the read loop: + +

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

    +The code is reading blocks of data using ov_read(). +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. + +

    +Now that we've finished playing, we can pack up and go home. It's important to call ov_clear() when we're finished. + +

    + + + + +
    +
    
+
+  ov_clear(&vf);
+    
+  fprintf(stderr,"Done.\n");
+  return(0);
+}
+
    +
    + +

    +The full source for vorbisfile_example.c can be found with the vorbis +distribution in vorbisfile_example.c. + +

    +

    + + + + + + + + +

    copyright © 2000 vorbis team

    Ogg Vorbis

    vorbisfile documentation

    vorbisfile version 1.25 - 20000615

    + + + + diff --git a/doc/vorbisfile/style.css b/doc/vorbisfile/style.css new file mode 100644 index 0000000..81cf417 --- /dev/null +++ b/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/doc/vorbisfile/threads.html b/doc/vorbisfile/threads.html new file mode 100644 index 0000000..274e115 --- /dev/null +++ b/doc/vorbisfile/threads.html @@ -0,0 +1,50 @@ + + + +Vorbisfile - Thread Safety + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    Thread Safety

    + +Vorbisfile's libvorbisfile may be used safely in a threading environment +so long as thread access to individual OggVorbis_File instances is serialized. + + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + diff --git a/doc/vorbisfile/vorbisfile_example_c.html b/doc/vorbisfile/vorbisfile_example_c.html new file mode 100644 index 0000000..f3ba1d6 --- /dev/null +++ b/doc/vorbisfile/vorbisfile_example_c.html @@ -0,0 +1,106 @@ + + + +vorbisfile - vorbisfile_example.c + + + + + + + + + +

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + +

    vorbisfile_example.c

    + +

    +The example program source: + +

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

    +

    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + -- cgit v1.1