PyCriCodecsEx 0.0.1__cp313-cp313-win_amd64.whl → 0.0.2__cp313-cp313-win_amd64.whl

PyCriCodecsEx/__init__.py

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

PyCriCodecsEx/acb.py

@@ -1,18 +1,16 @@
-from struct import iter_unpack
-from typing import BinaryIO, List
-from io import BytesIO
-from PyCriCodecsEx.chunk import *
-from PyCriCodecsEx.utf import UTF, UTFBuilder, UTFViewer
-from PyCriCodecsEx.awb import AWB, AWBBuilder
-from PyCriCodecsEx.hca import HCA
-from copy import deepcopy
-import os
-
 # Credit:
 # - github.com/vgmstream/vgmstream which is why this is possible at all
 # - Original work by https://github.com/Youjose/PyCriCodecs
 # See Research/ACBSchema.py for more details.
 
+from typing import Generator, List, Tuple
+from PyCriCodecsEx.chunk import *
+from PyCriCodecsEx.utf import UTF, UTFBuilder, UTFViewer
+from PyCriCodecsEx.usm import HCACodec, ADXCodec
+from PyCriCodecsEx.awb import AWB, AWBBuilder
+from dataclasses import dataclass
+from copy import deepcopy
+
 class CueNameTable(UTFViewer):
     CueIndex: int
     CueName: str
@@ -20,11 +18,13 @@ class CueNameTable(UTFViewer):
 
 class CueTable(UTFViewer):
     CueId: int
+    Length: int
     ReferenceIndex: int
     ReferenceType: int
 
 
 class SequenceTable(UTFViewer):
+    NumTracks : int
     TrackIndex: bytes
     Type: int
 
@@ -65,6 +65,75 @@ class ACBTable(UTFViewer):
     TrackTable: List[TrackTable]
     WaveformTable: List[WaveformTable]
 
