Vorbisfile

https://xiph.org/vorbis/doc/vorbisfile/
Admin
This project provides documentation for libvorbisfile, a C library that offers a high-level API for...
Tokens:29,960
Snippets:260
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Vorbisfile Example C Program

Source: https://xiph.org/vorbis/doc/vorbisfile/vorbisfile_example_c.html

This C program demonstrates how to open an Ogg Vorbis stream from standard input, read its metadata, and decode the audio data to standard output using the vorbisfile library. It includes platform-specific setup for binary I/O on Windows.

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

```

--------------------------------

### Windows Binary Mode Setup

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Conditionally include headers and declare functions for setting stdin/stdout to binary mode on Windows systems.

```c
#ifdef _WIN32
#include <io.h>
#include <fcntl.h>
#endif
```

--------------------------------

### Using ov_open_callbacks as ov_open Substitute on Windows

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_open_callbacks.html

This example shows how to use ov_open_callbacks to achieve the same functionality as ov_open() but with guaranteed compatibility on Windows systems.

```c
`ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);`
```

--------------------------------

### Typical ov_read_filter() Usage Example

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_read_filter.html

Demonstrates a typical call to ov_read_filter() with common parameter values for reading audio data and applying a filter.

```c
bytes_read = ov_read_filter(&vf, buffer, 4096,0,2,1,&current_section, filter, (void *)filter_data_ptr)
```

--------------------------------

### Typical ov_read() Usage Example

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_read.html

A common example demonstrating how to call ov_read() to decode audio data. This call specifies a buffer size of 4096 bytes, little-endian format, 16-bit word size, signed data, and tracks the current section.

```c
bytes_read = ov_read(&vf, buffer, 4096,0,2,1,&current_section)
```

--------------------------------

### Using ov_test_callbacks as ov_test() Substitute on Windows

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_test_callbacks.html

This example demonstrates how to use ov_test_callbacks with default callbacks to achieve the same functionality as ov_test() on Windows, ensuring compatibility and avoiding potential runtime issues.

```c
`ov_test_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);`
```

--------------------------------

### C Example: Open and Read Vorbisfile Information

Source: https://xiph.org/vorbis/doc/vorbisfile/chaining_example_c.html

This C code snippet demonstrates how to open an Ogg Vorbis file (or standard input) using vorbisfile, retrieve information about its logical bitstreams, and print details such as sample rate, channels, bitrate, and playback time. It includes platform-specific handling for Windows and checks for seekability.

```c
#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;
}

```

--------------------------------

### C Example: Seeking Test in Vorbisfile

Source: https://xiph.org/vorbis/doc/vorbisfile/seeking_test_c.html

This C code demonstrates how to open an Ogg Vorbis file from standard input, test if it's seekable, and then perform random seeks within the file using ov_time_seek. It's useful for verifying seeking capabilities.

```c
#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;
}

```

--------------------------------

### Check Stream Properties and Get Information

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

Check if the stream is seekable, get the number of logical bitstreams, and determine the total playing time of the physical bitstream.

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

--------------------------------

### Get Current Decoding Time Offset

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_time_tell.html

Use ov_time_tell to get the current playback position in seconds. Ensure the OggVorbis_File structure is valid.

```c
#include <vorbis/vorbisfile.h>

// Assuming 'vf' is a valid OggVorbis_File pointer
double currentTime = ov_time_tell(vf);

```

--------------------------------

### Get Instantaneous Bitrate

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_bitrate_instant.html

Use this function to get the most recent bitrate played back within the file. It returns 0 if the bitrate has not changed or it is the beginning of the file. OV_FALSE is returned if playback is not in progress, and OV_EINVAL if the stream is not open.

```c
long ov_bitrate_instant(OggVorbis_File *vf);
```

--------------------------------

### ov_pcm_seek_page_lap

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_pcm_seek_page_lap.html

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.

```APIDOC
## ov_pcm_seek_page_lap

### Description
Seeks to the closest page preceding the specified location (in pcm samples) within the physical bitstream, with automatic crosslapping to eliminate discontinuities.

### Method
int

### Endpoint
ov_pcm_seek_page_lap

### Parameters
#### Path Parameters
- **vf** (OggVorbis_File *) - Required - A pointer to the OggVorbis_File structure used for all external libvorbisfile functions.
- **pos** (ogg_int64_t) - Required - Position in pcm samples to seek to in the bitstream.

