ww2ogg

https://docs.rs/ww2ogg/latest/
Admin
ww2ogg converts Wwise RIFF/RIFX Vorbis audio files (.wem) to standard Ogg Vorbis format by...
Tokens:64,373
Snippets:476
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Usage of WwiseRiffVorbisBuilder

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbisBuilder.html

Demonstrates how to create and configure a WwiseRiffVorbis converter using the builder pattern. This example shows setting inline codebooks and full setup options.

```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(false)
    .full_setup(false)
    .build()?;
```

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

### Setting Full Setup Option

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.ConversionOptions.html

Configures whether the setup packet contains full Vorbis setup data.

```rust
pub fn with_full_setup(self, value: bool) -> Self
```

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

### Handling Full Setup Mode Data

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Copies remaining bits from the setup reader to the Ogg stream when in full setup mode, as no explicit mode data needs parsing.

```rust
while setup_reader.total_bits_read() < setup_packet.size as u64 * 8 {
    ogg.write_bits(setup_reader.read_bits(1)?, 1)?;
}
(Vec::new(), 0)

```

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

### WwiseRiffVorbisBuilder::full_setup

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Sets whether the setup packet includes the full Vorbis setup information. This is an option for the builder pattern.

```APIDOC
## WwiseRiffVorbisBuilder::full_setup

### Description
Configures the converter to indicate whether the setup packet contains the complete Vorbis setup information. This is part of the builder pattern for advanced configuration.

### Method
Builder method

### Parameters
- **value**: `bool` - `true` if the full setup is present, `false` otherwise.

### Returns
- `Self` - The builder instance, allowing for method chaining.
```

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

### Example Usage of ConversionOptions

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.ConversionOptions.html

Demonstrates how to create and configure ConversionOptions using builder methods.

```rust
use ww2ogg::{ConversionOptions, ForcePacketFormat};

let options = ConversionOptions::default()
    .with_inline_codebooks(true)
    .with_force_packet_format(ForcePacketFormat::ForceModPackets);
```

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

### Copying Vorbis Codebooks in Full Setup

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Copies Vorbis codebooks directly from the setup reader to the Ogg stream when the full setup is available.

```rust
self.codebooks.copy(&mut setup_reader, ogg)?

```

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

### Read and Copy Vorbis Setup Packet

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Reads a Vorbis setup packet, validates its type and granule, and copies its contents, including codebooks, to the Ogg stream. This function is crucial for reconstructing the Vorbis stream header.

```rust
let setup_packet = Packet8::read(&mut self.input, offset, self.little_endian)?;

        if setup_packet.granule != 0 {
            return Err(WemError::parse("setup packet granule != 0"));
        }

        self.input.seek(SeekFrom::Start(setup_packet.offset))?;
        let mut setup_reader = BitReader::new(&mut self.input);

        let ptype = setup_reader.read_bits(8)?;

        if ptype != 5 {
            return Err(WemError::parse("wrong type for setup packet"));
        }

        ogg.write_bits(ptype, 8)?;

        // 'vorbis'
        for _ in 0..6 {
            let c = setup_reader.read_bits(8)?;
            ogg.write_bits(c, 8)?;
        }

        // Codebook count
        let codebook_count_less1 = setup_reader.read_bits(8)?;
        let codebook_count = codebook_count_less1 + 1;
        ogg.write_bits(codebook_count_less1, 8)?;

        // Use empty codebook library for copying
        let cbl = CodebookLibrary::empty();

        for _ in 0..codebook_count {
            cbl.copy(&mut setup_reader, ogg)?;
        }

        while setup_reader.total_bits_read() < setup_packet.size as u64 * 8 {
            ogg.write_bits(setup_reader.read_bits(1)?, 1)?;
        }

        ogg.flush_page(false, false)?;

        if setup_packet.next_offset != data.offset + self.first_audio_packet_offset as u64 {
            return Err(WemError::parse(
                "first audio packet doesn't follow setup packet",
            ));
        }

        Ok(())
    }
```

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

### Quick Start: Convert .wem to .ogg

Source: https://docs.rs/ww2ogg/latest/ww2ogg/index.html

Basic usage for converting a .wem file to an .ogg file using default codebooks. Ensure input.wem exists and output.ogg can be created.

```rust
use std::fs::File;
use std::io::{BufReader, BufWriter};
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

fn main() -> Result<(), ww2ogg::WemError> {
    // Open input .wem file
    let input = BufReader::new(File::open("input.wem")?);

    // Load the default codebooks
    let codebooks = CodebookLibrary::default_codebooks()?;

    // Create converter and parse the input
    let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

    // Convert to Ogg Vorbis
    let mut output = BufWriter::new(File::create("output.ogg")?);
    converter.generate_ogg(&mut output)?;

    Ok(())
}
```

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

