Ogg

https://xiph.org/ogg/doc/
Admin
Ogg is a container format designed to provide framing, error protection, and seeking structure for...
Tokens:29,466
Snippets:324
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### ogg_sync_pageout Usage Example

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_pageout.html

Demonstrates a standard reading loop that attempts to sync a page and fills the buffer if more data is required.

```c
if (ogg_sync_pageout(&oy, &og) != 1) {
	buffer = ogg_sync_buffer(&oy, 8192);
	bytes = fread(buffer, 1, 8192, stdin);
	ogg_sync_wrote(&oy, bytes);
}
```

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

### Ogg Packet Segmentation Example

Source: https://xiph.org/ogg/doc/framing.html

Illustrates how a raw packet is logically divided into segments for the Ogg page header. Lacing values indicate segment sizes, with a value less than 255 marking the end of a packet.

```text
`
raw packet:
  ___________________________________________
 |______________packet data__________________|
 753 bytes

lacing values for page header segment table: 255,255,243
`
```

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

### Get Buffer for Synchronization - C

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_buffer.html

Use this function to obtain a buffer for writing data into the ogg_sync_state. The returned buffer size includes the requested size plus an additional 4096 bytes. Do not rely on the extra space as it may change.

```c
char *ogg_sync_buffer(ogg_sync_state *oy, long size);
```

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

### Get ogg_page Version

Source: https://xiph.org/ogg/doc/libogg/ogg_page_version.html

Use this function to get the version of the ogg_page struct. It should always return 0 for current libogg versions. Nonzero values indicate an error.

```c
int ogg_page_version(ogg_page *og);
```

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

### ogg_stream_pageout

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_pageout.html

Forms packets into pages. In a typical encoding situation, this would be called after using ogg_stream_packetin() to submit data packets to the bitstream. Internally, this function assembles the accumulated packet bodies into an Ogg page suitable for writing to a stream. The function is typically called in a loop until there are no more pages ready for output. This function will only return a page when a "reasonable" amount of packet data is available. Normally this is appropriate since it limits the overhead of the Ogg page headers in the bitstream, and so calling ogg_stream_pageout() after ogg_stream_packetin() should be the common case. Call ogg_stream_flush() if immediate page generation is desired. This may be occasionally necessary, for example, to limit the temporal latency of a variable bitrate stream.

```APIDOC
## ogg_stream_pageout

### Description
Forms packets into pages. Assembles accumulated packet bodies into an Ogg page suitable for writing to a stream. Called in a loop until no more pages are ready for output.

### Method
int

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (Non-zero)
- A page has been completed and returned.

#### Error Response (Zero)
- Insufficient data has accumulated to fill a page, or an internal error occurred. In this case _og_ is not modified.

#### Response Example
None
```

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

### Get oggpack_buffer Data Pointer

Source: https://xiph.org/ogg/doc/libogg/oggpack_get_buffer.html

Use oggpack_get_buffer to obtain a pointer to the data buffer within an oggpack_buffer struct. This function requires a pointer to the oggpack_buffer as input.

```c
unsigned char *oggpack_get_buffer(oggpack_buffer *b);
```

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

### Initialize oggpack_buffer for Reading

Source: https://xiph.org/ogg/doc/libogg/oggpack_readinit.html

Use oggpack_readinit to prepare an oggpack_buffer for reading from a raw byte buffer. This function is declared in "ogg/ogg.h".

```c
void oggpack_readinit(oggpack_buffer *b,unsigned char *buf,int bytes);
```

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

### oggpack_writeinit Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_writeinit.html

Initializes an oggpack_buffer for writing.

```APIDOC
## oggpack_writeinit

### Description
This function initializes an oggpack_buffer for writing using the Ogg bitpacking functions.

### Method
void

### Endpoint
Declared in "ogg/ogg.h"

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **b** (oggpack_buffer*) - Required - Buffer to be used for writing. This is an ordinary data buffer with some extra markers to ease bit navigation and manipulation.

### Request Example
```json
{
  "example": "No request body, parameters are passed via function arguments."
}
```

### Response
#### Success Response (void)
- No values are returned. If initialization fails, the buffer is unusable and calls to oggpack_writecheck() will report the error.

#### Response Example
```json
{
  "example": "No return value."
}
```
```

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

### Get oggpack_buffer bit count

Source: https://xiph.org/ogg/doc/libogg/oggpack_bits.html

Use this function to retrieve the current number of bits stored in an oggpack_buffer. Ensure the oggpack_buffer struct is properly initialized before calling.

```c
long oggpack_bits(oggpack_buffer *b);
```

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

### Bitpacking Functions Reference

Source: https://xiph.org/ogg/doc/libogg/bitpacking.html

