Ogg

https://github.com/xiph/ogg
Admin
The Ogg project provides the Ogg bitstream format for arranging compressed media bitstreams,...
Tokens:50,821
Snippets:127
Trust Score:7.7
License:BSD-3-Clause
Update:1 year ago
Show doc for...
Tokens:
Raw
### Build libogg with Autotools

Source: https://github.com/xiph/ogg/blob/main/README.md

Standard build process for libogg using autotools from a tarball distribution. Installs libraries, headers, and API documentation.

```bash
./configure
make
make install
```

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

### Cross-compile libogg for Windows from Linux

Source: https://github.com/xiph/ogg/blob/main/README.md

Instructions for cross-compiling libogg for Windows from a Linux environment using MinGW. Includes installing cross-compiler tools and running tests under Wine.

```bash
sudo apt-get install mingw32 mingw32-binutils mingw32-runtime wine
./configure --host=i586-mingw32msvc --target=i586-mingw32msvc --build=i586-linux
make
make check
```

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

### Ogg Media Type Examples

Source: https://github.com/xiph/ogg/blob/main/doc/rfc5334.txt

Illustrates the usage of Ogg media types with the 'codecs' parameter, demonstrating how to specify encapsulated audio, video, and other data formats.

```APIDOC
application/ogg; codecs="theora, cmml, ecmascript"
video/ogg; codecs="theora, vorbis"
audio/ogg; codecs=speex
```

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

### Ogg Granule Position Encoding Examples

Source: https://github.com/xiph/ogg/blob/main/doc/ogg-multiplex.html

Illustrates different ways the Granule Position can be encoded by codecs, including timestamps, frame counts, and sample counts.

```APIDOC
Granule Position Encoding Examples:

1.  **Timestamp Encoding**: A simple approach where Granule Position directly encodes a timestamp, e.g., milliseconds from the beginning of the stream. This allows for very long stream durations before wrapping.
    *   Example: `granule_position = milliseconds_from_start`

2.  **Framestamp Encoding**: Suitable for audio encodings where frames have a fixed number of samples. Granule Position represents the count of frames since the beginning of the stream.
    *   Time Calculation: `time = granule_position * samples_per_frame / samples_per_second`

3.  **Samplestamp Encoding (Vorbis)**: Used when frames have a variable number of samples, like in Vorbis. Granule Position counts the number of raw samples from the beginning of the stream.
    *   Time Calculation: `time = granule_position / samples_per_second`
```

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

### libogg CMake Build Configuration

Source: https://github.com/xiph/ogg/blob/main/CMakeLists.txt

This snippet outlines the CMake build configuration for libogg. It sets the minimum CMake version, extracts the project version from configure.ac, defines build options such as shared libraries and framework bundles, and configures installation paths for documentation and package manager files. It also includes a helper function to configure pkg-config files.

```cmake
cmake_minimum_required(VERSION 3.10)

# Extract project version from configure.ac
file(READ configure.ac CONFIGURE_AC_CONTENTS)
string(REGEX MATCH "AC_INIT\(\[libogg\],\[([0-9]*\.[0-9]*\.[0-9]*)\]" DUMMY ${CONFIGURE_AC_CONTENTS})

project(ogg VERSION ${CMAKE_MATCH_1} LANGUAGES C)

# Required modules
include(GNUInstallDirs)
include(CheckIncludeFiles)
include(CMakePackageConfigHelpers)

# Build options
option(BUILD_SHARED_LIBS "Build shared library" OFF)
if(APPLE)
    option(BUILD_FRAMEWORK "Build Framework bundle for OSX" OFF)
endif()

# Install options
option(INSTALL_DOCS "Install documentation" ON)
option(INSTALL_PKG_CONFIG_MODULE "Install ogg.pc file" ON)
option(INSTALL_CMAKE_PACKAGE_MODULE "Install CMake package configuration module" ON)

# Extract library version from configure.ac
string(REGEX MATCH "LIB_CURRENT=([0-9]*)" DUMMY ${CONFIGURE_AC_CONTENTS})
set(LIB_CURRENT ${CMAKE_MATCH_1})

string(REGEX MATCH "LIB_AGE=([0-9]*)" DUMMY ${CONFIGURE_AC_CONTENTS})
set(LIB_AGE ${CMAKE_MATCH_1})

string(REGEX MATCH "LIB_REVISION=([0-9]*)" DUMMY ${CONFIGURE_AC_CONTENTS})
set(LIB_REVISION ${CMAKE_MATCH_1})

math(EXPR LIB_SOVERSION "${LIB_CURRENT} - ${LIB_AGE}")
set(LIB_VERSION "${LIB_SOVERSION}.${LIB_AGE}.${LIB_REVISION}")


# Helper function to configure pkg-config files
function(configure_pkg_config_file pkg_config_file_in)
    set(prefix ${CMAKE_INSTALL_PREFIX})
    set(exec_prefix ${CMAKE_INSTALL_FULL_BINDIR})
    set(libdir ${CMAKE_INSTALL_FULL_LIBDIR})
    set(includedir ${CMAKE_INSTALL_FULL_INCLUDEDIR})
    set(VERSION ${PROJECT_VERSION})
    string(REPLACE ".in" "" pkg_config_file ${pkg_config_file_in})
    configure_file(${pkg_config_file_in} ${pkg_config_file} @ONLY)
endfunction()

message(STATUS "Configuring ${PROJECT_NAME} ${PROJECT_VERSION}")

```

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