### Generating Ogg Vorbis to a File

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbis.html

Demonstrates writing the converted Ogg Vorbis audio data to a file using `generate_ogg`. This example uses `BufWriter` for efficient file writing.

```rust
use std::fs::File;
use std::io::{BufReader, BufWriter};
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

let input = BufReader::new(File::open("input.wem")?);
let codebooks = CodebookLibrary::default_codebooks()?;
let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

// Write to a file
let output = BufWriter::new(File::create("output.ogg"));
converter.generate_ogg(output)?;
```

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

### Advanced Configuration with Builder Pattern

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/lib.rs.html

Illustrates using the builder pattern for advanced configuration of the WwiseRiffVorbis converter. This allows fine-tuning options like inlining codebooks, full setup, and forcing packet formats.

```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, ForcePacketFormat};

# fn main() -> Result<(), ww2ogg::WemError> {
let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let mut converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(false)
    .full_setup(false)
    .force_packet_format(ForcePacketFormat::NoForce)
    .build()?;
# Ok(())
# }
```

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

### Getting Metadata with `and_then`

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Shows how to chain fallible operations like getting file metadata, using `and_then` to handle potential errors.

```Rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Quick Start: Convert .wem to .ogg

Source: https://docs.rs/ww2ogg/latest/index.html

Use this snippet for a basic conversion of a .wem file to an .ogg file. It loads default codebooks and generates the Ogg Vorbis output.

```rust
use std::fs::File;
use std::io::{BufReader, BufWriter};
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

fn main() -> Result<(), ww2ogg::WemError> {
    // Open input .wem file
    let input = BufReader::new(File::open("input.wem")?);

    // Load the default codebook library
    let codebooks = CodebookLibrary::default_codebooks()?;

    // Create converter and parse the input
    let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

    // Convert to Ogg Vorbis
    let mut output = BufWriter::new(File::create("output.ogg")?);
    converter.generate_ogg(&mut output)?;

    Ok(())
}
```

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

### Advanced WwiseRiffVorbis Conversion with Builder

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Illustrates advanced conversion using the WwiseRiffVorbis builder pattern to customize options like embedded codebooks, full setup, and packet format. Suitable for files requiring special handling.

```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, ForcePacketFormat};

# fn main() -> Result<(), ww2ogg::WemError> {
let input = File::open("special.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let mut converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(true)   // Codebooks embedded in file
    .full_setup(true)         // Full Vorbis setup present
    .force_packet_format(ForcePacketFormat::ForceModPackets)
    .build()?;

let mut output = File::create("output.ogg")?;
converter.generate_ogg(&mut output)?;
# Ok(())
# }
```

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

### Get Default Codebooks

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Retrieves the standard Vorbis codebooks. Use this for most Wwise audio files. If issues arise, consider using aoTuV codebooks.

```rust
pub fn default_codebooks() -> WemResult<Self>
```

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

### Basic unwrap on Result

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Demonstrates the basic usage of `unwrap()` to get the value from an `Ok` variant. Panics if the Result is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### Get Codebook Count

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Returns the total number of codebooks present in the library.

```rust
pub fn codebook_count(&self) -> usize
```

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

### Advanced Configuration with Builder Pattern

Source: https://docs.rs/ww2ogg/latest/index.html

Utilize the builder pattern for advanced configuration options when creating a WwiseRiffVorbis converter. This allows customization of codebook inlining, setup, and packet format forcing.

```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, ForcePacketFormat};

let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let mut converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(false)
    .full_setup(false)
    .force_packet_format(ForcePacketFormat::NoForce)
    .build()?;