A collection of functions for bit-level buffer manipulation in libogg.

```APIDOC
## Bitpacking Functions

### Description
Functions for manipulating data within a buffer, declared in 'ogg/ogg.h'.

### Functions
- **oggpack_writeinit**: Initializes a buffer for writing.
- **oggpack_writecheck**: Asynchronously checks error status of bitpacker write buffer.
- **oggpack_reset**: Clears and resets the buffer to the initial position.
- **oggpack_writeclear**: Frees the memory used by the buffer.
- **oggpack_readinit**: Initializes a buffer for reading.
- **oggpack_write**: Writes bytes to the specified location within the buffer.
- **oggpack_look**: Look at a specified number of bits (<=32) without advancing the pointer.
- **oggpack_look1**: Looks at one bit without advancing the pointer.
- **oggpack_adv**: Advances the location pointer by a specified number of bits.
- **oggpack_adv1**: Advances the location pointer by one bit.
- **oggpack_read**: Reads a specified number of bits from the buffer.
- **oggpack_read1**: Reads one bit from the buffer.
- **oggpack_bytes**: Returns the total number of bytes in the buffer.
- **oggpack_bits**: Returns the total number of bits in the buffer.
- **oggpack_get_buffer**: Returns a pointer to the buffer encapsulated within the oggpack_buffer struct.
```

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

### oggpack_readinit Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_readinit.html

Initializes an oggpack_buffer for reading using Ogg bitpacking functions.

```APIDOC
## oggpack_readinit

### Description
This function takes an ordinary buffer and prepares an oggpack_buffer for reading using the Ogg bitpacking functions.

### Method
void

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```c
void oggpack_readinit(oggpack_buffer *b, unsigned char *buf, int bytes);
```

### Response
#### Success Response (200)
- No values are returned.

#### Response Example
- None
```

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

### Get ogg_page Serial Number

Source: https://xiph.org/ogg/doc/libogg/ogg_page_serialno.html

Use this function to retrieve the unique serial number for the logical bitstream associated with a given ogg_page. The serial number is present in every page.

```c
**
int ogg_page_serialno(ogg_page *og);

**
```

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

### Initialize Ogg Bitpacking Buffer

Source: https://xiph.org/ogg/doc/libogg/oggpack_writeinit.html

Initializes an oggpack_buffer for writing using Ogg bitpacking functions. The buffer is used for writing data and includes markers for bit navigation. If initialization fails, calls to oggpack_writecheck() will report an error.

```c
void  oggpack_writeinit(oggpack_buffer *b);
```

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

### oggpack_writealign Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_writealign.html

Pads the oggpack_buffer with zeros out to the next byte boundary. The oggpack_buffer must already be initialized for writing using oggpack_writeinit. Only 32 bits can be written at a time.

```APIDOC
## oggpack_writealign

### Description
This function pads the oggpack_buffer with zeros out to the next byte boundary. The oggpack_buffer must already be initialized for writing using oggpack_writeinit. Only 32 bits can be written at a time.

### Method
void

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```
// No request body for this function
```

### Response
#### Success Response (200)
- No values are returned.

#### Response Example
```
// No response body for this function
```
```

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

### ogg_sync_init

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_init.html

Initializes an ogg_sync_state struct for Ogg bitstream decoding.

```APIDOC
## ogg_sync_init

### Description
This function is used to initialize an ogg_sync_state struct to a known initial value in preparation for manipulation of an Ogg bitstream. The ogg_sync struct is important when decoding, as it synchronizes retrieval and return of data.

### Parameters
- **oy** (ogg_sync_state*) - Required - Pointer to a previously declared ogg_sync_state struct.

### Return Values
- **0** (int) - Always returned upon successful initialization.
```

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

### Synchronize Ogg bitstream with ogg_sync_pageseek

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_pageseek.html

Use this function to advance the sync state to the next page in the bitstream. It requires a pointer to an initialized ogg_sync_state and an ogg_page structure.

```c
int ogg_sync_pageseek(ogg_sync_state *oy, ogg_page *og);
```

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

### void oggpack_adv(oggpack_buffer *b, int bits)

Source: https://xiph.org/ogg/doc/libogg/oggpack_adv.html

Advances the location pointer in the oggpack_buffer by a specified number of bits.

```APIDOC
## void oggpack_adv(oggpack_buffer *b, int bits)

### Description
This function advances the location pointer by the specified number of bits without reading any data.

### Parameters
- **b** (oggpack_buffer*) - Required - Pointer to the current oggpack_buffer.
- **bits** (int) - Required - Number of bits to advance.

### Return Values
- No values are returned.
```

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

### Check ogg_sync_state status

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_check.html

