### Install Python Package

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Commands to install the Python package from the repository root.

```sh
python -m pip install .
```

```sh
python -m pip install --no-build-isolation -ve .
```

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

### Configure Qt6 Dependencies and Install Paths

Source: https://github.com/youjose/cricodecs/blob/main/CriStudio/CMakeLists.txt

Initializes required Qt6 components and standard GNU installation directories.

```cmake
find_package(Qt6 REQUIRED COMPONENTS Widgets Multimedia MultimediaWidgets Concurrent LinguistTools)
include(GNUInstallDirs)
```

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

### Configure and Install CMake Package Files

Source: https://github.com/youjose/cricodecs/blob/main/CMakeLists.txt

Generates and installs package configuration and version files to support find_package integration.

```cmake
get_target_property(CRICODECS_PACKAGE_NEEDS_ICONV CriCodecs CRICODECS_PACKAGE_NEEDS_ICONV)
    set(cricodecs_package_dir "${CMAKE_INSTALL_LIBDIR}/cmake/CriCodecs")
    configure_package_config_file(
        "${CMAKE_CURRENT_SOURCE_DIR}/CriCodecs/cmake/CriCodecsConfig.cmake.in"
        "${CMAKE_CURRENT_BINARY_DIR}/CriCodecsConfig.cmake"
        INSTALL_DESTINATION "${cricodecs_package_dir}"
    )
    write_basic_package_version_file(
        "${CMAKE_CURRENT_BINARY_DIR}/CriCodecsConfigVersion.cmake"
        VERSION "${PROJECT_VERSION}"
        COMPATIBILITY SameMajorVersion
    )
    install(
        EXPORT CriCodecsTargets
        FILE CriCodecsTargets.cmake
        NAMESPACE CriCodecs::
        DESTINATION "${cricodecs_package_dir}"
    )
    install(
        FILES
            "${CMAKE_CURRENT_BINARY_DIR}/CriCodecsConfig.cmake"
            "${CMAKE_CURRENT_BINARY_DIR}/CriCodecsConfigVersion.cmake"
        DESTINATION "${cricodecs_package_dir}"
    )
endif()
```

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

### Build and Install CLI Executable

Source: https://github.com/youjose/cricodecs/blob/main/CMakeLists.txt

Defines the CLI target, sets C++23 requirements, and handles runtime DLL installation on Windows.

```cmake
if(CRICODECS_BUILD_CLI)
    add_executable(cricodecs_cli
        CriCodecs/src/cli/cricodecs_cli_main.cpp
    )
    target_link_libraries(cricodecs_cli PRIVATE CriCodecs)
    target_compile_features(cricodecs_cli PRIVATE cxx_std_23)
    set_target_properties(cricodecs_cli PROPERTIES
        OUTPUT_NAME cricodecs
    )
    if(NOT CRICODECS_BUILD_PYTHON)
        install(TARGETS cricodecs_cli RUNTIME DESTINATION .)
        if(WIN32 AND CMAKE_VERSION VERSION_GREATER_EQUAL "3.21")
            install(
                FILES $<TARGET_RUNTIME_DLLS:cricodecs_cli>
                DESTINATION .
                OPTIONAL
            )
        endif()
    endif()
endif()
```

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

### Install Python Stubs and Runtime Dependencies

Source: https://github.com/youjose/cricodecs/blob/main/PyCriCodecs/CMakeLists.txt

Configures the installation of Python stub files and necessary MinGW runtime DLLs.

```cmake
set(cricodecs_python_stub_files
    package/cricodecs/__init__.pyi
    package/cricodecs/aax.pyi
    package/cricodecs/acb.pyi
    package/cricodecs/acx.pyi
    package/cricodecs/adx.pyi
    package/cricodecs/afs.pyi
    package/cricodecs/ahx.pyi
    package/cricodecs/aix.pyi
    package/cricodecs/awb.pyi
    package/cricodecs/cpk.pyi
    package/cricodecs/csb.pyi
    package/cricodecs/cvm.pyi
    package/cricodecs/hca.pyi
    package/cricodecs/sfd.pyi
    package/cricodecs/usm.pyi
    package/cricodecs/utf.pyi
    package/cricodecs/video.pyi
    package/cricodecs/wav.pyi
    package/cricodecs/py.typed
)

foreach(cricodecs_python_stub_file IN LISTS cricodecs_python_stub_files)
    get_filename_component(cricodecs_python_stub_name "${cricodecs_python_stub_file}" NAME)
    configure_file(
        "${cricodecs_python_stub_file}"
        "${cricodecs_python_package_dir}/${cricodecs_python_stub_name}"
        COPYONLY
    )
endforeach()

install(
    TARGETS cricodecs
    LIBRARY DESTINATION cricodecs
    RUNTIME DESTINATION cricodecs
)
if(MINGW)
    get_filename_component(cricodecs_mingw_runtime_dir "${CMAKE_CXX_COMPILER}" DIRECTORY)
    install(
        FILES
            "${cricodecs_mingw_runtime_dir}/libgcc_s_seh-1.dll"
            "${cricodecs_mingw_runtime_dir}/libstdc++-6.dll"
            "${cricodecs_mingw_runtime_dir}/libwinpthread-1.dll"
            "${cricodecs_mingw_runtime_dir}/libiconv-2.dll"
            "${cricodecs_mingw_runtime_dir}/libcharset-1.dll"
        DESTINATION cricodecs
        OPTIONAL
    )
endif()
install(
    FILES ${cricodecs_python_stub_files}
    DESTINATION cricodecs
)
```

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