+    @staticmethod
+    def decode_tlv(data : bytes):
+        pos = 0
+        while pos < len(data):
+            tag = data[pos : pos + 2]
+            length = data[pos + 3]            
+            value = data[pos + 4 : pos + 4 + length]
+            pos += 3 + length
+            yield (tag, value)
+
+    def waveform_of_track(self, index: int):
+        tlv = self.decode_tlv(self.TrackEventTable[index])
+        def noteOn(data: bytes):
+            # Handle note on event
+            tlv_type, tlv_index = AcbTrackCommandNoteOnStruct.unpack(data[:AcbTrackCommandNoteOnStruct.size])
+            match tlv_type:
+                case 0x02: # Synth
+                    yield from self.waveform_of_synth(tlv_index)
+                case 0x03: # Sequence
+                    yield from self.waveform_of_sequence(tlv_index)
+                # Ignore others silently                
+        for code, data in tlv:
+            match code:
+                case 2000:
+                    yield from noteOn(data)
+                case 2003:
+                    yield from noteOn(data)            
+
+    def waveform_of_sequence(self, index : int):
+        seq = self.SequenceTable[index]
+        for i in range(seq.NumTracks):
+            track_index = int.from_bytes(seq.TrackIndex[i*2:i*2+2], 'big')
+            yield self.WaveformTable[track_index]
+
+    def waveform_of_synth(self, index: int):        
+        item_type, item_index = AcbSynthReferenceStruct.unpack(self.SynthTable[index].ReferenceItems)
+        match item_type:
+            case 0x00: # No audio
+                return
+            case 0x01: # Waveform
+                yield self.WaveformTable[item_index]
+            case 0x02: # Yet another synth...
+                yield from self.waveform_of_synth(item_index)
+            case 0x03: # Sequence
+                yield from self.waveform_of_sequence(item_index)
+            case _:
+                raise NotImplementedError(f"Unknown synth reference type: {item_type} at index {index}")
+
+    def waveform_of(self, index : int) -> List["WaveformTable"]:
+        cue = next(filter(lambda c: c.CueId == index, self.CueTable), None)
+        assert cue, "cue of index %d not found" % index
+        match cue.ReferenceType:
+            case 0x01:
+                return [self.WaveformTable[index]]
+            case 0x02:
+                return list(self.waveform_of_synth(index))
+            case 0x03:
+                return list(self.waveform_of_sequence(index))
+            case 0x08:
+                raise NotImplementedError("BlockSequence type not implemented yet")
+            case _:
+                raise NotImplementedError(f"Unknown cue reference type: {cue.ReferenceType}")
+
+@dataclass(frozen=True)
+class CueItem:
+    CueId: int
+    CueName: str
+    Length: float
+    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."""
@@ -73,21 +142,117 @@ class ACB(UTF):
 
     @property
     def payload(self) -> dict:
-        """Retrives the only top-level UTF table dict within the ACB file."""
+        """Retrives the only UTF table dict within the ACB file."""
         return self.dictarray[0]
 
     @property
     def view(self) -> ACBTable:
-        """Returns a view of the ACB file, with all known tables mapped to their respective classes."""
+        """Returns a view of the ACB file, with all known tables mapped to their respective classes.
+        
+        * Use this to interact with the ACB payload instead of `payload` for helper functions, etc"""
         return ACBTable(self.payload)
 
-    # TODO: Extraction routines
-    # See Research/ACBSchema.py. vgmstream presented 4 possible permutations of subsong retrieval.
+    @property
+    def name(self) -> str:
+        """Returns the name of the ACB file."""
+        return self.view.Name
+
+    @property
+    def awb(self) -> AWB:
+        """Returns the AWB object associated with the ACB."""
+        return AWB(self.view.AwbFile)
+
+    def get_waveforms(self) -> List[HCACodec | ADXCodec | Tuple[AcbEncodeTypes, int, int, int,  bytes]]:
+        """Returns a list of decoded waveforms.
+
+        Item may be a codec (if known), or a tuple of (Codec ID, Channel Count, Sample Count, Sample Rate, Raw data).
+        """
+        CODEC_TABLE = {
+            AcbEncodeTypes.ADX: ADXCodec,
+            AcbEncodeTypes.HCA: HCACodec,
+            AcbEncodeTypes.HCAMX: HCACodec,
+        }
+        awb = self.awb
+        wavs = []        
+        for wav in self.view.WaveformTable:
+            encode = AcbEncodeTypes(wav.EncodeType)
+            codec = (CODEC_TABLE.get(encode, None))
+            if codec:
+                wavs.append(codec(awb.get_file_at(wav.MemoryAwbId)))
+            else:
+                wavs.append((encode, wav.NumChannels, wav.NumSamples, wav.SamplingRate, awb.get_file_at(wav.MemoryAwbId)))
+        return wavs
+
+    def set_waveforms(self, value: List[HCACodec | ADXCodec | Tuple[AcbEncodeTypes, int, int, int, bytes]]):
+        """Sets the waveform data.
+
+        Input item may be a codec (if known), or a tuple of (Codec ID, Channel Count, Sample Count, Sample Rate, Raw data).
+
+        NOTE: Cue duration is not set. You need to change that manually.
+        """
+        WAVEFORM = self.view.WaveformTable[0]._payload.copy()
+        encoded = []
+        tables = self.view.WaveformTable
+        tables.clear()
+        for i, codec in enumerate(value):
+            if type(codec) == HCACodec:
+                encoded.append(codec.get_encoded())
+                tables.append(WaveformTable(WAVEFORM.copy()))
+                entry = tables[-1]
+                entry.EncodeType = AcbEncodeTypes.HCA.value
+                entry.NumChannels = codec.chnls
+                entry.NumSamples = codec.total_samples
+                entry.SamplingRate = codec.sampling_rate
+            elif type(codec) == ADXCodec:
+                encoded.append(codec.get_encoded())
+                tables.append(WaveformTable(WAVEFORM.copy()))
+                entry = tables[-1]
+                entry.EncodeType = AcbEncodeTypes.ADX.value
+                entry.NumChannels = codec.chnls
+                entry.NumSamples = codec.total_samples
+                entry.SamplingRate = codec.sampling_rate                
+            elif isinstance(codec, tuple):
+                e_type, e_channels, e_samples, e_rate, e_data = codec
+                encoded.append(e_data)
+                tables.append(WaveformTable(WAVEFORM.copy()))
+                entry = tables[-1]
+                entry.EncodeType = e_type.value
+                entry.NumChannels = e_channels
+                entry.NumSamples = e_samples
+                entry.SamplingRate = e_rate
+            else:
+                raise TypeError(f"Unsupported codec type: {type(codec)}")
+            tables[-1].MemoryAwbId = i
+        awb = self.awb
+        self.view.AwbFile = AWBBuilder(encoded, awb.subkey, awb.version, align=awb.align).build()
+        pass
+
+    @property
+    def cues(self) -> Generator[CueItem, None, None]:
+        """Returns a generator of **read-only** Cues.
+
+        Cues reference waveform bytes by their AWB IDs, which can be accessed via `waveforms`.
+        To modify cues, use the `view` property instead.
+        """
+        for name, cue in zip(self.view.CueNameTable, self.view.CueTable):
+            waveforms = self.view.waveform_of(cue.CueId)
+            yield CueItem(cue.CueId, name.CueName, cue.Length / 1000.0, [waveform.MemoryAwbId for waveform in waveforms])
 
 class ACBBuilder:
     acb: ACB
 
     def __init__(self, acb: ACB) -> None:
+        """Initializes the ACBBuilder with an existing ACB object.
+        
+        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.
+
+        Maybe one day I'll get around to this. But otherwise starting from nothing is a WONTFIX for now.
+        """
         self.acb = acb
 
     def build(self) -> bytes:
@@ -95,6 +260,9 @@ class ACBBuilder:
 
         The object may be modified in place before building, which will be reflected in the output binary.
         """
-        payload = deepcopy(self.acb.dictarray)
-        binary = UTFBuilder(payload, encoding=self.acb.encoding, table_name=self.acb.table_name)
+        # Check whether all AWB indices are valid
+        assert all(
+            waveform.MemoryAwbId < self.acb.awb.numfiles for waveform in self.acb.view.WaveformTable
+        ), "one or more AWB indices are out of range"
+        binary = UTFBuilder(self.acb.dictarray, encoding=self.acb.encoding, table_name=self.acb.table_name)
         return binary.bytes()

PyCriCodecsEx/awb.py

@@ -19,16 +19,21 @@ class AWB:
     headersize: int
     id_alignment: int
 
-    def __init__(self, stream) -> None:
+    def __init__(self, stream : str | BinaryIO) -> None:
+        """Initializes the AWB object
+
+        Args:
+            stream (str | BinaryIO): Source file path or binary stream
+        """
         if type(stream) == str:
             self.stream = FileIO(stream)
             self.filename = stream
         else:
             self.stream = BytesIO(stream)
             self.filename = ""