Use this function to verify if the ogg_sync_state structure is ready or has encountered an unrecoverable error.

```c
int ogg_sync_check(ogg_sync_state *oy);
```

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

### Check oggpack_buffer status

Source: https://xiph.org/ogg/doc/libogg/oggpack_writecheck.html

Verifies if the buffer is ready for writing. Returns zero if ready, and a nonzero value if an error occurred.

```c
int  oggpack_writecheck(oggpack_buffer *b);
```

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

### int oggpack_writecheck(oggpack_buffer *b)

Source: https://xiph.org/ogg/doc/libogg/oggpack_writecheck.html

Checks the readiness status of an oggpack_buffer previously initialized for writing.

```APIDOC
## int oggpack_writecheck(oggpack_buffer *b)

### Description
This function checks the readiness status of an oggpack_buffer previously initialized for writing using the Ogg bitpacking functions. A write buffer that encounters an error will flag itself as 'not ready', and subsequent write attempts will silently fail.

### Parameters
- **b** (oggpack_buffer*) - Required - An oggpack_buffer previously initialized for writing.

### Return Values
- **zero** - Buffer is ready for writing.
- **nonzero** - Buffer is not ready or encountered an error.
```

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

### Initialize ogg_sync_state

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_init.html

Initializes an ogg_sync_state struct to a known initial value. This is required before manipulating an Ogg bitstream.

```c
int ogg_sync_init(ogg_sync_state *oy);
```

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

### Write bits to oggpack_buffer

Source: https://xiph.org/ogg/doc/libogg/oggpack_write.html

Writes a specified number of bits into an oggpack_buffer. The buffer must be initialized with oggpack_writeinit prior to use.

```c
void  oggpack_write(oggpack_buffer *b,unsigned long value,int bits);
```

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

### Read bits from oggpack_buffer

Source: https://xiph.org/ogg/doc/libogg/oggpack_read.html

Reads the requested number of bits from the buffer. Ensure the buffer is initialized with oggpack_readinit before calling.

```c
long oggpack_read(oggpack_buffer *b,int bits);
```

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

### Truncate oggpack_buffer - C

Source: https://xiph.org/ogg/doc/libogg/oggpack_writetrunc.html

Use oggpack_writetrunc to reduce the size of an initialized oggpack_buffer. The buffer must have been previously set up with oggpack_writeinit.

```c
void  oggpack_writetrunc(oggpack_buffer *b, long bits);
```

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

### oggpack_writecopy Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_writecopy.html

Copies a sequence of bits from a source buffer into an oggpack_buffer. The oggpack_buffer must be initialized for writing. Only 32 bits can be written at a time.

```APIDOC
## oggpack_writecopy

### Description
This function copies a sequence of bits from a source buffer into an oggpack_buffer. The oggpack_buffer must already be initialized for writing using oggpack_writeinit. Only 32 bits can be written at a time.

### Method
void

### Endpoint
Declared in "ogg/ogg.h"

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **b** (oggpack_buffer *) - Buffer to be used for writing.
- **source** (void *) - A pointer to the data to be written into the buffer.
- **bits** (long) - The number of bits to be copied into the buffer.

### Request Example
```json
{
  "b": "oggpack_buffer object",
  "source": "pointer to data",
  "bits": 32
}
```

### Response
#### Success Response (200)
- No values are returned.

#### Response Example
```json
{
  "message": "Operation successful, no return value."
}
```
```

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

### ogg_stream_init

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_init.html

Initializes an ogg_stream_state struct and allocates memory for stream processing.

```APIDOC
## ogg_stream_init

### Description
This function is used to initialize an ogg_stream_state struct and allocates appropriate memory in preparation for encoding or decoding. It also assigns the stream a given serial number.

### Parameters
- **os** (ogg_stream_state*) - Required - Pointer to the ogg_stream_state struct that we will be initializing.
- **serialno** (int) - Required - Serial number that we will attach to this stream.

### Return Values
- **0** - Successful
- **-1** - Unsuccessful
```

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

### Add Complete Page to Bitstream - C

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_pagein.html

Use this function after ogg_sync_pageout to submit a valid ogg_page struct to the streaming layer. It prepares the page data for packet extraction. Failure can occur if the page's serial number or version is incorrect.

```c
int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
```

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

### Initialize Ogg Stream State - C

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_init.html

Initializes an ogg_stream_state struct and allocates memory for encoding or decoding. Assigns a serial number to the stream. Returns 0 on success, -1 on failure.

```c
int ogg_stream_init(ogg_stream_state *os,int serialno);
```

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

### oggpack_write Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_write.html

Writes bits into an oggpack_buffer. The buffer must be initialized for writing using oggpack_writeinit. Only 32 bits can be written at a time.

