### AfsArchiveBuilder Initialization

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Creates a new `AfsArchiveBuilder` with default settings. Use this to start building an AFS2 archive.

```rust
pub fn new() -> Self {
        Self {
            alignment: 32,
            subkey: 0,
            files: Vec::new(),
        }
    }
```

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

### Create a new UsmBuilder

Source: https://docs.rs/cridecoder/latest/cridecoder/usm/struct.UsmBuilder.html

Initializes a new UsmBuilder instance with the specified filename. This is the starting point for building a USM container.

```rust
pub fn new(filename: impl Into<String>) -> Self
```

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

### Create a new BitReader

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Initializes a new `BitReader` with the provided byte slice. The reading position starts at the beginning of the data.

```Rust
pub fn new(data: &'a [u8]) -> Self {
        Self { data, position: 0 }
    }
```

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

### Build Music Synth Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Initializes the 'Synth' table for music ACB files. This snippet shows the basic setup for the table and the 'Type' column.

```rust
fn build_music_synth_table(&self, config: &MusicAcbConfig) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("Synth");

        table.add_column(ColumnDef::constant("Type", Value::U8(0)));
        table.add_column(ColumnDef::constant(
            "VoiceLimitGroupName",
            Value::String(String::new()),

```

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

### BitReader::new

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Creates a new BitReader starting at the beginning of the data slice.