### Install Python wheels

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Command to install the CriCodecs Python package from PyPI.

```bash
python -m pip install cricodecs
```

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

### Build and install cricodecs with CMake

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Standard sequence of commands to configure, build, and install the project using the Ninja generator.

```sh
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCRICODECS_BUILD_TESTS=OFF \
  -DCRICODECS_INSTALL_CPP=ON
cmake --build build --parallel 4
cmake --install build --prefix ./install
```

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

### Install CriCodecs via pip

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Use this command to install the Python package and the associated command-line interface.

```console
pip install cricodecs
```

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

### Define UTF Table Structure

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Example structure for a UTF table using a list of dictionaries where keys map to tuples of type and value.

```python
CpkHeader = [
                {
                    "UpdateDateTime": (UTFTypeValues.ullong, 0),
                    "ContentOffset": (UTFTypeValues.ullong, ContentOffset),
                    "ContentSize": (UTFTypeValues.ullong, ContentSize),
                    "TocOffset": (UTFTypeValues.ullong, 0x800),
                    # etc....
                },
                {
                    ....
                }
            ]
```

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

### Configure plan looping and playback

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Customize loop counts and playback behavior when generating a cue plan.

```python
plan = bank.cue_plan(
    cue_index,
    selectors={"Music_GameState": "Scene"},
    loop_count=2,
    advance_after_infinite=False,
    include_empty_holds=True,  # Opt in only when the authored hold is useful.
    block_loop_counts={3: 4},
)
```

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

### Build archives and stream containers

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Create archive files or stream containers like USM and SFD from directories or prepared media.

```sh
cricodecs --build -f cpk input_directory -o archive.cpk
cricodecs --build -f awb waveforms -o sound.awb
cricodecs --build -f awb waveforms -o sound.awb \
  --header-version 2 --alignment 32 --subkey 0
cricodecs --build -f cpk input_directory -o archive.cpk \
  --profile filename-id --alignment 2048

cricodecs --build -f usm movie.ivf \
  --audio dialogue.adx \
  --audio music.hca \
  -o movie.usm

cricodecs --build -f sfd movie.mpg \
  --audio soundtrack.adx \
  -o movie.sfd
```

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

### Resolve cue options and plans

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Inspect selector options and resolve cues into playable plans.

```python
print(bank.selector_options(cue_index))
# {'Music_GameState': ['Battle', 'Scene']}

resolution = bank.resolve_cue(cue_index)
print(resolution.plan_count)       # 2
print(resolution.filenames())

for resolved in resolution.plans:
    print(resolved.plan)
    for source in resolved.sources:
        print(source.source_cue_name)
        print(source.selector_values)
        print(source.action_cue_chain)
        print(source.paths)
```

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

### plan.wav_bytes(bank)

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Renders the plan to raw WAV bytes.

```APIDOC
## plan.wav_bytes(bank)

### Description
Generates the WAV file bytes for a resolved plan using the source ACB bank.

### Parameters
- **bank** (acb.Acb) - Required - The source ACB object.
```

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

### Basic CLI Usage

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Standard input-driven usage for decoding audio or extracting archives.

```sh
cricodecs input.hca
cricodecs input.cpk
```

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

### Generate cue plans

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Create a cue plan using specific selectors or cue IDs.

```python
plan = bank.cue_plan(
    cue_index,
    selectors={"Music_GameState": "Scene"},
)

# The cue-ID form is explicit rather than treating IDs and indexes as the same.
same_plan = bank.cue_plan_by_id(
    cue_id,
    selectors={"Music_GameState": "Scene"},
)
```

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

### Build C++ SDK and CLI

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Build commands for the C++ SDK and CLI using CMake.

```sh
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
cmake --install build --prefix ./install
```

```sh
cmake -S . -B build-vs -G "Visual Studio 18 2026" -A x64
cmake --build build-vs --config Release --parallel 4
cmake --install build-vs --config Release --prefix install
```

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

### Print configuration representation

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Display the string representation of configuration objects.

```python
from cricodecs import adx

print(repr(adx.AdxEncodeConfig()))
```

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

### cpk.load / cpk.create

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Methods for inspecting, extracting, and building CPK archives.