```APIDOC
## oggpack_write

### Description
This function writes bits into an oggpack_buffer. The oggpack_buffer must already be initialized for writing using oggpack_writeinit. Only 32 bits can be written at a time.

### Method
void

### Endpoint
Declared in "ogg/ogg.h"

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **b** (oggpack_buffer *) - Buffer to be used for writing.
- **value** (unsigned long) - The data to be written into the buffer. This must be 32 bits or fewer.
- **bits** (int) - The number of bits being written into the buffer.

### Request Example
```json
{
  "b": "oggpack_buffer_instance",
  "value": 12345,
  "bits": 16
}
```

### Response
#### Success Response (200)
- No values are returned.

#### Response Example
```json
{
  "message": "Operation successful"
}
```
```

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

### int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og)

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_pageout.html

This function takes data stored in the ogg_sync_state buffer and inserts it into an ogg_page structure. It is essential for clearing the buffer during the decoding process.

```APIDOC
## Function: ogg_sync_pageout

### Description
This function takes the data stored in the buffer of the ogg_sync_state struct and inserts them into an ogg_page. It should be called in a decoding loop to ensure the buffer is cleared and data is properly synced.

### Parameters
- **oy** (ogg_sync_state*) - Required - Pointer to a previously declared ogg_sync_state struct.
- **og** (ogg_page*) - Required - Pointer to the page struct to be filled by this function.

### Return Values
- **-1**: Stream has not yet captured sync (bytes were skipped).
- **0**: More data is needed or an internal error occurred.
- **1**: A page was synced and returned.

### Example Usage
```c
if (ogg_sync_pageout(&oy, &og) != 1) {
	buffer = ogg_sync_buffer(&oy, 8192);
	bytes = fread(buffer, 1, 8192, stdin);
	ogg_sync_wrote(&oy, bytes);
}
```
```

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

### Declare ogg_stream_packetout Function

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_packetout.html

This function assembles a data packet for output to the codec decoding engine. The data has already been submitted to the ogg_stream_state and broken into segments. Each successive call returns the next complete packet built from those segments. In a typical decoding situation, this should be used after calling ogg_stream_pagein() to submit a page of data to the bitstream. If the function returns 0, more data is needed and another page should be submitted. A non-zero return value indicates successful return of a packet. The _op_ is filled in with pointers to memory managed by the stream state and is only valid until the next call. The client must copy the packet data if a longer lifetime is required.

```c
int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
```

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

### ogg_sync_pageseek

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_pageseek.html

Synchronizes the ogg_sync_state struct to the next ogg_page in the bitstream.

```APIDOC
## ogg_sync_pageseek

### Description
This function synchronizes the ogg_sync_state struct to the next ogg_page. It is used when seeking within a bitstream to find the next valid page.

### Parameters
- **oy** (ogg_sync_state*) - Required - Pointer to a previously declared ogg_sync_state struct.
- **og** (ogg_page*) - Required - Pointer to a page (or an incomplete page) of data to sync.

### Return Values
- **-n** (int) - Indicates that n bytes were skipped within the bitstream.
- **0** (int) - Indicates that the page is not ready (needs more data) or an internal error occurred.
- **n** (int) - Indicates the page was synced at the current location with a length of n bytes.
```

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

### libogg Synchronization Functions

Source: https://xiph.org/ogg/doc/libogg/decoding.html

Functions used to manage the Ogg synchronization layer, including initialization, buffer management, and page extraction.

```APIDOC
## libogg Synchronization Functions

### Description
These functions manage the ogg_sync_state struct to coordinate incoming data and extract Ogg pages.

### Functions
- **ogg_sync_init**: Initializes an Ogg bitstream.
- **ogg_sync_clear**: Clears the status information from the synchronization struct.
- **ogg_sync_reset**: Resets the synchronization status to initial values.
- **ogg_sync_destroy**: Frees the synchronization struct.
- **ogg_sync_check**: Check for asynchronous errors.
- **ogg_sync_buffer**: Exposes a buffer from the synchronization layer in order to read data.
- **ogg_sync_wrote**: Tells the synchronization layer how many bytes were written into the buffer.
- **ogg_sync_pageseek**: Finds the borders of pages and resynchronizes the stream.
- **ogg_sync_pageout**: Outputs a page from the synchronization layer.
```

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

### Advance oggpack_buffer Pointer

Source: https://xiph.org/ogg/doc/libogg/oggpack_adv.html

Use oggpack_adv to advance the location pointer of an oggpack_buffer by a given number of bits. This function does not read any data. Ensure the buffer pointer is valid and the number of bits is within appropriate bounds.

```c
void  oggpack_adv(oggpack_buffer *b,int bits);
```

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