```

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

### Checking if Result is Ok

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Provides examples of using the `is_ok()` method to check if a `Result` contains an `Ok` value.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### Getting a Reference to the Ok value

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Illustrates using `as_ref()` to obtain a `Result<&T, &E>` from a `&Result<T, E>`. This allows inspecting the contained values without consuming the original Result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### Generate Ogg Vorbis Stream from Wwise Data

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Converts parsed Wwise audio data into a standard Ogg Vorbis stream, including identification, comment, setup, and audio packets. Requires an output writer and a codebook library.

```Rust
/// Generates a standard Ogg Vorbis stream from the parsed Wwise audio data.
///
/// This method performs the actual conversion, writing a complete Ogg Vorbis
/// stream to the provided output. The output includes:
///
/// 1. **Identification header** - Vorbis version, channels, sample rate, etc.
/// 2. **Comment header** - Vendor string identifying this converter
/// 3. **Setup header** - Codebooks, floor/residue/mapping configuration
/// 4. **Audio packets** - Converted audio data with proper granule positions
///
/// # Arguments
///
/// * `output` - Any type implementing [`Write`], such as a file or buffer
///
/// # Errors
///
/// Returns an error if:
/// - The audio data is corrupted or truncated
/// - A referenced codebook ID is not found in the library
/// - The codebook data doesn't match (wrong codebook library)
///
/// # Example
///
/// ```no_run
/// use std::fs::File;
/// use std::io::{BufReader, BufWriter};
/// use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};
///
/// # fn main() -> Result<(), ww2ogg::WemError> {
/// let input = BufReader::new(File::open("input.wem")?);
/// let codebooks = CodebookLibrary::default_codebooks()?;
/// let mut converter = WwiseRiffVorbis::new(input, codebooks)?;
///
/// // Write to a file
/// let output = BufWriter::new(File::create("output.ogg")?);
/// converter.generate_ogg(output)?;
/// # Ok(())
/// # }
/// ```
///
/// You can also write to a `Vec<u8>` for in-memory processing:
///
/// ```no_run
/// use std::io::Cursor;
/// use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};
///
/// # fn convert(wem_data: &[u8]) -> Result<Vec<u8>, ww2ogg::WemError> {
/// let input = Cursor::new(wem_data);
/// let codebooks = CodebookLibrary::default_codebooks()?;
/// let mut converter = WwiseRiffVorbis::new(input, codebooks)?;
///
/// let mut ogg_data = Vec::new();
/// // converter.generate_ogg(&mut ogg_data)?;
/// // return Ok(ogg_data);
/// # Ok(Vec::new()) // Placeholder for compilation
/// # }
/// ```
```

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

### Load Custom Codebooks from File

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Demonstrates how to load a custom codebook library from a binary file. Ensure the file path is correct.

```rust
use ww2ogg::CodebookLibrary;

let codebooks = CodebookLibrary::from_file("packed_codebooks_custom.bin")?;
```

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

### Getting a Mutable Reference to Result values

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Shows how to use `as_mut()` to get a `Result<&mut T, &mut E>` from a `&mut Result<T, E>`. This enables in-place modification of the contained values.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Loading Custom Codebooks from File

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/codebook.rs.html

Shows how to load a custom codebook library from a binary file. This is useful for games that use non-standard codebook formats.

```rust
use ww2ogg::CodebookLibrary;

let codebooks = CodebookLibrary::from_file("packed_codebooks_custom.bin")?;
# Ok::<(), ww2ogg::WemError>(())
```

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

### Configure Wwise to Ogg conversion options

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Shows how to create and customize ConversionOptions for the WwiseRiffVorbis converter. Use this to control inline codebooks and packet format detection.

```rust
use ww2ogg::{ConversionOptions, ForcePacketFormat};

let options = ConversionOptions::default()
    .with_inline_codebooks(true)
    .with_force_packet_format(ForcePacketFormat::ForceModPackets);

```

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

### Checking if Result is Err

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Provides examples of using the `is_err()` method to check if a `Result` contains an `Err` value.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### Creating Default Conversion Options

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.ConversionOptions.html

Initializes ConversionOptions with default settings.

```rust
pub fn new() -> Self
```

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

### Codebook Library Loading

Source: https://docs.rs/ww2ogg/latest/ww2ogg

Shows how to load different codebook libraries for Wwise audio conversion.

```APIDOC
## `CodebookLibrary::default_codebooks` and `CodebookLibrary::aotuv_codebooks`

### Description
Loads the necessary Vorbis codebook data required for converting Wwise audio files. Two libraries are available: the standard one and the aoTuV 6.03 variant.

### Method
- `CodebookLibrary::default_codebooks()`
- `CodebookLibrary::aotuv_codebooks()`

### Parameters
None

### Request Example
```rust
use ww2ogg::CodebookLibrary;

// Try the default codebooks first
let codebooks = CodebookLibrary::default_codebooks()?;

// If audio is garbled, try the aoTuV codebooks
// let codebooks = CodebookLibrary::aotuv_codebooks()?;
```

### Response
- Returns a `CodebookLibrary` instance upon success.
- Returns `WemError` if the codebooks cannot be loaded.
```

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

### CodebookLibrary::copy

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Copies a codebook directly from an input stream to an output stream. Useful for inline or full setup scenarios.

```APIDOC
## `copy<B: BitRead, W: Write>(&self, input: &mut B, output: &mut BitOggStream<W>)`

### Description
Copy a codebook directly from input to output (for inline/full setup).