### Return Values
- **0** for success
- **nonzero** indicates failure, described by several error codes:
  - **OV_ENOSEEK**: Bitstream is not seekable.
  - **OV_EINVAL**: Invalid argument value; possibly called with an OggVorbis_File structure that isn't open.
  - **OV_EREAD**: A read from media returned an error.
  - **OV_EFAULT**: Internal logic fault; indicates a bug or heap/stack corruption.
  - **OV_EOF**: Indicates stream is at end of file immediately after a seek (making crosslap impossible as there's no preceeding decode state to crosslap).
  - **OV_EBADLINK**: Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
```

--------------------------------

### ov_time_seek_page_lap

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_time_seek_page_lap.html

For seekable streams, ov_time_seek_page_lap seeks to the closest full page preceding 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.

```APIDOC
## ov_time_seek_page_lap

### Description
Seeks to the closest full page preceding the given time in a seekable stream, automatically crosslapping the transition from the previous playback position to eliminate clicking and boundary discontinuities.

### Method
C Function

### Signature
```c
int ov_time_seek_page_lap(OggVorbis_File *vf, double s);
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
* **vf** (*OggVorbis_File* *) - Pointer to an initialized OggVorbis_File structure.
* **s** (*double*) - The target time in seconds to seek to. The function will seek to the page preceding this time.

### Return Values
* **0** for success.
* **Nonzero** indicates failure. Possible error codes include:
  * **OV_ENOSEEK**: The bitstream is not seekable.
  * **OV_EINVAL**: Invalid argument value (e.g., an uninitialized OggVorbis_File structure).
  * **OV_EREAD**: An error occurred during media reading.
  * **OV_EFAULT**: An internal logic fault or memory corruption.
  * **OV_EOF**: The stream is at the end of the file immediately after seeking, making crosslapping impossible.
  * **OV_EBADLINK**: The requested stream section is invalid or corrupt.
```

--------------------------------

### ov_pcm_seek_lap

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_pcm_seek_lap.html

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.

```APIDOC
## ov_pcm_seek_lap

### Description
Seeks to the offset specified (in pcm samples) within the physical bitstream, automatically cross-lapping the transition from the previous playback position into the new playback position to eliminate clicking and boundary discontinuities. Updates decoder state for immediate reading from the new position.

### Function Signature
```c
int ov_pcm_seek_lap(OggVorbis_File *vf, ogg_int64_t pos);
```

### Parameters
#### Path Parameters
* **vf** (OggVorbis_File *) - A pointer to the OggVorbis_File structure.
* **pos** (ogg_int64_t) - Position in pcm samples to seek to in the bitstream.

### Return Values
* **0** for success
* **Nonzero** indicates failure, described by several error codes:
  * **OV_ENOSEEK** - Bitstream is not seekable.
  * **OV_EINVAL** - Invalid argument value; possibly called with an OggVorbis_File structure that isn't open.
  * **OV_EREAD** - A read from media returned an error.
  * **OV_EFAULT** - Internal logic fault; indicates a bug or heap/stack corruption.
  * **OV_EOF** - Indicates stream is at end of file immediately after a seek (making crosslap impossible as there's no preceeding decode state to crosslap).
  * **OV_EBADLINK** - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
```

--------------------------------

### Main Function and Initialization

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Initialize the OggVorbis_File structure, declare variables for tracking decoding progress, and set stdin/stdout to binary mode on Windows.

```c
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
```

--------------------------------

### Get Serial Number of Logical Bitstream

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_serialnumber.html

Use this function to get the serial number of a specific logical bitstream link. For non-seekable files, the 'i' parameter is ignored and the current bitstream's serial number is returned. Set 'i' to -1 to get the serial number of the current bitstream.

```c
long ov_serialnumber(OggVorbis_File *vf,int i);
```

--------------------------------

### Setup/Teardown Functions

Source: https://xiph.org/vorbis/doc/vorbisfile/reference.html

Functions for opening, closing, and testing Vorbis files.

```APIDOC
## Setup/Teardown Functions

### Description
Functions for opening, closing, and testing Vorbis files.

### Functions
- `ov_fopen(const char *filename)`
- `ov_open(FILE *vf, ov_callbacks callbacks)`
- `ov_open_callbacks(void *datasource, ov_callbacks callbacks, long荪)`
- `ov_clear(OggVorbis_File *vf)`
- `ov_test(const char *filename)`
- `ov_test_callbacks(void *datasource, ov_callbacks callbacks)`
- `ov_test_open(const char *filename)`
```

--------------------------------

### Get Total Raw Bytes of Bitstream

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_raw_total.html

Use this function to get the total compressed bytes of the entire physical bitstream. Set the second parameter to -1 to retrieve the total bytes for the whole stream.

```c
ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i);
```

--------------------------------

### Get Total Time of Bitstream

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_time_total.html

Use ov_time_total to get the total duration in seconds of the entire audio file (physical bitstream) or a specific logical bitstream. Set the second parameter to -1 for the entire file.

```c
double ov_time_total(OggVorbis_File *vf,int i);
```

--------------------------------

### Get Vorbis Comment Structure

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_comment.html

Retrieves the vorbis_comment struct for a specific logical bitstream. For non-seekable streams, it returns the comment for the current bitstream. Use -1 for the link parameter to get the comment for the current bitstream.

```c
vorbis_comment *ov_comment(OggVorbis_File *vf,int link);
```

--------------------------------

### Get Vorbis Stream Info

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_info.html

Use ov_info to retrieve the vorbis_info structure for a specific logical bitstream. For non-seekable files, it returns the info for the current stream. Set the link parameter to -1 to get the current stream's info.

```c
vorbis_info *ov_info(OggVorbis_File *vf,int link);
```

--------------------------------

### Open OggVorbis File with Callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

Initialize the OggVorbis_File structure using ov_open_callbacks and verify the input is a Vorbis file. OV_CALLBACKS_NOCLOSE prevents closing stdin during cleanup.

```c
  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);
  }

```

--------------------------------

### Initialize OggVorbis_File with a FILE pointer

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_open.html

Use ov_open to initialize an OggVorbis_File structure from an existing FILE pointer. Note the warning for Windows developers; ov_open_callbacks is recommended on Windows. The application must not fclose the FILE pointer after a successful call; ov_clear will handle closing.

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

--------------------------------

### Initialize OggVorbis_File Structure

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

Declare the primary OggVorbis_File structure and other variables needed for processing.

```c
int main(){
  OggVorbis_File ov;
  int i;
```

--------------------------------

### Include Vorbisfile and Codec Headers

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Include necessary headers for standard I/O, memory allocation, math functions, and the Vorbis codec and file structures.

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

--------------------------------

### Get Current PCM Offset

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_pcm_tell.html

Use ov_pcm_tell to retrieve the current sample offset. Ensure the OggVorbis_File structure is valid. Returns OV_EINVAL if the bitstream is invalid.

```c
ogg_int64_t ov_pcm_tell(OggVorbis_File *vf);
```

--------------------------------

### Get Number of Logical Bitstreams

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_streams.html

Use this function to determine the number of logical bitstreams in an OggVorbis_File structure. A return value of 1 indicates a single logical bitstream or an unseekable file.

```c
long ov_streams(OggVorbis_File *vf);
```

--------------------------------

### Typical Usage of ov_read_float()

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_read_float.html

Demonstrates the typical way to call ov_read_float() within an application to read decoded audio samples. Ensure the OggVorbis_File structure is properly initialized.

```c
float **pcm;
samples_read = ov_read_float(&vf, pcm, 1024, &current_section);
```

--------------------------------

### ov_open

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_open.html

Initializes an OggVorbis_File structure using a FILE pointer. This function is used to prepare a bitstream for playback. Note: This function has specific warnings for Windows developers and should not be used in Windows applications; ov_open_callbacks() is recommended instead.

```APIDOC
## ov_open

### Description
Initializes an `OggVorbis_File` structure using a `FILE` pointer, preparing a bitstream for playback. It is one of three initialization functions for `OggVorbis_File`.

### Warning
**Do not use `ov_open()` in Windows applications** due to `FILE *` handle restrictions. Use `ov_open_callbacks()` instead.

### Parameters
#### Parameters
- **f** (`FILE *`) - A pointer to an already opened file or pipe. It does not need to be seekable.
- **vf** (`OggVorbis_File *`) - A pointer to the `OggVorbis_File` structure to be initialized. This structure will be used by all subsequent libvorbisfile functions.
- **initial** (`char *`) - Typically `NULL`. If data has already been read and the stream is not seekable, this points to a buffer containing the pre-read data.
- **ibytes** (`long`) - Typically `0`. If `initial` is used, this is the length (in bytes) of the data in the `initial` buffer.

### Return Values
- **0**: Indicates success.
- **Less than 0**: Indicates failure with specific error codes:
  - `OV_EREAD`: A read from media returned an error.
  - `OV_ENOTVORBIS`: Bitstream is not Vorbis data.
  - `OV_EVERSION`: Vorbis version mismatch.
  - `OV_EBADHEADER`: Invalid Vorbis bitstream header.
  - `OV_EFAULT`: Internal logic fault (bug or corruption).

### Important Notes
- Once `ov_open()` succeeds, the application **must not** `fclose()` or manipulate the `FILE *` handle. Vorbisfile will close it in `ov_clear()`.
- If `ov_open()` fails, the application **must** explicitly `fclose()` the `FILE *` pointer.
- If the initialized `vf` structure will not be used, call `ov_clear()` to clean up.
```

--------------------------------

### Open Vorbis Stream with Callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Initialize the OggVorbis_File structure using ov_open_callbacks, verifying the input is a valid Ogg bitstream. OV_CALLBACKS_NOCLOSE prevents closing stdin during cleanup.

```c
  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);
  }

```

--------------------------------

### Get Raw Offset with ov_raw_tell

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_raw_tell.html

Use this function to retrieve the current byte offset in the raw compressed data. Be aware that seeking back to this position might not be exact due to internal buffering.

```c
ogg_int64_t ov_raw_tell(OggVorbis_File *vf);
```

--------------------------------

### Predefined Callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_callbacks.html

Libvorbisfile provides several predefined sets of callbacks for common use cases, simplifying the process of initializing streams with specific I/O behaviors.

```APIDOC
## Predefined Callbacks

Libvorbisfile offers predefined `ov_callbacks` structures for common scenarios:

- **`OV_CALLBACKS_DEFAULT`**: Provides the same behavior as the default callbacks used internally by `ov_fopen()` and `ov_open()`. This is suitable for standard stdio file operations.

- **`OV_CALLBACKS_NOCLOSE`**: Identical to `OV_CALLBACKS_DEFAULT` but with the `close_func` member set to NULL. This prevents `ov_clear()` from attempting to close the file or data handle, useful when the handle is managed externally.

- **`OV_CALLBACKS_STREAMONLY`**: Configures callbacks to enforce strict streaming-only behavior by setting `seek_func` and `tell_func` to NULL. This ensures that the input is treated as a stream, regardless of its actual seekability.

- **`OV_CALLBACKS_STREAMONLY_NOCLOSE`**: Combines the streaming-only behavior of `OV_CALLBACKS_STREAMONLY` with the non-closing behavior of `OV_CALLBACKS_NOCLOSE`. Both `seek_func` and `tell_func` are set to NULL, and `close_func` is also NULL, preventing both seeking and automatic closure of the data handle.
```

--------------------------------

### ov_bitrate

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_bitrate.html

Returns the average bitrate for the specified logical bitstream. For seekable files, this is the actual average bitrate. For non-seekable files, it returns the nominal bitrate or the average of the upper and lower bounds if set. Use -1 for 'i' to get the bitrate for the entire bitstream.

```APIDOC
## ov_bitrate

### Description
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.

### Method
`long ov_bitrate(OggVorbis_File *vf, int i);`

### Parameters
#### Path Parameters
- **vf** (OggVorbis_File *) - A pointer to the OggVorbis_File structure.
- **i** (int) - 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**: Indicates that the file is nonseekable and the upper, lower, and nominal bitrates were unset.
- **n** (long): 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).
```

--------------------------------

### ov_fopen

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be used.

```APIDOC
## ov_fopen

### Description
Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be used.

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### ov_open

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be used. Do not use this call under Windows; Use ov_fopen() or ov_open_callbacks() instead.

```APIDOC
## ov_open

### Description
Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be used. Do not use this call under Windows; Use ov_fopen() or ov_open_callbacks() instead.

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### ov_time_seek_page

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_time_seek_page.html

For seekable streams, this seeks to the 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.

```APIDOC
## ov_time_seek_page

### Description
Seeks to the closest full page preceding the given time in a seekable stream. This function is faster but less accurate than `ov_time_seek` and is recommended when speed is important. It updates the decoder state for immediate reading from the new position.

### Function Signature
```c
int ov_time_seek_page(OggVorbis_File *vf, double s);
```

### Parameters
#### Path Parameters
* **vf** (OggVorbis_File *) - Pointer to an opened and initialized OggVorbis_File structure.
* **s** (double) - Location to seek to within the file, specified in seconds.

### Return Values
* **0** for success
* **Nonzero** indicates failure, with the following possible error codes:
  * **OV_ENOSEEK**: Bitstream is not seekable.
  * **OV_EINVAL**: Invalid argument value; possibly called with an uninitialized OggVorbis_File structure.
  * **OV_EREAD**: A read from media returned an error.
  * **OV_EFAULT**: Internal logic fault; indicates a bug or heap/stack corruption.
  * **OV_EBADLINK**: Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
```

--------------------------------

### ov_test_callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

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.

```APIDOC
## ov_test_callbacks

### Description
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.

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### Declare ov_fopen Function

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_fopen.html

This is the function declaration for ov_fopen, which opens and initializes an OggVorbis_File structure.

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

--------------------------------

### ov_open_callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

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

```APIDOC
## ov_open_callbacks

### Description
Initializes 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.

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### Include Vorbisfile Headers

Source: https://xiph.org/vorbis/doc/vorbisfile/seekexample.html

Include necessary standard and vorbis-specific headers for Ogg Vorbis file operations.

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

--------------------------------

### ov_test_open

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_test_open.html

Finishes opening a file that was partially opened with ov_test() or ov_test_callbacks(). It takes a pointer to an OggVorbis_File structure and returns 0 on success or a negative error code on failure.

```APIDOC
## ov_test_open

### Description
Finishes opening a file that was partially opened with `ov_test()` or `ov_test_callbacks()`.

### Function Signature
```c
int ov_test_open(OggVorbis_File *vf);
```

### Parameters
#### Path Parameters
* **vf** (OggVorbis_File *) - A pointer to the `OggVorbis_File` structure. This structure is used for all 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:
  * **OV_EREAD**: A read from media returned an error.
  * **OV_ENOTVORBIS**: Bitstream is not Vorbis data.
  * **OV_EVERSION**: Vorbis version mismatch.
  * **OV_EBADHEADER**: Invalid Vorbis bitstream header.
  * **OV_EFAULT**: Internal logic fault; indicates a bug or heap/stack corruption.
```

--------------------------------

### ov_test_callbacks

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_test_callbacks.html

Opens and tests an OggVorbis stream using custom callback functions for data access. This is an alternative to ov_test() and is recommended for use on Windows or when custom I/O behavior is needed.

```APIDOC
## ov_test_callbacks

### Description
This function is used to open and test an OggVorbis stream from a data source using custom file manipulation routines. It is particularly useful when the data source is not a standard file, or when specific I/O behaviors need to be controlled, such as on Windows where `ov_test()` may not be suitable.

### Function Signature
```c
int ov_test_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks);
```

### Parameters
#### Datasource
- **datasource** (void *) - A pointer to the data source. This can be a file pointer, a pipe, or any other data source for which custom callbacks are provided.

#### OggVorbis_File Structure
- **vf** (OggVorbis_File *) - A pointer to an `OggVorbis_File` structure. This structure will be initialized by the function and must be used for all subsequent libvorbisfile operations on this stream.

#### Initial Data Buffer
- **initial** (char *) - Typically set to `NULL`. If the stream is not seekable and some data has already been read, this parameter should point to a buffer containing that pre-read data.

#### Initial Data Size
- **ibytes** (long) - Typically set to `0`. If `initial` is used, this parameter specifies the size in bytes of the data in the `initial` buffer.

#### Callbacks
- **callbacks** (ov_callbacks) - A completed `ov_callbacks` struct that defines the custom file manipulation routines (read, seek, close, etc.) to be used for accessing the data source.

### Return Values
- **0** for success.
- **Less than zero** for failure, with specific error codes:
  - **OV_EREAD**: A read operation on the media returned an error.
  - **OV_ENOTVORBIS**: The bitstream does not contain valid Vorbis data.
  - **OV_EVERSION**: A Vorbis version mismatch was detected.
  - **OV_EBADHEADER**: The Vorbis bitstream header is invalid.
  - **OV_EFAULT**: An internal logic fault occurred, possibly indicating a bug or memory corruption.

### Notes
**Windows Compatibility:** For Windows applications, `ov_test_callbacks()` is a safe substitute for `ov_test()` to avoid potential CRT linking issues. Using `OV_CALLBACKS_DEFAULT` with `ov_test_callbacks()` provides equivalent functionality to `ov_test()`.

**Example Usage (Windows):**
```c
ov_test_callbacks(f, vf, NULL, 0, OV_CALLBACKS_DEFAULT);
```
```