### oggpack_adv1 Function

Source: https://xiph.org/ogg/doc/libogg/oggpack_adv1.html

Advances the location pointer by one bit without reading any data.

```APIDOC
## oggpack_adv1

### Description
This function advances the location pointer by one bit without reading any data.

### Method
void

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```
// No request body for this function
```

### Response
#### Success Response (200)
- No values are returned.

#### Response Example
```
// No return value
```
```

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

### Libogg API Functions

Source: https://xiph.org/ogg/doc/libogg/reference.html

This section details the various functions available in the libogg library for handling Ogg data streams.

```APIDOC
## Libogg API Reference

This document outlines the functions and data structures provided by the libogg library for working with the Ogg container format.

### Data Structures
- `oggpack_buffer`
- `ogg_page`
- `ogg_stream_state`
- `ogg_packet`
- `ogg_sync_state`

### Bitpacking Functions
- `oggpack_writeinit()`: Initializes a packing buffer for writing.
- `oggpack_writecheck()`: Checks the status of a packing buffer.
- `oggpack_reset()`: Resets a packing buffer.
- `oggpack_writetrunc()`: Truncates a packing buffer.
- `oggpack_writealign()`: Aligns the packing buffer.
- `oggpack_writecopy()`: Copies data into the packing buffer.
- `oggpack_writeclear()`: Clears and frees a packing buffer.
- `oggpack_readinit()`: Initializes a packing buffer for reading.
- `oggpack_write()`: Writes data to the packing buffer.
- `oggpack_look()`: Looks at data in the packing buffer without advancing.
- `oggpack_look1()`: Looks at a single bit in the packing buffer.
- `oggpack_adv()`: Advances the read position in the packing buffer.
- `oggpack_adv1()`: Advances the read position by one bit.
- `oggpack_read()`: Reads data from the packing buffer.
- `oggpack_read1()`: Reads a single bit from the packing buffer.
- `oggpack_bytes()`: Returns the number of bytes currently in the packing buffer.
- `oggpack_bits()`: Returns the number of bits currently in the packing buffer.
- `oggpack_get_buffer()`: Gets the internal buffer of the packing structure.

### Decoding-Related Functions
- `ogg_sync_init()`: Initializes an Ogg synchronization state.
- `ogg_sync_check()`: Checks the status of the synchronization state.
- `ogg_sync_clear()`: Clears and frees the synchronization state.
- `ogg_sync_destroy()`: Destroys the synchronization state.
- `ogg_sync_reset()`: Resets the synchronization state.
- `ogg_sync_buffer()`: Provides a buffer for incoming data.
- `ogg_sync_wrote()`: Indicates how much data has been written to the sync buffer.
- `ogg_sync_pageseek()`: Seeks for the next page boundary in the sync buffer.
- `ogg_sync_pageout()`: Retrieves a complete Ogg page from the sync buffer.
- `ogg_stream_pagein()`: Inputs an Ogg page into a stream state.
- `ogg_stream_packetout()`: Retrieves a complete Ogg packet from the stream state.
- `ogg_stream_packetpeek()`: Peeks at the next Ogg packet in the stream state without removing it.

### Encoding-Related Functions
- `ogg_stream_packetin()`: Inputs an Ogg packet into a stream state for encoding.
- `ogg_stream_pageout()`: Retrieves an Ogg page from the stream state for encoding.
- `ogg_stream_pageout_fill()`: Fills an Ogg page buffer with data from the stream state.
- `ogg_stream_flush()`: Flushes any remaining data in the stream state into pages.
- `ogg_stream_flush_fill()`: Fills a page buffer with flushed data from the stream state.

### General Stream Functions
- `ogg_stream_init()`: Initializes an Ogg stream state.
- `ogg_stream_check()`: Checks the status of the stream state.
- `ogg_stream_clear()`: Clears and frees the stream state.
- `ogg_stream_reset()`: Resets the stream state.
- `ogg_stream_reset_serialno()`: Resets the stream state and its serial number.
- `ogg_stream_destroy()`: Destroys the stream state.

### Page Information Functions
- `ogg_page_version()`: Returns the Ogg page version.
- `ogg_page_continued()`: Checks if the Ogg page is continued from a previous page.
- `ogg_page_packets()`: Returns the number of packets in the Ogg page.
- `ogg_page_bos()`: Checks if the Ogg page is the beginning of a stream (BOS).
- `ogg_page_eos()`: Checks if the Ogg page is the end of a stream (EOS).
- `ogg_page_granulepos()`: Returns the granule position of the Ogg page.
- `ogg_page_serialno()`: Returns the serial number of the Ogg page.
- `ogg_page_pageno()`: Returns the page number within the stream.
- `ogg_page_checksum_set()`: Sets the checksum for the Ogg page.
```

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