### Method
`pub fn copy<B: BitRead, W: Write>( &self, input: &mut B, output: &mut BitOggStream<W>, ) -> WemResult<()>`
```

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

### Basic WwiseRiffVorbis Conversion

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbis.html

Demonstrates the basic usage of WwiseRiffVorbis for converting a .wem file to .ogg. Requires opening input and output files and loading default codebooks.

```rust
use std::fs::File;
use std::io::BufReader;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

// Basic usage with default options
let input = BufReader::new(File::open("input.wem")?);
let codebooks = CodebookLibrary::default_codebooks()?;
let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

let mut output = File::create("output.ogg")?;
converter.generate_ogg(&mut output)?;
```

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

### Get Codebook Size by Index

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Retrieves the size of a specific codebook using its index. Returns -1 if the index is invalid.

```rust
pub fn get_codebook_size(&self, index: usize) -> i32
```

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

### WwiseRiffVorbis::new

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Creates a new WwiseRiffVorbis converter with default options. This is the basic way to initialize the converter.

```APIDOC
## WwiseRiffVorbis::new

### Description
Initializes a new WwiseRiffVorbis converter with default settings. This is suitable for most common conversion tasks.

### Method
Associated function (constructor-like)

### Parameters
- **input**: `R` - A readable and seekable source of the Wwise audio data (e.g., `BufReader<File>`).
- **codebooks**: `CodebookLibrary` - The library of Vorbis codebooks to use for conversion.

### Returns
- `WemResult<WwiseRiffVorbis<R>>` - A Result containing the initialized converter or a `WemError` if initialization fails.
```

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

### WwiseRiffVorbis::with_options

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Creates a new WwiseRiffVorbis converter with explicit control over all available options. This method is less ergonomic than using the builder pattern.

```APIDOC
## WwiseRiffVorbis::with_options

### Description
Creates a new WwiseRiffVorbis converter with all available options explicitly set. While functional, using `builder()` is recommended for a more user-friendly API.

### Method
`pub fn with_options(mut input: R, codebooks: CodebookLibrary, inline_codebooks: bool, full_setup: bool, force_packet_format: ForcePacketFormat) -> WemResult<Self>`

### Parameters
* `input`: The input stream implementing `Read` and `Seek`.
* `codebooks`: The `CodebookLibrary` to use for decoding.
* `inline_codebooks`: A boolean indicating whether to inline codebooks.
* `full_setup`: A boolean indicating whether to use a full setup.
* `force_packet_format`: Specifies the `ForcePacketFormat` to use.

### Returns
A `WemResult` containing the initialized `WwiseRiffVorbis` converter or a `WemError` if parsing fails.
```

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

### Rebuilding Vorbis Codebooks from Reader

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Rebuilds Vorbis codebooks from a reader and writes them to an Ogg stream. This is used when the full setup is not available.

```rust
self.codebooks.rebuild_from_reader(&mut setup_reader, ogg)?

```

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

### Get Codebook Data by Index

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/codebook.rs.html

Retrieves the raw data for a specific codebook using its index. Performs bounds checking and validates offsets.

```Rust
fn get_codebook(&self, index: usize) -> WemResult<&[u8]> {
        if self.codebook_offsets.is_empty() {
            return Err(WemError::parse("codebook library not loaded"));
        }

        if index >= self.codebook_count() {
            return Err(WemError::invalid_codebook_id(index as i32));
        }

        let start = self.codebook_offsets[index] as usize;
        let end = self.codebook_offsets[index + 1] as usize;

        if end > self.codebook_data.len() || start > end {
            return Err(WemError::parse("invalid codebook offset"));
        }

        Ok(&self.codebook_data[start..end])
    }
```

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

### WwiseRiffVorbis::with_options

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbis.html

Creates a new WwiseRiffVorbis converter with all options specified.

```APIDOC
## WwiseRiffVorbis::with_options

### Description
Creates a new WwiseRiffVorbis converter with all options. Consider using `builder()` for a more ergonomic API.

### Method
`with_options(input: R, codebooks: CodebookLibrary, inline_codebooks: bool, full_setup: bool, force_packet_format: ForcePacketFormat) -> WemResult<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, ForcePacketFormat};

let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let mut converter = WwiseRiffVorbis::with_options(
    input,
    codebooks,
    true, // inline_codebooks
    true, // full_setup
    ForcePacketFormat::ForceModPackets
)?;
```

### Response
#### Success Response (200)
`WwiseRiffVorbis<R>` - A new converter instance with specified options.