-        self.readheader()
+        self._readheader()
     
-    def readheader(self):
+    def _readheader(self):
         # Reads header.
         magic, self.version, offset_intsize, self.id_intsize, self.numfiles, self.align, self.subkey = AWBChunkHeader.unpack(
             self.stream.read(AWBChunkHeader.size)
@@ -39,9 +44,9 @@ class AWB:
         # Reads data in the header.
         self.ids = list()
         self.ofs = list()
-        for i in iter_unpack(f"<{self.stringtypes(self.id_intsize)}", self.stream.read(self.id_intsize*self.numfiles)):
+        for i in iter_unpack(f"<{self._stringtypes(self.id_intsize)}", self.stream.read(self.id_intsize*self.numfiles)):
             self.ids.append(i[0])
-        for i in iter_unpack(f"<{self.stringtypes(offset_intsize)}", self.stream.read(offset_intsize*(self.numfiles+1))):
+        for i in iter_unpack(f"<{self._stringtypes(offset_intsize)}", self.stream.read(offset_intsize*(self.numfiles+1))):
             self.ofs.append(i[0] if i[0] % self.align == 0 else (i[0] + (self.align - (i[0] % self.align))))
         
         # Seeks to files offset.
@@ -51,21 +56,20 @@ class AWB:
         self.stream.seek(self.headersize, 0)
 
     def get_files(self):
-        """ Generator function to yield all data blobs from an AWB. """
+        """Generator function to yield all data blobs from an AWB. """
+        self.stream.seek(self.headersize, 0)
         for i in range(1, len(self.ofs)):
             data = self.stream.read((self.ofs[i]-self.ofs[i-1]))
             self.stream.seek(self.ofs[i], 0)
             yield data
     
-    def get_file_at(self, index):
-        """ Gets you a file at specific index. """
-        index += 1
+    def get_file_at(self, index) -> bytes:
+        """Gets you a file at specific index. """
         self.stream.seek(self.ofs[index], 0)
-        data = self.stream.read(self.ofs[index]-self.ofs[index-1])
-        self.stream.seek(self.headersize, 0) # Seeks back to headersize for getfiles.
+        data = self.stream.read(self.ofs[index + 1]-self.ofs[index])
         return data
 
-    def stringtypes(self, intsize: int) -> str:
+    def _stringtypes(self, intsize: int) -> str:
         if intsize == 1:
             return "B" # Probably impossible.
         elif intsize == 2:
@@ -79,6 +83,15 @@ class AWB:
 
 class AWBBuilder:
     def __init__(self, infiles: list[bytes], subkey: int = 0, version: int = 2, id_intsize = 0x2, align: int = 0x20) -> None:
+        """Initializes the AWB builder.
+
+        Args:
+            infiles (list[bytes]): List of bytes to be included in the AWB file.
+            subkey (int, optional): AWB subkey. Defaults to 0.
+            version (int, optional): AWB version. Defaults to 2.
+            id_intsize (hexadecimal, optional): Integer size (in bytes) for string lengths. Defaults to 0x2.
+            align (int, optional): Alignment. Defaults to 0x20.
+        """
         if version == 1 and subkey != 0:
             raise ValueError("Cannot have a subkey with AWB version of 1.")
         elif id_intsize not in [0x2, 0x4, 0x8]:
@@ -89,7 +102,7 @@ class AWBBuilder:
         self.subkey = subkey
         self.id_intsize = id_intsize
         
-    def stringtypes(self, intsize: int) -> str:
+    def _stringtypes(self, intsize: int) -> str:
         if intsize == 1:
             return "B" # Probably impossible.
         elif intsize == 2:
@@ -102,6 +115,7 @@ class AWBBuilder:
             raise ValueError("Unknown int size.")
 
     def build(self) -> bytes:
+        """Builds the AWB file from the provided infiles bytes."""
         size = 0
         ofs = []
         numfiles = 0
@@ -122,7 +136,7 @@ class AWBBuilder:
             b'AFS2', self.version, intsize, self.id_intsize, numfiles, self.align, self.subkey
         )
 
-        id_strsize = f"<{self.stringtypes(self.id_intsize)}"
+        id_strsize = f"<{self._stringtypes(self.id_intsize)}"
         for i in range(numfiles):
             header += pack(id_strsize, i)
         

PyCriCodecsEx/chunk.py

@@ -12,7 +12,8 @@ WavNoteHeaderStruct = Struct("<4sII")
 WavDataHeaderStruct = Struct("<4sI")
 AdxHeaderStruct = Struct(">HHBBBBIIHBB")
 AdxLoopHeaderStruct = Struct(">HHHHIIII")
-
+AcbSynthReferenceStruct = Struct(">HH")
+AcbTrackCommandNoteOnStruct = Struct(">HH")
 class USMChunckHeaderType(Enum):
     CRID  = b"CRID" # Header.
     SFSH  = b"SFSH" # SofDec1 Header?
@@ -72,4 +73,25 @@ class CriHcaQuality(Enum):
     High    = 1
     Middle  = 2
     Low     = 3
