cridecoder 0.1.0__tar.gz

cridecoder-0.1.0/.github/copilot-Instructions.md

@@ -0,0 +1,51 @@
+# Copilot Instructions for cridecoder
+
+## Project Context
+
+This is a pure Rust library (`cridecoder`) for decoding CRI Middleware audio/video formats (ACB, HCA, USM). The CRI format implementation is based on [vgmstream](https://github.com/vgmstream/vgmstream). It also provides optional Python bindings via pyo3/maturin.
+
+## Code Style
+
+- **Rust edition**: 2021
+- **Error handling**: Use `thiserror` derive macros for error enums
+- **Binary I/O**: Use the `reader.rs` wrapper around `byteorder` for all binary reading
+- **Text encoding**: CRI formats use Shift-JIS; use `encoding_rs::SHIFT_JIS` for decoding
+- **Module structure**: Use Rust 2018+ flat module style (`src/acb.rs` + `src/acb/` directory), not `mod.rs`
+- **Feature gates**: Python bindings use `#[cfg(feature = "python")]` — pure Rust builds should not depend on pyo3
+- **Tests**: Unit tests are inline `#[cfg(test)] mod tests`, integration tests are in `tests/`
+
+## Important Notes
+
+- The `ClHca` struct (HCA decoder state) is very large (~200KB on stack). Use `RUST_MIN_STACK=16777216` when running integration tests
+- ACB files may contain embedded AWB data or reference external `.awb` files
+- HCA files support encryption — use `HcaDecoder::set_key()` or `KeyTest` for key testing
+- USM files contain interleaved video (M2V) and audio (ADX) chunks with XOR masking
+
+## Public API
+
+```rust
+// ACB
+pub fn extract_acb_from_file(path, output_dir) -> Result<Option<Vec<String>>>
+pub fn extract_acb(reader, output_dir, awb_reader) -> Result<Vec<String>>
+
+// HCA
+pub struct HcaDecoder { ... }
+impl HcaDecoder {
+    pub fn from_file(path) -> Result<Self>
+    pub fn from_reader(reader) -> Result<Self>
+    pub fn info(&self) -> &HcaInfo
+    pub fn decode_to_wav(&mut self, writer) -> Result<()>
+    pub fn decode_all(&mut self) -> Result<Vec<f32>>
+}
+
+// USM
+pub fn extract_usm_file(path, output_dir, key, export_audio) -> Result<Vec<PathBuf>>
+pub fn extract_usm(reader, output_dir, name, key, export_audio) -> Result<Vec<PathBuf>>
+```
+
+## Testing
+
+```bash
+cargo test                              # Unit tests only
+RUST_MIN_STACK=16777216 cargo test       # Full test suite (needs test fixture files)
+```

cridecoder-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_MIN_STACK: "16777216"
+
+jobs:
+  test:
+    name: Test (Rust)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test
+      - run: cargo clippy -- -D warnings
+
+  fmt:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all --check

cridecoder-0.1.0/.github/workflows/release-crate.yml

@@ -0,0 +1,21 @@
+name: Release Crate
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish-crate:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Verify package
+        run: cargo publish --dry-run
+      - name: Publish
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

cridecoder-0.1.0/.github/workflows/release-python.yml

@@ -0,0 +1,139 @@
+name: Release Python
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # ──────────────────────────────────────────────
+  # Build wheels for Linux (x86_64, aarch64)
+  # ──────────────────────────────────────────────
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --find-interpreter
+          sccache: "true"
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  # ──────────────────────────────────────────────
+  # Build wheels for macOS (x86_64, aarch64)
+  # ──────────────────────────────────────────────
+  macos:
+    runs-on: macos-15
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: |
+            3.9
+            3.10
+            3.11
+            3.12
+            3.13
+            3.14
+            3.14t
+          allow-prereleases: true
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --find-interpreter
+          sccache: "true"
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  # ──────────────────────────────────────────────
+  # Build wheels for Windows (x86_64)
+  # ──────────────────────────────────────────────
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: |
+            3.9
+            3.10
+            3.11
+            3.12
+            3.13
+            3.14
+            3.14t
+          allow-prereleases: true
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist --find-interpreter
+          sccache: "true"
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-windows-x64
+          path: dist
+
+  # ──────────────────────────────────────────────
+  # Build source distribution
+  # ──────────────────────────────────────────────
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # ──────────────────────────────────────────────
+  # Publish all wheels + sdist to PyPI
+  # ──────────────────────────────────────────────
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [linux, macos, windows, sdist]
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cridecoder
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist/
+      - name: Publish to PyPI
+        uses: PyO3/maturin-action@v1
+        with:
+          command: upload
+          args: --non-interactive --skip-existing dist/*

cridecoder-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# Generated by cargo mutants
+# Contains mutation testing data
+**/mutants.out*/
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Test output
+test_output_acb/
+test_output_usm/
+
+# Test data files (large binary)
+*.acb
+*.usm
+*.hca
+*.wav
+*.m2v

cridecoder-0.1.0/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+## Project Overview
+
+**cridecoder** is a pure Rust library for decoding CRI Middleware formats, with optional Python bindings via pyo3/maturin.
+
+### Credits
+
+CRI format implementation is based on [vgmstream](https://github.com/vgmstream/vgmstream).
+
+## Architecture
+
+```
+src/
+├── lib.rs          # Crate root, re-exports public API, #[pymodule] (behind "python" feature)
+├── reader.rs       # Binary reader utilities (endianness, primitive types, alignment)
+├── acb.rs          # ACB module root (re-exports submodules)
+├── acb/
+│   ├── consts.rs   # ACB/UTF constants and helpers
+│   ├── utf.rs      # CRI UTF table parser
+│   ├── afs.rs      # AFS2 archive parser
+│   ├── track.rs    # Track list extraction from ACB
+│   └── extractor.rs # ACB extraction logic
+├── hca.rs          # HCA module root (re-exports submodules)
+├── hca/
+│   ├── decoder.rs  # Core HCA decoder (ClHca, header parsing, block decoding)
+│   ├── hca_file.rs # High-level HcaDecoder with streaming, WAV output, key testing
+│   ├── tables.rs   # Lookup tables for HCA decoding
+│   ├── cipher.rs   # HCA encryption/decryption cipher
+│   ├── ath.rs      # ATH (Absolute Threshold of Hearing) tables
+│   ├── bitreader.rs # Bit-level reader/writer
+│   └── imdct.rs    # Inverse MDCT transform
+├── usm.rs          # USM module root (re-exports submodules)
+├── usm/
+│   ├── extractor.rs # USM extraction (video/audio stream demuxing)
+│   └── metadata.rs  # USM metadata reading and JSON export
+└── python.rs       # Python bindings (behind "python" feature)
+```
+
+## Key Types
+
+- `extract_acb_from_file()` / `extract_acb()` — ACB extraction entry points
+- `HcaDecoder` — High-level HCA to WAV/PCM decoder
+- `extract_usm_file()` / `extract_usm()` — USM extraction entry points
+- `ClHca` — Low-level HCA decoder state machine
+
+## Building
+
+```bash
+# Pure Rust
+cargo build
+cargo test                              # Unit tests only
+RUST_MIN_STACK=16777216 cargo test       # Unit + integration tests (HCA needs larger stack)
+
+# Python extension
+python3 -m maturin build --release
+
+# crates.io dry run
+cargo publish --dry-run --allow-dirty
+```
+
+## Testing
+
+- **Unit tests**: Inline `#[cfg(test)] mod tests` in most modules
+- **Integration tests**: `tests/integration_tests.rs` — requires `se_0126_01.acb` and `0703.usm` test fixtures in project root
+- Integration tests need `RUST_MIN_STACK=16777216` due to large `ClHca` struct
+
+## Conventions
+
+- Use `thiserror` for error types
+- Use `byteorder` for binary reading via the `reader.rs` wrapper
+- Use `encoding_rs` for Shift-JIS text decoding (CRI uses Shift-JIS strings)
+- Public API lives in module root files (`acb.rs`, `hca.rs`, `usm.rs`); internals are `mod` (private)
+- Python bindings are behind `#[cfg(feature = "python")]` so they're opt-in