#### Response Example
None provided.
```

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

### Get aoTuV Codebooks

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Retrieves the aoTuV 6.03 tuned Vorbis codebooks. Use this if the default codebooks result in errors or garbled audio.

```rust
pub fn aotuv_codebooks() -> WemResult<Self>
```

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

### Copy Codebook Directly

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Copies a codebook directly from an input bit reader to an output bit stream. Useful for inline or full setup scenarios.

```rust
pub fn copy<B: BitRead, W: Write>(
    &self,
    input: &mut B,
    output: &mut BitOggStream<W>,
) -> WemResult<()>
```

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

### Codebook Data Access

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/codebook.rs.html

Methods for accessing individual codebook data, including retrieving raw data, getting size, and rebuilding or copying codebooks.

```APIDOC
## `CodebookLibrary::get_codebook_size`

### Description
Gets the size of a codebook by index.

### Arguments
* `index` - The index of the codebook to query.

### Returns
- `i32` - The size of the codebook in bytes, or -1 if the index is invalid.

## `CodebookLibrary::rebuild`

### Description
Rebuilds a codebook from the library by index and writes it to the provided output stream.

### Arguments
* `index` - The index of the codebook to rebuild.
* `output` - A mutable reference to a `BitOggStream` to write the rebuilt codebook to.

### Returns
- `WemResult<()>` - Ok if successful, or an error if the codebook cannot be rebuilt.

## `CodebookLibrary::copy`

### Description
Copies a codebook directly from an input bit reader to an output stream. This is typically used for inline or full setup scenarios.

### Arguments
* `input` - A mutable reference to a `BitRead` implementing type, representing the source of the codebook data.
* `output` - A mutable reference to a `BitOggStream` to write the copied codebook data to.

### Returns
- `WemResult<()>` - Ok if the copy operation is successful, or an error if an invalid identifier is encountered or other issues arise during copying.

## `CodebookLibrary::rebuild_from_reader`

### Description
Rebuilds a codebook from a stripped format using a bit reader. This is used for inline codebooks that are not part of a library.

### Arguments
* `input` - A mutable reference to a `BitRead` implementing type, representing the source of the stripped codebook data.
* `output` - A mutable reference to a `BitOggStream` to write the rebuilt codebook to.

### Returns
- `WemResult<()>` - Ok if the rebuild is successful, or an error if the format is invalid or other issues occur.
```

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

### Loading Codebook Libraries in Rust

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/codebook.rs.html

Demonstrates how to load different codebook libraries. Try default codebooks first, then aoTuV, or load from a custom file if needed.

```rust
use ww2ogg::CodebookLibrary;

// Try default codebooks first
let codebooks = CodebookLibrary::default_codebooks()?;

// If that doesn't work, try aoTuV
let codebooks = CodebookLibrary::aotuv_codebooks()?;

// Or load from a custom file
let codebooks = CodebookLibrary::from_file("custom_codebooks.bin")?;
# Ok::<(), ww2ogg::WemError>(())
```

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

### WwiseRiffVorbis Builder Pattern

Source: https://docs.rs/ww2ogg/latest/ww2ogg

Illustrates how to use the builder pattern for advanced configuration of the `WwiseRiffVorbis` converter.

```APIDOC
## `WwiseRiffVorbis::builder`

### Description
Provides a fluent builder interface for creating `WwiseRiffVorbis` converters with custom conversion options.

### Method
`WwiseRiffVorbis::builder(input, codebooks)` followed by configuration methods and `.build()`

### Parameters
#### Input
- `input`: A readable stream containing the .wem file data.
- `codebooks`: A `CodebookLibrary` instance.

#### Builder Options
- `.inline_codebooks(bool)`: Whether to inline codebooks (default: `true`).
- `.full_setup(bool)`: Whether to use full setup headers (default: `true`).
- `.force_packet_format(ForcePacketFormat)`: Specifies how to handle Wwise modified Vorbis packet format. Options include `NoForce`, `Vorbis`, `Ogg`.

### Request Example
```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, ForcePacketFormat};

let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let mut converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(false)
    .full_setup(false)
    .force_packet_format(ForcePacketFormat::NoForce)
    .build()?;
```

### Response
#### Success Response
- Returns a configured `WwiseRiffVorbis` converter instance.

#### Error Handling
- Returns `WemError` if the builder fails to construct the converter.
```

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

### Deprecated Error Description Method

Source: https://docs.rs/ww2ogg/latest/ww2ogg/enum.WemError.html

Provides a deprecated method for getting a string description of the error. It is recommended to use the `Display` implementation or `to_string()` instead.

```rust
fn description(&self) -> &str
```

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

### Deprecated Error Cause Method

Source: https://docs.rs/ww2ogg/latest/ww2ogg/enum.WemError.html

Provides a deprecated method for getting the underlying cause of the error. The `Error::source` method is the modern replacement and supports downcasting.

```rust
fn cause(&self) -> Option<&dyn Error>
```

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

### WwiseRiffVorbisBuilder Methods

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbisBuilder.html

This section details the methods available on the WwiseRiffVorbisBuilder for configuring and building a WwiseRiffVorbis converter.

```APIDOC
## WwiseRiffVorbisBuilder