-    Lowest  = 5
+    Lowest  = 5
+
+class AcbEncodeTypes(Enum):
+    ADX = 0
+    PCM = 1
+    HCA = 2
+    ADX_ALT = 3
+    WiiDSP = 4
+    NDSDSP = 5
+    HCAMX = 6
+    VAG = 7
+    ATRAC3 = 8
+    CWAV = 9
+    HEVAG = 10
+    ATRAC9 = 11
+    X360XMA = 12
+    DSP = 13
+    CWACDSP = 14
+    PS4HEVAG = 15
+    PS4ATRAC9 = 16
+    AACM4A = 17
+    SwitchOpus = 18

PyCriCodecsEx/cpk.py

@@ -8,7 +8,7 @@ from concurrent.futures import ProcessPoolExecutor, as_completed
 from tempfile import NamedTemporaryFile
 import CriCodecsEx
 
-def worker_do_compression(src : str, dst: str):
+def _worker_do_compression(src : str, dst: str):
     with open(src, "rb") as fsrc, open(dst, "wb") as fdst:
         data = fsrc.read()
         compressed = CriCodecsEx.CriLaylaCompress(data)
@@ -55,7 +55,12 @@ class CPK:
     stream: BinaryIO
     tables: dict
     filename: str
-    def __init__(self, filename) -> None:
+    def __init__(self, filename : str | BinaryIO) -> None:
+        """Loads a CPK archive's table-of-content and ready for file reading.
+
+        Args:
+            filename (str | BinaryIO): The path to the CPK file or a BinaryIO stream containing the CPK data.
+        """
         if type(filename) == str:
             self.filename = filename
             self.stream = FileIO(filename)
@@ -271,7 +276,7 @@ class CPKBuilder:
                 futures = []
                 for (src, _, _), (dst, compress) in zip(self.in_files,self.os_files):
                     if compress:
-                        futures.append(exec.submit(worker_do_compression, src, dst))
+                        futures.append(exec.submit(_worker_do_compression, src, dst))
                 for i, fut in as_completed(futures):
                     try:
                         fut.result()
@@ -281,7 +286,7 @@ class CPKBuilder:
         else:
             for i, ((src, _, _), (dst, compress)) in enumerate(zip(self.in_files,self.os_files)):
                     if compress:
-                        worker_do_compression(src, dst)
+                        _worker_do_compression(src, dst)
                         self.progress_cb("Compress %s" % os.path.basename(src), i + 1, len(self.in_files))
         for (src, filename, _) , (dst, _) in zip(self.in_files,self.os_files):
             file_size = os.stat(src).st_size         

PyCriCodecsEx/hca.py

@@ -46,7 +46,14 @@ class HCA:
     table: array
     looping: bool
 
-    def __init__(self, stream: BinaryIO, key: int = 0, subkey: int = 0) -> None:
+    def __init__(self, stream: str | BinaryIO, key: int = 0, subkey: int = 0) -> None:
+        """Initializes the HCA encoder/decoder
+
+        Args:
+            stream (str | BinaryIO): Path to the HCA or WAV file, or a BinaryIO stream.
+            key (int, optional): HCA key. Defaults to 0.
+            subkey (int, optional): HCA subkey. Defaults to 0.
+        """
         if type(stream) == str:
             self.stream = FileIO(stream)
             self.hcastream = FileIO(stream)
@@ -66,10 +73,10 @@ class HCA:
         self.hcabytes: bytearray = b''
         self.enc_table: array = b''
         self.table: array = b''
-        self.Pyparse_header()
+        self._Pyparse_header()
     
 
-    def Pyparse_header(self) -> None:
+    def _Pyparse_header(self) -> None:
         self.HcaSig, self.version, self.header_size = HcaHeaderStruct.unpack(
             self.hcastream.read(HcaHeaderStruct.size)
         )
@@ -230,7 +237,7 @@ class HCA:
         self.hcastream.seek(0)
     
     def info(self) -> dict:
-        """ Returns info related to the input file. """
+        """Returns info related to the input file. """
         if self.filetype == "hca":
             return self.hca
         elif self.filetype == "wav":
@@ -238,6 +245,7 @@ class HCA:
             return wav
     
     def decode(self) -> bytes:
+        """Decodes the HCA or WAV file to WAV bytes. """
         if self.filetype == "wav":
             raise ValueError("Input type for decoding must be an HCA file.")
         self.hcastream.seek(0)
@@ -247,6 +255,7 @@ class HCA:
         return bytes(self.wavbytes)
     
     def encode(self, force_not_looping: bool = False, encrypt: bool = False, keyless: bool = False, quality_level: CriHcaQuality = CriHcaQuality.High) -> bytes:
+        """Encodes the WAV file to HCA bytes."""
         if self.filetype == "hca":
             raise ValueError("Input type for encoding must be a WAV file.")
         if force_not_looping == False:
@@ -260,21 +269,21 @@ class HCA:
         self.stream.seek(0)
         self.hcabytes = CriCodecsEx.HcaEncode(self.stream.read(), force_not_looping, quality_level.value)
         self.hcastream = BytesIO(self.hcabytes)
-        self.Pyparse_header()
+        self._Pyparse_header()
         if encrypt:
             if self.key == 0 and not keyless:
                 self.key = 0xCF222F1FE0748978 # Default key.
-            self.encrypt(self.key, keyless)
+            self._encrypt(self.key, keyless)
         return self.get_hca()
  
