cridecoder 0.1.2__tar.gz → 0.2.1__tar.gz

cridecoder-0.2.1/.github/copilot-instructions.md

@@ -0,0 +1,105 @@
+# 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)
+```
+
+## Git commits
+
+All commit subjects must follow:
+
+```text
+[Type] Short description starting with capital letter
+```
+
+Allowed types:
+
+| Type      | Usage                                                 |
+|-----------|-------------------------------------------------------|
+| `[Feat]`  | New feature or capability                             |
+| `[Fix]`   | Bug fix                                               |
+| `[Chore]` | Maintenance, refactoring, dependency or build changes |
+| `[Docs]`  | Documentation-only changes                            |
+
+Rules:
+
+- Description starts with a capital letter.
+- Use imperative mood: `Add ...`, not `Added ...`.
+- No trailing period.
+- Keep the subject at or below roughly 70 characters.
+- **Agent attribution uses the standard Git `Co-authored-by:` trailer in the commit body, not a free-form `Agent:` line.** This makes GitHub render the co-author avatar on the commit page. The trailer must be on its own line, separated from the subject by a blank line, in the form `Co-authored-by: <Display Name> <email>`. Suggested values per agent:
+  - Claude (any 4.x): `Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>` (substitute the actual model, e.g. `Claude Sonnet 4.6`, `Claude Haiku 4.5`)
+  - Codex: `Co-authored-by: Codex <noreply@openai.com>`
+  - Copilot: `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>`
+
+Examples from this repo's history:
+
+```text
+[Feat] Add encoding Python bindings
+[Fix] Resolve check and clippy warnings
+[Chore] Configure Dependabot updates
+[Feat] Add encoding support but not tested in game
+```
+
+## GitHub Actions workflows
+
+Use the standardized workflow layout in `.github/workflows`:
+
+- `ci.yml` runs on `main` pushes, pull requests targeting `main`, and manual dispatch.
+- Rust CI order: `cargo fmt --all -- --check`, `cargo check --locked --all-targets`, `cargo clippy --locked --all-targets -- -D warnings`, then `cargo test --locked`.
+- `release-crate.yml` publishes the Rust crate and keeps its package-specific release flow.
+- `release-python.yml` builds and publishes Python artifacts and keeps its package-specific release flow.
+
+Workflow maintenance rules:
+
+- Keep workflow filenames and top-level names aligned: `CI`, `Release`, `Docker`, and optional package-specific names.
+- Use `actions/checkout@v6`, `actions/setup-go@v6`, `actions/upload-artifact@v7`, `actions/download-artifact@v8`, `softprops/action-gh-release@v3`, and current Docker actions (`setup-buildx@v4`, `login@v4`, `metadata@v6`, `build-push@v7`).
+- Keep `permissions` minimal: `contents: read` for CI/Docker build-only work, `contents: write` for release publishing, and `packages: write` only when pushing container images.
+- Use workflow `concurrency` keyed by workflow name and ref, with release jobs using `release-${{ github.ref_name }}` and `cancel-in-progress: false`.
+- Do not reintroduce legacy workflow names such as `rust-ci.yml`, `build.yml`, `release-build.yml`, `docker-build.yml`, or `docker-release.yml` unless a package-specific workflow already exists and is intentionally preserved.

cridecoder-0.2.1/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Asia/Shanghai"
+    commit-message:
+      prefix: "[Chore] "
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Asia/Shanghai"
+    commit-message:
+      prefix: "[Chore] "
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Asia/Shanghai"
+    commit-message:
+      prefix: "[Chore] "

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: Rust checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache Rust artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Check build
+        run: cargo check --locked --all-targets
+
+      - name: Run Clippy
+        run: cargo clippy --locked --all-targets -- -D warnings
+
+      - name: Run tests
+        run: cargo test --locked

{cridecoder-0.1.2 → cridecoder-0.2.1}/.github/workflows/release-crate.yml

@@ -10,7 +10,7 @@ jobs:
     name: Publish to crates.io
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: Set version from tag

{cridecoder-0.1.2 → cridecoder-0.2.1}/.github/workflows/release-python.yml

@@ -22,7 +22,7 @@ jobs:
       matrix:
         target: [x86_64, aarch64]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |
@@ -37,7 +37,7 @@ jobs:
           sccache: "true"
           manylinux: auto
       - name: Upload wheels
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: wheels-linux-${{ matrix.target }}
           path: dist
@@ -51,7 +51,7 @@ jobs:
       matrix:
         target: [x86_64, aarch64]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |
@@ -76,7 +76,7 @@ jobs:
           args: --release --out dist --find-interpreter
           sccache: "true"
       - name: Upload wheels
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: wheels-macos-${{ matrix.target }}
           path: dist
@@ -87,7 +87,7 @@ jobs:
   windows:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set version from tag
         if: github.event_name == 'release'
         shell: bash
@@ -113,7 +113,7 @@ jobs:
           args: --release --out dist --find-interpreter
           sccache: "true"
       - name: Upload wheels
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: wheels-windows-x64
           path: dist
@@ -124,7 +124,7 @@ jobs:
   sdist:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |
@@ -137,7 +137,7 @@ jobs:
           command: sdist
           args: --out dist
       - name: Upload sdist
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         with:
           name: wheels-sdist
           path: dist
@@ -156,7 +156,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8
         with:
           pattern: wheels-*
           merge-multiple: true

cridecoder-0.2.1/AGENTS.md

@@ -0,0 +1,128 @@
+# 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
+
+## Git commits
+
+All commit subjects must follow:
+
+```text
+[Type] Short description starting with capital letter
+```
+
+Allowed types:
+
+| Type      | Usage                                                 |
+|-----------|-------------------------------------------------------|
+| `[Feat]`  | New feature or capability                             |
+| `[Fix]`   | Bug fix                                               |
+| `[Chore]` | Maintenance, refactoring, dependency or build changes |
+| `[Docs]`  | Documentation-only changes                            |
+
+Rules:
+
+- Description starts with a capital letter.
+- Use imperative mood: `Add ...`, not `Added ...`.
+- No trailing period.
+- Keep the subject at or below roughly 70 characters.
+- **Agent attribution uses the standard Git `Co-authored-by:` trailer in the commit body, not a free-form `Agent:` line.** This makes GitHub render the co-author avatar on the commit page. The trailer must be on its own line, separated from the subject by a blank line, in the form `Co-authored-by: <Display Name> <email>`. Suggested values per agent:
+  - Claude (any 4.x): `Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>` (substitute the actual model, e.g. `Claude Sonnet 4.6`, `Claude Haiku 4.5`)
+  - Codex: `Co-authored-by: Codex <noreply@openai.com>`
+  - Copilot: `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>`
+
+Examples from this repo's history:
+
+```text
+[Feat] Add encoding Python bindings
+[Fix] Resolve check and clippy warnings
+[Chore] Configure Dependabot updates
+[Feat] Add encoding support but not tested in game
+```
+
+## GitHub Actions workflows
+
+Use the standardized workflow layout in `.github/workflows`:
+
+- `ci.yml` runs on `main` pushes, pull requests targeting `main`, and manual dispatch.
+- Rust CI order: `cargo fmt --all -- --check`, `cargo check --locked --all-targets`, `cargo clippy --locked --all-targets -- -D warnings`, then `cargo test --locked`.
+- `release-crate.yml` publishes the Rust crate and keeps its package-specific release flow.
+- `release-python.yml` builds and publishes Python artifacts and keeps its package-specific release flow.
+
+Workflow maintenance rules:
+
+- Keep workflow filenames and top-level names aligned: `CI`, `Release`, `Docker`, and optional package-specific names.
+- Use `actions/checkout@v6`, `actions/setup-go@v6`, `actions/upload-artifact@v7`, `actions/download-artifact@v8`, `softprops/action-gh-release@v3`, and current Docker actions (`setup-buildx@v4`, `login@v4`, `metadata@v6`, `build-push@v7`).
+- Keep `permissions` minimal: `contents: read` for CI/Docker build-only work, `contents: write` for release publishing, and `packages: write` only when pushing container images.
+- Use workflow `concurrency` keyed by workflow name and ref, with release jobs using `release-${{ github.ref_name }}` and `cancel-in-progress: false`.
+- Do not reintroduce legacy workflow names such as `rust-ci.yml`, `build.yml`, `release-build.yml`, `docker-build.yml`, or `docker-release.yml` unless a package-specific workflow already exists and is intentionally preserved.

cridecoder-0.2.1/CLAUDE.md

@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+Repository guidance is maintained in `AGENTS.md`.
+
+Claude Code should read `AGENTS.md` and follow the same build, test, architecture,
+commit, and workflow instructions to avoid duplicated guidance drifting over time.

{cridecoder-0.1.2 → cridecoder-0.2.1}/Cargo.lock

@@ -28,7 +28,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "cridecoder"
-version = "0.1.2"
+version = "0.2.1"
 dependencies = [
  "byteorder",
  "encoding_rs",

{cridecoder-0.1.2 → cridecoder-0.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cridecoder"
-version = "0.1.2"
+version = "0.2.1"
 edition = "2021"
 description = "CRI codec library for ACB/AWB, HCA audio, and USM video extraction"
 license = "MIT"
@@ -16,16 +16,16 @@ exclude = ["*.acb", "*.usm", "*.hca", "*.wav", "*.m2v", "test_output_*"]
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-byteorder = "1.5"
-thiserror = "2.0.18"
-encoding_rs = "0.8.35"
-serde = { version = "1.0.228", features = ["derive"] }
-serde_json = "1.0.149"
-hex = "0.4.3"
+byteorder = "1"
+thiserror = "2"
+encoding_rs = "0.8"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+hex = "0.4"
 pyo3 = { version = "0.28", features = ["extension-module"], optional = true }
 
 [dev-dependencies]
-tempfile = "3.10"
+tempfile = "3"
 
 [features]
 default = []

{cridecoder-0.1.2 → cridecoder-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cridecoder
-Version: 0.1.2
+Version: 0.2.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 
 # cridecoder
 
-A pure Rust library for CRI Middleware codec decoding. Supports ACB/AWB audio containers, HCA (High Compression Audio) decoding, and USM video container extraction.
+A pure Rust library for CRI Middleware codec encoding and decoding. Supports ACB/AWB audio containers, HCA (High Compression Audio) encoding/decoding, and USM video container extraction/building.
 
 ## Credits
 
@@ -26,11 +26,12 @@ This project's CRI format implementation is based on and inspired by [vgmstream]
 
 ## Features
 
-- **ACB/AWB Extraction** — Parse CRI ACB audio containers and extract embedded/external audio tracks
-- **HCA Decoding** — Decode HCA audio to PCM samples (f32 or i16) or WAV files
-- **USM Extraction** — Extract MPEG2 video and ADX audio streams from USM video containers
+- **ACB/AWB Extraction & Building** — Parse and create CRI ACB audio containers
+- **HCA Encoding & Decoding** — Encode PCM to HCA, decode HCA to PCM/WAV
+- **USM Extraction & Building** — Extract or create USM video containers
 - **USM Metadata** — Read and export USM metadata as structured JSON
 - **Key Testing** — Test decryption keys for encrypted HCA files
+- **Encryption Support** — Encode HCA with encryption keys
 - **Pure Rust** — No C dependencies, works on any platform Rust supports
 
 ## Usage
@@ -60,6 +61,22 @@ if let Some(tracks) = tracks {
 }
 ```
 