```APIDOC
## cpk.load(path)

### Description
Loads a CPK archive for inspection and extraction.

## cpk.create(preset)

### Description
Creates a new CPK archive instance using a specified preset.
```

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

### bank.cue_plan(cue_index, ...)

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Generates a playable plan for a specific cue index.

```APIDOC
## bank.cue_plan(cue_index, selectors=None, variant=None, loop_count=0, advance_after_infinite=True, include_empty_holds=False, block_loop_counts=None)

### Description
Returns a plan for a cue. If multiple plans exist, selectors or a variant index must be provided.

### Parameters
- **cue_index** (int) - Required - The zero-based index of the cue.
- **selectors** (dict) - Optional - Dictionary of named selectors to resolve the plan.
- **variant** (int) - Optional - The zero-based variant index for random/sequential alternatives.
- **loop_count** (int) - Optional - Number of repeats after initial block play.
- **advance_after_infinite** (bool) - Optional - Whether to advance after an infinite audio block.
- **include_empty_holds** (bool) - Optional - Whether to include synthesized duration of empty infinite holds.
- **block_loop_counts** (dict) - Optional - Mapping of block indices to loop counts.
```

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

### Define and Parse Project Version

Source: https://github.com/youjose/cricodecs/blob/main/CriStudio/CMakeLists.txt

Sets the project version string and extracts major, minor, and patch components using regex.

```cmake
set(CRISTUDIO_VERSION "1.2.0" CACHE STRING "CriStudio release version")
string(REGEX MATCH "^([0-9]+)\\.([0-9]+)\\.([0-9]+)" cristudio_numeric_version "${CRISTUDIO_VERSION}")
if(NOT cristudio_numeric_version)
    message(FATAL_ERROR "CRISTUDIO_VERSION must begin with major.minor.patch")
endif()
set(CRISTUDIO_VERSION_MAJOR "${CMAKE_MATCH_1}")
set(CRISTUDIO_VERSION_MINOR "${CMAKE_MATCH_2}")
set(CRISTUDIO_VERSION_PATCH "${CMAKE_MATCH_3}")
```

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

### Handle ACB and USM files

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Inspect cue sheets, resolve plans, and mux USM movie files.

```python
from cricodecs import acb, usm

cue_sheet = acb.load("sound.acb")
print(cue_sheet.info())
print(cue_sheet.graph)

cue_index = 0
print(cue_sheet.selector_options(cue_index))
resolution = cue_sheet.resolve_cue(cue_index)
print(resolution.filenames())

# Choose one inspected static result; named selectors can also be passed to
# cue_sheet.cue_plan(...) when the ACB provides them.
plan = resolution.plans[0].plan
plan.export(cue_sheet, "cue.wav")

# Flat waveform extraction remains available separately.
cue_sheet.extract("sound_waveforms")

movie = usm.load("movie.usm")
print(movie.info())
movie.extract("movie_streams")

config = usm.UsmMuxConfig(
    video_path="movie.264",
    audio_tracks=[usm.UsmMuxAudioTrack("movie.adx")],
    subtitle_tracks=[
        usm.UsmMuxSubtitleTrack(
            "subtitles_en.srt",
            language_id=0,
            format=usm.UsmSubtitleFormat.SRT,
        ),
    ],
)
usm.mux(config, "movie_with_subtitles.usm")
```

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

### Assemble cue nodes and edges

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Retrieve the assembly of nodes and edges for a specific cue index.

```python
assembly = graph.assemble_cue(cue_index)
print(assembly.nodes)
print(assembly.edges)
print(assembly.unresolved)
```

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

### Parse UTF Data

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Demonstrates how to load a UTF file and access its internal table, payload, and encoding properties.

```python
from PyCriCodecs import *
# Parsing UTF
data = UTF("filename_or_bytes.dat")
data.table # This will give you the internal parsed table that is used by my CPK lib.
payload = data.get_payload() # This will return a list of dictionaries which can be used to build UTF tables, you can modify them as well.
data.encoding # Returns the type of encoding of the UTF data, although not specified in the UTF table, the code will try all 3 possible encodings.
```

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

### Configure PyCriCodecs Build Environment

Source: https://github.com/youjose/cricodecs/blob/main/PyCriCodecs/CMakeLists.txt

Initializes the build environment by verifying the parent project target and locating Python and nanobind dependencies.

