From 0dea514251507fa16f9d2c7d7780025bbf0c800a Mon Sep 17 00:00:00 2001 From: Monty Date: Tue, 2 Jul 2002 21:40:29 +0000 Subject: [PATCH] Numerous corrections and updates to libVorbisfile docs svn path=/trunk/vorbis/; revision=3495 --- doc/vorbisfile/OggVorbis_File.html | 78 ++++++++++++++++++++-------------- doc/vorbisfile/datastructures.html | 22 +++++----- doc/vorbisfile/decoding.html | 52 ++++++++++++++++++----- doc/vorbisfile/example.html | 26 ++++++------ doc/vorbisfile/fileinfo.html | 21 +++++---- doc/vorbisfile/index.html | 37 +++++++++------- doc/vorbisfile/initialization.html | 71 ++++++++++++++++++++++--------- doc/vorbisfile/ov_bitrate.html | 21 +++++---- doc/vorbisfile/ov_bitrate_instant.html | 24 +++++------ doc/vorbisfile/ov_callbacks.html | 50 +++++++++++----------- doc/vorbisfile/ov_clear.html | 27 ++++++------ doc/vorbisfile/ov_comment.html | 19 +++++---- doc/vorbisfile/ov_info.html | 21 +++++---- doc/vorbisfile/ov_open.html | 37 ++++++++-------- doc/vorbisfile/ov_open_callbacks.html | 30 +++++++------ doc/vorbisfile/ov_pcm_seek.html | 25 ++++++----- doc/vorbisfile/ov_pcm_seek_page.html | 22 +++++----- doc/vorbisfile/ov_pcm_tell.html | 22 +++++----- doc/vorbisfile/ov_pcm_total.html | 21 ++++----- doc/vorbisfile/ov_raw_seek.html | 28 ++++++------ doc/vorbisfile/ov_raw_tell.html | 22 +++++----- doc/vorbisfile/ov_raw_total.html | 28 ++++++------ doc/vorbisfile/ov_read.html | 66 +++++++++++++++------------- doc/vorbisfile/ov_read_float.html | 13 +++--- doc/vorbisfile/ov_seekable.html | 26 ++++++------ doc/vorbisfile/ov_serialnumber.html | 26 ++++++------ doc/vorbisfile/ov_streams.html | 21 +++++---- doc/vorbisfile/ov_test.html | 24 +++++------ doc/vorbisfile/ov_test_callbacks.html | 30 +++++++------ doc/vorbisfile/ov_test_open.html | 27 +++++++----- doc/vorbisfile/ov_time_seek.html | 21 +++++---- doc/vorbisfile/ov_time_seek_page.html | 23 +++++----- doc/vorbisfile/ov_time_tell.html | 26 ++++++------ doc/vorbisfile/ov_time_total.html | 33 ++++++-------- doc/vorbisfile/overview.html | 36 +++++++++++----- doc/vorbisfile/reference.html | 19 ++++++--- doc/vorbisfile/seeking.html | 41 ++++++++++-------- doc/vorbisfile/vorbis_comment.html | 23 +++++----- doc/vorbisfile/vorbis_info.html | 52 +++++++---------------- 39 files changed, 660 insertions(+), 551 deletions(-) diff --git a/doc/vorbisfile/OggVorbis_File.html b/doc/vorbisfile/OggVorbis_File.html index a00e26b..05548c8 100644 --- a/doc/vorbisfile/OggVorbis_File.html +++ b/doc/vorbisfile/OggVorbis_File.html @@ -1,15 +1,15 @@ -vorbisfile - datatype - OggVorbis_File +Vorbisfile - datatype - OggVorbis_File - - + +

vorbisfile documentation

vorbisfile - 20011218

Vorbisfile documentation

libVorbisfile version 1.65 - 20020702

@@ -20,10 +20,30 @@

The OggVorbis_File structure defines an Ogg Vorbis file.

-This structure is used in all vorbisfile routines. Before it can be used, it must be initialized by ov_open or ov_open_callbacks. + +This structure is used in all libvorbisfile routines. Before it can be used, +it must be initialized by ov_open() or ov_open_callbacks(). + +

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