### oggpack_writecopy function declaration

Source: https://xiph.org/ogg/doc/libogg/oggpack_writecopy.html

This function copies bits from a source buffer into an oggpack_buffer. The buffer must be initialized with oggpack_writeinit before use.

```c
void  oggpack_writecopy(oggpack_buffer *b, void *source, long bits);
```

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

### oggpack_look1

Source: https://xiph.org/ogg/doc/libogg/oggpack_look1.html

Examines the next bit in the buffer without moving the pointer.

```APIDOC
## oggpack_look1

### Description
This function looks at the next bit without advancing the location pointer. The next bit is read starting from the location pointer.

### Parameters
- **b** (oggpack_buffer*) - Required - Pointer to an oggpack_buffer struct containing our buffer.

### Return Values
- **n** (long) - Represents the value of the next bit after the location pointer.
```

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

### Ogg Packet Segmentation with 255-byte Packet

Source: https://xiph.org/ogg/doc/framing.html

Shows the lacing values for a raw packet that is exactly 255 bytes. A lacing value of 255 followed by 0 indicates a full 255-byte segment and the end of the packet.

```text
`
raw packet:
  _______________________________
 |________packet data____________|          255 bytes

lacing values: 255, 0
`
```

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

### int ogg_stream_packetout(ogg_stream_state *os, ogg_packet *op)

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_packetout.html

Assembles a data packet for output to the codec decoding engine from the provided stream state.

```APIDOC
## int ogg_stream_packetout(ogg_stream_state *os, ogg_packet *op)

### Description
This function assembles a data packet for output to the codec decoding engine. The data has already been submitted to the ogg_stream_state and broken into segments. Each successive call returns the next complete packet built from those segments.

### Parameters
- **os** (ogg_stream_state*) - Required - Pointer to a previously declared ogg_stream_state struct. Before this function is called, an ogg_page should be submitted to the stream using ogg_stream_pagein().
- **op** (ogg_packet*) - Required - Pointer to the packet to be filled in with pointers to the new data. The pointers are only valid until the next call on this stream state.

### Return Values
- **-1** - Out of sync and there is a gap in the data. Recoverable error; op has not been updated.
- **0** - Insufficient data available to complete a packet, or an unrecoverable internal error occurred. op has not been updated.
- **1** - A packet was assembled normally. op contains the next packet from the stream.
```

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

### int ogg_stream_check(ogg_stream_state *os)

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_check.html

Checks the error or readiness condition of an ogg_stream_state structure.

```APIDOC
## int ogg_stream_check(ogg_stream_state *os)

### Description
This function is used to check the error or readiness condition of an ogg_stream_state structure. It is safe practice to ignore unrecoverable errors returned by ogg stream synchronization calls and handle error detection via a single call to ogg_stream_check at the end of the operational block.

### Parameters
#### Path Parameters
- **os** (ogg_stream_state*) - Required - Pointer to a previously declared ogg_stream_state struct.

### Response
#### Success Response (0)
- **int** - Returned if the ogg_stream_state structure is initialized and ready.

#### Error Response (nonzero)
- **int** - Returned if the structure was never initialized, or if an unrecoverable internal error occurred in a previous call.
```

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

### ogg_stream_flush_fill Function

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_flush_fill.html

This function flushes available packets into pages, similar to ogg_stream_flush(), but allows applications to explicitly request a specific page spill size. It checks for remaining packets inside the stream and forces them into pages of approximately the requested size. This should be used when you want to flush all remaining data from a stream. It can be called in a loop until all packets are flushed, as a single packet may span multiple pages.

```APIDOC
## ogg_stream_flush_fill

### Description
This function flushes available packets into pages, similar to ogg_stream_flush(), but allows applications to explicitly request a specific page spill size. It checks for remaining packets inside the stream and forces them into pages of approximately the requested size. This should be used when you want to flush all remaining data from a stream. It can be called in a loop until all packets are flushed, as a single packet may span multiple pages.

### Method
int

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
- **os** (ogg_stream_state *) - Required - Pointer to a previously declared ogg_stream_state struct, which represents the current logical bitstream.
- **og** (ogg_page *) - Required - Pointer to a page of data. The remaining packets in the stream will be placed into this page, if any remain.
- **fillbytes** (int) - Required - Packet data watermark in bytes.

### Return Values
#### Success Response (0)
- **0** - Means that all packet data has already been flushed into pages, and there are no packets to put into the page. 0 is also returned in the case of an ogg_stream_state that has been cleared explicitly or implicitly due to an internal error.

#### Success Response (Nonzero)
- **Nonzero** - Means that remaining packets have successfully been flushed into the page.

### Request Example
```c
int result = ogg_stream_flush_fill(os, og, fillbytes);
```

### Response Example
```c
// Return value indicates success or if all data is flushed
```
```

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