```APIDOC
## BitReader::new

### Description
Creates a new `BitReader` instance initialized to read from the beginning of the provided data slice.

### Method
`BitReader::new(data: &'a [u8]) -> Self`

### Parameters
* `data` (&'a [u8]): A slice of bytes representing the HCA data to be read.
```

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

### Build Music Track Event Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Initializes the TrackEvent table with a 'Command' column. The loop to populate rows based on music cue count is started but not completed in this snippet.

```rust
let mut table = UtfTableBuilder::new("TrackEvent");
table.add_column(ColumnDef::per_row("Command", COLUMN_TYPE_DATA));

for i in 0..Self::music_cue_count(config) {
    let mut row = HashMap::new();
    row.insert("Command".to_string(),
```

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

### AfsArchiveBuilder file_offsets Method

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Calculates the starting offset for each file within the AFS2 archive, considering header size, alignment, and file data lengths.

```rust
fn file_offsets(&self, header_size: u32, files: &[(u32, Vec<u8>)]) -> Vec<u64> {
        let mut offsets = Vec::with_capacity(files.len() + 1);
        let mut current_offset = header_size as u64;

        for (_, data) in files {
            offsets.push(current_offset);
            current_offset =
                align_to_u64(current_offset, self.alignment as u64) + data.len() as u64;
        }

        offsets.push(current_offset);
        offsets
    }
```

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

### Test BitReader with Offset

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Demonstrates initializing BitReader with an offset, allowing reads to start at a specific bit position within the data. Checks the initial position and peeking at data.

```rust
    #[test]
    fn test_with_offset() {
        let data = [0xAB, 0xCD, 0xEF];
        let reader = BitReader::with_offset(&data, 1);
        assert_eq!(reader.position(), 8);
        assert_eq!(reader.peek(8), 0xCD);
    }
```

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

### AcbBuilder::new()

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AcbBuilder.html

Creates a new instance of AcbBuilder. This is the starting point for building an ACB file.

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

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

### Build USM File

Source: https://docs.rs/cridecoder/latest/src/cridecoder/usm/builder.rs.html

Demonstrates creating a basic USM file with video data and verifying the header.

```rust
let video_data = vec![0u8; 1000];

        let builder = UsmBuilder::new("test_video").video(video_data);

        let mut output = std::io::Cursor::new(Vec::new());
        builder.build(&mut output).unwrap();

        let data = output.into_inner();
        assert_eq!(&data[0..4], b"CRID");
```

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

### Retrieve File Data by Cue ID

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/afs.rs.html

Provides a method to get the data of a specific file within the AFS2 archive using its cue ID. It includes a fallback mechanism for archives where cue IDs start from 0.

```rust
    /// Get file data for a specific cue ID
    pub fn file_data_for_cue_id(&mut self, cue_id: i32) -> Result<Vec<u8>, AfsError> {
        if let Some(&idx) = self.cue_index.get(&cue_id) {
            return self.file_data_at_index(idx);
        }

        // Fallback to first file if cue IDs start at 0
        if !self.files.is_empty() && self.files[0].cue_id == 0 {
            return self.file_data_at_index(0);
        }

        Err(AfsError::CueNotFound(cue_id))
    }

```

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

### Create Output Files

Source: https://docs.rs/cridecoder/latest/src/cridecoder/usm/extractor.rs.html

Creates the necessary output files for video and optionally audio based on the decoded filename and codec information. It returns the file handles and a list of output paths.

```rust
/// Create output files
fn create_output_files(
    target_dir: &Path,
    decoded_filename: &str,
    has_audio: bool,
    export_audio: bool,
    mpeg_codec: Option<u32>,
    audio_codec: Option<u32>,
) -> Result<(File, Option<File>, Vec<PathBuf>), UsmError> {
    let base_name = Path::new(decoded_filename)
        .file_stem()
        .and_then(|s| s.to_str())
        .unwrap_or(decoded_filename);

    let video_path = target_dir.join(format!( ".{}", video_ext(mpeg_codec)));
    let video_file = File::create(&video_path)?;

    let mut output_files = vec![video_path];
    let audio_file = if has_audio && export_audio {
        let audio_path = target_dir.join(format!( ".{}", audio_ext(audio_codec)));
        let file = File::create(&audio_path)?;
        output_files.push(audio_path);
        Some(file)
    } else {
        None
    };

    Ok((video_file, audio_file, output_files))
}
```

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

### Get Stream Position

Source: https://docs.rs/cridecoder/latest/cridecoder/reader/struct.Reader.html

Gets the current stream position of the reader.

```rust
pub fn stream_position(&mut self) -> Result<u64>
```

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

### Build an AFS Archive

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Shows how to construct an AFS archive by adding files with content and then building the archive into an output stream. Includes verification of the archive's header and file data.

```rust
    #[test]
    fn test_afs_builder() {
        let mut builder = AfsArchiveBuilder::new();
        builder.add_file(0, vec![1, 2, 3, 4]);
        builder.add_file(1, vec![5, 6, 7, 8, 9]);

        let mut output = std::io::Cursor::new(Vec::new());
        builder.build(&mut output).unwrap();

        let data = output.into_inner();
        assert_eq!(&data[0..4], b"AFS2");
        assert_eq!(&data[4..8], &[0x01, 0x02, 0x02, 0x00]);
        assert_eq!(&data[12..14], &32u16.to_le_bytes());
        assert_eq!(&data[14..16], &0u16.to_le_bytes());

        let mut archive = crate::acb::afs::AfsArchive::new(std::io::Cursor::new(data)).unwrap();
        assert_eq!(archive.alignment, 32);
        assert_eq!(archive.subkey, 0);
        assert_eq!(
            archive.file_data_for_cue_id(1).unwrap(),
            vec![5, 6, 7, 8, 9]
        );
    }
```

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

### Add ACB GUID to ACB Builder

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Adds the ACB GUID (Globally Unique Identifier) to the ACB builder. This value is cloned from the configuration.

```rust
Self::add_row_value(
            &mut table,
            &mut row,
            "AcbGuid",
            COLUMN_TYPE_DATA,
            Value::Data(config.acb_guid.clone()),
        );
```

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

### BitReader::position

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Gets the current bit position of the reader.

```APIDOC
## BitReader::position

### Description
Returns the current bit position within the data slice that the `BitReader` is tracking.

### Method
`BitReader::position(&self) -> usize`

### Returns
* `usize`: The current bit position.
```

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

### UsmBuilder::new

Source: https://docs.rs/cridecoder/latest/cridecoder/usm/struct.UsmBuilder.html

Initializes a new UsmBuilder instance with a specified filename.

```APIDOC
## UsmBuilder::new

### Description
Initializes a new UsmBuilder instance with a specified filename.

### Signature
`pub fn new(filename: impl Into<String>) -> Self`

### Parameters
* `filename` (impl Into<String>) - The name of the file to be associated with the builder.
```

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

### BitReader::with_offset

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Creates a new BitReader starting at a specified byte offset.

```APIDOC
## BitReader::with_offset

### Description
Creates a new `BitReader` instance, initializing its read position to a specific byte offset within the data slice.

### Method
`BitReader::with_offset(data: &'a [u8], byte_offset: usize) -> Self`

### Parameters
* `data` (&'a [u8]): A slice of bytes representing the HCA data.
* `byte_offset` (usize): The starting byte index for the reader.
```

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

### Build a UTF Table with constant and per-row columns

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Demonstrates creating a UTF table with a constant 'Version' column and a per-row 'Name' column. It adds a row with data and then verifies the table's content after building and parsing.

```rust
    #[test]
    fn test_utf_table_builder() {
        let mut builder = UtfTableBuilder::new("TestTable");
        builder.add_column(ColumnDef::constant("Version", Value::U32(1)));
        builder.add_column(ColumnDef::per_row("Name", COLUMN_TYPE_STRING));

        let mut row = HashMap::new();
        row.insert("Name".to_string(), Value::String("test".to_string()));
        builder.add_row(row);

        let mut output = std::io::Cursor::new(Vec::new());
        builder.build(&mut output).unwrap();

        let data = output.into_inner();
        assert_eq!(&data[0..4], b"@UTF");
        assert_eq!(&data[8..10], &[0, 0]);

        let parsed = crate::acb::utf::UtfTable::new(std::io::Cursor::new(data)).unwrap();
        assert_eq!(parsed.name, "TestTable");
        assert_eq!(
            parsed.rows[0].get("Name").and_then(Value::as_string),
            Some("test")
        );
    }
```

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

### Getting Column Value Size

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Calculates the size in bytes for a given column type.

```rust
impl UtfTableBuilder {
    // ... with_encoding method

    /// Get the size of a column value in bytes
    fn value_size(typ: u8) -> u32 {
        match typ {
            COLUMN_TYPE_1BYTE | COLUMN_TYPE_1BYTE2 => 1,
            COLUMN_TYPE_2BYTE | COLUMN_TYPE_2BYTE2 => 2,
            COLUMN_TYPE_4BYTE | COLUMN_TYPE_4BYTE2 | COLUMN_TYPE_FLOAT | COLUMN_TYPE_STRING => 4,
            COLUMN_TYPE_8BYTE | COLUMN_TYPE_DATA => 8,
            _ => 0,
        }
    }
// ... other methods
```

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

### Build Music Synth Command Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Creates a simple SynthCommand table with a single 'Command' column. It adds one row with a predefined byte vector as the command data.

```rust
let mut table = UtfTableBuilder::new("SynthCommand");
table.add_column(ColumnDef::per_row("Command", COLUMN_TYPE_DATA));

let mut row = HashMap::new();
row.insert("Command".to_string(),
Value::Data(vec![0x00, 0x6f, 0x04, 0x00, 0x03, 0x13, 0x88]),
);
table.add_row(row);

Self::finish_music_nested_table(table)
```

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

### HcaDecoder::reset

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/struct.HcaDecoder.html

Resets the decoder to the beginning of the HCA file, allowing for re-decoding from the start.

```APIDOC
## HcaDecoder::reset

### Description
Resets the decoder to the beginning of the HCA file.

### Method
POST

### Endpoint
`/hca/decoder/{decoder_id}/reset`

### Parameters
#### Path Parameters
- **decoder_id** (string) - Required - Identifier for the HCA decoder instance.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful reset.

#### Response Example
```json
{
  "status": "reset successful"
}
```
```

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

### TrackList::new

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.TrackList.html

Creates a new TrackList instance from a UTF table.

```APIDOC
## pub fn new(utf: &UtfTable) -> Result<Self, TrackError>

### Description
Create a TrackList from a UTF table.

### Parameters
* `utf` (&UtfTable) - A reference to the UtfTable to create the TrackList from.

### Returns
* Result<Self, TrackError> - Ok(TrackList) if successful, Err(TrackError) otherwise.
```

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

### Build Music Cue Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Constructs the 'Cue' table for music ACB files. Use this to define individual music cues with their IDs, references, and other metadata.

```rust
fn build_music_cue_table(
        &self,
        info: HcaTrackInfo,
        config: &MusicAcbConfig,
    ) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("Cue");

        table.add_column(ColumnDef::per_row("CueId", COLUMN_TYPE_4BYTE));
        table.add_column(ColumnDef::constant("ReferenceType", Value::U8(3)));
        table.add_column(ColumnDef::per_row("ReferenceIndex", COLUMN_TYPE_2BYTE));
        table.add_column(ColumnDef::constant(
            "UserData",
            Value::String(String::new()),
        ));
        table.add_column(ColumnDef::constant("Worksize", Value::U16(0)));
        table.add_column(ColumnDef::constant(
            "AisacControlMap",
            Value::Data(Vec::new()),
        ));
        table.add_column(ColumnDef::constant("Length", Value::U32(info.length_ms)));
        table.add_column(ColumnDef::constant("NumAisacControlMaps", Value::U8(0)));
        table.add_column(ColumnDef::constant("HeaderVisibility", Value::U8(1)));
        table.add_column(ColumnDef::constant("NumRelatedWaveforms", Value::U16(1)));

        for i in 0..Self::music_cue_count(config) {
            let mut row = HashMap::new();
            row.insert(
                "CueId".to_string(),
                Value::U32(config.cue_id.saturating_add(i as u32)),
            );
            row.insert("ReferenceIndex".to_string(), Value::U16(i));
            table.add_row(row);
        }

        Self::finish_music_nested_table(table)
    }
```

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

### Build Music Sequence Table - Rust

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Initializes the 'Sequence' table for music data with a constant 'PlaybackRatio' column.

```rust
fn build_music_sequence_table(&self, config: &MusicAcbConfig) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("Sequence");

        table.add_column(ColumnDef::constant("PlaybackRatio", Value::U16(100)));

```

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

### Error::cause Implementation for HcaDecoderError

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/enum.HcaDecoderError.html

Deprecated method for getting the underlying error cause. Replaced by Error::source.

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

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

### BitWriter: Get Data Slice

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Returns a slice of the underlying byte data that has been written to. This allows inspection of the written bytes.

```rust
    pub fn data(&self) -> &[u8] {
        &self.data
    }

```

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

### Configure Music ACB

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Sets up the configuration for a music ACB file. This method takes numerous parameters to define the audio properties and metadata.

```rust
pub fn music_acb(
        mut self,
        cue_id: u32,
        virtual_cue_suffix: Option<String>,
        memory_awb_id: u16,
        reference_num_samples: u32,
        reference_length_ms: u32,
        acb_version: u32,
        acf_md5_hash: Vec<u8>,
        acb_guid: Vec<u8>,
        version_string: String,
        acb_volume: f32,
        category_extension: u8,
        cue_priority_type: u8,
        acf_category_name: String,
        acf_category_id: u32,
        acf_bus_names: Vec<String>,
    ) -> Self {
        self.music_acb_config = Some(MusicAcbConfig {
            cue_id,
            memory_awb_id,
            virtual_cue_suffix,
            reference_num_samples,
            reference_length_ms,
            acb_version,
            acf_md5_hash,
            acb_guid,
            version_string,
            acb_volume,
            category_extension,
            cue_priority_type,
            acf_category_name,
            acf_category_id,
            acf_bus_names,
        });
        self
    }
```

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

### Get Current Bit Position

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Returns the current bit position within the data slice. This is an inline function for performance.

```Rust
#[inline]
    pub fn position(&self) -> usize {
        self.position
    }
```

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

### Build Music Cue Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Constructs the music cue table by adding constant and per-row columns. It iterates to add rows based on the music cue count from the configuration.

```rust
table.add_column(ColumnDef::constant("NumTracks", Value::U16(1)));
table.add_column(ColumnDef::per_row("TrackIndex", COLUMN_TYPE_DATA));
table.add_column(ColumnDef::per_row("CommandIndex", COLUMN_TYPE_2BYTE));
table.add_column(ColumnDef::constant("LocalAisacs", Value::Data(Vec::new())));
table.add_column(ColumnDef::constant("GlobalAisacStartIndex",
Value::U16(0xffff),
));
table.add_column(ColumnDef::constant("GlobalAisacNumRefs", Value::U16(0)));
table.add_column(ColumnDef::constant("ParameterPallet", Value::U16(0xffff)));
table.add_column(ColumnDef::constant("ActionTrackStartIndex",
Value::U16(0xffff),
));
table.add_column(ColumnDef::constant("NumActionTracks", Value::U16(0)));
table.add_column(ColumnDef::constant("TrackValues", Value::Data(Vec::new())));
table.add_column(ColumnDef::constant("Type", Value::U8(0)));
table.add_column(ColumnDef::per_row("ControlWorkArea1", COLUMN_TYPE_2BYTE));
table.add_column(ColumnDef::per_row("ControlWorkArea2", COLUMN_TYPE_2BYTE));
table.add_column(ColumnDef::constant("InstPluginTrackStartIndex",
Value::U16(0xffff),
));
table.add_column(ColumnDef::constant("NumInstPluginTracks", Value::U16(0)));

for i in 0..Self::music_cue_count(config) {
    let mut row = HashMap::new();
    row.insert("TrackIndex".to_string(),
    Value::Data(i.to_be_bytes().to_vec()),
    );
    row.insert("CommandIndex".to_string(), Value::U16(i));
    row.insert("ControlWorkArea1".to_string(), Value::U16(i));
    row.insert("ControlWorkArea2".to_string(), Value::U16(i));
    table.add_row(row);
}

Self::finish_music_nested_table(table)
```

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

### Implement Error for HcaEncoderError

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/enum.HcaEncoderError.html

Provides methods for error handling, including getting the source of the error and a deprecated description method.

```rust
impl Error for HcaEncoderError {
    fn source(&self) -> Option<&(dyn Error + 'static)>
    fn description(&self) -> &str
    fn cause(&self) -> Option<&dyn Error>
    fn provide<'a>(&'a self, request: &mut Request<'a>)
}
```

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

### AcbBuilder::build

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AcbBuilder.html

Builds the ACB file and optionally the AWB file.

```APIDOC
## AcbBuilder::build

### Description
Build the ACB file and optionally AWB file.

### Method
`build<W: Write + Seek>(&self, acb_writer: &mut W, awb_writer: Option<&mut W>) -> Result<(), BuilderError>`

### Parameters
#### Path Parameters
- `acb_writer` (&mut W): A mutable reference to a writer for the ACB file.
- `awb_writer` (Option<&mut W>): An optional mutable reference to a writer for the AWB file.

### Returns
- `Result<(), BuilderError>`: Ok if the build was successful, or a BuilderError if it failed.
```

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

### BitWriter: Initialization

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Creates a new BitWriter with a specified capacity for the underlying byte vector. The writer starts at position 0.

```rust
pub struct BitWriter {
    data: Vec<u8>,
    position: usize,
}

impl BitWriter {
    pub fn new(capacity: usize) -> Self {
        Self {
            data: vec![0; capacity],
            position: 0,
        }
    }

```

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

### UtfTableBuilder::new

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.UtfTableBuilder.html

Creates a new instance of UtfTableBuilder. Initializes the builder with a specified table name.

```rust
pub fn new(table_name: impl Into<String>) -> Self>
```

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

### BitWriter: Get Current Position

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Returns the current bit position within the writer. This indicates how many bits have been written so far.

```rust
    pub fn position(&self) -> usize {
        self.position
    }

```

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

### AcbBuilder::new

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AcbBuilder.html

Creates a new instance of AcbBuilder.

```APIDOC
## AcbBuilder::new

### Description
Creates a new instance of AcbBuilder.

### Method
`new()`

### Returns
- `Self`: A new AcbBuilder instance.
```

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

### Build Music Cue Name Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Constructs the 'CueName' table for music ACB files. Use this to associate names with specific cue indices.

```rust
fn build_music_cue_name_table(
        &self,
        track: &TrackInput,
        config: &MusicAcbConfig,
    ) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("CueName");

        table.add_column(ColumnDef::per_row("CueName", COLUMN_TYPE_STRING));
        table.add_column(ColumnDef::per_row("CueIndex", COLUMN_TYPE_2BYTE));

        for (i, name) in Self::music_cue_names(track, config).into_iter().enumerate() {
            let mut row = HashMap::new();
            row.insert("CueName".to_string(), Value::String(name));
            row.insert("CueIndex".to_string(), Value::U16(i as u16));
            table.add_row(row);
        }

        Self::finish_music_nested_table(table)
    }
```

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

### Get Waveform File Extension

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/consts.rs.html

Maps a waveform encoding type to its corresponding file extension. Returns an empty string for unknown types.

```rust
pub fn wave_type_extension(enc_type: i32) -> &'static str {
    match enc_type {
        WAVEFORM_ENCODE_TYPE_ADX | WAVEFORM_ENCODE_TYPE_ADX_ALT => ".adx",
        WAVEFORM_ENCODE_TYPE_AHX => ".ahx",
        WAVEFORM_ENCODE_TYPE_HCA => ".hca",
        WAVEFORM_ENCODE_TYPE_WII_ADPCM => ".wiiadpcm",
        WAVEFORM_ENCODE_TYPE_DS_ADPCM => ".dsadpcm",
        // HCA-MX is a standard HCA bitstream (HCA\0 magic); vgmstream awb.c:178
        // and PyCriCodecs both return ".hca" for type 6.
        WAVEFORM_ENCODE_TYPE_HCA_MX => ".hca",
        WAVEFORM_ENCODE_TYPE_VAG | WAVEFORM_ENCODE_TYPE_HEVAG => ".vag",
        WAVEFORM_ENCODE_TYPE_ATRAC3 => ".at3",
        WAVEFORM_ENCODE_TYPE_BCWAV => ".bcwav",
        WAVEFORM_ENCODE_TYPE_ATRAC9 | WAVEFORM_ENCODE_TYPE_PS4_ATRAC9 => ".at9",
        WAVEFORM_ENCODE_TYPE_XMA => ".xma",
        WAVEFORM_ENCODE_TYPE_NINTENDO_DSP => ".dsp",
        WAVEFORM_ENCODE_TYPE_M4A => ".m4a",
        WAVEFORM_ENCODE_TYPE_SWITCH_OPUS => ".lopus",
        _ => "",
    }
}
```

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

### Get Video Frame Rate

Source: https://docs.rs/cridecoder/latest/cridecoder/usm/struct.Metadata.html

Retrieves the video frame rate from the metadata. Returns an Option containing a tuple of (numerator, denominator) if available.

```rust
pub fn video_frame_rate(&self) -> Option<(i32, i32)>
```

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

### Error::description Implementation for HcaDecoderError

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/enum.HcaDecoderError.html

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

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

### Test AfsFileEntry Creation and Assertions

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/afs.rs.html

Demonstrates the creation of an AfsFileEntry struct and asserts the values of its fields. This is useful for verifying the correct initialization of file entry data.

```rust
fn test_afs_file_entry() {
        let entry = AfsFileEntry {
            cue_id: 0,
            offset: 0x100,
            size: 0x200,
        };
        assert_eq!(entry.cue_id, 0);
        assert_eq!(entry.offset, 0x100);
        assert_eq!(entry.size, 0x200);
    }
```

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

### AfsArchiveBuilder with_alignment Method

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Sets the alignment for file data within the AFS2 archive. This ensures files start at specific byte boundaries.

```rust
pub fn with_alignment(mut self, alignment: u32) -> Self {
        self.alignment = alignment;
        self
    }
```

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

### Create BitReader with Byte Offset

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Initializes a new `BitReader` starting at a specific byte offset within the data. The position is calculated in bits.

```Rust
pub fn with_offset(data: &'a [u8], byte_offset: usize) -> Self {
        Self {
            data,
            position: byte_offset * 8,
        }
    }
```

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

### Create TrackList from UTF Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/track.rs.html

Constructor for `TrackList` that parses a given `UtfTable` to extract track information. It handles potential errors like empty tables or missing required sub-tables.

```rust
impl TrackList {
    /// Create a TrackList from a UTF table
    pub fn new(utf: &UtfTable) -> Result<Self, TrackError> {
        if utf.rows.is_empty() {
            return Err(TrackError::NoRows);
        }

        let tables = parse_acb_tables(&utf.rows[0])?;
        let name_map = build_name_map(&tables.nams);

        let mut tl = TrackList { tracks: Vec::new() };
        // Track all chosen names so duplicate detection is O(1) instead of an
        // O(n^2) scan of every prior track name.
        let mut seen_names: HashSet<String> = HashSet::new();
        extract_tracks_from_tables(&tables, &name_map, &mut tl, &mut seen_names)?;

        Ok(tl)
    }
}
```

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

### UTF Table Builder Initialization

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Creates a new UtfTableBuilder with a specified table name. Default alignments and encoding are applied.

```rust
pub struct UtfTableBuilder {
    pub table_name: String,
    pub columns: Vec<ColumnDef>,
    pub rows: Vec<HashMap<String, Value>>,
    data_offset_alignment: u32,
    table_alignment: u32,
    data_item_alignment: u32,
    encoding: u16,
}

impl UtfTableBuilder {
    pub fn new(table_name: impl Into<String>) -> Self {
        Self {
            table_name: table_name.into(),
            columns: Vec::new(),
            rows: Vec::new(),
            data_offset_alignment: 32,
            table_alignment: 32,
            data_item_alignment: 1,
            encoding: 0,
        }
    }
// ... other methods
```

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

### Reset HcaDecoder

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/struct.HcaDecoder.html

Resets the decoder to the beginning of the audio stream. This is useful for re-decoding the audio from the start without creating a new decoder instance.

```rust
pub fn reset(&mut self)
```

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

### Get String Field from ValueMap

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/utf.rs.html

Retrieves a string value associated with a given key from a ValueMap. Returns None if the key is not found or the value is not a string.

```rust
pub fn get_string_field<'a>(row: &'a ValueMap, key: &str) -> Option<&'a str> {
    row.get(key).and_then(|v| v.as_string())
}
```

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

### Build Music Sequence Command Table - Rust

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Constructs the 'SequenceCommand' table for music data. It defines a single column for 'Command' which holds byte data representing commands. The number of commands added is limited by the music cue count.

```rust
fn build_music_seq_command_table(
        &self,
        config: &MusicAcbConfig,
    ) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("SequenceCommand");
        table.add_column(ColumnDef::per_row("Command", COLUMN_TYPE_DATA));

        let commands = [
            vec![
                0x00, 0x41, 0x04, 0x00, 0x00, 0x00, 0x05, 0x00, 0x45, 0x04, 0x41, 0xf0, 0x00, 0x00,
                0x00, 0x6f, 0x04, 0x00, 0x00, 0x27, 0x10,
            ],
            vec![
                0x00, 0x41, 0x04, 0x00, 0x00, 0x00, 0x05, 0x00, 0x45, 0x04, 0x41, 0xf0, 0x00, 0x00,
                0x00, 0x6f, 0x04, 0x00, 0x00, 0x23, 0x28, 0x00, 0x6f, 0x04, 0x00, 0x01, 0x13, 0x88,
                0x00, 0x6f, 0x04, 0x00, 0x03, 0x13, 0x88,
            ],
        ];
        for command in commands
            .into_iter()
            .take(Self::music_cue_count(config) as usize)
        {
            let mut row = HashMap::new();
            row.insert("Command".to_string(), Value::Data(command));
            table.add_row(row);
        }

        Self::finish_music_nested_table(table)
    }
```

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

### Get HCA Info

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/struct.HcaDecoder.html

Retrieves information about the HCA file, such as sample rate, channels, and bitrate. This method returns an immutable reference to the HcaInfo struct.

```rust
pub fn info(&self) -> &HcaInfo
```

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

### TrackInput::new Constructor

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Creates a new `TrackInput` instance. It automatically detects the audio encoding type based on the provided data.

```rust
impl TrackInput {
    pub fn new(name: impl Into<String>, cue_id: u32, data: Vec<u8>) -> Self {
        let encode_type = Self::detect_encode_type(&data);
        Self {
            name: name.into(),
            cue_id,
            data,
            encode_type,
        }
    }

    fn detect_encode_type(data: &[u8]) -> i32 {
        if data.len() < 4 {
            return WAVEFORM_ENCODE_TYPE_HCA;
        }
        match &data[0..4] {
            [0x80, 0x00, ..] | [0x00, 0x00, 0x00, 0x80] => WAVEFORM_ENCODE_TYPE_ADX,
            b"HCA\0" | [0xc8, 0xc3, 0xc1, 0x80] => WAVEFORM_ENCODE_TYPE_HCA, // HCA or masked HCA
            _ if data.len() > 6 && data[0] == 0xC8 => WAVEFORM_ENCODE_TYPE_HCA, // masked HCA header
            _ => WAVEFORM_ENCODE_TYPE_HCA,
        }
    }
}
```

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

### Get decoder information

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/struct.ClHca.html

Retrieves information about the HCA file, such as sample rate, channels, and frame count. Returns a `Result` containing `HcaInfo` or an `HcaError`.

```rust
pub fn get_info(&self) -> Result<HcaInfo, HcaError>
```

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

### Building the UTF Table

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Initiates the process of building the UTF table by collecting strings and data blobs. Requires a writer that implements Write and Seek traits.

```rust
impl UtfTableBuilder {
    // ... encode_string method

    /// Build the UTF table and write to output
    pub fn build<W: Write + Seek>(&self, writer: &mut W) -> Result<(), BuilderError> {
        // Phase 1: Collect all strings and data blobs
        let mut string_table = StringTable::new();
        let mut data_table = DataTable::new(self.data_item_alignment);

        // Add table name
        let table_name_offset = string_table.add_table_name(&self.table_name);

        // Add column names and constant strings/data
        let mut column_name_offsets = Vec::new();
// ... rest of the method
```

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

### Initialize Cipher Table for Type 56 (Key-Based Encryption)

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/cipher.rs.html

Initializes a 256-byte cipher table for type 56 encryption, which is key-based. It uses a keycode to generate the table.

```Rust
pub fn cipher_init_56(cipher_table: &mut [u8; 256], keycode: u64) {
    let mut kc = [0u8; 8];
    let mut seed = [0u8; 16];
    let mut base = [0u8; 256];
    let mut base_r = [0u8; 16];
    let mut base_c = [0u8; 16];

    let keycode = if keycode != 0 { keycode - 1 } else { keycode };

    for (r, entry) in kc.iter_mut().enumerate().take(7) {
        *entry = ((keycode >> (r * 8)) & 0xFF) as u8;
    }

    seed[0x00] = kc[1];
    seed[0x01] = kc[1] ^ kc[6];
    seed[0x02] = kc[2] ^ kc[3];
    seed[0x03] = kc[2];
    seed[0x04] = kc[2] ^ kc[1];
    seed[0x05] = kc[3] ^ kc[4];
    seed[0x06] = kc[3];
    seed[0x07] = kc[3] ^ kc[2];
    seed[0x08] = kc[4] ^ kc[5];
    seed[0x09] = kc[4];
    seed[0x0A] = kc[4] ^ kc[3];
    seed[0x0B] = kc[5] ^ kc[6];
    seed[0x0C] = kc[5];
    seed[0x0D] = kc[5] ^ kc[4];
    seed[0x0E] = kc[6] ^ kc[1];
    seed[0x0F] = kc[6];

    cipher_init_56_create_table(&mut base_r, kc[0]);
    for r in 0..16 {
        cipher_init_56_create_table(&mut base_c, seed[r]);
        let nb = base_r[r] << 4;
        for c in 0..16 {
            base[r * 16 + c] = nb | base_c[c];
        }
    }

    let mut x: usize = 0;
    let mut pos = 1;
    for _ in 0..256 {
        x = (x + 17) & 0xFF;
        if base[x] != 0 && base[x] != 0xFF {
            cipher_table[pos] = base[x];
            pos += 1;
        }
    }
    cipher_table[0] = 0;
    cipher_table[0xFF] = 0xFF;
}
```

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

### Get Integer Field from ValueMap

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/utf.rs.html

Retrieves an integer value (i64) associated with a given key from a ValueMap. Returns 0 if the key is not found or the value is not an integer.

```rust
pub fn get_int_field(row: &ValueMap, key: &str) -> i64 {
    row.get(key).and_then(|v| v.as_int()).unwrap_or(0)
}
```

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

### AcbBuilder::music_acb()

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AcbBuilder.html

Configures the builder for a music ACB file. Requires numerous parameters to define the music cue.

```rust
pub fn music_acb( self, cue_id: u32, virtual_cue_suffix: Option<String>, memory_awb_id: u16, reference_num_samples: u32, reference_length_ms: u32, acb_version: u32, acf_md5_hash: Vec<u8>, acb_guid: Vec<u8>, version_string: String, acb_volume: f32, category_extension: u8, cue_priority_type: u8, acf_category_name: String, acf_category_id: u32, acf_bus_names: Vec<String>, ) -> Self
```

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

### HcaEncoderConfig::new

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/encoder.rs.html

Creates a new HcaEncoderConfig with specified sample rate and channels, using default values for other settings.

```APIDOC
## fn new(sample_rate: u32, channels: u32) -> Self

### Description
Constructs a new `HcaEncoderConfig` with the specified sample rate and number of channels. Other parameters are initialized to their default values.

### Parameters
*   `sample_rate` (u32) - The desired sample rate in Hz.
*   `channels` (u32) - The desired number of audio channels.
```

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

### Get File Data by Entry

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AfsArchive.html

Retrieves the raw data for a file using its AfsFileEntry. This is useful when you already have the file entry information and want to access its content.

```rust
pub fn file_data(&mut self, entry: AfsFileEntry) -> Result<Vec<u8>, AfsError>
```

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

### HcaDecoder::from_file

Source: https://docs.rs/cridecoder/latest/cridecoder/hca/struct.HcaDecoder.html

Creates a new HCA decoder instance from a given file path. This is a convenient way to start decoding an HCA file directly from storage.

```APIDOC
## HcaDecoder::from_file

### Description
Creates a new HCA decoder from a file path.

### Method
GET

### Endpoint
`/hca/decoder/file/{filename}`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the HCA file.

### Response
#### Success Response (200)
- **HcaDecoder** - An instance of the HCA decoder.

#### Response Example
```json
{
  "decoder_instance": "<HcaDecoder object>"
}
```
```

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

### Generate Masks from Key

Source: https://docs.rs/cridecoder/latest/src/cridecoder/usm/builder.rs.html

Generates video and audio masks based on a given u64 key. Asserts the expected lengths of the generated masks.

```rust
let key: u64 = 0x12345678_9ABCDEF0;
        let (vmask, amask) = get_mask(key);

        assert_eq!(vmask.len(), 2);
        assert_eq!(vmask[0].len(), 0x20);
        assert_eq!(vmask[1].len(), 0x20);
        assert_eq!(amask.len(), 0x20);
```

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

### Build Music Cue Table - Rust

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/builder.rs.html

Constructs the 'Cue' table for music data. It defines columns for command index, reference items, control work areas, and constant values for local and global AISACs, track values, and parameter pallets. Rows are added based on the music cue count.

```rust
fn build_music_cue_table(config: &MusicAcbConfig) -> Result<Vec<u8>, BuilderError> {
        let mut table = UtfTableBuilder::new("Cue");
        table.add_column(ColumnDef::per_row("CommandIndex", COLUMN_TYPE_2BYTE));
        table.add_column(ColumnDef::per_row("ReferenceItems", COLUMN_TYPE_DATA));
        table.add_column(ColumnDef::constant("LocalAisacs", Value::Data(Vec::new())));
        table.add_column(ColumnDef::constant(
            "GlobalAisacStartIndex",
            Value::U16(0xffff),
        ));
        table.add_column(ColumnDef::constant("GlobalAisacNumRefs", Value::U16(0)));
        table.add_column(ColumnDef::per_row("ControlWorkArea1", COLUMN_TYPE_2BYTE));
        table.add_column(ColumnDef::per_row("ControlWorkArea2", COLUMN_TYPE_2BYTE));
        table.add_column(ColumnDef::constant("TrackValues", Value::Data(Vec::new())));
        table.add_column(ColumnDef::constant("ParameterPallet", Value::U16(0xffff)));
        table.add_column(ColumnDef::constant(
            "ActionTrackStartIndex",
            Value::U16(0xffff),
        ));
        table.add_column(ColumnDef::constant("NumActionTracks", Value::U16(0)));

        for i in 0..Self::music_cue_count(config) {
            let mut row = HashMap::new();
            row.insert(
                "CommandIndex".to_string(),
                Value::U16(if i == 0 { 0xffff } else { 0 }),
            );
            row.insert(
                "ReferenceItems".to_string(),
                Value::Data(vec![0x00, 0x01, 0x00, 0x00]),
            );
            row.insert("ControlWorkArea1".to_string(), Value::U16(i));
            row.insert("ControlWorkArea2".to_string(), Value::U16(i));
            table.add_row(row);
        }

        Self::finish_music_nested_table(table)
    }
```

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

### Get HCA Decoder Information

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/decoder.rs.html

Retrieves detailed information about the HCA decoder's current state and file properties. Returns an HcaInfo struct or an HcaError if the decoder is not initialized.

```rust
pub fn get_info(&self) -> Result<HcaInfo, HcaError> {
        if !self.is_valid {
            return Err(HcaError::NotInitialized);
        }

        Ok(HcaInfo {
            version: self.version,
            header_size: self.header_size,
            sampling_rate: self.sample_rate,
            channel_count: self.channels,
            block_size: self.frame_size,
            block_count: self.frame_count,
            encoder_delay: self.encoder_delay,
            encoder_padding: self.encoder_padding,
            loop_enabled: self.loop_flag,
            loop_start_block: self.loop_start_frame,
            loop_end_block: self.loop_end_frame,
            loop_start_delay: self.loop_start_delay,
            loop_end_padding: self.loop_end_padding,
            samples_per_block: HCA_SAMPLES_PER_FRAME,
            comment: if self.comment_len > 0 {
                String::from_utf8_lossy(&self.comment[..self.comment_len]).to_string()
            } else {
                String::new()
            },
            encryption_enabled: self.ciph_type == 56,
        })
    }
```

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

### AfsArchive Implementations

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.AfsArchive.html

Provides methods for creating and manipulating AFS archives.

```APIDOC
### impl<R: Read + Seek> AfsArchive<R>

Methods for interacting with an AFS archive.

#### `new(r: R) -> Result<Self, AfsError>`

Creates a new AFS archive from a given reader.

#### `file_data_for_cue_id(&mut self, cue_id: i32) -> Result<Vec<u8>, AfsError>`

Retrieves the data for a file associated with a specific cue ID.

#### `file_data(&mut self, entry: AfsFileEntry) -> Result<Vec<u8>, AfsError>`

Retrieves the data for a given file entry.
```

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

### TrackInput Constructor

Source: https://docs.rs/cridecoder/latest/cridecoder/acb/struct.TrackInput.html

Creates a new instance of TrackInput. Accepts a name, cue ID, and audio data.

```rust
pub fn new(name: impl Into<String>, cue_id: u32, data: Vec<u8>) -> Self
```

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

### ath_init_0

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/ath.rs.html

Initializes an ATH curve with all zero values. This is useful for a baseline or when no specific ATH is required.

```APIDOC
## ath_init_0

### Description
Initializes an ATH curve with all zero values. This is useful for a baseline or when no specific ATH is required.

### Signature
`pub fn ath_init_0(ath_curve: &mut [u8; HCA_SAMPLES_PER_SUBFRAME])`

### Parameters
* `ath_curve` (&mut [u8; HCA_SAMPLES_PER_SUBFRAME]) - A mutable slice representing the ATH curve to be initialized.
```

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

### BitReader Test: Peek Bits

Source: https://docs.rs/cridecoder/latest/src/cridecoder/hca/bitreader.rs.html

Tests the `peek` functionality of the BitReader, which reads bits without advancing the position. It verifies peeking different bit lengths from the start of the buffer.

```rust
    #[test]
    fn test_peek() {
        let data = [0b10110100];
        let reader = BitReader::new(&data);

        assert_eq!(reader.peek(4), 0b1011);
        assert_eq!(reader.peek(8), 0b10110100);
    }

```

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

### Get Bytes Field from Row

Source: https://docs.rs/cridecoder/latest/src/cridecoder/acb/utf.rs.html

Safely retrieves a byte slice from a ValueMap, returning None if the key is not found or the value is not of bytes type. Use this for read-only access to byte data.

```rust
pub fn get_bytes_field<'a>(row: &'a ValueMap, key: &str) -> Option<&'a [u8]> {
    row.get(key).and_then(|v| v.as_bytes())
}
```