+### ACB Building
+
+```rust
+use std::io::Cursor;
+use cridecoder::{AcbBuilder, TrackInput};
+
+let hca_data = std::fs::read("track.hca").unwrap();
+let track = TrackInput::new("my_track", 0, hca_data);
+
+let mut builder = AcbBuilder::new();
+builder.add_track(track);
+
+let mut output = Cursor::new(Vec::new());
+builder.build(&mut output, None).unwrap();
+```
+
 ### HCA to WAV
 
 ```rust
@@ -74,6 +91,23 @@ let mut output = File::create("output.wav").unwrap();
 decoder.decode_to_wav(&mut output).unwrap();
 ```
 
+### PCM to HCA
+
+```rust
+use std::io::Cursor;
+use cridecoder::{HcaEncoder, HcaEncoderConfig};
+
+// Generate or load PCM samples (interleaved stereo f32)
+let samples: Vec<f32> = vec![0.0; 44100 * 2]; // 1 second of silence
+
+let config = HcaEncoderConfig::new(44100, 2)  // 44.1kHz stereo
+    .with_bitrate(256_000);  // 256 kbps
+
+let mut encoder = HcaEncoder::new(config).unwrap();
+let mut output = Cursor::new(Vec::new());
+encoder.encode(&samples, &mut output).unwrap();
+```
+
 ### USM Extraction
 
 ```rust
@@ -92,14 +126,29 @@ for file in &files {
 }
 ```
 
+### USM Building
+
+```rust
+use std::io::Cursor;
+use cridecoder::UsmBuilder;
+
+let video_data = std::fs::read("video.m2v").unwrap();
+
+let builder = UsmBuilder::new("my_video".to_string())
+    .video(video_data);
+
+let mut output = Cursor::new(Vec::new());
+builder.build(&mut output).unwrap();
+```
+
 ## Supported Formats
 
-| Format | Description | Operation |
-|--------|-------------|-----------|
-| ACB | CRI Audio Container | Extract embedded HCA/ADX tracks |
-| AWB | CRI Audio Waveform Bank | External track storage for ACB |
-| HCA | High Compression Audio | Decode to WAV/PCM |
-| USM | CRI Video Container | Extract M2V video + ADX audio |
+| Format | Description | Operations |
+|--------|-------------|------------|
+| ACB | CRI Audio Container | Extract / Build |
+| AWB | CRI Audio Waveform Bank | Extract / Build |
+| HCA | High Compression Audio | Encode / Decode |
+| USM | CRI Video Container | Extract / Build |
 
 ## License