```cmake
if(NOT TARGET CriCodecs)
    message(FATAL_ERROR "PyCriCodecs/CMakeLists.txt expects the parent project to define the CriCodecs target")
endif()

set(cricodecs_python_root_dir "${PROJECT_BINARY_DIR}/python")
set(cricodecs_python_package_dir "${cricodecs_python_root_dir}/cricodecs")

find_package(Python 3.9
    REQUIRED COMPONENTS Interpreter Development.Module
    OPTIONAL_COMPONENTS Development.SABIModule
)

execute_process(
    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
    RESULT_VARIABLE cricodecs_nanobind_status
    OUTPUT_STRIP_TRAILING_WHITESPACE
    OUTPUT_VARIABLE cricodecs_nanobind_root
    ERROR_QUIET
)

if(cricodecs_nanobind_status EQUAL 0)
    list(APPEND CMAKE_PREFIX_PATH "${cricodecs_nanobind_root}")
endif()

find_package(nanobind CONFIG REQUIRED)
```

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

### Include C++ SDK headers

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Includes the umbrella header for the complete public API surface.

```cpp
#include <cricodecs/cricodecs.hpp>
```

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

### Initialize UTFBuilder

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Constructor signature for the UTFBuilder class, which requires a list of dictionaries to construct a table.

```python
def __init__(self, dictarray: list[dict], encrypt: bool = False, encoding: str = "utf-8", table_name: str = "PyCriCodecs_table") -> None:
```

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

### ACB Infinite Block Configuration

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Adjust loop counts and handling of infinite blocks during ACB cue rendering.

```sh
# Add two repeats to every audio-bearing infinite block.
cricodecs --cue --cue-loop-count 2 Music.acb -o Music_cues

# Override one zero-based block position on selected plan 3.
cricodecs --cue --index 3 --cue-block-loop-count 3=4 \
  Music.acb -o Music_cues

# Stop after the first rendered infinite block.
cricodecs --cue --cue-stop-at-loop Music.acb -o Music_cues

# Include waveform-less infinite holding blocks when their authored silence is
# useful for a particular export.
cricodecs --cue --cue-include-empty-holds Music.acb -o Music_cues
```

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

### Load a CPK archive in C++

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Loads a CPK container and iterates through its file metadata.

```cpp
#include <cricodecs/cpk/cpk_container.hpp>

auto archive = cricodecs::cpk::Cpk::load("input.cpk");
if (!archive) {
    return 1;
}

for (const auto& file : archive->files()) {
    // Inspect entry metadata without materializing every payload.
}
```

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

### USM Muxing

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Build a USM file using specific audio inputs and an encryption key.

```sh
cricodecs --build -f usm --key 0x165CF4E2138F7BDA \
  --audio dialogue.adx --audio music.hca -o movie.usm movie.ivf
```

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

### Inspect, Extract, and Build CPK archives

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Manage CPK archives by loading, extracting contents, or creating new archives.

```python
from pathlib import Path

from cricodecs import cpk

archive = cpk.load("input.cpk")
print(archive.info())
archive.extract("input_extracted")

new_archive = cpk.create(cpk.CpkPreset.FILENAME)
new_archive.add_file("data/voice.adx", "voice/voice.adx")
new_archive.add_bytes(b"hello", "text/readme.txt")
Path("output.cpk").write_bytes(new_archive.save_bytes())
```

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

### Include CriCodecs API and CMake Configuration

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Include the main header and link the library using CMake.

```cpp
#include <cricodecs/cricodecs.hpp>
```

```cmake
find_package(CriCodecs CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE CriCodecs::CriCodecs)
```

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

### Export plan audio

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Write a plan to a WAV file or export it using the plan's export method.

```python
from pathlib import Path

Path("village_scene.wav").write_bytes(plan.wav_bytes(bank))
plan.export(bank, "village_scene.wav")
```

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

### Load CPK Container

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Load a CPK archive and verify file contents.

```cpp
#include <cricodecs/cpk/cpk_container.hpp>

int main() {
    auto archive = cricodecs::cpk::Cpk::load("input.cpk");
    if (!archive) {
        return 1;
    }

    return archive->files().empty() ? 1 : 0;
}
```

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

### Inspect plan blocks and clips

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Iterate through the blocks and waveform clips within a resolved plan.

```python
for block in plan.blocks:
    print(
        block.block_position,
        block.name,
        block.duration_us,
        block.authored_loop_count,
        block.render_loop_count,
    )
    for clip in block.clips:
        print(
            clip.waveform_index,
            clip.start_time_us,
            clip.awb_wave_id,
            clip.awb_stream_index,
            clip.awb_bank,
        )
```

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

### Handle C++ errors with std::expected

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Demonstrates checking for errors when loading and decoding ADX files.

```cpp
#include <iostream>
#include <cricodecs/adx/adx_codec.hpp>

int main() {
    auto input = cricodecs::adx::Adx::load("input.adx");
    if (!input) {
        std::cerr << input.error() << '\n';
        return 1;
    }

    auto decoded = input->decode();
    if (!decoded) {
        std::cerr << decoded.error() << '\n';
        return 1;
    }

    std::cout << decoded->sample_rate << " Hz\n";
}
```

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

### acb.load(path)

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Loads an ACB file from the specified path.

