PyCriCodecsEx 0.0.2__cp312-cp312-musllinux_1_2_i686.whl → 0.0.3__cp312-cp312-musllinux_1_2_i686.whl

PyCriCodecsEx/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.2"
+__version__ = "0.0.3"

PyCriCodecsEx/acb.py

@@ -3,10 +3,11 @@
 # - Original work by https://github.com/Youjose/PyCriCodecs
 # See Research/ACBSchema.py for more details.
 
-from typing import Generator, List, Tuple
+from typing import Generator, List, Tuple, BinaryIO
 from PyCriCodecsEx.chunk import *
 from PyCriCodecsEx.utf import UTF, UTFBuilder, UTFViewer
-from PyCriCodecsEx.usm import HCACodec, ADXCodec
+from PyCriCodecsEx.hca import HCACodec
+from PyCriCodecsEx.adx import ADXCodec
 from PyCriCodecsEx.awb import AWB, AWBBuilder
 from dataclasses import dataclass
 from copy import deepcopy
@@ -136,9 +137,14 @@ class CueItem:
     Waveforms: list[int] # List of waveform IDs
 
 class ACB(UTF):
-    """An ACB is basically a giant @UTF table. Use this class to extract any ACB, and potentially modifiy it in place."""
-    def __init__(self, filename) -> None:
-        super().__init__(filename,recursive=True)
+    """Use this class to read, and modify ACB files in memory."""
+    def __init__(self, stream : str | BinaryIO) -> None:
+        """Loads an ACB file from the given stream.
+
+        Args:
+            stream (str | BinaryIO): The path to the ACB file or a BinaryIO stream containing the ACB data.
+        """
+        super().__init__(stream, recursive=True)
 
     @property
     def payload(self) -> dict:
@@ -239,17 +245,22 @@ class ACB(UTF):
             yield CueItem(cue.CueId, name.CueName, cue.Length / 1000.0, [waveform.MemoryAwbId for waveform in waveforms])
 
 class ACBBuilder:
+    """Use this class to build ACB files from an existing ACB object."""
     acb: ACB
 
     def __init__(self, acb: ACB) -> None:
         """Initializes the ACBBuilder with an existing ACB object.
         
+        Args:
+            acb (ACB): The ACB object to build from.
+
         Building ACB from scratch isn't planned for now since:
-        * We don't know how SeqCommandTable TLVs work. This is the biggest issue.
-        * Many fields are unknown or not well understood
-          - Games may expect AcfReferenceTable, Asiac stuff etc to be present for their own assets in conjunction
-            with their own ACF table. Missing these is not a fun debugging experience.
-        * ACB tables differ a LOT from game to game (e.g. Lipsync info), contary to USM formats.
+                
+            * We don't know how SeqCommandTable TLVs work. This is the biggest issue.
+            * Many fields are unknown or not well understood
+            - Games may expect AcfReferenceTable, Asiac stuff etc to be present for their own assets in conjunction
+                with their own ACF table. Missing these is not a fun debugging experience.
+            * ACB tables differ a LOT from game to game (e.g. Lipsync info), contary to USM formats.
 
         Maybe one day I'll get around to this. But otherwise starting from nothing is a WONTFIX for now.
         """

PyCriCodecsEx/adx.py

@@ -1,8 +1,13 @@
+from typing import BinaryIO
+from io import BytesIO
+from PyCriCodecsEx.chunk import *
 import CriCodecsEx
-
 class ADX:
-    """ADX Module for decoding and encoding ADX files, pass the either `adx file` or `wav file` in bytes to either `decode` or `encode` respectively."""  
-    
+    """ADX class for decoding and encoding ADX files, pass the either `adx file` or `wav file` in bytes to either `decode` or `encode` respectively.
+
+    **NOTE:** Direct usage of this class is not recommended, use the `ADXCodec` wrapper instead.
+    """
+
     # Decodes ADX to WAV.
     @staticmethod
     def decode(data: bytes) -> bytes:
@@ -13,4 +18,138 @@ class ADX:
     @staticmethod
     def encode(data: bytes, BitDepth = 0x4, Blocksize = 0x12, Encoding = 3, AdxVersion = 0x4, Highpass_Frequency = 0x1F4, Filter = 0, force_not_looping = False) -> bytes:
         """ Encodes WAV to ADX. """