--------------------------------

### Include Vorbisfile Headers

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

Include necessary headers for vorbis codec and vorbisfile operations, along with a misc header.

```c
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#include "../lib/misc.h"
```

--------------------------------

### Declare ov_open_callbacks Function

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_open_callbacks.html

This is the function declaration for ov_open_callbacks, used to open and initialize an OggVorbis_File structure with custom callbacks.

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

--------------------------------

### Retrieve and Display File Information

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Extract and display channel count, sample rate, comments, and vendor information from the Ogg Vorbis file using ov_info and ov_comment.

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

--------------------------------

### ov_test

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

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.

```APIDOC
## ov_test

### Description
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.

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### ov_test_open

Source: https://xiph.org/vorbis/doc/vorbisfile/initialization.html

Finish opening a file after a successful call to ov_test() or ov_test_callbacks().

```APIDOC
## ov_test_open

### Description
Finish opening a file after a successful call to ov_test() or ov_test_callbacks().

### Method
(Not specified, likely a C function call)

### Parameters
(Not specified)

### Request Example
(Not specified)

### Response
(Not specified)
```

--------------------------------

### Declare ov_pcm_seek_page

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_pcm_seek_page.html

This is the function declaration for ov_pcm_seek_page. It takes a pointer to an OggVorbis_File structure and a 64-bit integer representing the target PCM sample position.

```c
int ov_pcm_seek_page(OggVorbis_File *vf,ogg_int64_t pos);
```

--------------------------------

### ov_pcm_seek_page_lap Function Declaration

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_pcm_seek_page_lap.html

This is the function declaration for ov_pcm_seek_page_lap. It takes a pointer to an OggVorbis_File structure and the desired PCM sample position as input.

```c
int ov_pcm_seek_page_lap(OggVorbis_File *vf,ogg_int64_t pos);
```

--------------------------------

### Set stdin to Binary Mode (Windows)

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

On Windows, set stdin to binary mode to prevent data corruption when reading input.

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

--------------------------------

### Iterate and Print Logical Bitstream Info

Source: https://xiph.org/vorbis/doc/vorbisfile/chainingexample.html

Loop through each logical bitstream to extract and print its information, including rate, channels, bitrate, serial number, compressed length, and play time.

```c
  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));
  } 