### Ogg Library CMake Configuration

Source: https://github.com/xiph/ogg/blob/main/CMakeLists.txt

Configures the Ogg library using CMake, including checking for necessary header files, defining source and header files, setting library properties, and managing installation. It also handles framework builds for macOS and package configuration for pkg-config and CMake.

```cmake
check_include_files(inttypes.h INCLUDE_INTTYPES_H)
check_include_files(stdint.h INCLUDE_STDINT_H)
check_include_files(sys/types.h INCLUDE_SYS_TYPES_H)

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
set(SIZE16 int16_t)
set(USIZE16 uint16_t)
set(SIZE32 int32_t)
set(USIZE32 uint32_t)
set(SIZE64 int64_t)
set(USIZE64 uint64_t)

include(CheckSizes)

configure_file(include/ogg/config_types.h.in include/ogg/config_types.h @ONLY)

set(OGG_HEADERS
    ${CMAKE_CURRENT_BINARY_DIR}/include/ogg/config_types.h
    include/ogg/ogg.h
    include/ogg/os_types.h
)

set(OGG_SOURCES
    src/bitwise.c
    src/framing.c
    src/crctable.h
)

if(WIN32 AND BUILD_SHARED_LIBS)
    list(APPEND OGG_SOURCES win32/ogg.def)
endif()

if(BUILD_FRAMEWORK)
    set(BUILD_SHARED_LIBS TRUE)
endif()

add_library(ogg ${OGG_HEADERS} ${OGG_SOURCES})
add_library(Ogg::ogg ALIAS ogg)
target_include_directories(ogg PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)

set_target_properties(
    ogg PROPERTIES
    SOVERSION ${LIB_SOVERSION}
    VERSION ${LIB_VERSION}
    PUBLIC_HEADER "${OGG_HEADERS}"
)

if(BUILD_FRAMEWORK)
    set_target_properties(ogg PROPERTIES
        FRAMEWORK TRUE
        FRAMEWORK_VERSION ${PROJECT_VERSION}
        MACOSX_FRAMEWORK_IDENTIFIER org.xiph.ogg
        MACOSX_FRAMEWORK_SHORT_VERSION_STRING ${PROJECT_VERSION}
        MACOSX_FRAMEWORK_BUNDLE_VERSION ${PROJECT_VERSION}
        XCODE_ATTRIBUTE_INSTALL_PATH "@rpath"
        OUTPUT_NAME Ogg
    )
endif()

configure_pkg_config_file(ogg.pc.in)

install(TARGETS ogg
    EXPORT OggTargets
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    FRAMEWORK DESTINATION ${CMAKE_INSTALL_PREFIX}
    PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/ogg
)

export(EXPORT OggTargets NAMESPACE Ogg:: FILE OggTargets.cmake)

if(INSTALL_CMAKE_PACKAGE_MODULE)
    set(CMAKE_INSTALL_CONFIGDIR ${CMAKE_INSTALL_LIBDIR}/cmake/Ogg)
    install(EXPORT OggTargets
        DESTINATION ${CMAKE_INSTALL_CONFIGDIR}
        NAMESPACE Ogg::
    )

    include(CMakePackageConfigHelpers)

    configure_package_config_file(${PROJECT_SOURCE_DIR}/cmake/OggConfig.cmake.in ${PROJECT_BINARY_DIR}/OggConfig.cmake
        INSTALL_DESTINATION ${CMAKE_INSTALL_CONFIGDIR}
        PATH_VARS CMAKE_INSTALL_FULL_INCLUDEDIR
    )

    write_basic_package_version_file(${PROJECT_BINARY_DIR}/OggConfigVersion.cmake
        VERSION ${PROJECT_VERSION}
        COMPATIBILITY SameMajorVersion
    )

    install(FILES ${PROJECT_BINARY_DIR}/OggConfig.cmake ${PROJECT_BINARY_DIR}/OggConfigVersion.cmake
        DESTINATION ${CMAKE_INSTALL_CONFIGDIR}
    )
endif()

if(INSTALL_PKG_CONFIG_MODULE)
    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/ogg.pc
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
    )
endif()

if(INSTALL_DOCS)
    set(OGG_DOCS
        doc/framing.html
        doc/index.html
        doc/oggstream.html
        doc/ogg-multiplex.html
        doc/fish_xiph_org.png
        doc/multiplex1.png
        doc/packets.png
        doc/pages.png
        doc/stream.png
        doc/vorbisword2.png
        doc/white-ogg.png
        doc/white-xifish.png
        doc/rfc3533.txt
        doc/rfc5334.txt
        doc/skeleton.html
    )
    install(FILES ${OGG_DOCS} DESTINATION ${CMAKE_INSTALL_DOCDIR}/html)
    install(DIRECTORY doc/libogg DESTINATION ${CMAKE_INSTALL_DOCDIR}/html PATTERN "*.am" EXCLUDE)
endif()

if(BUILD_TESTING)
    add_executable(test_bitwise src/bitwise.c ${OGG_HEADERS})
    target_compile_definitions(test_bitwise PRIVATE _V_SELFTEST)
    target_include_directories(test_bitwise PRIVATE
        include
        ${CMAKE_CURRENT_BINARY_DIR}/include
    )
    add_test(NAME test_bitwise COMMAND $<TARGET_FILE:test_bitwise>)

    add_executable(test_framing src/framing.c ${OGG_HEADERS})
    target_compile_definitions(test_framing PRIVATE _V_SELFTEST)
    target_include_directories(test_framing PRIVATE
        include
        ${CMAKE_CURRENT_BINARY_DIR}/include
    )
    add_test(NAME test_framing COMMAND $<TARGET_FILE:test_framing>)
endif()

set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
include(CPack)
```

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