```APIDOC
## acb.load(path)

### Description
Loads an ACB file and returns an `acb.Acb` object for further inspection and rendering.

### Parameters
- **path** (str) - Required - The file path to the .acb file.
```

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

### Mux USM files in Python

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Configures and executes a USM muxing operation with video, audio, and subtitle tracks.

```python
from cricodecs import usm

config = usm.UsmMuxConfig(
    video_path="movie.264",
    audio_tracks=[usm.UsmMuxAudioTrack("movie.adx")],
    subtitle_tracks=[
        usm.UsmMuxSubtitleTrack(
            "subtitles_en.srt",
            language_id=0,
            format=usm.UsmSubtitleFormat.SRT,
        ),
        usm.UsmMuxSubtitleTrack(
            "subtitles_alt.ass",
            language_id=1,
            format=usm.UsmSubtitleFormat.ASS,
        ),
    ],
)
usm.mux(config, "movie_with_subtitles.usm")
```

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

### Basic CLI Operations

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Perform standard decoding and extraction tasks using the CLI.

```sh
cricodecs music.hca
cricodecs archive.cpk
cricodecs movie.usm -o movie_streams
```

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

### ACB Cue Inspection and Rendering

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Manage ACB file extraction using flat waveform views or resolved cue-plan views.

```sh
# Authored cue, resolved-plan, non-playable cue, and waveform counts.
cricodecs -m Music.acb

# Flat waveform view.
cricodecs --list Music.acb
cricodecs Music.acb -o Music_waveforms

# Resolved cue-plan view.
cricodecs --cue --list Music.acb

# Show blocks, clips, timings, AWB IDs, and physical AWB stream indexes for
# zero-based resolved-plan index 3.
cricodecs --cue --list --index 3 Music.acb

# Show detailed blocks and clips for every resolved plan.
cricodecs --cue --list --verbose Music.acb

# Render all unique static plans, or only plan index 3.
cricodecs --cue Music.acb -o Music_cues
cricodecs --cue --index 3 Music.acb -o Music_cues
```

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

### Work with CPK archives

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Extract contents from an existing archive or create a new one by adding files and bytes.

```python
from pathlib import Path
from cricodecs import cpk

archive = cpk.load("input.cpk")
print(archive.info())
archive.extract("input_extracted")

created = cpk.create(cpk.CpkPreset.FILENAME)
created.add_file("voice.adx", "audio/voice.adx")
created.add_bytes(b"hello\n", "docs/readme.txt")
Path("output.cpk").write_bytes(created.save_bytes())
```

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

### Resolve and extract entire cue sheets

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Process all cues in a bank and extract them to a directory.

```python
sheet = bank.resolve_cues()
print(sheet.plan_count)
print(sheet.non_playable_cues)
print(sheet.filenames())

written_paths = bank.extract_cues("Music_cues")
```

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

### Define nanobind Module and Targets

Source: https://github.com/youjose/cricodecs/blob/main/PyCriCodecs/CMakeLists.txt

Defines the nanobind module with source files and configures target properties for Python output.

```cmake
nanobind_add_module(cricodecs
    NB_STATIC
    NB_SUPPRESS_WARNINGS
    src/module.cpp
    src/adx_bindings.cpp
    src/ahx_bindings.cpp
    src/aax_bindings.cpp
    src/aix_bindings.cpp
    src/acx_bindings.cpp
    src/acb_bindings.cpp
    src/acb_cue_bindings.cpp
    src/hca_bindings.cpp
    src/awb_bindings.cpp
    src/afs_bindings.cpp
    src/cpk_bindings.cpp
    src/csb_bindings.cpp
    src/cvm_bindings.cpp
    src/sfd_bindings.cpp
    src/usm_bindings.cpp
    src/utf_bindings.cpp
    src/video_bindings.cpp
    src/wav_bindings.cpp
)

target_link_libraries(cricodecs PRIVATE CriCodecs)

if(CRICODECS_ENABLE_PCH)
    target_precompile_headers(cricodecs PRIVATE
        <algorithm>
        <array>
        <cstdint>
        <filesystem>
        <memory>
        <optional>
        <span>
        <string>
        <string_view>
        <type_traits>
        <unordered_map>
        <utility>
        <vector>
        <nanobind/nanobind.h>
        <nanobind/stl/optional.h>
        <nanobind/stl/string.h>
        <nanobind/stl/vector.h>
    )
endif()

set_target_properties(cricodecs PROPERTIES
    OUTPUT_NAME "__init__"
    LIBRARY_OUTPUT_DIRECTORY "${cricodecs_python_package_dir}"
    RUNTIME_OUTPUT_DIRECTORY "${cricodecs_python_package_dir}"
)
```

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

### Handle encrypted audio files

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Supply a keycode directly to decode or encrypt HCA files.