Builder for creating `WwiseRiffVorbis` converters with custom options. This provides a fluent API for configuring the converter.

### `new(input: R, codebooks: CodebookLibrary) -> Self`

Create a new builder with the given input and codebook library.

### `inline_codebooks(self, value: bool) -> Self`

Set whether codebooks are inline in the data.

### `full_setup(self, value: bool) -> Self`

Set whether the setup packet contains full Vorbis setup.

### `force_packet_format(self, format: ForcePacketFormat) -> Self`

Set the packet format detection mode.

### `options(self, options: ConversionOptions) -> Self`

Set all options from a ConversionOptions struct.

### `build(self) -> WemResult<WwiseRiffVorbis<R>>`

Build the converter, parsing the input stream.
```

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

### WwiseRiffVorbis::new

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Creates a new WwiseRiffVorbis converter with default options. For more control over the conversion process, consider using the `builder()` method.

```APIDOC
## WwiseRiffVorbis::new

### Description
Creates a new WwiseRiffVorbis converter and parses the input stream using default options.

### Method
`pub fn new(input: R, codebooks: CodebookLibrary) -> WemResult<Self>`

### Parameters
* `input`: The input stream implementing `Read` and `Seek`.
* `codebooks`: The `CodebookLibrary` to use for decoding.

### Returns
A `WemResult` containing the initialized `WwiseRiffVorbis` converter or a `WemError` if parsing fails.
```

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

### Build WwiseRiffVorbis converter with custom options

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Illustrates using the WwiseRiffVorbisBuilder for a fluent API to configure the converter with specific options before building it. This is useful for advanced customization.

```rust
use std::fs::File;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

let input = File::open("input.wem")?;
let codebooks = CodebookLibrary::aotuv_codebooks()?;

let converter = WwiseRiffVorbis::builder(input, codebooks)
    .inline_codebooks(false)
    .full_setup(false)
    .build()?;
# Ok::<(), ww2ogg::WemError>(())

```

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

### Parse SMPL Chunk

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Parses the 'smpl ' chunk to extract loop information, specifically the loop count, start, and end points. It enforces that exactly one loop is expected.

```Rust
fn parse_smpl_chunk(&mut self) -> WemResult<()> {
    if let Some(smpl) = self.chunks.smpl {
        self.input.seek(SeekFrom::Start(smpl.offset + 0x1C))?;
        self.loop_count = self.read_u32()?;

        if self.loop_count != 1 {
            return Err(WemError::parse("expected one loop"));
        }

        self.input.seek(SeekFrom::Start(smpl.offset + 0x2C))?;
        self.loop_start = self.read_u32()?;
        self.loop_end = self.read_u32()?;
    }
    Ok(())
}
```

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

### WwiseRiffVorbis::new

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.WwiseRiffVorbis.html

Creates a new WwiseRiffVorbis converter and parses the input stream using default options.

```APIDOC
## WwiseRiffVorbis::new

### Description
Creates a new WwiseRiffVorbis converter and parses the input stream. This uses default options. For more control, use `builder()`.

### Method
`new(input: R, codebooks: CodebookLibrary) -> WemResult<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use std::fs::File;
use std::io::BufReader;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

let input = BufReader::new(File::open("input.wem")?);
let codebooks = CodebookLibrary::default_codebooks()?;
let mut converter = WwiseRiffVorbis::new(input, codebooks)?;
```

### Response
#### Success Response (200)
`WwiseRiffVorbis<R>` - A new converter instance.

#### Response Example
None provided.
```

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

### Convert Wwise Audio with Auto-Detected Codebooks

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/validator.rs.html

Shows a common pattern for converting Wwise audio by first trying default codebooks and falling back to aoTuV codebooks if the initial validation fails. This helps handle different audio compression schemes.

```rust
use std::io::Cursor;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, validate};