### libogg Bitpacking Initialization Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/bitpacking.html

Initializes and prepares buffers for bitpacking operations. Includes functions for both writing and reading data using the bitpacking library.

```c
oggpack_writeinit(oggpack_buffer *b);
oggpack_readinit(oggpack_buffer *b, const unsigned char *buf, intbeiten);

```

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

### Build libogg from Repository with Autotools

Source: https://github.com/xiph/ogg/blob/main/README.md

Build process for libogg from repository source using autotools. Includes autogen.sh for generating configuration scripts.

```bash
./autogen.sh
./configure
make
make install
```

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

### oggpack_look1 Function - libogg

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/oggpack_look1.html

The oggpack_look1 function inspects the next bit in an oggpack_buffer without advancing the location pointer. It reads the bit starting from the current location pointer.

```APIDOC
oggpack_look1
  declared in "ogg/ogg.h"
  Parameters:
    b: Pointer to an oggpack_buffer struct containing our buffer.
  Return Values:
    n: represents the value of the next bit after the location pointer.
```

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

### Get Ogg Page Number (C)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_page_pageno.html

The ogg_page_pageno function returns the sequential page number of an ogg_page. This is useful for ordering pages or detecting lost pages.

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

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

### Test libogg on Windows with MSBuild

Source: https://github.com/xiph/ogg/blob/main/README.md

Instructions for running automated tests for libogg when built with MSBuild on Windows, specifying the build configuration (Debug or Release).

```bash
ctest -C Debug
ctest -C Release
```

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

### Test libogg on Unix-like Systems or MinGW

Source: https://github.com/xiph/ogg/blob/main/README.md

Instructions for running automated tests for libogg, depending on the build system used (Autotools or CMake).

```bash
make check
make test
ctest
```

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

### Get Ogg Page Serial Number (C)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_page_serialno.html