-        return CriCodecsEx.AdxEncode(bytes(data), BitDepth, Blocksize, Encoding, Highpass_Frequency, Filter, AdxVersion, force_not_looping)
+        return CriCodecsEx.AdxEncode(bytes(data), BitDepth, Blocksize, Encoding, Highpass_Frequency, Filter, AdxVersion, force_not_looping)
+    
+class ADXCodec(ADX):
+    """Use this class for encoding and decoding ADX files, from and to WAV."""
+
+    CHUNK_INTERVAL = 99.9
+    BASE_FRAMERATE = 2997
+    # TODO: Move these to an enum
+    AUDIO_CODEC = 2
+    METADATA_COUNT = 0
+
+    filename : str
+    filesize : int
+
+    adx : bytes
+    header : bytes
+    sfaStream: BinaryIO    
+
+    AdxDataOffset: int
+    AdxEncoding: int
+    AdxBlocksize: int
+    AdxSampleBitdepth: int
+    AdxChannelCount: int
+    AdxSamplingRate: int
+    AdxSampleCount: int
+    AdxHighpassFrequency: int
+    AdxVersion: int
+    AdxFlags: int
+
+    chnls: int
+    sampling_rate: int
+    total_samples: int
+    avbps: int
+
+    def __init__(self, stream: str | bytes, filename: str = "default.adx", bitdepth: int = 4, **kwargs):
+        """Initializes the ADX encoder/decoder
+
+        Args:
+            stream (str | bytes): Path to the ADX or WAV file, or a BinaryIO stream. WAV files will be automatically encoded with the given settings first.
+            filename (str, optional): Output filename. Defaults to "default.adx".
+            bitdepth (int, optional): Audio bit depth within [2,15]. Defaults to 4.
+        """
+        if type(stream) == str:
+            self.adx = open(stream, "rb").read()
+        else:
+            self.adx = stream
+        self.filename = filename
+        self.filesize = len(self.adx)
+        magic = self.adx[:4]
+        if magic == b"RIFF":
+            self.adx = self.encode(self.adx, bitdepth, force_not_looping=True)        
+        self.sfaStream = BytesIO(self.adx)
+        header = AdxHeaderStruct.unpack(self.sfaStream.read(AdxHeaderStruct.size))
+        FourCC, self.AdxDataOffset, self.AdxEncoding, self.AdxBlocksize, self.AdxSampleBitdepth, self.AdxChannelCount, self.AdxSamplingRate, self.AdxSampleCount, self.AdxHighpassFrequency, self.AdxVersion, self.AdxFlags = header
+        assert FourCC == 0x8000, "either ADX or WAV is supported"
+        assert self.AdxVersion in {3,4}, "unsupported ADX version"
+        if self.AdxVersion == 4:
+            self.sfaStream.seek(4 + 4  * self.AdxChannelCount, 1)  # Padding + Hist values, they always seem to be 0.
+        self.sfaStream.seek(0)
+        self.chnls = self.AdxChannelCount
+        self.sampling_rate = self.AdxSamplingRate
+        self.total_samples = self.AdxSampleCount
+        self.avbps = int(self.filesize * 8 * self.chnls) - self.filesize
+    
+    def generate_SFA(self, index: int, builder):
+        # USMBuilder usage
+        current_interval = 0
+        stream_size = len(self.adx) - self.AdxBlocksize
+        chunk_size = int(self.AdxSamplingRate // (self.BASE_FRAMERATE / 100) // 32) * (self.AdxBlocksize * self.AdxChannelCount)
+        self.sfaStream.seek(0)
+        res = []
+        while self.sfaStream.tell() < stream_size:
+            if self.sfaStream.tell() > 0:
+                if self.sfaStream.tell() + chunk_size < stream_size:
+                    datalen = chunk_size
+                else:
+                    datalen = (stream_size - (self.AdxDataOffset + 4) - chunk_size) % chunk_size
+            else:
+                datalen = self.AdxDataOffset + 4
+            if not datalen:
+                break
+            padding = (0x20 - (datalen % 0x20) if datalen % 0x20 != 0 else 0)
+            SFA_chunk = USMChunkHeader.pack(
+                    USMChunckHeaderType.SFA.value,
+                    datalen + 0x18 + padding,
+                    0,
+                    0x18,
+                    padding,
+                    index,
+                    0,
+                    0,
+                    0,
+                    round(current_interval),
+                    self.BASE_FRAMERATE,
+                    0,
+                    0
+                    )
+            chunk_data = self.sfaStream.read(datalen)
+            if builder.encrypt_audio:
+                SFA_chunk = builder.AudioMask(chunk_data)
+            SFA_chunk += chunk_data.ljust(datalen + padding, b"\x00")            
+            current_interval += self.CHUNK_INTERVAL
+            res.append(SFA_chunk)
+        # ---
+        SFA_chunk = USMChunkHeader.pack(
+                    USMChunckHeaderType.SFA.value,
+                    0x38,
+                    0,
+                    0x18,
+                    0,
+                    index,
+                    0,
+                    0,
+                    2,
+                    0,
+                    30,
+                    0,
+                    0
+                    )
+        SFA_chunk += b"#CONTENTS END   ===============\x00"
+        res[-1] += SFA_chunk
+        return res
+
+    def get_metadata(self):
+        return None
+
+    def get_encoded(self):
+        """Gets the encoded ADX audio data."""
+        return self.adx
+
+    def save(self, filepath: str):
+        """Saves the encoded ADX audio to filepath"""
+        with open(filepath, "wb") as f:
+            f.write(self.decode(self.adx))
+

PyCriCodecsEx/awb.py

@@ -82,6 +82,7 @@ class AWB:
             raise ValueError("Unknown int size.")
 
 class AWBBuilder:
+    """Use this class to build AWB files from a list of bytes."""
     def __init__(self, infiles: list[bytes], subkey: int = 0, version: int = 2, id_intsize = 0x2, align: int = 0x20) -> None:
         """Initializes the AWB builder.
 

PyCriCodecsEx/chunk.py

@@ -46,11 +46,6 @@ class HCAType(Enum):
     HCA   = b"HCA\x00" # Header.
     EHCA  = b"\xC8\xC3\xC1\x00" # Encrypted HCA header.
 
-class VideoType(Enum):
-    IVF   = b"DKIF" # Header.
-    # H264  = b"" # Header.
-    # MPEG  = b"" # Header.
-
 # I saw some devs swap the unsigned/signed indexes. So I am not sure what's correct or not.
 # In my own experience, swapping those results in an incorrect signed values (should be unsigned) in ACB's/CPK's.
 # If someone were to change this, they must change 'stringtypes' function in UTF/UTFBuilder classes.

PyCriCodecsEx/cpk.py

@@ -48,6 +48,7 @@ class _TOC():
         self.table = UTF(self.stream.read()).table
 
 class CPK:
+    """Use this class to load CPK file table-of-content, and read files from them on-demand."""
     magic: bytes
     encflag: int
     packet_size: int
@@ -189,7 +190,7 @@ class CPKBuilder:
     ContentSize: int
     EnabledDataSize: int
     EnabledPackedSize: int
-    outfile: str
+    outfile: BinaryIO
     init_toc_len: int # This is a bit of a redundancy, but some CPK's need it.
 
     in_files : list[tuple[str, str, bool]] # (source path, dest filename, compress or not)
@@ -254,14 +255,13 @@ class CPKBuilder:
         
         self.in_files.append((src, dst, compress))
 
-    def _writetofile(self, header) -> None:
-        with open(self.outfile, "wb") as out:
-            out.write(header)
-            for i, ((path, _), (filename, file_size, pack_size)) in enumerate(zip(self.os_files, self.files)):
-                src = open(path, 'rb').read()
-                out.write(src)
-                out.write(bytes(0x800 - pack_size % 0x800))
-                self.progress_cb("Write %s" % os.path.basename(filename), i + 1, len(self.files))
+    def _writetofile(self, header) -> None:        
+        self.outfile.write(header)
+        for i, ((path, _), (filename, file_size, pack_size)) in enumerate(zip(self.os_files, self.files)):
+            src = open(path, 'rb').read()
+            self.outfile.write(src)
+            self.outfile.write(bytes(0x800 - pack_size % 0x800))
+            self.progress_cb("Write %s" % os.path.basename(filename), i + 1, len(self.files))
 
     def _populate_files(self, parallel : bool):
         self.files = []
@@ -304,12 +304,12 @@ class CPKBuilder:
                 pass
         self.os_files = []
 
-    def save(self, outfile : str, parallel : bool = False):
+    def save(self, outfile : str | BinaryIO, parallel : bool = False):
         """Build and save the bundle into a file
 
 
         Args:
-            outfile (str): The output file path.
+            outfile (str | BinaryIO): The output file path or a writable binary stream.
             parallel (bool, optional): Whether to use parallel processing for file compression (if at all used). Defaults to False.
 
         NOTE: 
@@ -318,6 +318,8 @@ class CPKBuilder:
         """
         assert self.in_files, "cannot save empty bundle"
         self.outfile = outfile
+        if type(outfile) == str:
+            self.outfile = open(outfile, "wb")
         self._populate_files(parallel)
         if self.encrypt:
             encflag = 0
@@ -363,7 +365,9 @@ class CPKBuilder:
             data = self.CPKdata.ljust(len(self.CPKdata) + (0x800 - len(self.CPKdata) % 0x800) - 6, b'\x00') + bytearray(b"(c)CRI") + self.ITOCdata
         self._writetofile(data)
         self._cleanup_files()
-    
+        if type(outfile) == str:
+            self.outfile.close()
+            
     def _generate_GTOC(self) -> bytearray:
         # NOTE: Practically useless
         # I have no idea why are those numbers here.

PyCriCodecsEx/hca.py

@@ -5,7 +5,7 @@ from array import array
 import CriCodecsEx
 
 from PyCriCodecsEx.chunk import *
-
+from PyCriCodecsEx.utf import UTFTypeValues, UTFBuilder
 HcaHeaderStruct = Struct(">4sHH")
 HcaFmtHeaderStruct = Struct(">4sIIHH")
 HcaCompHeaderStruct = Struct(">4sHBBBBBBBBBB")
@@ -17,6 +17,10 @@ HcaCiphHeaderStruct = Struct(">4sH")
 HcaRvaHeaderStruct = Struct(">4sf")
 
 class HCA:
+    """HCA class for decoding and encoding HCA files
+
+    **NOTE:** Direct usage of this class is not recommended, use the `HCACodec` wrapper instead.
+    """
     stream: BinaryIO
     hcastream: BinaryIO
     HcaSig: bytes
@@ -205,32 +209,28 @@ class HCA:
                     raise ValueError(f"WAV bitdepth of {self.fmtBitCount} is not supported, only 16 bit WAV files are supported.")
                 elif self.fmtSize != 16:
                     raise ValueError(f"WAV file has an FMT chunk of an unsupported size: {self.fmtSize}, the only supported size is 16.")
-                if self.stream.read(4) == b"smpl":
-                    self.stream.seek(-4, 1)
-                    self.looping = True
-                    # Will just be naming the important things here.
-                    smplsig, smplesize, _, _, _, _, _, _, _, self.LoopCount, _, _, _, self.LoopStartSample, self.LoopEndSample, _, _ = WavSmplHeaderStruct.unpack(
-                        self.stream.read(WavSmplHeaderStruct.size)
-                    )
-                    if self.LoopCount != 1:
-                        self.looping = False # Unsupported multiple looping points, so backtracks, and ignores looping data.
-                        self.stream.seek(-WavSmplHeaderStruct.size, 1)
-                        self.stream.seek(8 + smplesize, 1)
-                else:
-                    self.stream.seek(-4, 1)
-                    self.looping = False
-                if self.stream.read(4) == b"note": # There's no use for this on ADX.
-                    len = self.stream.read(4)
-                    self.stream.seek(len+4) # + 1? + padding maybe?
-                else:
-                    self.stream.seek(-4, 1)
-                if self.stream.read(4) == b"data":
-                    self.stream.seek(-4, 1)
-                    self.dataSig, self.dataSize = WavDataHeaderStruct.unpack(
-                        self.stream.read(WavDataHeaderStruct.size)
-                    )
-                else:
-                    raise ValueError("Invalid or an unsupported wav file.")
+                while (hdr := self.stream.read(4)):
+                    size = int.from_bytes(self.stream.read(4), 'little')
+                    size += (size & 1) # padding
+                    offset = self.stream.tell()
+                    match hdr:
+                        case b"smpl":
+                            self.stream.seek(-4, 1)
+                            self.looping = True
+                            # Will just be naming the important things here.
+                            smplsig, smplesize, _, _, _, _, _, _, _, self.LoopCount, _, _, _, self.LoopStartSample, self.LoopEndSample, _, _ = WavSmplHeaderStruct.unpack(
+                                self.stream.read(WavSmplHeaderStruct.size)
+                            )
+                            if self.LoopCount != 1:
+                                self.looping = False # Unsupported multiple looping points, so backtracks, and ignores looping data.
+                                self.stream.seek(-WavSmplHeaderStruct.size, 1)
+                                self.stream.seek(8 + smplesize, 1)
+                        case b"data":
+                            self.stream.seek(-4, 1)
+                            self.dataSig, self.dataSize = WavDataHeaderStruct.unpack(
+                                self.stream.read(WavDataHeaderStruct.size)
+                            )
+                    self.stream.seek(offset + size, 0)
         else:
             raise ValueError("Invalid HCA or WAV file.")
         self.stream.seek(0)
@@ -309,3 +309,143 @@ class HCA:
         header = self.hcastream.read(self.header_size)
         self.hcastream.seek(0)
         return header
+
+
+class HCACodec(HCA):
+    """Use this class for encoding and decoding HCA files, from and to WAV."""
+    CHUNK_INTERVAL = 64
+    BASE_FRAMERATE = 2997 # dt = CHUNK_INTERVAL / BASE_FRAMERATE
+    AUDIO_CODEC = 4
+    METADATA_COUNT = 1
+
+    filename: str
+
+    chnls: int
+    sampling_rate: int
+    total_samples: int
+    avbps: int
+
+    filesize: int
+
+    def __init__(self, stream: str | bytes, filename: str = "default.hca", quality: CriHcaQuality = CriHcaQuality.High, key=0, subkey=0, **kwargs):
+        """Initializes the HCA encoder/decoder
+
+        Args:
+            stream (str | bytes): Path to the HCA or WAV file, or a BinaryIO stream. WAV files will be automatically encoded with the given settings first.
+            filename (str, optional): USM filename. Defaults to "default.hca".
+            quality (CriHcaQuality, optional): Encoding quality. Defaults to CriHcaQuality.High.
+            key (int, optional): HCA key. Defaults to 0.
+            subkey (int, optional): HCA subkey. Defaults to 0.
+        """
+        self.filename = filename
+        super().__init__(stream, key, subkey)
+        if self.filetype == "wav":
+            self.encode(
+                force_not_looping=True,
+                encrypt=key != 0,
+                keyless=False,
+                quality_level=quality
+            )
+        self.hcastream.seek(0, 2)
+        self.filesize = self.hcastream.tell()
+        self.hcastream.seek(0)
+
+        if self.filetype == "wav":
+            self.chnls = self.fmtChannelCount
+            self.sampling_rate = self.fmtSamplingRate
+            self.total_samples = int(self.dataSize // self.fmtSamplingSize)
+        else:
+            self.chnls = self.hca["ChannelCount"]
+            self.sampling_rate = self.hca["SampleRate"]
+            self.total_samples = self.hca["FrameCount"]
+        # I don't know how this is derived so I am putting my best guess here. TODO
+        self.avbps = int(self.filesize / self.chnls)
+
+    def generate_SFA(self, index: int, builder):
+        # USMBuilder usage
+        current_interval = 0
+        padding = (
+            0x20 - (self.hca["HeaderSize"] % 0x20)
+            if self.hca["HeaderSize"] % 0x20 != 0
+            else 0
+        )
+        SFA_chunk = USMChunkHeader.pack(
+            USMChunckHeaderType.SFA.value,
+            self.hca["HeaderSize"] + 0x18 + padding,
+            0,
+            0x18,
+            padding,
+            index,
+            0,
+            0,
+            0,
+            current_interval,
+            self.BASE_FRAMERATE,
+            0,
+            0,
+        )
+        SFA_chunk += self.get_header().ljust(self.hca["HeaderSize"] + padding, b"\x00")
+        res = []
+        res.append(SFA_chunk)
+        for i, frame in enumerate(self.get_frames(), start=1):
+            padding = (
+                0x20 - (self.hca["FrameSize"] % 0x20)
+                if self.hca["FrameSize"] % 0x20 != 0
+                else 0
+            )
+            SFA_chunk = USMChunkHeader.pack(
+                USMChunckHeaderType.SFA.value,
+                self.hca["FrameSize"] + 0x18 + padding,
+                0,
+                0x18,
+                padding,
+                index,
+                0,
+                0,
+                0,
+                current_interval,
+                self.BASE_FRAMERATE,
+                0,
+                0,
+            )
+            SFA_chunk += frame[1].ljust(self.hca["FrameSize"] + padding, b"\x00")
+            current_interval = round(i * self.CHUNK_INTERVAL)            
+            res.append(SFA_chunk)
+        else:
+            SFA_chunk = USMChunkHeader.pack(
+                USMChunckHeaderType.SFA.value,
+                0x38,
+                0,
+                0x18,
+                0,
+                index,
+                0,
+                0,
+                2,
+                0,
+                30,
+                0,
+                0,
+            )
+            SFA_chunk += b"#CONTENTS END   ===============\x00"
+            res[-1] += SFA_chunk
+
+        return res
+
+    def get_metadata(self):
+        payload = [dict(hca_header=(UTFTypeValues.bytes, self.get_header()))]
+        p = UTFBuilder(payload, table_name="AUDIO_HEADER")
+        p.strings = b"<NULL>\x00" + p.strings
+        return p.bytes()
+
+    def get_encoded(self):
+        """Gets the encoded HCA audio data."""
+        self.hcastream.seek(0)
+        res = self.hcastream.read()
+        self.hcastream.seek(0)
+        return res
+    
+    def save(self, filepath: str):
+        """Saves the decoded WAV audio to filepath"""
+        with open(filepath, "wb") as f:
+            f.write(self.decode())

PyCriCodecsEx/usm.py

@@ -6,8 +6,6 @@ from functools import cached_property
 
 from PyCriCodecsEx.chunk import *
 from PyCriCodecsEx.utf import UTF, UTFBuilder
-from PyCriCodecsEx.adx import ADX
-from PyCriCodecsEx.hca import HCA
 try:
     import ffmpeg
 except ImportError:
@@ -22,6 +20,7 @@ import tempfile
 # code for a complete breakdown of the USM format.
 
 class USMCrypt:
+    """USM related crypto functions"""
     videomask1: bytearray
     videomask2: bytearray
     audiomask: bytearray
@@ -162,6 +161,13 @@ class FFmpegCodec:
     avbps: int
 
     def __init__(self, stream: str | bytes):
+        """Initialize FFmpegCodec with a media stream, gathering metadata and frame info.
+
+        Args:
+            stream (str | bytes): The media stream to process.
+        NOTE:
+            A temp file maybe created for probing only. Which will be deleted after use.
+        """
         if type(stream) == str:
             self.filename = stream
         else:
@@ -317,260 +323,11 @@ class MPEG1Codec(FFmpegCodec):
         super().__init__(stream)
         assert self.format == "mpegvideo", "must be m1v format (mpegvideo)."
 
-class HCACodec(HCA):
-    CHUNK_INTERVAL = 64
-    BASE_FRAMERATE = 2997 # dt = CHUNK_INTERVAL / BASE_FRAMERATE
-    AUDIO_CODEC = 4
-    METADATA_COUNT = 1
-
-    filename: str
-
-    chnls: int
-    sampling_rate: int
-    total_samples: int
-    avbps: int
-
-    filesize: int
-
-    def __init__(self, stream: str | bytes, filename: str = "default.hca", quality: CriHcaQuality = CriHcaQuality.High, key=0, subkey=0, **kwargs):
-        self.filename = filename
-        super().__init__(stream, key, subkey)
-        if self.filetype == "wav":
-            self.encode(
-                force_not_looping=True,
-                encrypt=key != 0,
-                keyless=False,
-                quality_level=quality
-            )
-        self.hcastream.seek(0, 2)
-        self.filesize = self.hcastream.tell()
-        self.hcastream.seek(0)
-
-        if self.filetype == "wav":
-            self.chnls = self.fmtChannelCount
-            self.sampling_rate = self.fmtSamplingRate
-            self.total_samples = int(self.dataSize // self.fmtSamplingSize)
-        else:
-            self.chnls = self.hca["ChannelCount"]
-            self.sampling_rate = self.hca["SampleRate"]
-            self.total_samples = self.hca["FrameCount"]
-        # I don't know how this is derived so I am putting my best guess here. TODO
-        self.avbps = int(self.filesize / self.chnls)
-
-    def generate_SFA(self, index: int, builder: "USMBuilder"):
-        current_interval = 0
-        padding = (
-            0x20 - (self.hca["HeaderSize"] % 0x20)
-            if self.hca["HeaderSize"] % 0x20 != 0
-            else 0
-        )
-        SFA_chunk = USMChunkHeader.pack(
-            USMChunckHeaderType.SFA.value,
-            self.hca["HeaderSize"] + 0x18 + padding,
-            0,
-            0x18,
-            padding,
-            index,
-            0,
-            0,
-            0,
-            current_interval,
-            self.BASE_FRAMERATE,
-            0,
-            0,
-        )
-        SFA_chunk += self.get_header().ljust(self.hca["HeaderSize"] + padding, b"\x00")
-        res = []
-        res.append(SFA_chunk)
-        for i, frame in enumerate(self.get_frames(), start=1):
-            padding = (
-                0x20 - (self.hca["FrameSize"] % 0x20)
-                if self.hca["FrameSize"] % 0x20 != 0
-                else 0
-            )
-            SFA_chunk = USMChunkHeader.pack(
-                USMChunckHeaderType.SFA.value,
-                self.hca["FrameSize"] + 0x18 + padding,
-                0,
-                0x18,
-                padding,
-                index,
-                0,
-                0,
-                0,
-                current_interval,
-                self.BASE_FRAMERATE,
-                0,
-                0,
-            )
-            SFA_chunk += frame[1].ljust(self.hca["FrameSize"] + padding, b"\x00")
-            current_interval = round(i * self.CHUNK_INTERVAL)            
-            res.append(SFA_chunk)
-        else:
-            SFA_chunk = USMChunkHeader.pack(
-                USMChunckHeaderType.SFA.value,
-                0x38,
-                0,
-                0x18,
-                0,
-                index,
-                0,
-                0,
-                2,
-                0,
-                30,
-                0,
-                0,
-            )
-            SFA_chunk += b"#CONTENTS END   ===============\x00"
-            res[-1] += SFA_chunk
-
-        return res
-
-    def get_metadata(self):
-        payload = [dict(hca_header=(UTFTypeValues.bytes, self.get_header()))]
-        p = UTFBuilder(payload, table_name="AUDIO_HEADER")
-        p.strings = b"<NULL>\x00" + p.strings
-        return p.bytes()
-
-    def get_encoded(self):
-        """Gets the encoded HCA audio data."""
-        self.hcastream.seek(0)
-        res = self.hcastream.read()
-        self.hcastream.seek(0)
-        return res
-    
-    def save(self, filepath: str):
-        """Saves the decoded WAV audio to filepath"""
-        with open(filepath, "wb") as f:
-            f.write(self.decode())
-
-class ADXCodec(ADX):
-    CHUNK_INTERVAL = 99.9
-    BASE_FRAMERATE = 2997
-    # TODO: Move these to an enum
-    AUDIO_CODEC = 2
-    METADATA_COUNT = 0
-
-    filename : str
-    filesize : int
-
-    adx : bytes
-    header : bytes
-    sfaStream: BinaryIO    
-
-    AdxDataOffset: int
-    AdxEncoding: int
-    AdxBlocksize: int
-    AdxSampleBitdepth: int
-    AdxChannelCount: int
-    AdxSamplingRate: int
-    AdxSampleCount: int
-    AdxHighpassFrequency: int
-    AdxVersion: int
-    AdxFlags: int
-
-    chnls: int
-    sampling_rate: int
-    total_samples: int
-    avbps: int
-
-    def __init__(self, stream: str | bytes, filename: str = "default.adx", bitdepth: int = 4, **kwargs):
-        if type(stream) == str:
-            self.adx = open(stream, "rb").read()
-        else:
-            self.adx = stream
-        self.filename = filename
-        self.filesize = len(self.adx)
-        magic = self.adx[:4]
-        if magic == b"RIFF":
-            self.adx = self.encode(self.adx, bitdepth, force_not_looping=True)        
-        self.sfaStream = BytesIO(self.adx)
-        header = AdxHeaderStruct.unpack(self.sfaStream.read(AdxHeaderStruct.size))
-        FourCC, self.AdxDataOffset, self.AdxEncoding, self.AdxBlocksize, self.AdxSampleBitdepth, self.AdxChannelCount, self.AdxSamplingRate, self.AdxSampleCount, self.AdxHighpassFrequency, self.AdxVersion, self.AdxFlags = header
-        assert FourCC == 0x8000, "either ADX or WAV is supported"
-        assert self.AdxVersion in {3,4}, "unsupported ADX version"
-        if self.AdxVersion == 4:
-            self.sfaStream.seek(4 + 4  * self.AdxChannelCount, 1)  # Padding + Hist values, they always seem to be 0.
-        self.sfaStream.seek(0)
-        self.chnls = self.AdxChannelCount
-        self.sampling_rate = self.AdxSamplingRate
-        self.total_samples = self.AdxSampleCount
-        self.avbps = int(self.filesize * 8 * self.chnls) - self.filesize
-    
-    def generate_SFA(self, index: int, builder: "USMBuilder"):
-        current_interval = 0
-        stream_size = len(self.adx) - self.AdxBlocksize
-        chunk_size = int(self.AdxSamplingRate // (self.BASE_FRAMERATE / 100) // 32) * (self.AdxBlocksize * self.AdxChannelCount)
-        self.sfaStream.seek(0)
-        res = []
-        while self.sfaStream.tell() < stream_size:
-            if self.sfaStream.tell() > 0:
-                if self.sfaStream.tell() + chunk_size < stream_size:
-                    datalen = chunk_size
-                else:
-                    datalen = (stream_size - (self.AdxDataOffset + 4) - chunk_size) % chunk_size
-            else:
-                datalen = self.AdxDataOffset + 4
-            if not datalen:
-                break
-            padding = (0x20 - (datalen % 0x20) if datalen % 0x20 != 0 else 0)
-            SFA_chunk = USMChunkHeader.pack(
-                    USMChunckHeaderType.SFA.value,
-                    datalen + 0x18 + padding,
-                    0,
-                    0x18,
-                    padding,
-                    index,
-                    0,
-                    0,
-                    0,
-                    round(current_interval),
-                    self.BASE_FRAMERATE,
-                    0,
-                    0
-                    )
-            chunk_data = self.sfaStream.read(datalen)
-            if builder.encrypt_audio:
-                SFA_chunk = builder.AudioMask(chunk_data)
-            SFA_chunk += chunk_data.ljust(datalen + padding, b"\x00")            
-            current_interval += self.CHUNK_INTERVAL
-            res.append(SFA_chunk)
-        # ---
-        SFA_chunk = USMChunkHeader.pack(
-                    USMChunckHeaderType.SFA.value,
-                    0x38,
-                    0,
-                    0x18,
-                    0,
-                    index,
-                    0,
-                    0,
-                    2,
-                    0,
-                    30,
-                    0,
-                    0
-                    )
-        SFA_chunk += b"#CONTENTS END   ===============\x00"
-        res[-1] += SFA_chunk
-        return res
-
-    def get_metadata(self):
-        return None
-
-    def get_encoded(self):
-        """Gets the encoded ADX audio data."""
-        return self.adx
-
-    def save(self, filepath: str):
-        """Saves the encoded ADX audio to filepath"""
-        with open(filepath, "wb") as f:
-            f.write(self.decode(self.adx))
-
+from PyCriCodecsEx.hca import HCACodec
+from PyCriCodecsEx.adx import ADXCodec
 
 class USM(USMCrypt):
-    """USM class for extracting infromation and data from a USM file."""
+    """Use this class to extract infromation and data from a USM file."""
 
     filename: str
     decrypt: bool
@@ -585,7 +342,7 @@ class USM(USMCrypt):
 
     metadata: list
 
-    def __init__(self, filename, key: str | int = None):
+    def __init__(self, filename : str | BinaryIO, key: str | int = None):
         """Loads a USM file into memory and prepares it for processing.
 
         Args:
@@ -601,7 +358,10 @@ class USM(USMCrypt):
         self._load_file()
     
     def _load_file(self):
-        self.stream = open(self.filename, "rb")
+        if type(self.filename) == str:
+            self.stream = open(self.filename, "rb")
+        else:
+            self.stream = self.filename
         self.stream.seek(0, 2)
         self.size = self.stream.tell()
         self.stream.seek(0)
@@ -716,7 +476,7 @@ class USM(USMCrypt):
 
     @property
     def streams(self):
-        """[Type (@SFV, @SFA), Filename, Raw stream data]"""
+        """Generator of Tuple[Stream Type ("@SFV", "@SFA"), File name, Raw stream data]"""
         for stream in self.CRIDObj.dictarray[1:]:
             filename, stmid, chno = stream["filename"][1], stream["stmid"][1], stream["chno"][1]
             stmid = int.to_bytes(stmid, 4, 'big', signed='False')
@@ -751,7 +511,7 @@ class USM(USMCrypt):
                 return []
 
 class USMBuilder(USMCrypt):
-    """USM class for building USM files."""
+    """Use this class to build USM files."""
     video_stream: VP9Codec | H264Codec | MPEG1Codec
     audio_streams: List[HCACodec | ADXCodec]
 

PyCriCodecsEx/utf.py

@@ -8,6 +8,7 @@ from struct import unpack, calcsize, pack
 from PyCriCodecsEx.chunk import *
 
 class UTF:
+    """Use this class to unpack @UTF table binary payload."""
 
     _dictarray: list
 
@@ -23,11 +24,11 @@ class UTF:
     recursive: bool
     encoding : str = 'utf-8'
 
-    def __init__(self, stream, recursive=False):
+    def __init__(self, stream : str | BinaryIO, recursive=False):
         """Unpacks UTF table binary payload
 
         Args:
-            stream (Union[str, bytes]): The input stream or file path to read the UTF table from.
+            stream (Union[str | BinaryIO]): The input stream or file path to read the UTF table from.
             recursive (bool): Whether to recursively unpack nested UTF tables.
         """
         if type(stream) == str:
@@ -290,6 +291,7 @@ class UTF:
         return self._dictarray
 
 class UTFBuilder:
+    """Use this class to build UTF table binary payloads from a `dictarray`."""
 
     encoding: str
     dictarray: list
@@ -591,34 +593,16 @@ class UTFBuilder:
         return dataarray
 
 class UTFViewer:
+    """Use this class to create dataclass-like access to `dictarray`s."""
+
     _payload: dict
 
     def __init__(self, payload):
         """Construct a non-owning read-write, deletable view of a UTF table dictarray.
+
         Nested classes are supported.
-        Sorting (using .sort()) is done in-place and affects the original payload.
 
-        Example:
-        ```python
-            class CueNameTable(UTFViewer):
-                CueName : str
-                CueIndex : int
-            class ACBTable(UTFViewer):
-                CueNameTable : List[CueNameTable]
-                Awb : AWB
-            src = ACB(ACB_sample)
-            payload = ACBTable(src.payload)
-            >>> Referencing items through Python is allowed
-            name = payload.CueNameTable
-            >>> Lists can be indexed
-            name_str = name[0].CueName
-            >>> Deleting items from lists is also allowed
-            src.view.CueNameTable.pop(1)
-            src.view.CueTable.pop(1)
-            >>> The changes will be reflected in the original UTF payload
-            
-            See __new__ for the actual constructor.
-        ```
+        Sorting (using .sort()) is done in-place and affects the original payload.
         """
         assert isinstance(payload, dict), "payload must be a dictionary."
         super().__setattr__("_payload", payload)

pycricodecsex-0.0.3.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: PyCriCodecsEx
+Version: 0.0.3
+Summary: Criware formats library for Python
+Home-page: https://mos9527.github.io/PyCriCodecsEx/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: usm
+Requires-Dist: ffmpeg-python; extra == "usm"
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+PyCriCodecsEx
+---
+A continuation of @Youjose's work on Criware formats. Feautres are still in flux and subject to change. When in doubt, Refer to the [original repo](https://github.com/Youjose/PyCriCodecs) for more information.
+
+Detailed documentation, installation instructions are available at https://mos9527.com/PyCriCodecsEx
+
+
+# Credits
+- https://github.com/Youjose/PyCriCodecs
+- https://github.com/Mikewando/PyCriCodecs ([PR#1 on USM](https://github.com/mos9527/PyCriCodecsEx/pull/1))
+- https://github.com/donmai-me/WannaCRI
+- https://github.com/vgmstream/vgmstream
+- https://github.com/K0lb3/UnityPy (For CI script)

pycricodecsex-0.0.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+CriCodecsEx.cpython-312-i386-linux-musl.so,sha256=BFNR6EisI_-4HhrIBCoUVARsahMUbTm8B95jhsBmRkU,298493
+pycricodecsex-0.0.3.dist-info/RECORD,,
+pycricodecsex-0.0.3.dist-info/METADATA,sha256=yvFl7vPBIloog0TJ9nUgf7psQbf1IrL2URvIXdDoU90,1256
+pycricodecsex-0.0.3.dist-info/top_level.txt,sha256=mSrrEse9hT0s6nl-sWAQWAhNRuZ6jo98pbFoN3L2MXk,26
+pycricodecsex-0.0.3.dist-info/WHEEL,sha256=Vuwis_LWaa45QUuJ2qqSgABfO0elv3qQohyjTF3DnPc,110
+pycricodecsex-0.0.3.dist-info/licenses/LICENSE,sha256=GyZb4dzF2tM3LU5I_tJXpHtUDz8297zeUuCJ5qz8io0,1063
+pycricodecsex.libs/libgcc_s-f3fb5a36.so.1,sha256=SrjjCCuY7RHj-T9JLrY9XFMgCCpYD9Qmezr4uoJGVEQ,168321
+pycricodecsex.libs/libstdc++-d2a021ba.so.6.0.32,sha256=1zr_iwGwEBe95gyKdgiw7C4Y1RR9ijV40j66rk4elzg,3537349
+PyCriCodecsEx/cpk.py,sha256=3ymJe_2kRBDll0C4SAjQBEROXSbVigDGU_QTa31kw-g,37466
+PyCriCodecsEx/hca.py,sha256=YrG1uMj4penM5m1Qm7cIfGUcWdcRCPGgUAEjH-cqLcs,18994
+PyCriCodecsEx/utf.py,sha256=ORSoyRrgBbdaGP6cQQejWfqkdWz6vEGG_sTo_fbO48Y,27555
+PyCriCodecsEx/adx.py,sha256=2oRgzwKL74pvQyHgX2zWckSGM0vpRrN7dB7KjdeqGhw,5812
+PyCriCodecsEx/awb.py,sha256=2R3xK8YBXOGygn_kBflzuk3DY1hQHiF-hLaPcrzj1sk,6198
+PyCriCodecsEx/chunk.py,sha256=ZYyeqqcBK6dDDj12YvrhpZDzW0iyOhysRlYuCD3rgQ8,2719
+PyCriCodecsEx/acb.py,sha256=CgZabDx1t19DP6fWR6pSgLVF9n1Gp3owAjx0pOU4_Bw,10444
+PyCriCodecsEx/usm.py,sha256=TsJNBaPul3EYGQJwqLUcbMOSs_oGw8gvjz7mexosURc,35977
+PyCriCodecsEx/__init__.py,sha256=4GZKi13lDTD25YBkGakhZyEQZWTER_OWQMNPoH_UM2c,22

pycricodecsex-0.0.2.dist-info/METADATA

@@ -1,86 +0,0 @@
-Metadata-Version: 2.4
-Name: PyCriCodecsEx
-Version: 0.0.2
-Summary: Criware formats library for Python
-Home-page: https://github.com/mos9527/PyCriCodecsEx
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: usm
-Requires-Dist: ffmpeg-python; extra == "usm"
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-python
-Dynamic: summary
-
-# PyCriCodecsEx
-A continuation of @Youjose's work on Criware formats. Feautres are still in flux and subject to change. When in doubt, Refer to the [original repo](https://github.com/Youjose/PyCriCodecs) for more information.
-
-# Installation
-```bash
-pip install PyCriCodecsEx
-```
-
-For USM features, you need `ffmpeg` installed and available in your PATH. See also https://github.com/kkroening/ffmpeg-python?tab=readme-ov-file#installing-ffmpeg
-
-## Features
-If not otherwise mentioned, all features marked with [x] are considered working, and has been verified with official tools.
-
-Examples are available in [Tests](https://github.com/mos9527/PyCriCodecsEx/tree/main/Tests)
-
-### ACB Cue sheets (also AWB)
-- [x] Cue extraction support for most ACBs
-- [x] Cue waveform(s) encoding with ADX/HCA support
-- [x] Comprehensive Cue metadata editing support (via Python API)
-
-### USM Sofdec2 (Encode & Decode)
-#### Audio Stream
-For audio to be muxed in, you need a PCM WAV sample with NO metadata, which can be produced with e.g.:
-```bash
-ffmpeg -i input.mp3 -vn -c:a pcm_s16le -map_metadata -1 output.wav
-```
-Decoding and Encoded format can be the following:
-- [x] HCA
-- [x] ADX
-#### Video Stream
-**NOTE**: You definitely want to tweak these encode settings a bit.
-- [x] Sofdec Prime (MPEG1, from `.m1v` container)
-    - Prepare source file with: `ffmpeg -i <input_file> -c:v mpeg1video -an <output_file>.m1v`
-- [x] H264 (from `.h264` raw container)
-    - Prepare source file with: `ffmpeg -i <input_file> -c:v libx264 -an <output_file>.h264`
-- [x] VP9 (from `.ivf` container)
-    - Prepare source file with: `ffmpeg -i <input_file> -c:v libvpx -an <output_file>.ivf`
-### HCA Audio Codec
-- [x] Decoding (up to version 3.0)
-- [x] Encoding (up to version 3.0)
-### ADX Audio Codec
-- [x] Decoding
-- [x] Encoding
-### CPK
-- [x] Unpacking
-- [x] Packing
-
-## Roadmap
-- [x] ACB Extraction (Massive TODO. see also https://github.com/mos9527/PyCriCodecsEx/blob/main/Research/ACBSchema.py)
-- [ ] Interface for encode tasks (CLI then maybe GUI?)
-- [ ] Documentation
-- [ ] C/C++ port + FFI
-## Currently Known Bugs
-- USM seeking does not work. Though most games don't use it anyways.
-- Not important, and might not fix: ADX encoding and decoding at higher bitdepths (11-15) adds popping noise.
-- Some CPK's that has the same filename for every file in the entry will overwrite each other.
-- Probably many more I am unaware of, report if you find any.
-
-# Credits
-- https://github.com/Youjose/PyCriCodecs
-- https://github.com/Mikewando/PyCriCodecs ([PR#1 on USM](https://github.com/mos9527/PyCriCodecsEx/pull/1))
-- https://github.com/donmai-me/WannaCRI
-- https://github.com/vgmstream/vgmstream
-- https://github.com/K0lb3/UnityPy (For CI script)

pycricodecsex-0.0.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-CriCodecsEx.cpython-312-i386-linux-musl.so,sha256=BFNR6EisI_-4HhrIBCoUVARsahMUbTm8B95jhsBmRkU,298493
-pycricodecsex.libs/libgcc_s-f3fb5a36.so.1,sha256=SrjjCCuY7RHj-T9JLrY9XFMgCCpYD9Qmezr4uoJGVEQ,168321
-pycricodecsex.libs/libstdc++-d2a021ba.so.6.0.32,sha256=1zr_iwGwEBe95gyKdgiw7C4Y1RR9ijV40j66rk4elzg,3537349
-pycricodecsex-0.0.2.dist-info/RECORD,,
-pycricodecsex-0.0.2.dist-info/METADATA,sha256=gdddHtzOzTWQJUszhu_mCanshANM_6j61_DfggTnpc8,3352
-pycricodecsex-0.0.2.dist-info/top_level.txt,sha256=mSrrEse9hT0s6nl-sWAQWAhNRuZ6jo98pbFoN3L2MXk,26
-pycricodecsex-0.0.2.dist-info/WHEEL,sha256=Vuwis_LWaa45QUuJ2qqSgABfO0elv3qQohyjTF3DnPc,110
-pycricodecsex-0.0.2.dist-info/licenses/LICENSE,sha256=GyZb4dzF2tM3LU5I_tJXpHtUDz8297zeUuCJ5qz8io0,1063
-PyCriCodecsEx/cpk.py,sha256=-SbUua1vMQ6OR-WN0TOv0iieLluy4fExueQYkRlM7IY,37196
-PyCriCodecsEx/hca.py,sha256=OlcDJS8BSaa_g4LH2KS8bOHS_SfGrzwKH5tuCihBMmo,14239
-PyCriCodecsEx/utf.py,sha256=xUAG0fHZjznUuBMwf6sXlfw-GHHvt2GtoHNrg9T4BFY,28111
-PyCriCodecsEx/adx.py,sha256=dKv1HcBoe4Wkfot4Y2bfViBV2wJe1rrTzM325VA6RKk,762
-PyCriCodecsEx/awb.py,sha256=NSm3eia1MR4xCLuAUJC-82uzbPYk7PO6kQBYOsNRWW8,6132
-PyCriCodecsEx/chunk.py,sha256=MbajWDE_6g9JF254aZw-tyWcKpGVmQgIbGISpC7ootQ,2829
-PyCriCodecsEx/acb.py,sha256=j5u4mcv4Jz9uYxjpFCbvh9oxXcSpigb8ulB0wlvr4Ig,10084
-PyCriCodecsEx/usm.py,sha256=MT_Gl-6x25PMy4G0t3RipgPS5Pz-XyqpQGdQIhkK_7E,43872
-PyCriCodecsEx/__init__.py,sha256=QvlVh4JTl3JL7jQAja76yKtT-IvF4631ASjWY1wS6AQ,22