-    def encrypt(self, keycode: int, subkey: int = 0, keyless: bool = False) -> None:
+    def _encrypt(self, keycode: int, subkey: int = 0, keyless: bool = False) -> None:
         if(self.encrypted):
             raise ValueError("HCA is already encrypted.")
         self.encrypted = True
         enc = CriCodecsEx.HcaCrypt(self.get_hca(), 1, self.header_size, (1 if keyless else 56), keycode, subkey)
         self.hcastream = BytesIO(enc)
 
-    def decrypt(self, keycode: int, subkey: int = 0) -> None:
+    def _decrypt(self, keycode: int, subkey: int = 0) -> None:
         if(not self.encrypted):
             raise ValueError("HCA is already decrypted.")
         self.encrypted = False
@@ -282,20 +291,20 @@ class HCA:
         self.hcastream = BytesIO(dec)
 
     def get_hca(self) -> bytes:
-        """ Use this function to get the HCA file bytes after encrypting or decrypting. """
+        """Get the HCA file bytes after encrypting or decrypting. """
         self.hcastream.seek(0)
         fl: bytes = self.hcastream.read()
         self.hcastream.seek(0)
         return fl
     
     def get_frames(self):
-        """ Generator function to yield Frame number, and Frame data. """
+        """Generator function to yield Frame number, and Frame data. """
         self.hcastream.seek(self.header_size, 0)
         for i in range(self.hca['FrameCount']):
             yield (i, self.hcastream.read(self.hca['FrameSize']))
     
     def get_header(self) -> bytes:
-        """ Use this function to retrieve the HCA Header. """
+        """Get the HCA Header. """
         self.hcastream.seek(0)
         header = self.hcastream.read(self.header_size)
         self.hcastream.seek(0)

PyCriCodecsEx/usm.py

@@ -332,7 +332,7 @@ class HCACodec(HCA):
 
     filesize: int
 
-    def __init__(self, stream: str | bytes, filename: str, quality: CriHcaQuality = CriHcaQuality.High, key=0, subkey=0, **kwargs):
+    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":
@@ -433,6 +433,13 @@ class HCACodec(HCA):
         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:
@@ -468,7 +475,7 @@ class ADXCodec(ADX):
     total_samples: int
     avbps: int
 
-    def __init__(self, stream: str | bytes, filename: str, bitdepth: int = 4, **kwargs):
+    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:
@@ -481,8 +488,8 @@ class ADXCodec(ADX):
         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"
+        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)
@@ -552,6 +559,10 @@ class ADXCodec(ADX):
     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:
@@ -729,7 +740,7 @@ class USM(USMCrypt):
         stream.filename = sfname
         return stream
 
-    def get_audios(self) -> List[HCACodec]:
+    def get_audios(self) -> List[ADXCodec | HCACodec]:
         """Create a list of audio codecs from the available streams."""
         match self.audio_codec:
             case ADXCodec.AUDIO_CODEC:
@@ -742,113 +753,71 @@ class USM(USMCrypt):
 class USMBuilder(USMCrypt):
     """USM class for building USM files."""
     video_stream: VP9Codec | H264Codec | MPEG1Codec
-    
-    enable_audio: bool
     audio_streams: List[HCACodec | ADXCodec]
 
-    key: int
-    encrypt: bool
-    encrypt_audio: bool
+    key: int = None
+    encrypt: bool = False
+    encrypt_audio: bool = False
 
-    audio_codec: int
-    # !!: TODO Quality settings
     def __init__(
         self,
-        video: str,
-        audio: List[str] | str = None,
         key = None,
-        audio_codec=HCACodec.AUDIO_CODEC,
-        encrypt_audio: bool = False,
+        encrypt_audio = False
     ) -> None:
         """Initialize the USMBuilder from set source files.
 
         Args:
-            video (str): The path to the video file. The video source format will be used to map accordingly to the ones Sofdec use.
-                - MPEG1 (with M1V container): MPEG1 Codec (Sofdec Prime)
-                - H264 (with H264 container): H264 Codec
-                - VP9 (with IVF container): VP9 Codec
-            audio (List[str] | str, optional): The path(s) to the audio file(s). Defaults to None.
             key (str | int, optional): The encryption key. Either int64 or a hex string. Defaults to None.
-            audio_codec (int, optional): The audio codec to use. Defaults to HCACodec.AUDIO_CODEC.
-            encrypt_audio (bool, optional): Whether to encrypt the audio. Defaults to False.
+            encrypt_audio (bool, optional): Whether to also encrypt the audio. Defaults to False.
         """
-        self.audio_codec = audio_codec
-        self.encrypt = False
-        self.enable_audio = False
-        self.encrypt_audio = encrypt_audio
-        self.key = 0
-        if encrypt_audio and not key:
-            raise ValueError("Cannot encrypt Audio without key.")
         if key:
             self.init_key(key)
             self.encrypt = True
-        self.load_video(video)
+        self.encrypt_audio = encrypt_audio
         self.audio_streams = []
-        if audio:
-            self.load_audio(audio)
-            self.enable_audio = True
-
-    def load_video(self, video):
-        temp_stream = FFmpegCodec(video)
-        self.video_stream = None
-        match temp_stream.stream["codec_name"]:
-            case "h264":
-                self.video_stream = H264Codec(video)
-            case "vp9":
-                self.video_stream = VP9Codec(video)
-            case "mpeg1video":
-                self.video_stream = MPEG1Codec(video)
-        assert self.video_stream, (
-            "fail to match suitable video codec. Codec=%s"
-            % temp_stream.stream["codec_name"]
-        )
 