+Once a file or data source is opened successfully by libvorbisfile +(using ov_open() or ov_open_callbacks()), it is owned by +libvorbisfile. The file should not be used by any other applications or +functions outside of the libvorbisfile API. The file must not be closed +directly by the application at any time after a successful open; +libvorbisfile expects to close the file within ov_clear().

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

Once a file or data source is passed to libvorbisfile, it is owned by vorbisfile. The file should not be used by any other applications or functions outside the Vorbisfile API. +If the call to ov_open() or ov_open_callbacks() fails, +libvorbisfile does not assume ownership of the file and the +application is expected to close it if necessary. +

@@ -31,28 +51,28 @@ After use, the OggVorbis_File structure must be deallocated with a call to typedef struct { void *datasource; /* Pointer to a FILE *, etc. */ int seekable; - int64_t offset; - int64_t end; + 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; - int64_t *offsets; - int64_t *dataoffsets; + ogg_int64_t *offsets; + ogg_int64_t *dataoffsets; long *serialnos; - int64_t *pcmlengths; + ogg_int64_t *pcmlengths; vorbis_info *vi; vorbis_comment *vc; /* Decoding working state local storage */ - int64_t pcm_offset; + ogg_int64_t pcm_offset; int ready_state; long current_serialno; int current_link; - double bittrack; - double samptrack; + ogg_int64_t bittrack; + ogg_int64_t samptrack; ogg_stream_state os; /* take physical pages, weld into a logical stream of packets */ @@ -69,34 +89,30 @@ After use, the OggVorbis_File structure must be deallocated with a call to Relevant Struct Members

datasource
-
Pointer to file or other ogg source.
+ +
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, i.e., physical file is seekable, a pipe isn't.
+
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.
+
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.

-
Notes
- -
If your system's <sys/types.h> does not -define int64_t, you will need to define this as a 64-bit type -inside your system's project file/Makefile, etc. On win32, for example, -this should be defined as __int64. On the Unix platform, these -are usually defined properly in the system header files. -
- -

- - + + - - + +

copyright © 2001 vorbis team
Ogg Vorbis
team@vorbis.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile - 20011218
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

diff --git a/doc/vorbisfile/datastructures.html b/doc/vorbisfile/datastructures.html index 7a53003..72d7cf3 100644 --- a/doc/vorbisfile/datastructures.html +++ b/doc/vorbisfile/datastructures.html @@ -1,24 +1,22 @@ -vorbisfile - Base Data Structures +Vorbisfile - Base Data Structures - - + +

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

Base Data Structures

-
There are several data structures used to hold file and bitstream information during vorbisfile decoding. +
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".
-All the vorbisfile specific data structures are declared in "vorbis/vorbisfile.h" or "vorbis/codec.h". -
-
When using vorbisfile, we usually won't need to know about most of the contents of these data structures, but it may be helpful to understand what they contain. +
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.

@@ -42,7 +40,7 @@ All the vorbisfile specific data structures are declared in "vorbis/vorbi - +

ov_callbacks This structure contains pointers to file manipulation routines. Can be user-specified for use with ov_open_callbacks(). This 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.

@@ -50,11 +48,11 @@ All the vorbisfile specific data structures are declared in "vorbis/vorbi
- - + + - - + +

copyright © 2000 vorbis team
Ogg Vorbis
team@vorbis.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

diff --git a/doc/vorbisfile/decoding.html b/doc/vorbisfile/decoding.html index afb25c8..e7151db 100644 --- a/doc/vorbisfile/decoding.html +++ b/doc/vorbisfile/decoding.html @@ -1,24 +1,57 @@ -vorbisfile - Decoding +Vorbisfile - Decoding - - + +

vorbisfile documentation
vorbisfile - 20011218
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

Decoding

-All the vorbisfile decoding routines are declared in "vorbis/vorbisfile.h". +All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".
+After initialization, decoding audio +is as simple as calling ov_read(). 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. + +
@@ -31,7 +64,7 @@ OggVorbis_File structure, which must have been initialized by a previous call to ov_open(). - +

function

ov_read ov_read_float This function decodes to floats instead of integer samples.

@@ -40,15 +73,14 @@ call to ov_open().
- - + + - - + +

copyright © 2001 Xiphophorus
www.vorbis.org
team@icecast.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile - 20011218
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

- diff --git a/doc/vorbisfile/example.html b/doc/vorbisfile/example.html index 2a5cfaf..12977f1 100644 --- a/doc/vorbisfile/example.html +++ b/doc/vorbisfile/example.html @@ -1,15 +1,15 @@ -vorbisfile - Example Code +Vorbisfile - Example Code - - + +

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

@@ -17,11 +17,11 @@
The following is a run-through of the decoding example program supplied -with vorbisfile - vorbisfile_example.c. +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 "codec.h" and "vorbisfile.h" have to be included. +First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included.

@@ -32,7 +32,7 @@ First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" #include <stdlib.h> #include <math.h> #include "vorbis/codec.h" -#include "vorbis/vorbisfile.h" +#include "vorbisfile.h" @@ -123,6 +123,8 @@ We also want to pull out and show the user a comment attached to the file using ++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); } @@ -141,7 +143,7 @@ Here's the read loop:
while(!eof){ - long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,¤t_section); + long ret=ov_read(&vf,pcmout,sizeof(pcmout),¤t_section); if (ret == 0) { /* EOF */ eof=1; @@ -185,18 +187,16 @@ Now that we've finished playing, we can pack up and go home. It's important to

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

- - + + - - + +

copyright © 2000 vorbis team
Ogg Vorbis
team@vorbis.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

diff --git a/doc/vorbisfile/fileinfo.html b/doc/vorbisfile/fileinfo.html index 27f6370..db9bdbe 100644 --- a/doc/vorbisfile/fileinfo.html +++ b/doc/vorbisfile/fileinfo.html @@ -1,22 +1,22 @@ -vorbisfile - File Information +Vorbisfile - File Information - - + +

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

File Information
-
Vorbisfile contains many functions to get information about bitstream attributes and decoding status. +
Libvorbisfile contains many functions to get information about bitstream attributes and decoding status.
-All the vorbisfile file information routines are declared in "vorbis/vorbisfile.h". +All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h".
@@ -30,7 +30,7 @@ All the vorbisfile file information routines are declared in "vorbis/vorb - + @@ -82,15 +82,14 @@ All the vorbisfile file information routines are declared in "vorbis/vorb

ov_bitrate_instant Returns the exact bitrate since the last call of this function, or -1 if beginning of the bitream or no new info is available. Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitream or no new information is available.

ov_streams
- - + + - - + +

copyright © 2000 vorbis team
Ogg Vorbis
team@vorbis.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

- diff --git a/doc/vorbisfile/index.html b/doc/vorbisfile/index.html index 102636a..87addd5 100644 --- a/doc/vorbisfile/index.html +++ b/doc/vorbisfile/index.html @@ -1,39 +1,46 @@ -vorbisfile - Documentation +Vorbisfile - Documentation - - + +

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

-
VorbisFile Documentation
+
Vorbisfile Documentation

-VorbisFile is a stdio-based convenience library for decoding vorbis bitstreams. -It is the simplest and quickest way to go from file to raw PCM audio samples--if -your decoder doesn't need to read from anything other than a file, use -this. This document explains how to use the vorbisfile API in detail. + +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. +
-vorbisfile api overview
-vorbisfile example code
-vorbisfile api reference
+API overview
+API reference
+Example code

- - + + - - + +

copyright © 2000 vorbis team
Ogg Vorbis
team@vorbis.org
copyright © 2002 Xiph.org
Ogg Vorbis

vorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

diff --git a/doc/vorbisfile/initialization.html b/doc/vorbisfile/initialization.html index fd0c5cc..aa226f1 100644 --- a/doc/vorbisfile/initialization.html +++ b/doc/vorbisfile/initialization.html @@ -1,22 +1,34 @@ -libvorbisfile - Setup/Teardown +Vorbisfile - Setup/Teardown - - + +

libvorbisfile documentation
vorbisfile version 1.25 - 20000615
Vorbisfile documentation
libVorbisfile version 1.65 - 20020702

-
Setup/Teardown
-
In order to decode audio using libvorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished. +
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 fopen() to open a Vorbis +file and then pass the FILE * to an ov_open() call. A successful return code from ov_open() 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. Do not call fclose() on the +file; libvorbisfile does this in the ov_clear() call. +

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

@@ -31,23 +43,44 @@ All the vorbisfile initialization and deallocation routines are declared - - - - - + + - - + + + + - + + +Finish opening a file after a successful call to ov_test() or ov_test_callbacks(). + + +

ov_open_callbacks Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of ov_open when working with a data source other than a file.
ov_clear Closes the bitstream and cleans up loose ends. Must be called when we're done with the bitstream. Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of ov_open() when working with other than stdio based I/O.
ov_test Partially opens a vorbis file for testing. ov_test Partially opens a file just far enough to determine if the file +is an Ogg Vorbis file or not. A successful return indicates that the +file appears to be an Ogg Vorbis file, but the 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_callbacks Same as above but useful for non-files like streams. As 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 open a file opened for testing.
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. + +

@@ -55,11 +88,11 @@ All the vorbisfile initialization and deallocation routines are declared

- - + + - - + +

copyright © 2000 vorbis team	Ogg Vorbis team@vorbis.org	copyright © 2002 Xiph.org	Ogg Vorbis
vorbisfile documentation	vorbisfile version 1.25 - 20000615	Vorbisfile documentation	libVorbisfile version 1.65 - 20020702

diff --git a/doc/vorbisfile/ov_bitrate.html b/doc/vorbisfile/ov_bitrate.html index 5c379cf..bcfd257 100644 --- a/doc/vorbisfile/ov_bitrate.html +++ b/doc/vorbisfile/ov_bitrate.html @@ -1,15 +1,15 @@ -vorbisfile - function - ov_bitrate +Vorbisfile - function - ov_bitrate - - + +

vorbisfile documentation

vorbisfile version 1.25 - 20000615

Vorbisfile documentation

libVorbisfile version 1.65 - 20020702

@@ -35,7 +35,7 @@ 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 vorbisfile +; 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.

copyright © 2001 vorbis team	Ogg Vorbis team@vorbis.org	copyright © 2002 Xiph.org	Ogg Vorbis
vorbisfile documentation	vorbisfile - 20011218	Vorbisfile documentation	libVorbisfile version 1.65 - 20020702

function
ov_read	ov_read_float	This function decodes to floats instead of integer samples.

copyright © 2001 Xiphophorus	www.vorbis.org team@icecast.org	copyright © 2002 Xiph.org	Ogg Vorbis
vorbisfile documentation	vorbisfile - 20011218	Vorbisfile documentation	libVorbisfile version 1.65 - 20020702

ov_bitrate_instant	Returns the exact bitrate since the last call of this function, or -1 if beginning of the bitream or no new info is available.	Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitream or no new information is available.
ov_streams

ov_open_callbacks	Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of ov_open when working with a data source other than a file.
ov_clear	Closes the bitstream and cleans up loose ends. Must be called when we're done with the bitstream.	Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of ov_open() when working with other than stdio based I/O.
ov_test	Partially opens a vorbis file for testing.	ov_test	Partially opens a file just far enough to determine if the file +is an Ogg Vorbis file or not. A successful return indicates that the +file appears to be an Ogg Vorbis file, but the 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_callbacks	Same as above but useful for non-files like streams.	As 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 open a file opened for testing.
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 © 2001 vorbis team	copyright © 2002 vorbis team	Ogg Vorbis team@vorbis.org
vorbisfile documentation	vorbisfile - 20011218	libVorbisfile version 1.65 - 20020702

Notes

Base Data Structures

Decoding

multiple stream links

returned data amount

file cursor position

File Information

VorbisFile Documentation

Vorbisfile Documentation

Setup/Teardown

Setup/Teardown

Parameters

Return Values

Parameters

Return Values

Relevant Struct Members

Parameters

Return Values

Parameters

Parameters

Return Values

Return Values

Parameters

Return Values

Parameters

Parameters

Return Values

Parameters

Parameters

Return Values

Parameters

Return Values

Parameters

Return Values

Parameters

Parameters

Return Values

Parameters

Parameters

Return Values

Return Values

Parameters

Parameters

Return Values

Parameters

Return Values

Notes

VorbisFile API Overview

Vorbisfile API Overview

Seeking

Parameters

`Parameters`