### ogg_sync_buffer Function

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_buffer.html

Provides a properly-sized buffer for writing. The buffer space which has already been returned is cleared, and the buffer is extended as necessary by the size plus some additional bytes. The buffer exposed by this function is empty internal storage from the ogg_sync_state struct, beginning at the fill mark within the struct. A pointer to this buffer is returned to be used by the calling application.

```APIDOC
## ogg_sync_buffer

### Description
This function is used to provide a properly-sized buffer for writing. Buffer space which has already been returned is cleared, and the buffer is extended as necessary by the size plus some additional bytes. Within the current implementation, an extra 4096 bytes are allocated, but applications should not rely on this additional buffer space. The buffer exposed by this function is empty internal storage from the ogg_sync_state struct, beginning at the fill mark within the struct. A pointer to this buffer is returned to be used by the calling application.

### Method
C Function

### Endpoint
ogg/ogg.h

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **oy** (*ogg_sync_state &#02a;&#02a;*) - Pointer to a previously declared ogg_sync_state struct.
- **size** (*long*) - Size of the desired buffer. The actual size of the buffer returned will be this size plus some extra bytes (currently 4096).

### Request Example
None

### Response
#### Success Response (200)
- **char &#02a;** - A pointer to the newly allocated buffer.

#### Response Example
```
char *ogg_sync_buffer(ogg_sync_state *oy, long size);
```

### Return Values
- Returns a pointer to the newly allocated buffer or NULL on error.
```

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

### Ogg Utility Functions

Source: https://xiph.org/ogg/doc/libogg/general.html

Utility functions for packet clearing and page checksumming.

```APIDOC
## Ogg Utility Functions

### Description
General utility functions for Ogg packet and page operations.

### Functions
- **ogg_packet_clear**: Clears the ogg_packet structure.
- **ogg_page_checksum_set**: Checksums an ogg_page.
```

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

### ogg_sync_wrote function declaration

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_wrote.html

The function signature for updating the sync state buffer pointer.

```c
int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
```

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

### Ogg Stream Management Functions

Source: https://xiph.org/ogg/doc/libogg/general.html

Functions for initializing, resetting, and destroying Ogg bitstream structures.

```APIDOC
## Ogg Stream Management Functions

### Description
Functions to manage the lifecycle and state of an Ogg bitstream.

### Functions
- **ogg_stream_init**: Initializes an Ogg bitstream.
- **ogg_stream_clear**: Clears the storage within the Ogg stream, but does not free the stream itself.
- **ogg_stream_reset**: Resets the stream status to its initial position.
- **ogg_stream_destroy**: Frees the entire Ogg stream.
- **ogg_stream_check**: Check for asynchronous errors.
- **ogg_stream_eos**: Indicates whether we are at the end of the stream.
```

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

### Check Ogg Stream State - C

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_check.html

Use this function to check the error or readiness condition of an ogg_stream_state structure. It's recommended to call this after a block of stream operations to detect unrecoverable errors.

```c
int ogg_stream_check(ogg_stream_state *os);
```

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

### Define ogg_iovec_t structure

Source: https://xiph.org/ogg/doc/libogg/ogg_iovec_t.html

The structure definition as declared in ogg/ogg.h.

```c
typedef struct {
  void *iov_base;
  size_t iov_len;
} ogg_iovec_t;
```

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

### ogg_sync_check

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_check.html

Checks the error or readiness condition of an ogg_sync_state structure.

```APIDOC
## ogg_sync_check

### Description
This function is used to check the error or readiness condition of an ogg_sync_state structure. It is safe practice to ignore unrecoverable errors returned by ogg stream synchronization calls and handle error detection via a single call to ogg_sync_check at the end of the operational block.

### Parameters
- **oy** (ogg_sync_state*) - Required - Pointer to a previously declared ogg_sync_state struct.

### Return Values
- **0** (int) - Returned if the ogg_sync_state structure is initialized and ready.
- **nonzero** (int) - Returned if the structure was never initialized, or if an unrecoverable internal error occurred.
```

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

### Retrieve Ogg page granular position

Source: https://xiph.org/ogg/doc/libogg/ogg_page_granulepos.html

Returns the 64-bit granular position from an ogg_page structure. Use this to track PCM sample numbers or frame numbers during playback or seeking.

```c
ogg_int64_t ogg_page_granulepos(ogg_page *og);
```

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

### oggpack_adv1 Function Declaration

Source: https://xiph.org/ogg/doc/libogg/oggpack_adv1.html