-    def load_audio(self, audio):
-        self.audio_filenames = []
-        if type(audio) == list:
-            count = 0
-            for track in audio:
-                if type(track) == str:
-                    self.audio_filenames.append(os.path.basename(track))
-                else:
-                    self.audio_filenames.append("{:02d}.sfa".format(count))
-                    count += 1
-        else:
-            if type(audio) == str:
-                self.audio_filenames.append(os.path.basename(audio))
-            else:
-                self.audio_filenames.append("00.sfa")
+    def add_video(self, video : str | H264Codec | VP9Codec | MPEG1Codec):
+        """Sets the video stream from the specified video file.
 
-        self.audio_streams = []
-        codec = None
-        match self.audio_codec:
-            case HCACodec.AUDIO_CODEC:
-                codec = HCACodec
-            case ADXCodec.AUDIO_CODEC:
-                codec = ADXCodec
-        assert codec, (
-            "fail to match suitable audio codec given option: %s" % self.audio_codec
-        )
-        if type(audio) == list:
-            for track in audio:
-                if type(track) == str:
-                    fn = os.path.basename(track)
-                else:
-                    fn = "{:02d}.sfa".format(count)
-                hcaObj = codec(track, fn, key=self.key)
-                self.audio_streams.append(hcaObj)
+        USMs only support one video stream. Consecutive calls to this method will replace the existing video stream.
+
+        When `video` is str - it will be treated as a file path. The video source format will be used to map accordingly to the ones Sofdec use.
+            - MPEG1 (with M1V container): MPEG1 Codec (Sofdec Prime)
+            - H264 (with H264 container): H264 Codec
+            - VP9 (with IVF container): VP9 Codec
+            
+        Args:
+            video (str | FFmpegCodec): The path to the video file or an FFmpegCodec instance.
+        """
+        if isinstance(video, str):
+            temp_stream = FFmpegCodec(video)
+            self.video_stream = None
+            match temp_stream.stream["codec_name"]:
+                case "h264":
+                    self.video_stream = H264Codec(video)
+                case "vp9":
+                    self.video_stream = VP9Codec(video)
+                case "mpeg1video":
+                    self.video_stream = MPEG1Codec(video)
+            assert self.video_stream, (
+                "fail to match suitable video codec. Codec=%s"
+                % temp_stream.stream["codec_name"]
+            )
         else:
-            if type(audio) == str:
-                fn = os.path.basename(audio)
-            else:
-                fn = "00.sfa"
-            hcaObj = codec(audio, fn, key=self.key)
-            self.audio_streams.append(hcaObj)
+            self.video_stream = video
 
+    def add_audio(self, audio : ADXCodec | HCACodec):
+        """Append the audio stream(s) from the specified audio file(s).
+
+        Args:
+            audio (ADXCodec | HCACodec): The path(s) to the audio file(s).
+        """
+        self.audio_streams.append(audio)
 
     def build(self) -> bytes:
+        """Build the USM payload"""
         SFV_list = self.video_stream.generate_SFV(self)
-        if self.enable_audio:
+        if self.audio_streams:
             SFA_chunks = [s.generate_SFA(i, self) for i, s in enumerate(self.audio_streams) ]
         else:
             SFA_chunks = []
@@ -928,7 +897,7 @@ class USMBuilder(USMCrypt):
         )
         CRIUSF_DIR_STREAM.append(video_dict)
 
-        if self.enable_audio:
+        if self.audio_streams:
             chno = 0
             for stream in self.audio_streams:
                 avbps = stream.avbps