```python
from cricodecs import hca

wav = hca.decode("encrypted.hca", keycode=0xCF222F1FE0748978)
encrypted = hca.encrypt(
    "plain.hca",
    cipher_type=56,
    keycode=0xCF222F1FE0748978,
)
```

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

### Detect and inspect file formats

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Use cricodecs.load to identify the format of a file based on its path or bytes.

```python
import cricodecs

document = cricodecs.load("archive.cpk")
print(type(document))
print(document)
```

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

### bank.extract_cues(directory)

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Extracts all cues from the bank to the specified directory.

```APIDOC
## bank.extract_cues(directory)

### Description
Resolves all cues in the bank and exports them as files to the target directory.

### Parameters
- **directory** (str) - Required - The target directory path.
```

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

### Load files with cricodecs

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Use the top-level load helper to inspect files.

```python
import cricodecs

obj = cricodecs.load("input.cpk")
print(type(obj))
print(repr(obj))
```

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

### Build UTF Binary Data

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Usage of the UTFBuilder to generate a bytearray from a payload.

```python
utfObj = UTFBuilder(payload, table_name="my_table")
utfObj.parse() # returns a bytearray of the UTF binary data to use.
```

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

### Decode and Encode ADX files

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Convert ADX files to WAV and vice versa using the adx module.

```python
from pathlib import Path

from cricodecs import adx

wav_bytes = adx.decode("input.adx")
Path("output.wav").write_bytes(wav_bytes)

encoded = adx.encode(Path("source.wav").read_bytes())
Path("output.adx").write_bytes(encoded)
```

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

### Key Recovery Commands

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Commands for recovering keys from various file formats including HCA, USM, ADX, and ACB.

```sh
cricodecs --recover-key -f hca music.hca
cricodecs --recover-key -f hca music.acb
cricodecs --recover-key -f usm movie.usm
cricodecs --recover-key -f adx music.adx
cricodecs --recover-key -f ahx voice_a.ahx voice_b.ahx
cricodecs --recover-key -f awb BGM.awb
cricodecs --recover-key -f acb BGM.acb --json
```

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

### Recover cryptographic keys

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Identify potential keys for various formats by analyzing input files or directories.

```sh
# HCA type-56 effective keys
cricodecs --recover-key -f hca music.hca
cricodecs --recover-key -f hca bank.acb --json
cricodecs --recover-key -f hca same_key_folder

# USM video/audio mask keys
cricodecs --recover-key -f usm movie.usm

# ADX/AHX encryption triplets
cricodecs --recover-key -f adx music.adx
cricodecs --recover-key -f ahx voice_a.ahx voice_b.ahx

# CRI AAC keys in AWB/ACB banks
cricodecs --recover-key -f awb BGM.awb
cricodecs --recover-key -f acb BGM.acb
```

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

### Load ACB and inspect graph structure

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Load an ACB file and access its graph components, including converting cue names to indexes.

```python
from cricodecs import acb

bank = acb.load("Music.acb")
graph = bank.graph

print(bank.waveform_count)
print(graph.cue_count, graph.waveform_count)
print(graph.sequences[0])
print(graph.track_events[0])

cue_index = next(
    row.cue_index
    for row in graph.cue_names
    if row.name == "Music_Chapter01_Village_Scene"
)
cue_id = graph.cue(cue_index).cue_id
assert graph.cue_index_by_id(cue_id) == cue_index
```

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

### Decode and encode audio files

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Perform audio conversion using the adx and hca modules, including configuration for HCA encoding.

```python
from pathlib import Path
from cricodecs import adx, hca

Path("music.wav").write_bytes(adx.decode("music.adx"))

adx_bytes = adx.encode(Path("source.wav").read_bytes())
Path("encoded.adx").write_bytes(adx_bytes)

hca_config = hca.HcaEncodeConfig()
hca_config.sample_rate = 48_000
hca_config.channel_count = 2
hca_config.quality = hca.HcaQuality.HIGH

hca_bytes = hca.encode(Path("source.wav").read_bytes(), hca_config)
Path("encoded.hca").write_bytes(hca_bytes)
```

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

### cricodecs.load(path)

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Loads a file from the given path and returns the corresponding object based on the file type.

```APIDOC
## cricodecs.load(path)

### Description
Loads a file from the specified path and returns the matching object type.

### Parameters
- **path** (str) - Required - The path to the file to be loaded.

### Example
```python
import cricodecs
obj = cricodecs.load("input.cpk")
```
```

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

### Resolve cues by variant

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Use resolve_cue to handle unlabeled alternatives by selecting a specific variant index.

```python
resolution = bank.resolve_cue(cue_index)
plan = bank.cue_plan(cue_index, variant=0)
```

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

### acb.load / usm.load / usm.mux

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Methods for handling ACB cue sheets and USM movie files, including muxing operations.

```APIDOC
## acb.load(path)

### Description
Loads an ACB cue sheet file.

## usm.load(path)

### Description
Loads a USM movie file.

## usm.mux(config, output_path)

### Description
Creates a USM file by muxing video, audio, and subtitle tracks based on the provided UsmMuxConfig.
```

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