The ogg_page_serialno function retrieves the unique serial number associated with the logical bitstream of a given Ogg page. This serial number is consistent across all pages belonging to the same logical bitstream.

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

/*
 * og: Pointer to the current ogg_page struct.
 * Returns: The serial number for this page.
 */
```

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

### Initialize Ogg Bitpacking Buffer (oggpack_writeinit)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/oggpack_writeinit.html

Initializes an oggpack_buffer for writing using Ogg bitpacking functions. The function takes a pointer to an oggpack_buffer as input. No values are returned upon successful initialization; failure is indicated by subsequent calls to oggpack_writecheck().

```APIDOC
oggpack_writeinit
  declared in "ogg/ogg.h";

  void oggpack_writeinit(oggpack_buffer *b);

  Parameters:
    b: Buffer to be used for writing. This is an ordinary data buffer with some extra markers to ease bit navigation and manipulation.

  Return Values:
    No values are returned. If initialization fail, the buffer is unusable and calls to oggpack_writecheck() will report the error.
```

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

### Build libogg with CMake

Source: https://github.com/xiph/ogg/blob/main/README.md

Build libogg using CMake, a meta build system. Generates native projects for different platforms. Supports building static or shared libraries.

```bash
mkdir build
cd build
cmake -G YOUR-PROJECT-GENERATOR ..
cmake -G YOUR-PROJECT-GENERATOR -DBUILD_SHARED_LIBS=1 ..
cmake -G "Visual Studio 12 2013" ..
cmake -G Xcode -DBUILD_FRAMEWORK=1 ..
cmake ..
make
```

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

### Initialize Ogg Bitpacking Buffer (libogg)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/oggpack_readinit.html

The oggpack_readinit function initializes an oggpack_buffer for reading data using Ogg bitpacking. It takes a pointer to the buffer structure, the data buffer, and its size as input. This function is declared in 'ogg/ogg.h'.

```APIDOC
oggpack_readinit

_declared in "ogg/ogg.h";_

This function takes an ordinary buffer and prepares an [oggpack_buffer](oggpack_buffer.html) for reading using the Ogg [bitpacking](bitpacking.html) functions.

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

### Parameters

_b_