fn convert_with_auto_detect(wem_data: &[u8]) -> Result<Vec<u8>, ww2ogg::WemError> {
    // Try default codebooks first
    let input = Cursor::new(wem_data);
    let codebooks = CodebookLibrary::default_codebooks()?;
    let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

    let mut ogg_data = Vec::new();
    converter.generate_ogg(&mut ogg_data)?;

    if validate(&ogg_data).is_ok() {
        return Ok(ogg_data);
    }

    // Fall back to aoTuV codebooks
    let input = Cursor::new(wem_data);
    let codebooks = CodebookLibrary::aotuv_codebooks()?;
    let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

    let mut ogg_data = Vec::new();
    converter.generate_ogg(&mut ogg_data)?;
    validate(&ogg_data)?;

    Ok(ogg_data)
}
```

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

### into_ok

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Returns the contained Ok value, but never panics. This is an unstable, nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. This method consumes the `self` argument. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur. This is a nightly-only experimental API.

### Method
`into_ok()`

### Parameters
None

### Request Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

### Response
#### Success Response
- **T** (type): The contained Ok value.

#### Response Example
```rust
// If the Result is Ok(value), returns value.
```
```

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

### Convert and Validate Wwise Audio

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/validator.rs.html

Demonstrates how to convert Wwise audio (WEM format) to Ogg Vorbis and then validate the generated Ogg data. This is useful for ensuring the conversion process used the correct codebooks.

```rust
use std::fs::File;
use std::io::{BufReader, Read};
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary, validate};

fn convert_and_validate(wem_path: &str) -> Result<Vec<u8>, ww2ogg::WemError> {
    let input = BufReader::new(File::open(wem_path)?);
    let codebooks = CodebookLibrary::default_codebooks()?;
    let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

    let mut ogg_data = Vec::new();
    converter.generate_ogg(&mut ogg_data)?;

    // Validate the output
    validate(&ogg_data)?;

    Ok(ogg_data)
}
```

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

### Read Packet Header at a Specific Offset

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/packet.rs.html

Reads a 2-byte packet header starting at a specified offset within the data. Asserts the calculated offset, packet size, and next offset.

```rust
    // Put packet header at offset 10
    let mut data = vec![0u8; 16];
    data[10] = 0x80; // size low byte
    data[11] = 0x00; // size high byte = 128

    let mut cursor = Cursor::new(data);
    let packet = Packet::read(&mut cursor, 10, true, true).unwrap();

    assert_eq!(packet.offset, 12); // 10 + 2
    assert_eq!(packet.size, 128);
    assert_eq!(packet.next_offset, 12 + 128);

```

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

### Loading Default Codebooks

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/codebook.rs.html

Retrieves the default packed codebooks library. This is the standard library for most Wwise audio files.

```rust
pub fn default_codebooks() -> WemResult<Self> {
    Self::from_bytes(DEFAULT_CODEBOOKS)
}
```

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

### Read and Copy Vorbis Comment Packet

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Reads a Vorbis comment packet from the input, validates its granule value, and copies its data to the Ogg stream. This is part of the initial setup for Vorbis streams.

```rust
let comment_packet = Packet8::read(&mut self.input, offset, self.little_endian)?;

        if comment_packet.granule != 0 {
            return Err(WemError::parse("comment packet granule != 0"));
        }

        self.input.seek(SeekFrom::Start(comment_packet.offset))?;
        let packet_type = self.read_byte()?;

        if packet_type != 3 {
            return Err(WemError::parse("wrong type for comment packet"));
        }

        ogg.write_bits(packet_type as u32, 8)?;

        for _ in 1..comment_packet.size {
            let b = self.read_byte()?;
            ogg.write_bits(b as u32, 8)?;
        }

        ogg.flush_page(false, false)?;
        offset = comment_packet.next_offset;
```

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

### Validate Audio Loops

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Validates the loop start and end points against the total sample count. Adjusts loop end if it's zero and ensures loop boundaries are within the valid range.

```Rust
fn validate_loops(&mut self) -> WemResult<()> {
        if self.loop_count != 0 {
            if self.loop_end == 0 {
                self.loop_end = self.sample_count;
            } else {
                self.loop_end += 1;
            }

            if self.loop_start >= self.sample_count
                || self.loop_end > self.sample_count
                || self.loop_start > self.loop_end
            {
                return Err(WemError::parse("loops out of range"));
            }
        }
        Ok(())
    }
```

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

### ConversionOptions Struct Definition

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.ConversionOptions.html

Defines the configuration options for Wwise to Ogg conversion.

```rust
pub struct ConversionOptions {
    pub inline_codebooks: bool,
    pub full_setup: bool,
    pub force_packet_format: ForcePacketFormat,
}
```

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

### Initialize BitOggStream

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/bit_ogg_stream.rs.html

Creates a new BitOggStream instance, initializing its internal buffers and state. The writer must implement the `std::io::Write` trait.