@@ -936,7 +905,7 @@ class USMBuilder(USMCrypt):
                 minbuf += 27860
                 audio_dict = dict(
                     fmtver=(UTFTypeValues.uint, 0),
-                    filename=(UTFTypeValues.string, self.audio_filenames[chno]),
+                    filename=(UTFTypeValues.string, stream.filename),
                     filesize=(UTFTypeValues.uint, stream.filesize),
                     datasize=(UTFTypeValues.uint, 0),
                     stmid=(
@@ -1018,7 +987,7 @@ class USMBuilder(USMCrypt):
 
         audio_metadata = []
         audio_headers = []
-        if self.enable_audio:
+        if self.audio_streams:
             chno = 0
             for stream in self.audio_streams:
                 metadata = stream.get_metadata()
@@ -1141,7 +1110,7 @@ class USMBuilder(USMCrypt):
         VIDEO_HDRINFO = gen_video_hdr_info(len(VIDEO_SEEKINFO))
 
         total_len = sum([len(x) for x in SFV_list]) + first_chk_ofs
-        if self.enable_audio:
+        if self.audio_streams:
             sum_len = 0
             for stream in SFA_chunks:
                 for x in stream:
@@ -1181,7 +1150,7 @@ class USMBuilder(USMCrypt):
 
         # Header chunks
         header += VIDEO_HDRINFO
-        if self.enable_audio:
+        if self.audio_streams:
             header += b''.join(audio_headers)            
         SFV_END = USMChunkHeader.pack(
             USMChunckHeaderType.SFV.value,
@@ -1202,7 +1171,7 @@ class USMBuilder(USMCrypt):
         header += SFV_END
 
         SFA_chk_END  = b'' # Maybe reused
-        if self.enable_audio:
+        if self.audio_streams:
             SFA_chk_END  = b''.join([
                 USMChunkHeader.pack(
                     USMChunckHeaderType.SFA.value,
@@ -1223,7 +1192,7 @@ class USMBuilder(USMCrypt):
         header += SFA_chk_END # Ends audio_headers
         header += VIDEO_SEEKINFO
 
-        if self.enable_audio:
+        if self.audio_streams:
             header += b''.join(audio_metadata)
         SFV_END = USMChunkHeader.pack(
             USMChunckHeaderType.SFV.value,

PyCriCodecsEx/utf.py

@@ -1,6 +1,8 @@
 from typing import BinaryIO, TypeVar, Type, List
+from copy import deepcopy
 
 T = TypeVar("T")
+Ty = TypeVar("Ty", bound="UTFViewer")
 from io import BytesIO, FileIO
 from struct import unpack, calcsize, pack
 from PyCriCodecsEx.chunk import *
@@ -302,7 +304,7 @@ class UTFBuilder:
 
     def __init__(
         self,
-        dictarray: list[dict],
+        dictarray_src: list[dict],
         encrypt: bool = False,
         encoding: str = "utf-8",
         table_name: str = "PyCriCodecs_table",
@@ -311,14 +313,14 @@ class UTFBuilder:
         """Packs UTF payload back into their binary form
         
         Args:
-            dictarray: A list of dictionaries representing the UTF table.
+            dictarray_src: list[dict]: A list of dictionaries representing the UTF table.
             encrypt: Whether to encrypt the table (default: False).
             encoding: The character encoding to use (default: "utf-8").
             table_name: The name of the table (default: "PyCriCodecs_table").
             ignore_recursion: Whether to ignore recursion when packing (default: False).
         """
-        assert type(dictarray) == list, "dictarray must be a list of dictionaries (see UTF.dictarray)."
-
+        assert type(dictarray_src) == list, "dictarray must be a list of dictionaries (see UTF.dictarray)."
+        dictarray = deepcopy(dictarray_src)
         # Preprocess for nested dictarray types
         def dfs(payload: list[dict], name: str) -> None:
             for dict in range(len(payload)):
@@ -618,7 +620,7 @@ class UTFViewer:
             See __new__ for the actual constructor.
         ```
         """
-        assert isinstance(payload, dict), "Payload must be a dictionary."
+        assert isinstance(payload, dict), "payload must be a dictionary."
         super().__setattr__("_payload", payload)
 
     def __getattr__(self, item):
@@ -643,7 +645,9 @@ class UTFViewer:
     def __setattr__(self, item, value):
         payload = super().__getattribute__("_payload")
         if item not in payload:
-            raise AttributeError(f"{item} not in payload")
+            raise AttributeError(f"{item} not in payload. UTFViewer should not store extra states")
+        if isinstance(value, dict) or isinstance(value, list):
+            raise AttributeError(f"Dict or list assignment is not allowed as this may potentially change the table layout. Access by elements and use list APIs instead")
         typeof, _ = payload[item]
         payload[item] = (typeof, value)
 
@@ -659,9 +663,9 @@ class UTFViewer:
 
     class ListView(list):
         _payload : List[dict]
-        def __init__(self, payload: list[T]):
+        def __init__(self, clazz : Type[Ty], payload: list[Ty]):
             self._payload = payload
-            super().__init__([UTFViewer(item) for item in payload])
+            super().__init__([clazz(item) for item in payload])
 
         def pop(self, index = -1):
             self._payload.pop(index)
@@ -669,7 +673,7 @@ class UTFViewer:
         
         def append(self, o : "UTFViewer"):
             if len(self):
-                assert type(self[0]) == type(o), "all items in the list must be of the same type."
+                assert isinstance(o, UTFViewer) and type(self[0]) == type(o), "all items in the list must be of the same type, and must be an instance of UTFViewer."
             self._payload.append(o._payload)
             return super().append(o)
         
@@ -677,9 +681,9 @@ class UTFViewer:
             for item in iterable:
                 self.append(item)
 
-        def insert(self, index, o : "UTFViewer"):
+        def insert(self, index, o : "UTFViewer"):         
             if len(self):
-                assert type(self[0]) == type(o), "all items in the list must be of the same type."            
+                assert isinstance(o, UTFViewer) and type(self[0]) == type(o), "all items in the list must be of the same type, and must be an instance of UTFViewer."
             self._payload.insert(index, o._payload)
             return super().insert(index, o)
 
@@ -698,7 +702,7 @@ class UTFViewer:
             self._payload[:] = [self._payload[i] for x,i in p]     
             self[:] = [x for x,i in p]            
 
-    def __new__(cls: Type[T], payload: list | dict, **args) -> T | List[T]:
+    def __new__(cls: Type[Ty], payload: list | dict, **args) -> Ty | List[Ty]:
         if isinstance(payload, list):
-            return UTFViewer.ListView(payload)
+            return UTFViewer.ListView(cls, payload)
         return super().__new__(cls)

{pycricodecsex-0.0.1.dist-info → pycricodecsex-0.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyCriCodecsEx
-Version: 0.0.1
+Version: 0.0.2
 Summary: Criware formats library for Python
 Home-page: https://github.com/mos9527/PyCriCodecsEx
 Classifier: Programming Language :: Python :: 3
@@ -33,8 +33,13 @@ For USM features, you need `ffmpeg` installed and available in your PATH. See al
 ## 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] Editing & Saving (Scripting APIs. Helper functions TODO. see examples in [Tests](https://github.com/mos9527/PyCriCodecsEx/tree/main/Tests))
+- [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.:
@@ -63,7 +68,7 @@ Decoding and Encoded format can be the following:
 - [x] Packing
 
 ## Roadmap
-- [ ] ACB Extraction (Massive TODO. see also https://github.com/mos9527/PyCriCodecsEx/blob/main/Research/ACBSchema.py)
+- [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

pycricodecsex-0.0.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+CriCodecsEx.cp313-win_amd64.pyd,sha256=rA5VO1X7Iwm0BehS5jnvj4ifrgdsdVUYHhhwG2ktVPo,89088
+PyCriCodecsEx/__init__.py,sha256=j7895T8JfsWQAOvxm8SAdESs5iFmIuAqKpyfjSAfKZ4,23
+PyCriCodecsEx/acb.py,sha256=vNPiGW1S0pkdWjcegTWId4C0suUCeX-kfFXUWuRnB-w,10352
+PyCriCodecsEx/adx.py,sha256=KnL4wy1ccoc6uHYZVino7cJQB2pMn4BbRhpH3r527TY,777
+PyCriCodecsEx/awb.py,sha256=sWUo5ITERYG504YVe9ejDYMM-bpLB31Ny4X-7rmmWlQ,6296
+PyCriCodecsEx/chunk.py,sha256=quk9VicOfp-_PgmcjyLL9rCIZQG8DhophXQZWpqfEUw,2925
+PyCriCodecsEx/cpk.py,sha256=sLFUGtG1yuwNC4puyp_TOgkhv1qnRGxVQu4ctlqXeUQ,37932
+PyCriCodecsEx/hca.py,sha256=ArZAaHogejBRE2rWEkTt8lS993Wf4SkjkjhNTo5Anqs,14550
+PyCriCodecsEx/usm.py,sha256=t2V98eno_beVuvU1tbuaFe4p7OohwROiUerMDHhPhEw,45107
+PyCriCodecsEx/utf.py,sha256=YWvgpgLy1tdhVWvRe4pbiJZFxnBRHdtQiR6xEetLsGk,28819
+pycricodecsex-0.0.2.dist-info/licenses/LICENSE,sha256=B47Qr_82CmMyuL-wNFAH_P6PNJWaonv5dxo9MfgjEXw,1083
+pycricodecsex-0.0.2.dist-info/METADATA,sha256=CAVs16QnoaoIrn8_PJH2w8wM64DTiIXNfxMUvCb-ZN0,3438
+pycricodecsex-0.0.2.dist-info/WHEEL,sha256=qV0EIPljj1XC_vuSatRWjn02nZIz3N1t8jsZz7HBr2U,101
+pycricodecsex-0.0.2.dist-info/top_level.txt,sha256=mSrrEse9hT0s6nl-sWAQWAhNRuZ6jo98pbFoN3L2MXk,26
+pycricodecsex-0.0.2.dist-info/RECORD,,

pycricodecsex-0.0.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-CriCodecsEx.cp313-win_amd64.pyd,sha256=bW3k3WYfeg9DMTVWSylRNGQGwLcdeHFjZqU77F9oO90,89088
-PyCriCodecsEx/__init__.py,sha256=ry5O5SW74ugwOUMKSV2_LbWjYa8B0IEvUm7S-lHPA2c,23
-PyCriCodecsEx/acb.py,sha256=v0CxjveQewxUWuila1O0qDGcAfvOxqnzYqAL4AHneqU,2706
-PyCriCodecsEx/adx.py,sha256=KnL4wy1ccoc6uHYZVino7cJQB2pMn4BbRhpH3r527TY,777
-PyCriCodecsEx/awb.py,sha256=p68tVqZOorOE1Js-w1Sqy4GMvu9gxzlBgUL2LAUNEqU,5657
-PyCriCodecsEx/chunk.py,sha256=nrRUANDFZ1LDszHEGDDnQDuNnAB_kGCzbpC7bsgtjqc,2504
-PyCriCodecsEx/cpk.py,sha256=AKShN6P7p70i3GQfKKS-VH3mkbexOLfHEJrjuxS0SQQ,37692
-PyCriCodecsEx/hca.py,sha256=lSslLyv1D1zM_kHFyOlKpbM7qzghmJDYRd-isP8qcyg,14192
-PyCriCodecsEx/usm.py,sha256=X4mv-3ksiX10C6EDACpu-dwRn9eSy3wmY7of2aO7eiA,46216
-PyCriCodecsEx/utf.py,sha256=Yp1Le3AS7UC4So_sGO39N5X5D23X7MsWugHo52npwR0,28256
-pycricodecsex-0.0.1.dist-info/licenses/LICENSE,sha256=B47Qr_82CmMyuL-wNFAH_P6PNJWaonv5dxo9MfgjEXw,1083
-pycricodecsex-0.0.1.dist-info/METADATA,sha256=Z4KAoITGoFoNhiiJ_YXSnrBE--W51_Q-pXt3lerFMX8,3324
-pycricodecsex-0.0.1.dist-info/WHEEL,sha256=qV0EIPljj1XC_vuSatRWjn02nZIz3N1t8jsZz7HBr2U,101
-pycricodecsex-0.0.1.dist-info/top_level.txt,sha256=mSrrEse9hT0s6nl-sWAQWAhNRuZ6jo98pbFoN3L2MXk,26
-pycricodecsex-0.0.1.dist-info/RECORD,,