Pointer to [oggpack_buffer](oggpack_buffer.html") to be initialized with some extra markers to ease bit navigation and manipulation.

_buf_

Original data buffer, to be inserted into the [oggpack_buffer](oggpack_buffer.html) so that it can be read using bitpacking functions.

### Return Values

> *   No values are returned.
```

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

### Ogg Programming with libogg

Source: https://github.com/xiph/ogg/blob/main/doc/index.html

Documentation for programming with the libogg library, which provides the core functionality for working with Ogg bitstreams. This section likely covers API usage, data structures, and common programming tasks.

```English
Programming with ogg (libogg/index.html)
```

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

### Initialize Ogg Sync State (libogg)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_sync_init.html

Initializes an ogg_sync_state struct for Ogg bitstream synchronization. This is essential for managing data retrieval and return during decoding.

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

/* Parameters:
 * oy: Pointer to a previously declared ogg_sync_state struct. After this function call, this struct has been initialized.
 * Return Values:
 * 0 is always returned.
 */
```

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

### libogg Bitpacking Write Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/bitpacking.html

Handles writing data to a buffer using the bitpacking library. Includes functions for checking write status and writing raw bytes.

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

```

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

### libogg Decoding Sequence

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/decoding.html

Explains the logical steps for decoding data using the libogg synchronization layer. It involves exposing a buffer, reading data, updating the sync state, and processing pages and packets.

```APIDOC
Decoding Process:
1. Expose a buffer using ogg_sync_buffer().
2. Read data into the buffer (e.g., using fread()).
3. Call ogg_sync_wrote() to indicate bytes written.
4. Output data using ogg_sync_pageout().
5. Submit the page to the stream layer with ogg_stream_pagein().
6. Output a packet to the decoder using ogg_stream_packetout().
```

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

### Ogg Bitstream Documentation

Source: https://github.com/xiph/ogg/blob/main/doc/index.html

Detailed documentation on the Ogg bitstream format, including an overview of its structure, framing mechanisms, and how to handle multi-stream multiplexing. It also covers the Ogg Skeleton Metadata Bitstream for metadata management.

```English
Ogg bitstream overview (oggstream.html)
Ogg bitstream framing (framing.html)
Ogg multi-stream multiplexing (ogg-multiplex.html)
The Ogg Skeleton Metadata Bitstream (skeleton.html)
```

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

### libogg oggpack_writealign Function

Source: https://github.com/xiph/ogg/blob/main/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

_declared in "ogg/ogg.h";_

This function pads the [oggpack_buffer](oggpack_buffer.html) with zeros out to the next byte boundary.

The oggpack_buffer must already be initialized for writing using [oggpack_writeinit](oggpack_writeinit.html).

Only 32 bits can be written at a time.

**void oggpack_writetrunc(oggpack_buffer *b);**

### Parameters

_b_
  Buffer to be used for writing.

### Return Values

> *   No values are returned.
```

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

### libogg Data Structures Overview

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/datastructures.html

Provides an overview of the fundamental data structures used within the libogg library for handling Ogg bitstream data. These structures are declared in the 'ogg/ogg.h' header file.

```documentation
ogg_page: Encapsulates data into one ogg bitstream page.
ogg_stream_state: Contains current encode/decode data for a logical bitstream.
ogg_packet: Encapsulates the data and metadata for a single Ogg packet.
ogg_sync_state: Contains bitstream synchronization information.
```

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

### Libogg General Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/reference.html

General utility functions for managing Ogg streams, pages, and packets, including initialization, clearing, and information retrieval.

```APIDOC
General Functions:
  ogg_stream_init(): Initializes an Ogg stream state.
  ogg_stream_check(): Checks the state of an Ogg stream structure.
  ogg_stream_clear(): Clears and frees an Ogg stream structure.
  ogg_stream_reset(): Resets an Ogg stream state.
  ogg_stream_reset_serialno(): Resets an Ogg stream state and sets the serial number.
  ogg_stream_destroy(): Destroys an Ogg stream structure.
  ogg_page_version(): Returns the version of an Ogg page.
  ogg_page_continued(): Checks if an Ogg page is a continuation of a previous page.
  ogg_page_packets(): Returns the number of packets in an Ogg page.
  ogg_page_bos(): Checks if an Ogg page is the beginning of a stream (BOS).
  ogg_page_eos(): Checks if an Ogg page is the end of a stream (EOS).
  ogg_page_granulepos(): Returns the granule position of an Ogg page.
  ogg_page_serialno(): Returns the serial number of an Ogg page.
  ogg_page_pageno(): Returns the page number of an Ogg page.
  ogg_packet_clear(): Clears and frees an Ogg packet structure.
  ogg_page_checksum_set(): Sets the checksum for an Ogg page.
```

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

### libogg Bitpacking Read Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/bitpacking.html

Handles reading data from a buffer using the bitpacking library. Includes functions for looking at bits without advancing the pointer and reading bits.

```c
oggpack_look(oggpack_buffer *b, int bits);
oggpack_look1(oggpack_buffer *b);
oggpack_adv(oggpack_buffer *b, int bits);
oggpack_adv1(oggpack_buffer *b);
oggpack_read(oggpack_buffer *b, int bits);
oggpack_read1(oggpack_buffer *b);

```

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

### Libogg Bitpacking Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/reference.html

Provides functions for bit-level packing and unpacking of data within the libogg library.

```APIDOC
Bitpacking Functions:
  oggpack_writeinit(): Initializes a bitpacker buffer.
  oggpack_writecheck(): Checks the state of a bitpacker buffer.
  oggpack_reset(): Resets a bitpacker buffer.
  oggpack_writetrunc(): Truncates a bitpacker buffer.
  oggpack_writealign(): Aligns a bitpacker buffer to a byte boundary.
  oggpack_writecopy(): Copies data into a bitpacker buffer.
  oggpack_writeclear(): Clears and frees a bitpacker buffer.
  oggpack_readinit(): Initializes a bitstream reader.
  oggpack_write(): Writes data to a bitpacker buffer.
  oggpack_look(): Looks at bits in a bitstream reader without advancing.
  oggpack_look1(): Looks at a single bit in a bitstream reader without advancing.
  oggpack_adv(): Advances the bitstream reader by a specified number of bits.
  oggpack_adv1(): Advances the bitstream reader by one bit.
  oggpack_read(): Reads a specified number of bits from a bitstream reader.
  oggpack_read1(): Reads a single bit from a bitstream reader.
  oggpack_bytes(): Returns the number of bytes currently in the bitpacker buffer.
  oggpack_bits(): Returns the number of bits currently in the bitpacker buffer.
  oggpack_get_buffer(): Gets the internal buffer of the bitpacker.
```

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

### libogg Bitpacking Buffer Management Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/bitpacking.html

Provides functions for managing the bitpacking buffer, including resetting the position, clearing the buffer, and retrieving buffer details.

```c
oggpack_reset(oggpack_buffer *b);
oggpack_writeclear(oggpack_buffer *b);
oggpack_bytes(oggpack_buffer *b);
oggpack_bits(oggpack_buffer *b);
oggpack_get_buffer(oggpack_buffer *b);

```

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

### Ogg Bitstream Structure Overview

Source: https://github.com/xiph/ogg/blob/main/doc/framing.html

Explains the fundamental structure of an Ogg bitstream, which divides incoming packets into segments and wraps them into pages with headers for framing, integrity checks, and seeking.

```APIDOC
Ogg Bitstream Structure:
  - Composed of pages, each preceded by a page header.
  - Incoming packets are divided into segments of up to 255 bytes.
  - A group of contiguous packet segments forms a page.
  - Page header contains sizing information and checksum data.
  - Capture pattern is used to identify the beginning of a page.
  - Checksum verifies page sync and data integrity.
```

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

### libogg Synchronization Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/decoding.html

Provides a list of libogg synchronization functions, their purposes, and their roles in managing the Ogg bitstream during decoding.

```APIDOC
ogg_sync_init(ogg_sync_state *oy)
  Initializes an Ogg bitstream.

ogg_sync_clear(ogg_sync_state *oy)
  Clears the status information from the synchronization struct.

ogg_sync_reset(ogg_sync_state *oy)
  Resets the synchronization status to initial values.

ogg_sync_destroy(ogg_sync_state *oy)
  Frees the synchronization struct.

ogg_sync_check(ogg_sync_state *oy)
  Check for asynchronous errors.

ogg_sync_buffer(ogg_sync_state *oy)
  Exposes a buffer from the synchronization layer in order to read data.

ogg_sync_wrote(ogg_sync_state *oy, int m)
  Tells the synchronization layer how many bytes were written into the buffer.

ogg_sync_pageseek(ogg_sync_state *oy, ogg_page *og)
  Finds the borders of pages and resynchronizes the stream.

ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og)
  Outputs a page from the synchronization layer.

ogg_stream_pagein(ogg_stream_state *os, ogg_page *og)
  Submits a complete page to the stream layer.

ogg_stream_packetout(ogg_stream_state *os, ogg_packet *op)
  Outputs a packet to the codec-specific decoding engine.

ogg_stream_packetpeek(ogg_stream_state *os, ogg_packet *op)
  Provides access to the next packet in the bitstream without advancing decoding.
```

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

### libogg ogg_packet Struct Members Explained

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_packet.html

Provides detailed explanations for each member of the ogg_packet structure. This includes the purpose and data type of packet data pointer, byte size, beginning/end of stream flags, granule position, and packet sequence number.

```APIDOC
ogg_packet:
  packet: Pointer to the packet's data. Treated as opaque by the ogg layer.
  bytes: Size of the packet data in bytes. Packets can be of arbitrary size.
  b_o_s: Flag indicating if this packet begins a logical bitstream (1 for first packet, 0 otherwise).
  e_o_s: Flag indicating if this packet ends a bitstream (1 for last packet, 0 otherwise).
  granulepos: Position of this packet in the decoded data, representing the last completely decodable unit.
  packetno: Sequential number of this packet within the ogg bitstream.
```

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

### Initialize Ogg Stream State (C)

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_stream_init.html

Initializes an ogg_stream_state struct, allocating memory for encoding or decoding and assigning a serial number. Returns 0 on success and -1 on failure.

```APIDOC
ogg_stream_init
=================

_declared in "ogg/ogg.h";

This function is used to initialize an [ogg_stream_state](ogg_stream_state.html) struct and allocates appropriate memory in preparation for encoding or decoding.

It also assigns the stream a given serial number.

**int ogg_stream_init([ogg_stream_state](ogg_stream_state.html) *os,int serialno);

### Parameters

_os_

Pointer to the ogg_stream_state struct that we will be initializing.

_serialno_

Serial number that we will attach to this stream.

### Return Values

> *   0 if successful
> *   -1 if unsuccessful.
```

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

### libogg API Documentation

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/ogg_page_pageno.html

API documentation for libogg functions, specifically detailing the ogg_page_pageno function.

```APIDOC
ogg_page_pageno
=========

_declared in "ogg/ogg.h";_

Returns the sequential page number.

This is useful for ordering pages or determining when pages have been lost.

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

### Parameters

_og_

Pointer to the current ogg_page struct.

### Return Values

> *   _n_ is the page number for this page.
```

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

### libogg oggpack_read1 Function

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/oggpack_read1.html

Reads one bit from the oggpack_buffer data buffer and advances the location pointer. The buffer must be initialized using oggpack_readinit before reading.

```APIDOC
oggpack_read1(oggpack_buffer *b)
  Parameters:
    b: Pointer to an oggpack_buffer struct containing buffered data to be read.
  Returns:
    n: The bit read by this function.
```

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

### oggpack_writecheck Function - libogg

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/oggpack_writecheck.html

Checks the readiness status of an oggpack_buffer initialized for writing. Returns zero if ready, non-zero if not ready or an error occurred. Safe to call on buffers that have already encountered errors.

```APIDOC
oggpack_writecheck(oggpack_buffer *b)
  Parameters:
    b: An oggpack_buffer previously initialized for writing.
  Return Values:
    zero: buffer is ready for writing
    nonzero: buffer is not ready or encountered an error
```

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

### Ogg Interoperability

Source: https://github.com/xiph/ogg/blob/main/doc/rfc5334.txt

Highlights the device-, platform-, and vendor-neutral nature of the Ogg container format, emphasizing its implementability across platforms. Mentions the availability of a portable reference implementation and the Xiph.Org Foundation's role in specification and testing.

```APIDOC
Interoperability:
  Device-, platform-, and vendor-neutral format.
  Widely implementable across computing platforms.
  Portable reference implementation [libogg] available under BSD license.
  Xiph.Org Foundation defines specification, interoperability, and conformance.
  Regular interoperability testing is conducted.
  Ogg Skeleton extension confirmed not to cause interoperability issues with existing implementations.
```

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

### Ogg Bitstream Design Constraints

Source: https://github.com/xiph/ogg/blob/main/doc/framing.html

Outlines the key design principles for Ogg bitstreams, emphasizing efficiency, streaming capabilities, and data management features.

```APIDOC
Ogg Bitstream Design Constraints:
  1. True streaming: Complete bitstream can be built without seeking.
  2. Bandwidth efficiency: Minimal bandwidth usage for framing and seeking (approx. 1-2%).
  3. Absolute position specification: Indicates position within the original sample stream.
  4. Simple editing: Facilitates mechanisms like concatenation.
  5. Data integrity and access: Corruption detection, error recapture, and random access to data.
```

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

### Ogg Logical vs. Physical Bitstreams

Source: https://github.com/xiph/ogg/blob/main/doc/framing.html

Differentiates between logical and physical Ogg bitstreams, explaining their relationship and composition.

```APIDOC
Ogg Bitstream Types:
  - Logical Bitstream: A contiguous stream of pages belonging to a single logical stream.
  - Physical Bitstream: Constructed from one or more logical Ogg bitstreams. The simplest physical bitstream contains a single logical bitstream.
```

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

### libogg Encoding Functions

Source: https://github.com/xiph/ogg/blob/main/doc/libogg/encoding.html

This section details the core functions used in the libogg encoding process. These functions manage the submission of raw packets into an Ogg bitstream and the generation of Ogg pages.

```c
ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op)
  Submits a raw packet to the streaming layer, so that it can be formed into a page.

ogg_stream_iovecin(ogg_stream_state *os, struct iovec *iov, int count, int eof)
  iovec version of ogg_stream_packetin() above.

ogg_stream_pageout(ogg_stream_state *os, ogg_page *og)
  Outputs a completed page if the stream contains enough packets to form a full page.

ogg_stream_pageout_fill(ogg_stream_state *os, ogg_page *og, int threshold)
  Similar to ogg_stream_pageout(), but specifies a page spill threshold in bytes.

ogg_stream_flush(ogg_stream_state *os, ogg_page *og)
  Forces any remaining packets in the stream to be returned as a page of any size.

ogg_stream_flush_fill(ogg_stream_state *os, ogg_page *og, int threshold)
  Similar to ogg_stream_flush(), but specifies a page spill threshold in bytes.
```
Tokens:
Raw