### Integrate C++ SDK with CMake

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Configures the project to use the CriCodecs library via CMake.

```cmake
find_package(CriCodecs CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE CriCodecs::CriCodecs)
```

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

### Recover encryption keys in Python

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Recovers keys for HCA, ADX, and USM formats. Set same_base_key to False for independent recovery.

```python
from cricodecs import adx, hca, usm

hca_result = hca.recover_key(
    ["voice_01.hca", "voice_02.hca"],
    same_base_key=True,
)
print(hca_result.candidates[0])

adx_result = adx.recover_key("music.adx")
movie_result = usm.recover_key("movie.usm")
```

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

### CPK Container Access

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Load a CPK archive and access its file contents.

```APIDOC
## cricodecs::cpk::Cpk::load

### Description
Loads a CPK archive from the filesystem.

### Signature
static std::expected<Cpk, std::string> load(const std::filesystem::path& path);

## cricodecs::cpk::Cpk::files

### Description
Returns a list of files contained within the CPK archive.

### Signature
const std::vector<CpkFile>& files() const;
```

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

### Metadata Inspection and Extraction

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Inspect file metadata or list contents without performing full extraction.

```sh
# Human-readable metadata
cricodecs -m archive.cpk

# Machine-readable metadata
cricodecs -m --json movie.usm

# List entries without extracting
cricodecs --list archive.cpk

# List entries as structured JSON
cricodecs --list --json archive.cpk

# Extract raw encoded payloads rather than decoding audio
cricodecs --raw archive.cpk -o raw_entries

# Extract selected entry indices
cricodecs archive.cpk --index 2 --index 7 -o selected
```

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

### Define CPK Header Structure

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

C++ structure representing the 16-byte CPK header.

```cpp
struct CpkHeader{
    unsigned int header;
    unsigned int encflag;
    unsigned int packet_size;
    unsigned int unk0C;
};
```

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

### Process HCA files

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Decode, encode, and encrypt HCA files with specific configurations and keys.

```python
from pathlib import Path

from cricodecs import hca

wav_bytes = hca.decode("input.hca", keycode=0xCF222F1FE0748978)
Path("decoded.wav").write_bytes(wav_bytes)

config = hca.HcaEncodeConfig()
config.sample_rate = 48000
config.channel_count = 2
config.quality = hca.HcaQuality.HIGH

hca_bytes = hca.encode(Path("source.wav").read_bytes(), config)
Path("encoded.hca").write_bytes(hca_bytes)

encrypted = hca.encrypt(hca_bytes, cipher_type=56, keycode=0xCF222F1FE0748978)
Path("encrypted.hca").write_bytes(encrypted)
```

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

### Encode audio formats

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Convert WAV files into HCA, ADX, or AHX formats with optional quality and header configurations.

```sh
cricodecs --encode -f hca input.wav -o output.hca
cricodecs --encode -f adx input.wav -o output.adx
cricodecs --encode -f ahx input.wav -o output.ahx

# Select HCA encoder behavior explicitly.
cricodecs --encode -f hca input.wav -o output.hca \
  --header-version 3.00 --quality low --bitrate 192000 --ms-stereo

# ADX supports modes 2/3/4 and header versions 3/4/5.
cricodecs --encode -f adx input.wav -o output.adx \
  --mode 4 --header-version 3 --highpass 500 --trim-after-loop

# AHX supports modes 0x10/0x11 and the built-in allocation profiles.
cricodecs --encode -f ahx input.wav -o output.ahx \
  --mode 0x11 --profile 22050
```

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

### Decode ADX Audio

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Load and decode an ADX file using the Adx codec header.

```cpp
#include <filesystem>
#include <fstream>
#include <vector>

#include <cricodecs/adx/adx_codec.hpp>

int main() {
    auto adx = cricodecs::adx::Adx::load("input.adx");
    if (!adx) {
        return 1;
    }

    auto decoded = adx->decode();
    if (!decoded) {
        return 1;
    }

    const auto& pcm = decoded->pcm_data;
    (void)pcm;
}
```

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

### Conditional Subdirectory Inclusion

Source: https://github.com/youjose/cricodecs/blob/main/CMakeLists.txt

Conditionally adds Python and Studio subdirectories based on build flags.

```cmake
if(CRICODECS_BUILD_PYTHON)
    add_subdirectory(PyCriCodecs)
endif()

if(CRICODECS_BUILD_CRISTUDIO)
    add_subdirectory(CriStudio)
endif()
```

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

### adx.decode / adx.encode

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Methods for decoding ADX audio files to WAV bytes and encoding WAV bytes into ADX format.

