cridecoder 0.3.0__tar.gz → 0.3.1__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "cridecoder"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2021"
 description = "CRI codec library for ACB/AWB, HCA audio, and USM video extraction"
 license = "MIT"

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

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

{cridecoder-0.3.0 → cridecoder-0.3.1}/cridecoder.pyi

@@ -9,6 +9,8 @@ from typing import Optional
 
 __all__ = [
     "extract_acb",
+    "extract_acb_tracks",
+    "decode_acb_to_wav",
     "build_acb",
     "build_acb_bytes",
     "build_music_acb_bytes",
@@ -31,6 +33,30 @@ def extract_acb(acb_path: str, output_dir: str) -> Optional[list[str]]:
     """
     ...
 
+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."""
     ...

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cridecoder"
-version = "0.3.0"
+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.3.0 → cridecoder-0.3.1}/src/acb/extractor.rs

@@ -209,11 +209,78 @@ fn get_track_data(
     Ok(None)
 }
 
-/// Convenience function to extract from a file path
-pub fn extract_acb_from_file(
-    acb_path: &Path,
+/// A track extracted to disk together with the metadata needed to decode it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExtractedTrackFile {
+    /// Path of the written waveform file.
+    pub path: String,
+    /// Cue name of the track (also the file stem).
+    pub name: String,
+    /// Cue id of the track.
+    pub cue_id: i32,
+    /// AFS2 subkey of the originating AWB. Required (with the global keycode) to
+    /// decrypt type-56 encrypted HCA; 0 when the AWB is unencrypted.
+    pub subkey: u16,
+}
+
+/// Extract all audio tracks to `target_dir`, returning per-track metadata
+/// (output path, cue name/id, and the originating AWB's AFS2 subkey).
+pub fn extract_acb_tracks<R: Read + Seek>(
+    acb_file: R,
     target_dir: &Path,
-) -> Result<Option<Vec<String>>, ExtractError> {
+    acb_file_path: Option<&Path>,
+) -> Result<Vec<ExtractedTrackFile>, ExtractError> {
+    let utf = UtfTable::new(acb_file)?;
+    let track_list = TrackList::new(&utf)?;
+    let mut embedded_awb = load_embedded_awb(&utf.rows[0]);
+    let mut external_awbs = load_external_awbs(&utf.rows[0], acb_file_path);
+
+    fs::create_dir_all(target_dir)?;
+
+    let mut outputs = Vec::new();
+    for track in &track_list.tracks {
+        if let Some(info) =
+            extract_single_track_file(track, target_dir, &mut embedded_awb, &mut external_awbs)?
+        {
+            outputs.push(info);
+        }
+    }
+    Ok(outputs)
+}
+
+fn extract_single_track_file(
+    track: &Track,
+    target_dir: &Path,
+    embedded_awb: &mut Option<AfsArchive<Cursor<Vec<u8>>>>,
+    external_awbs: &mut [AfsArchive<Cursor<Vec<u8>>>],
+) -> Result<Option<ExtractedTrackFile>, ExtractError> {
+    let ext = wave_type_extension(track.enc_type);
+    let ext = if ext.is_empty() {
+        format!(".{}", track.enc_type)
+    } else {
+        ext.to_string()
+    };
+
+    let filename = format!("{}{}", track.name, ext);
+    let output_path = target_dir.join(&filename);
+
+    let (data, subkey) = match get_track_data(track, embedded_awb, external_awbs)? {
+        Some(d) => d,
+        None => return Ok(None),
+    };
+
+    fs::write(&output_path, data)?;
+    Ok(Some(ExtractedTrackFile {
+        path: output_path.to_string_lossy().into_owned(),
+        name: track.name.clone(),
+        cue_id: track.cue_id,
+        subkey,
+    }))
+}
+
+/// Open and validate an ACB file, returning the seekable handle positioned at
+/// the start, or `None` if the path is missing or is not a valid ACB.
+fn open_validated_acb(acb_path: &Path) -> Result<Option<File>, ExtractError> {
     let info = match fs::metadata(acb_path) {
         Ok(i) => i,
         Err(_) => return Ok(None),
@@ -226,20 +293,40 @@ pub fn extract_acb_from_file(
 
     let mut file = File::open(acb_path)?;
 
-    // Read and validate the first 4 bytes
+    // Read and validate the @UTF magic (0x40 0x55 0x54 0x46)
     let mut header = [0u8; 4];
-    use std::io::Read;
     file.read_exact(&mut header)?;
-
-    // Check for @UTF magic (0x40 0x55 0x54 0x46)
     if header != [0x40, 0x55, 0x54, 0x46] {
         return Ok(None); // Not a valid ACB file
     }
 
-    // Seek back to start
-    use std::io::Seek;
     file.seek(std::io::SeekFrom::Start(0))?;
+    Ok(Some(file))
+}
 
+/// Convenience function to extract from a file path
+pub fn extract_acb_from_file(
+    acb_path: &Path,
+    target_dir: &Path,
+) -> Result<Option<Vec<String>>, ExtractError> {
+    let file = match open_validated_acb(acb_path)? {
+        Some(f) => f,
+        None => return Ok(None),
+    };
     let outputs = extract_acb(file, target_dir, Some(acb_path))?;
     Ok(Some(outputs))
 }
+
+/// Like [`extract_acb_from_file`], but returns per-track metadata (output path,
+/// cue name/id, and AFS2 subkey) instead of just the written paths.
+pub fn extract_acb_tracks_from_file(
+    acb_path: &Path,
+    target_dir: &Path,
+) -> Result<Option<Vec<ExtractedTrackFile>>, ExtractError> {
+    let file = match open_validated_acb(acb_path)? {
+        Some(f) => f,
+        None => return Ok(None),
+    };
+    let outputs = extract_acb_tracks(file, target_dir, Some(acb_path))?;
+    Ok(Some(outputs))
+}

{cridecoder-0.3.0 → cridecoder-0.3.1}/src/acb.rs

@@ -12,6 +12,9 @@ pub use builder::{
     AcbBuilder, AfsArchiveBuilder, BuilderError, ColumnDef, TrackInput, UtfTableBuilder,
 };
 pub use consts::*;
-pub use extractor::{extract_acb, extract_acb_from_file, extract_acb_to_memory, ExtractedAcbTrack};
+pub use extractor::{
+    extract_acb, extract_acb_from_file, extract_acb_to_memory, extract_acb_tracks,
+    extract_acb_tracks_from_file, ExtractedAcbTrack, ExtractedTrackFile,
+};
 pub use track::{Track, TrackList};
 pub use utf::{UtfHeader, UtfTable, Value};

{cridecoder-0.3.0 → cridecoder-0.3.1}/src/lib.rs

@@ -14,7 +14,10 @@ pub mod usm;
 mod python;
 
 // ACB/AWB exports
-pub use acb::{extract_acb, extract_acb_from_file, extract_acb_to_memory, ExtractedAcbTrack};
+pub use acb::{
+    extract_acb, extract_acb_from_file, extract_acb_to_memory, extract_acb_tracks,
+    extract_acb_tracks_from_file, ExtractedAcbTrack, ExtractedTrackFile,
+};
 pub use acb::{AcbBuilder, AfsArchiveBuilder, BuilderError, TrackInput, UtfTableBuilder};
 
 // HCA exports

{cridecoder-0.3.0 → cridecoder-0.3.1}/src/python.rs

@@ -37,6 +37,101 @@ fn extract_acb(acb_path: &str, output_dir: &str) -> PyResult<Option<Vec<String>>
         .map_err(|e| PyRuntimeError::new_err(format!("ACB extraction failed: {}", e)))
 }
 
+/// Extract audio tracks from an ACB file, returning per-track metadata.
+///
+/// Unlike :func:`extract_acb`, this also surfaces each track's cue id and the
+/// AFS2 subkey of the AWB it came from, which is required (together with the
+/// global keycode) to decode type-56 encrypted HCA.
+///
+/// Args:
+///     acb_path: Path to the ACB file
+///     output_dir: Directory to write extracted files to
+///
+/// Returns:
+///     List of dicts ``{"path", "name", "cue_id", "subkey"}``, or None if the
+///     file is invalid.
+#[pyfunction]
+fn extract_acb_tracks<'py>(
+    py: Python<'py>,
+    acb_path: &str,
+    output_dir: &str,
+) -> PyResult<Option<Vec<Bound<'py, pyo3::types::PyDict>>>> {
+    let acb_path = Path::new(acb_path);
+    let output_dir = Path::new(output_dir);
+    fs::create_dir_all(output_dir)
+        .map_err(|e| PyRuntimeError::new_err(format!("Failed to create output dir: {}", e)))?;
+
+    let tracks = acb::extract_acb_tracks_from_file(acb_path, output_dir)
+        .map_err(|e| PyRuntimeError::new_err(format!("ACB extraction failed: {}", e)))?;
+
+    let tracks = match tracks {
+        Some(t) => t,
+        None => return Ok(None),
+    };
+
+    let mut out = Vec::with_capacity(tracks.len());
+    for track in tracks {
+        let dict = pyo3::types::PyDict::new(py);
+        dict.set_item("path", track.path)?;
+        dict.set_item("name", track.name)?;
+        dict.set_item("cue_id", track.cue_id)?;
+        dict.set_item("subkey", track.subkey)?;
+        out.push(dict);
+    }
+    Ok(Some(out))
+}
+
+/// Extract an ACB and decode its HCA tracks straight to WAV files.
+///
+/// The per-AWB AFS2 subkey is read and applied automatically, so encrypted
+/// (type-56) ACBs only need the global ``key``. Non-HCA tracks are written out
+/// verbatim with their original extension.
+///
+/// Args:
+///     acb_path: Path to the ACB file
+///     output_dir: Directory to write the decoded WAV (and any raw) files to
+///     key: Global HCA keycode (omit/None for unencrypted ACBs)
+///
+/// Returns:
+///     List of written file paths.
+#[pyfunction]
+#[pyo3(signature = (acb_path, output_dir, key=None))]
+fn decode_acb_to_wav(acb_path: &str, output_dir: &str, key: Option<u64>) -> PyResult<Vec<String>> {
+    let out_dir = Path::new(output_dir);
+    fs::create_dir_all(out_dir)
+        .map_err(|e| PyRuntimeError::new_err(format!("Failed to create output dir: {}", e)))?;
+
+    let file = fs::File::open(acb_path)
+        .map_err(|e| PyRuntimeError::new_err(format!("Failed to open ACB: {}", e)))?;
+
+    let tracks = acb::extract_acb_to_memory(file, Some(Path::new(acb_path)))
+        .map_err(|e| PyRuntimeError::new_err(format!("ACB extraction failed: {}", e)))?;
+
+    let mut outputs = Vec::with_capacity(tracks.len());
+    for track in tracks {
+        if track.extension == "hca" {
+            let mut decoder = HcaDecoder::from_reader(Cursor::new(track.data))
+                .map_err(|e| PyRuntimeError::new_err(format!("Failed to parse HCA: {}", e)))?;
+            if let Some(k) = key {
+                decoder.set_encryption_key(k, track.subkey as u64);
+            }
+            let wav_path = out_dir.join(format!("{}.wav", track.name));
+            let mut wav = fs::File::create(&wav_path)
+                .map_err(|e| PyRuntimeError::new_err(format!("Failed to create WAV: {}", e)))?;
+            decoder
+                .decode_to_wav(&mut wav)
+                .map_err(|e| PyRuntimeError::new_err(format!("HCA decode failed: {}", e)))?;
+            outputs.push(wav_path.to_string_lossy().into_owned());
+        } else {
+            let raw_path = out_dir.join(format!("{}.{}", track.name, track.extension));
+            fs::write(&raw_path, &track.data)
+                .map_err(|e| PyRuntimeError::new_err(format!("Failed to write track: {}", e)))?;
+            outputs.push(raw_path.to_string_lossy().into_owned());
+        }
+    }
+    Ok(outputs)
+}
+
 /// Build an ACB file from track data.
 ///
 /// Args:
@@ -515,6 +610,8 @@ fn read_usm_metadata(usm_path: &str) -> PyResult<String> {
 pub fn register(m: &Bound<'_, PyModule>) -> PyResult<()> {
     // ACB functions
     m.add_function(wrap_pyfunction!(extract_acb, m)?)?;
+    m.add_function(wrap_pyfunction!(extract_acb_tracks, m)?)?;
+    m.add_function(wrap_pyfunction!(decode_acb_to_wav, m)?)?;
     m.add_function(wrap_pyfunction!(build_acb, m)?)?;
     m.add_function(wrap_pyfunction!(build_acb_bytes, m)?)?;
     m.add_function(wrap_pyfunction!(build_music_acb_bytes, m)?)?;

{cridecoder-0.3.0 → cridecoder-0.3.1}/tests/integration_tests.rs

@@ -559,6 +559,43 @@ fn test_acb_builder_basic() {
     assert_eq!(&extracted_data[0..4], b"HCA\x00");
 }
 
+/// Test extract_acb_tracks surfaces per-track metadata (path, cue id, subkey)
+#[test]
+fn test_acb_extract_tracks_metadata() {
+    use cridecoder::{extract_acb_tracks_from_file, AcbBuilder, TrackInput};
+
+    let dummy_hca = create_minimal_hca_header();
+    let mut builder = AcbBuilder::new();
+    builder.add_track(TrackInput::new("meta_track", 7, dummy_hca));
+
+    let mut output = Vec::new();
+    builder
+        .build(&mut Cursor::new(&mut output), None)
+        .expect("ACB build should succeed");
+
+    let dir = tempfile::tempdir().unwrap();
+    let acb_path = dir.path().join("built.acb");
+    std::fs::write(&acb_path, &output).unwrap();
+
+    let tracks = extract_acb_tracks_from_file(&acb_path, dir.path())
+        .expect("extract should succeed")
+        .expect("built ACB should be valid");
+
+    assert_eq!(tracks.len(), 1, "Should extract one track");
+    let track = &tracks[0];
+    assert_eq!(track.name, "meta_track");
+    // cue_id is the cue-table index (the builder lays a single track at cue 0).
+    assert_eq!(track.cue_id, 0);
+    // An unencrypted (builder-produced) AWB has no subkey.
+    assert_eq!(track.subkey, 0);
+    assert!(
+        std::path::Path::new(&track.path).exists(),
+        "Written track file should exist"
+    );
+    let data = std::fs::read(&track.path).expect("Should read extracted track");
+    assert_eq!(&data[0..4], b"HCA\x00");
+}
+
 /// Test ACB builder keeps Waveform AWB ids aligned with non-zero cue ids
 #[test]
 fn test_acb_builder_nonzero_cue_id() {