cridecoder 0.2.3__tar.gz → 0.3.1__tar.gz

{cridecoder-0.2.3 → cridecoder-0.3.1}/.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable

{cridecoder-0.2.3 → cridecoder-0.3.1}/.github/workflows/release-crate.yml

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

{cridecoder-0.2.3 → cridecoder-0.3.1}/.github/workflows/release-python.yml

@@ -22,7 +22,7 @@ jobs:
       matrix:
         target: [x86_64, aarch64]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |
@@ -51,7 +51,7 @@ jobs:
       matrix:
         target: [x86_64, aarch64]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |
@@ -87,7 +87,7 @@ jobs:
   windows:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set version from tag
         if: github.event_name == 'release'
         shell: bash
@@ -124,7 +124,7 @@ jobs:
   sdist:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set version from tag
         if: github.event_name == 'release'
         run: |

{cridecoder-0.2.3 → cridecoder-0.3.1}/.gitignore

@@ -30,3 +30,10 @@ test_output_usm/
 *.hca
 *.wav
 *.m2v
+
+# OS / editor / local benchmarking
+.DS_Store
+.idea/
+bench/
+__pycache__/
+*.pyc

{cridecoder-0.2.3 → cridecoder-0.3.1}/Cargo.lock

@@ -28,12 +28,13 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "cridecoder"
-version = "0.2.3"
+version = "0.3.1"
 dependencies = [
  "byteorder",
  "encoding_rs",
  "hex",
  "pyo3",
+ "rustc-hash",
  "serde",
  "serde_json",
  "tempfile",
@@ -204,9 +205,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91fd8e38a3b50ed1167fb981cd6fd60147e091784c427b8f7183a7ee32c31c12"
+checksum = "cd274650b21d4bfc26a0a47587962c1edb425f69287324355cd040c3ea66071c"
 dependencies = [
  "libc",
  "once_cell",
@@ -218,18 +219,18 @@ dependencies = [
 
 [[package]]
 name = "pyo3-build-config"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e"
+checksum = "c5e2a7d2f0d013342f295c048ad19237add5154a55b1c5a254c0ec93d4109078"
 dependencies = [
  "target-lexicon",
 ]
 
 [[package]]
 name = "pyo3-ffi"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e"
+checksum = "ca85c467da1bbc8d866eea5deff9cf29ea5f7785054a17da36e65bda9c05845b"
 dependencies = [
  "libc",
  "pyo3-build-config",
@@ -237,9 +238,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df6e520eff47c45997d2fc7dd8214b25dd1310918bbb2642156ef66a67f29813"
+checksum = "9ac53762fd065daa3194dd09337a38bd793a188100fd1a9304c4ab312d901771"
 dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
@@ -249,13 +250,12 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros-backend"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4cdc218d835738f81c2338f822078af45b4afdf8b2e33cbb5916f108b813acb"
+checksum = "4ca3a1557399783172dc5bf39cfca835157732532cba56b71d2292161e53b362"
 dependencies = [
  "heck",
  "proc-macro2",
- "pyo3-build-config",
  "quote",
  "syn",
 ]
@@ -275,6 +275,12 @@ version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
 [[package]]
 name = "rustix"
 version = "1.1.4"

{cridecoder-0.2.3 → cridecoder-0.3.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cridecoder"
-version = "0.2.3"
+version = "0.3.1"
 edition = "2021"
 description = "CRI codec library for ACB/AWB, HCA audio, and USM video extraction"
 license = "MIT"
@@ -33,7 +33,8 @@ encoding_rs = "0.8"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 hex = "0.4"
-pyo3 = { version = "0.28", features = ["extension-module"], optional = true }
+rustc-hash = "2"
+pyo3 = { version = "0.29", features = ["extension-module"], optional = true }
 
 [dev-dependencies]
 tempfile = "3"

cridecoder-0.3.1/KNOWN_GAPS.md

@@ -0,0 +1,84 @@
+# Known gaps / deferred items
+
+These are confirmed divergences from CRI/vgmstream behavior that are **intentionally
+not implemented yet**. All of them are **non-essential for the common decode/extract
+path** (and specifically for Project Sekai assets, which use unencrypted HCA-MX in
+ACB/AWB and VP9 USM). They are deferred because they are either pure performance,
+unreachable without new API, or deep restructures with **no test fixtures**, where a
+blind change to working code carries more regression risk than value.
+
+Verified against vgmstream `3f860bef` (`src/coding/libs/clhca.c`, `src/meta/acb.c`,
+`src/meta/awb.c`) and PyCriCodecs `usm.py` / `acb.py`.
+
+## ACB
+
+### Command / Synth traversal breadth — `src/acb/track.rs`
+`extract_tracks_from_event` / `extract_track_from_command` handle only the common path:
+command `0x07d0` (noteOn 2000) → `u1 == 2` (Synth) → **first** ReferenceItem →
+item-type 1 (Waveform). vgmstream (`acb.c:481-600`) also accepts noteOn `2003`, follows
+`tlv_type == 3` (Sequence), iterates **all** ReferenceItems, and recurses on item-types
+2 (Synth) and 3 (Sequence).
+- **Impact:** ACBs whose cues fan out to multiple/ nested waveforms extract only the
+  first. pjsk cues are single `noteOn → Synth → one Waveform`, so unaffected.
+- **Why deferred:** rewriting the core recursive traversal can silently change output
+  (extra/duplicate/mis-named tracks) on real multi-Synth/Sequence ACBs, and the test
+  ACBs are builder-made single-cue — no fixture would catch a semantic regression.
+  Needs a real multi-reference ACB fixture first.
+
+### Type-8 BlockSequence — `src/acb/track.rs`
+Cue `ReferenceType == 8` is currently routed through the Sequence path. vgmstream uses a
+dedicated `load_acb_blocksequence` → `load_acb_block` over the Block/BlockSequence tables
+(`acb.c:826-968`), which cridecoder does not parse. (Unknown ref types are now skipped
+rather than erroring; see commit `e958c9f`.)
+- **Impact:** none for pjsk (cues are type 3).
+- **Why deferred:** requires new Block/BlockSequence table parsing; implementable from
+  vgmstream but unverifiable without a type-8 fixture.
+
+### Legacy `Id` waveform field — `src/acb/track.rs`
+`extract_track_from_command` selects the waveform id from `StreamAwbId`/`MemoryAwbId`
+keyed on the `Streaming` flag. vgmstream (`acb.c:335-363`) first tries the legacy single
+`Id` column, falling back by `acb->is_memory`.
+- **Impact:** old ACBs that carry only `Id` (no split ids) resolve to id 0. pjsk uses
+  split ids, so unaffected.
+- **Why deferred:** `get_int_field` returns 0 for an absent column (can't distinguish
+  absent from 0); doing this correctly needs an optional column reader. Additive and
+  low-risk, but the legacy path has no fixture.
+
+## USM
+
+### Per-channel (`chno`) multi-track — `src/usm/extractor.rs`
+The `chno` byte (chunk offset 0x0C) is read but not used to separate streams; all `@SFA`
+chunks merge into one audio output. vgmstream/PyCriCodecs key outputs by
+`<signature>_<chno>`.
+- **Impact:** multi-track audio interleaves into one corrupt file. pjsk USMs are single
+  video + single audio (`chno == 0`), so unaffected.
+- **Why deferred:** requires restructuring the output path to per-`chno` sinks; the
+  single-track path is testable but multi-track has no fixture.
+
+## HCA encoder (PCM → HCA; not used for decoding/extraction)
+
+### Loop frame alignment (P17) — `src/hca/encoder.rs`
+The encoder does not apply CRI's loop pipeline (delay bump, 2048-byte loop-frame
+alignment, post-loop tail) from `clhca.c`, so a loop encoded by cridecoder would loop at
+the wrong sample in clHCA players.
+- **Status:** there is currently **no builder/encoder API that exposes loop config**, so
+  this code path is unreachable — implementing it would be dead, untestable code.
+  `HcaEncoderConfig.loop_start/loop_end` (if/when added) are therefore **not
+  CRI-accurate**. Documented here rather than implemented.
+
+### MDCT is O(N²) — `src/hca/encoder.rs`
+`mdct_transform` computes the forward DCT-IV as a naive double loop (`cos()` per (n,k)
+pair, ~16384 calls/subframe). It is mathematically correct (round-trips), just slow. The
+**decoder** side (`imdct.rs`) already uses a factorized DCT-IV with precomputed
+`SIN_TABLES`/`COS_TABLES`; the encoder could reuse the same approach (O(N log N)).
+- **Impact:** encoding speed only. Decoding (the pjsk path) is unaffected.
+- **Why deferred:** bit-sensitive rewrite; the existing round-trip tests only assert
+  non-empty output, so a proper encode→decode→compare-to-input fidelity test should be
+  added as a guard before changing it.
+
+## Intentionally not changed
+
+### ms_stereo permissiveness — `src/hca/decoder.rs`
+cridecoder decodes ms_stereo HCA; vgmstream (`clhca.c:985`) rejects it as
+`HCA_ERROR_HEADER` (`//TODO: should work but untested`). cridecoder's behavior is the
+more permissive (and arguably more useful) one, so this divergence is **kept on purpose**.

{cridecoder-0.2.3 → cridecoder-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cridecoder
-Version: 0.2.3
+Version: 0.3.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

cridecoder-0.3.1/cridecoder.pyi

@@ -0,0 +1,176 @@
+"""Type stubs for cridecoder — CRI codec library (ACB/AWB, HCA audio, USM video).
+
+These signatures mirror the PyO3 bindings in `src/python.rs`. Arguments typed
+`Optional[...]` without a default are required but accept ``None``; arguments
+with a default are optional.
+"""
+
+from typing import Optional
+
+__all__ = [
+    "extract_acb",
+    "extract_acb_tracks",
+    "decode_acb_to_wav",
+    "build_acb",
+    "build_acb_bytes",
+    "build_music_acb_bytes",
+    "decode_hca",
+    "decode_hca_bytes",
+    "encode_hca",
+    "encode_hca_bytes",
+    "extract_usm",
+    "build_usm",
+    "build_usm_bytes",
+    "read_usm_metadata",
+]
+
+# --- ACB ---------------------------------------------------------------------
+
+def extract_acb(acb_path: str, output_dir: str) -> Optional[list[str]]:
+    """Extract audio tracks from an ACB file to ``output_dir``.
+
+    Returns the list of written file paths, or ``None`` if the file is invalid.
+    """
+    ...
+
+def extract_acb_tracks(
+    acb_path: str, output_dir: str
+) -> Optional[list[dict[str, object]]]:
+    """Extract audio tracks from an ACB, returning per-track metadata.
+
+    Like :func:`extract_acb`, but each entry is a dict with ``path`` (written
+    file), ``name`` (cue name), ``cue_id`` and ``subkey`` — the AFS2 subkey of
+    the originating AWB, needed (with the global keycode) to decode type-56
+    encrypted HCA. Returns ``None`` if the file is invalid.
+    """
+    ...
+
+def decode_acb_to_wav(
+    acb_path: str, output_dir: str, key: Optional[int] = ...
+) -> list[str]:
+    """Extract an ACB and decode its HCA tracks straight to WAV files.
+
+    The per-AWB AFS2 subkey is applied automatically, so encrypted (type-56)
+    ACBs only need the global ``key`` (omit/``None`` for unencrypted ACBs).
+    Non-HCA tracks are written verbatim with their original extension. Returns
+    the list of written file paths.
+    """
+    ...
+
+def build_acb(tracks: list[tuple[str, int, bytes]], output_path: str) -> None:
+    """Build an ACB file from ``(name, cue_id, hca_data)`` tuples, writing to disk."""
+    ...
+
+def build_acb_bytes(tracks: list[tuple[str, int, bytes]]) -> bytes:
+    """Build an ACB from ``(name, cue_id, hca_data)`` tuples and return the bytes."""
+    ...
+
+def build_music_acb_bytes(
+    name: str,
+    hca_data: bytes,
+    cue_id: int,
+    virtual_cue_suffix: Optional[str],
+    memory_awb_id: int,
+    reference_num_samples: int,
+    reference_length_ms: int,
+    acb_version: int,
+    acf_md5_hash: bytes,
+    acb_guid: bytes,
+    version_string: str,
+    acb_volume: float,
+    category_extension: int,
+    cue_priority_type: int,
+    acf_category_name: str,
+    acf_category_id: int,
+    acf_bus_names: list[str],
+) -> bytes:
+    """Build a single-track music ACB from one HCA track and return the bytes.
+
+    ``acf_md5_hash`` and ``acb_guid`` are 16-byte values; ``virtual_cue_suffix``
+    may be ``None`` for no paired virtual cue.
+    """
+    ...
+
+# --- HCA ---------------------------------------------------------------------
+
+def decode_hca(
+    hca_path: str,
+    wav_path: str,
+    key: Optional[int] = ...,
+    subkey: Optional[int] = ...,
+) -> dict[str, int]:
+    """Decode an HCA file to a WAV file.
+
+    ``key``/``subkey`` apply the type-56 decryption keycode for encrypted HCA
+    (no-op for unencrypted files). Returns a dict with ``sample_rate``,
+    ``channels``, ``block_count``, ``block_size``, ``encoder_delay`` and
+    ``samples_per_block``.
+    """
+    ...
+
+def decode_hca_bytes(
+    hca_data: bytes,
+    key: Optional[int] = ...,
+    subkey: Optional[int] = ...,
+) -> bytes:
+    """Decode HCA bytes to WAV bytes in memory (``key``/``subkey`` as in :func:`decode_hca`)."""
+    ...
+
+def encode_hca_bytes(
+    wav_data: bytes,
+    sample_rate: Optional[int] = ...,
+    channels: Optional[int] = ...,
+    bitrate: int = ...,
+    encryption_key: Optional[int] = ...,
+) -> bytes:
+    """Encode WAV bytes to HCA bytes.
+
+    ``sample_rate``/``channels`` default to the WAV header when ``None``;
+    ``bitrate`` defaults to 256000 bps. Supports 16/24/32-bit PCM input.
+    """
+    ...
+
+def encode_hca(
+    wav_path: str,
+    hca_path: str,
+    bitrate: int = ...,
+    encryption_key: Optional[int] = ...,
+) -> dict[str, int]:
+    """Encode a WAV file to an HCA file. Returns a dict with ``size`` and ``bitrate``."""
+    ...
+
+# --- USM ---------------------------------------------------------------------
+
+def extract_usm(
+    usm_path: str,
+    output_dir: str,
+    key: Optional[int] = ...,
+    export_audio: bool = ...,
+) -> list[str]:
+    """Extract video (and optionally audio) streams from a USM file.
+
+    ``key`` decrypts encrypted USMs; ``export_audio`` (default ``False``) also
+    writes audio streams. Returns the list of written file paths.
+    """
+    ...
+
+def build_usm(
+    name: str,
+    video_data: bytes,
+    output_path: str,
+    encryption_key: Optional[int] = ...,
+) -> None:
+    """Build a USM file from M2V video data, writing to disk."""
+    ...
+
+def build_usm_bytes(
+    name: str,
+    video_data: bytes,
+    encryption_key: Optional[int] = ...,
+) -> bytes:
+    """Build a USM from M2V video data and return the bytes."""
+    ...
+
+def read_usm_metadata(usm_path: str) -> str:
+    """Read USM metadata and return it as a pretty-printed JSON string."""
+    ...

cridecoder-0.3.1/examples/profile_hca.rs

@@ -0,0 +1,48 @@
+//! HCA decode profiling harness. Decodes the file many times in a tight loop so
+//! a sampling profiler (`sample <pid>`) can attribute CPU time to hot functions.
+//!
+//! Also reports pure-Rust decode timing (to /dev/null, no WAV Vec growth and no
+//! input copy), isolating the decoder core from Python-binding overhead.
+
+use cridecoder::HcaDecoder;
+use std::env;
+use std::io::sink;
+use std::time::Instant;
+
+fn main() {
+    let args: Vec<String> = env::args().collect();
+    let hca_file = args.get(1).map(|s| s.as_str()).unwrap_or("music_5031.hca");
+    let iters: usize = args.get(2).and_then(|s| s.parse().ok()).unwrap_or(400);
+
+    let probe = HcaDecoder::from_file(hca_file).expect("open HCA");
+    println!(
+        "profiling: {} iters, {} blocks, {} ch, sr {}",
+        iters,
+        probe.info().block_count,
+        probe.info().channel_count,
+        probe.info().sampling_rate
+    );
+
+    // Warm up once.
+    {
+        let mut d = HcaDecoder::from_file(hca_file).unwrap();
+        d.decode_to_wav(&mut sink()).unwrap();
+    }
+
+    // Timed pure-decode loop: decode to /dev/null so we measure only the core.
+    let start = Instant::now();
+    let mut total = 0u64;
+    for _ in 0..iters {
+        let mut d = HcaDecoder::from_file(hca_file).unwrap();
+        d.decode_to_wav(&mut sink()).unwrap();
+        total += 1;
+    }
+    let elapsed = start.elapsed();
+    println!(
+        "pure decode core: {} iters in {:?} = {:.3} ms/decode (to /dev/null)",
+        iters,
+        elapsed,
+        elapsed.as_secs_f64() * 1000.0 / iters as f64
+    );
+    std::hint::black_box(total);
+}

{cridecoder-0.2.3 → cridecoder-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cridecoder"
-version = "0.2.3"
+version = "0.3.1"
 description = "CRI codec library for ACB/AWB, HCA audio, and USM video extraction"
 readme = "README.md"
 license = { text = "MIT" }

{cridecoder-0.2.3 → cridecoder-0.3.1}/src/acb/afs.rs

@@ -86,7 +86,13 @@ impl<R: Read + Seek> AfsArchive<R> {
         let mut files = Vec::with_capacity(file_count as usize);
         for i in 0..file_count as usize {
             let aligned_offset = align(alignment, offsets[i]);
-            let next_offset = offsets[i + 1];
+            // Align the next boundary too (except the final archive end), matching
+            // vgmstream awb.c so a subfile's size spans up to the next aligned start.
+            let next_offset = if i + 1 < file_count as usize {
+                align(alignment, offsets[i + 1])
+            } else {
+                offsets[i + 1]
+            };
             let size = next_offset - aligned_offset;
 
             files.push(AfsFileEntry {

{cridecoder-0.2.3 → cridecoder-0.3.1}/src/acb/consts.rs

@@ -52,7 +52,9 @@ pub fn wave_type_extension(enc_type: i32) -> &'static str {
         WAVEFORM_ENCODE_TYPE_HCA => ".hca",
         WAVEFORM_ENCODE_TYPE_WII_ADPCM => ".wiiadpcm",
         WAVEFORM_ENCODE_TYPE_DS_ADPCM => ".dsadpcm",
-        WAVEFORM_ENCODE_TYPE_HCA_MX => ".hcamx",
+        // 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",
@@ -83,7 +85,7 @@ mod tests {
             wave_type_extension(WAVEFORM_ENCODE_TYPE_DS_ADPCM),
             ".dsadpcm"
         );
-        assert_eq!(wave_type_extension(WAVEFORM_ENCODE_TYPE_HCA_MX), ".hcamx");
+        assert_eq!(wave_type_extension(WAVEFORM_ENCODE_TYPE_HCA_MX), ".hca");
         assert_eq!(wave_type_extension(WAVEFORM_ENCODE_TYPE_VAG), ".vag");
         assert_eq!(wave_type_extension(WAVEFORM_ENCODE_TYPE_ATRAC3), ".at3");
         assert_eq!(wave_type_extension(WAVEFORM_ENCODE_TYPE_BCWAV), ".bcwav");