```rust
pub fn new(writer: W) -> Self {
        Self {
            writer,
            page_buffer: vec![0u8; HEADER_BYTES + MAX_SEGMENTS + SEGMENT_SIZE * MAX_SEGMENTS],
            bit_buffer: 0,
            bits_stored: 0,
            payload_bytes: 0,
            granule: 0,
            seq_no: 0,
            first: true,
            continued: false,
        }
    }
```

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

### unwrap_or_default for Result

Source: https://docs.rs/ww2ogg/latest/ww2ogg/type.WemResult.html

Illustrates using `unwrap_or_default()` to get the contained value from an `Ok` Result or a default value if it's an `Err`. Useful for parsing user input where invalid data should result in a sensible default.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

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

### WwiseRiffVorbisBuilder::options

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Sets all conversion options from a provided `ConversionOptions` struct. This is an option for the builder pattern.

```APIDOC
## WwiseRiffVorbisBuilder::options

### Description
Sets all conversion options at once by providing a `ConversionOptions` struct. This is part of the builder pattern for advanced configuration.

### Method
Builder method

### Parameters
- **options**: `ConversionOptions` - A struct containing all desired conversion options.

### Returns
- `Self` - The builder instance, allowing for method chaining.
```

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

### Read 8-byte Packet Header at a Specific Offset

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/packet.rs.html

Reads an 8-byte packet header starting at a specified offset, including size and granule. Asserts the calculated offset, packet size, granule, and next offset.

```rust
    // Put packet header at offset 20
    let mut data = vec![0u8; 30];
    data[20] = 0x40; // size bytes (little-endian)
    data[21] = 0x00;
    data[22] = 0x00;
    data[23] = 0x00; // size = 64
    data[24] = 0x00; // granule bytes
    data[25] = 0x10;
    data[26] = 0x00;
    data[27] = 0x00; // granule = 4096

    let mut cursor = Cursor::new(data);
    let packet = Packet8::read(&mut cursor, 20, true).unwrap();

    assert_eq!(packet.offset, 28); // 20 + 8
    assert_eq!(packet.size, 64);
    assert_eq!(packet.granule, 4096);
    assert_eq!(packet.next_offset, 28 + 64);

```

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

### WwiseRiffVorbis::generate_ogg

Source: https://docs.rs/ww2ogg/latest/src/ww2ogg/wwise_riff_vorbis.rs.html

Generates a standard Ogg Vorbis stream from the parsed Wwise audio data. This method handles the creation of the identification, comment, setup, and audio packets, writing the complete Ogg stream to the provided output.

```APIDOC
## WwiseRiffVorbis::generate_ogg

### Description
Generates a standard Ogg Vorbis stream from the parsed Wwise audio data. This method performs the actual conversion, writing a complete Ogg Vorbis stream to the provided output. The output includes:

1. **Identification header** - Vorbis version, channels, sample rate, etc.
2. **Comment header** - Vendor string identifying this converter
3. **Setup header** - Codebooks, floor/residue/mapping configuration
4. **Audio packets** - Converted audio data with proper granule positions

### Arguments

* `output` - Any type implementing [`Write`], such as a file or buffer

### Errors

Returns an error if:
- The audio data is corrupted or truncated
- A referenced codebook ID is not found in the library
- The codebook data doesn't match (wrong codebook library)

### Example

```no_run
use std::fs::File;
use std::io::{BufReader, BufWriter};
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

# fn main() -> Result<(), ww2ogg::WemError> {
let input = BufReader::new(File::open("input.wem")?);
let codebooks = CodebookLibrary::default_codebooks()?;
let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

// Write to a file
let output = BufWriter::new(File::create("output.ogg")?);
converter.generate_ogg(output)?;
# Ok(())
# }
```

You can also write to a `Vec<u8>` for in-memory processing:

```no_run
use std::io::Cursor;
use ww2ogg::{WwiseRiffVorbis, CodebookLibrary};

# fn convert(wem_data: &[u8]) -> Result<Vec<u8>, ww2ogg::WemError> {
let input = Cursor::new(wem_data);
let codebooks = CodebookLibrary::default_codebooks()?;
let mut converter = WwiseRiffVorbis::new(input, codebooks)?;

let mut ogg_data = Vec::new();
// converter.generate_ogg(&mut ogg_data)?;
// Ok(ogg_data)
# Ok(Vec::new())
# }
```
```

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

### Create Empty Codebook Library

Source: https://docs.rs/ww2ogg/latest/ww2ogg/struct.CodebookLibrary.html

Creates an empty codebook library. This is used when the audio file contains its own codebook data (inline codebooks).

```rust
pub fn empty() -> Self
```
Tokens:
Raw