```APIDOC
## adx.decode(path)

### Description
Decodes an ADX file into raw WAV bytes.

### Parameters
- **path** (str) - Required - Path to the .adx file.

## adx.encode(data)

### Description
Encodes raw WAV bytes into ADX format.

### Parameters
- **data** (bytes) - Required - Raw WAV data.
```

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

### Define CPK Chunk Header Types

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Enumeration of known CPK table types used for parsing.

```python
class CPKChunkHeaderType(Enum):
    CPK   = b"CPK "
    TOC   = b"TOC "
    ITOC  = b"ITOC"
    ETOC  = b"ETOC"
    GTOC  = b"GTOC"
    HTOC  = b"HTOC"
    HGTOC = b"HGTOC"
```

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

### ADX Decoding

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Load and decode an ADX audio file using the cricodecs::adx::Adx class.

```APIDOC
## cricodecs::adx::Adx::load

### Description
Loads an ADX file from the filesystem.

### Signature
static std::expected<Adx, std::string> load(const std::filesystem::path& path);

## cricodecs::adx::Adx::decode

### Description
Decodes the loaded ADX data into PCM format.

### Signature
std::expected<DecodedAdx, std::string> decode() const;
```

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

### hca.decode / hca.encode / hca.encrypt

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Methods for handling HCA audio files, including decoding with keycodes, encoding with configuration, and encryption.

```APIDOC
## hca.decode(path, keycode)

### Description
Decodes an HCA file into WAV bytes using a specific keycode.

## hca.encode(data, config)

### Description
Encodes WAV bytes into HCA format using the provided HcaEncodeConfig.

## hca.encrypt(data, cipher_type, keycode)

### Description
Encrypts HCA bytes using a specified cipher type and keycode.
```

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

### Mutate archive contents

Source: https://github.com/youjose/cricodecs/blob/main/USAGE.md

Perform file operations such as adding, replacing, renaming, removing, or moving entries within an archive.

```sh
cricodecs archive.cpk --add local.bin=data/local.bin -o updated.cpk
cricodecs archive.cpk --replace data/old.bin=replacement.bin -o updated.cpk
cricodecs archive.cpk --rename data/old.bin=data/new.bin -o updated.cpk
cricodecs archive.cpk --remove data/unused.bin -o updated.cpk
cricodecs archive.cpk --move 4=1 -o updated.cpk
```

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

### ADX Encoding Function Signature

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Python function signature for encoding data into ADX format with configurable parameters.

```python
def encode(data: bytes, BitDepth = 0x4, Blocksize = 0x12, Encoding = 3, AdxVersion = 0x4, Highpass_Frequency = 0x1F4, Filter = 0, force_not_looping = False) -> bytes
```

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

### Decode HCA Audio

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Decode HCA data using a specific key.

```cpp
#include <cstdint>
#include <vector>

#include <cricodecs/hca/hca_codec.hpp>

std::vector<int16_t> decode_hca(std::span<const uint8_t> bytes) {
    auto decoded = cricodecs::hca::decode(bytes, 0xCF222F1FE0748978ULL);
    if (!decoded) {
        return {};
    }
    return std::move(*decoded);
}
```

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

### ADX Header Structure Definition

Source: https://github.com/youjose/cricodecs/wiki/Docs-and-Thoughts

Defines the C++ structure for an ADX file header, including fields for encoding mode, block size, and sample rate.

```C++
struct AdxHeader{
    unsigned short Signature;         /* 0x8000 */
    unsigned short DataOffset;        /* Good to standardize, but made variable here for generic purposes. */
    unsigned char  EncodingMode;      /* Fixed = 2, Linear = 3, Exponential = 4 */
    unsigned char  BlockSize;         /* 0x12 standardized in ADXPlay, but made variable in this encoder and will pad the PCM data if needed, change with care. */
    unsigned char  BitDepth;          /* Fixed at 4 in ADXPlay, but made variable here as long as it fits into BlockSize, change with care. */
    unsigned char  Channels;          /* Same as input PCM */
    unsigned int   SampleRate;        /* Same as input PCM */
    unsigned int   SampleCount;       /* Same as input PCM, calculated for per channel in ADX. */
    unsigned short HighpassFrequency; /* Cutoff Frequency. Not sure what it does, saw some say it alleviates noise when compressing. */
    unsigned char  AdxVersion;        /* 3, 4, or 5. 3 is an old version, 4 is most used, 5 does not support Looping it seems. */
    unsigned char  Flag;              /* 8 or 9 for encryption, unsupported if so. AHX can also be encrypted. */
};
```

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

### HCA Decoding

Source: https://github.com/youjose/cricodecs/blob/main/README.md

Decode HCA audio data from a byte span using a specific key.

```APIDOC
## cricodecs::hca::decode

### Description
Decodes HCA data provided as a byte span using a decryption key.

### Signature
std::expected<std::vector<int16_t>, std::string> decode(std::span<const uint8_t> bytes, uint64_t key);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.