```

--------------------------------

### Declare ov_raw_seek_lap Function

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_raw_seek_lap.html

This is the function declaration for ov_raw_seek_lap. It takes a pointer to an OggVorbis_File structure and the desired position in compressed bytes.

```c
int ov_raw_seek_lap(OggVorbis_File *vf,long pos);
```

--------------------------------

### ov_test

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_test.html

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.

```APIDOC
## ov_test

### Description
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.

### Method
int

### Endpoint
ov_test(FILE *f, OggVorbis_File *vf, char *initial, long ibytes)

### Parameters
#### Path Parameters
- **f** (FILE *) - 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** (OggVorbis_File *) - 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** (char *) - 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** (long) - 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:
  - OV_EREAD - A read from media returned an error.
  - OV_ENOTVORBIS - Bitstream contains no Vorbis data.
  - OV_EVERSION - Vorbis version mismatch.
  - OV_EBADHEADER - Invalid Vorbis bitstream header.
  - OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.

### Notes
Notes from ov_open()
```

--------------------------------

### Cleanup and Exit

Source: https://xiph.org/vorbis/doc/vorbisfile/example.html

Call ov_clear to release resources associated with the OggVorbis_File structure and exit the program.

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

```

--------------------------------

### Declare ov_raw_seek Function

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_raw_seek.html

This is the function declaration for ov_raw_seek. It takes a pointer to an OggVorbis_File structure and the desired byte position as input.

```c
int ov_raw_seek(OggVorbis_File *vf,long pos);
```

--------------------------------

### ov_test_callbacks Function Signature

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_test_callbacks.html

The function signature for ov_test_callbacks, which takes a data source, an OggVorbis_File structure, an initial buffer, its size, and a callback structure.

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

--------------------------------

### ov_time_seek_page_lap Function Signature

Source: https://xiph.org/vorbis/doc/vorbisfile/ov_time_seek_page_lap.html

This is the function signature for ov_time_seek_page_lap. It takes a pointer to an OggVorbis_File structure and the desired seek time in seconds.

```c
int ov_time_seek_page_lap(OggVorbis_File *vf, double s);
```

--------------------------------

### ov_bitrate_instant

Source: https://xiph.org/vorbis/doc/vorbisfile/fileinfo.html

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

```APIDOC
## ov_bitrate_instant

### Description
Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitstream or no new information is available.

### Method
Not applicable (function call)

### Parameters
None explicitly documented.

### Response
- Returns the exact bitrate since the last call or -1.
```
Tokens:
Raw