The function signature for advancing the bit pointer in an oggpack_buffer.

```c
void  oggpack_adv1(oggpack_buffer *b);
```

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

### Define oggpack_buffer structure

Source: https://xiph.org/ogg/doc/libogg/oggpack_buffer.html

The internal structure used for bitpacking operations in libogg.

```c
typedef struct {
  long endbyte;
  int  endbit;

  unsigned char *buffer;
  unsigned char *ptr;
  long storage;
} oggpack_buffer;
```

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

### ogg_stream_pageout

Source: https://xiph.org/ogg/doc/libogg/encoding.html

Outputs a completed page if the stream contains enough packets to form a full page.

```APIDOC
## ogg_stream_pageout

### Description
Outputs a completed page if the stream contains enough packets to form a full page.

### Method
Function Call

### Parameters
- **os** (ogg_stream_state*) - Required - Pointer to the stream state.
- **og** (ogg_page*) - Required - Pointer to the page structure to be filled.
```

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

### oggpack_bytes

Source: https://xiph.org/ogg/doc/libogg/oggpack_bytes.html

Returns the total number of complete bytes in an oggpack_buffer.

```APIDOC
## oggpack_bytes

### Description
This function returns the total number of bytes behind the current access point in the oggpack_buffer. For write-initialized buffers, this is the number of complete bytes written so far. For read-initialized buffers, it is the number of complete bytes that have been read so far.

### Parameters
- **b** (oggpack_buffer*) - Required - The oggpack_buffer struct to be checked.

### Return Values
- **long** - The total number of complete bytes within the current buffer (excluding extra bits < 8).
```

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

### Retrieve Ogg page number

Source: https://xiph.org/ogg/doc/libogg/ogg_page_pageno.html

Use this function to obtain the sequential page number from an ogg_page pointer.

```c
long ogg_page_pageno(ogg_page *og);
```

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

### oggpack_read1

Source: https://xiph.org/ogg/doc/libogg/oggpack_read1.html

Reads one bit from the oggpack_buffer data buffer and advances the location pointer.

```APIDOC
## oggpack_read1

### Description
Reads one bit from the oggpack_buffer data buffer and advances the location pointer. The buffer must be initialized using oggpack_readinit before calling this function.

### Function Signature
long oggpack_read1(oggpack_buffer *b);

### Parameters
- **b** (oggpack_buffer*) - Required - Pointer to an oggpack_buffer struct containing buffered data to be read.

### Return Values
- **n** (long) - The bit read by this function.
```

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

### ogg_sync_pageout Function Declaration

Source: https://xiph.org/ogg/doc/libogg/ogg_sync_pageout.html

The function signature for ogg_sync_pageout as defined in ogg/ogg.h.

```c
**
int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
**
```

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

### int ogg_page_packets(ogg_page *og)

Source: https://xiph.org/ogg/doc/libogg/ogg_page_packets.html

Returns the number of packets that are completed on the specified Ogg page.

```APIDOC
## int ogg_page_packets(ogg_page *og)

### Description
Returns the number of packets that are completed on this page. If the leading packet is begun on a previous page, but ends on this page, it is counted.

### Parameters
- **og** (ogg_page*) - Required - Pointer to the current ogg_page struct.

### Return Values
- Returns the count of completed packets on the page.
- If a page consists of a packet begun on a previous page and a new packet begun (but not completed) on this page, it returns 1.
- If a page is a single packet begun on a previous page and spans to the next page, it returns 0.
```

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

### oggpack_read

Source: https://xiph.org/ogg/doc/libogg/oggpack_read.html

Reads a requested number of bits from an oggpack_buffer and advances the internal pointer.

```APIDOC
## oggpack_read

### Description
This function reads the requested number of bits from the buffer and advances the location pointer. Before reading, the buffer should be initialized using oggpack_readinit.

### Parameters
- **b** (oggpack_buffer*) - Required - Pointer to an oggpack_buffer struct containing buffered data to be read.
- **bits** (int) - Required - Number of bits to read.

### Return Values
- **n** (long) - The requested bits read from the buffer.
```

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

### Reset ogg_stream_state structure

Source: https://xiph.org/ogg/doc/libogg/ogg_stream_reset.html

Resets the provided ogg_stream_state structure to its initial state. Returns 0 on success or a nonzero value if an internal error occurs.

```c
int ogg_stream_reset(ogg_stream_state *os);
```

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

### Truncate oggpack_buffer

Source: https://xiph.org/ogg/doc/libogg/oggpack_writealign.html

Truncates the specified oggpack_buffer. The buffer must be initialized for writing before calling this function.

```c
void  oggpack_writetrunc(oggpack_buffer *b);
```
Tokens:
Raw