PyCriCodecs

Python frontend with a C++ backend for managing Criware formats. Although for some tasks, python is used purely.

Supporting

I am running this on Python 3.11, although other earlier versions might work

So far this lib supports in terms of:

Extracting:

ACB/AWB (Incorrect filenames in extraction.)
USM (Any USM there is)
CPK (Most CPK's)

Decoding:

ADX (All versions)
HCA (All versions)

Building:

CPK (All CPK modes)
AWB (Anything)
USM (VP9 support only, ADX or HCA Audio support, multiple audio streams support as well, VP9/ADX only tested and for sure working!)

Encoding:

HCA (HCA Version 2.0)
ADX (All versions, any bitdepth, any blocksize, any HighPass Frequence, All encoding versions)

Installation and Usage

To install run

python setup.py install

or alternatively

pip install .

Note: all libs (except ADX) here are standardized to take either a filename/path or bytes/bytearray, so you can swap both.

Also, for audio related codecs, the looping input and output is defined in the metadata, the WAV file will not loop, but it will have a "smpl" chunk in the header, same if you want to encode a looping HCA or an ADX, the WAV must have a smpl chunk.

Otherwise it will loop normally.

Usage:

For ADX decoding and encoding:

from PyCriCodecs import *
# Decoding:
adx_data = open("path_to_adx_file.adx", "rb").read()
wavfilebytes = ADX.decode(adx_data) # Decode will return bytes object containing decoded ADX data as a wav file.

# Encoding:
wav_data = open("path_to_wav_file.wav", "rb").read()
adxbytes = ADX.encode(wav_data) # Returns an ADX file as bytes, check the wiki for more options.

For HCA decoding and encoding:

from PyCriCodecs import *
hcaObj = HCA("filename.hca", key=0xCF222F1FE0748978) # You can change the key, or remove it if the HCA is not encrypted. Key can be a hex string.
wavfile = hcaObj.decode() # Gets you the wav file after decoding.

wavObj = HCA("filename.wav")
hcabytes = wavObj.encode(encrypt=True) # and you will get an HCA file.
# You can provide a key from when initializing, otherwise it will default to the default key, you can also encrypt keyless with keyless=true.
# You can also force disable looping on HCA output by force_not_looping = True.

wavObj.encrypt()
# or
hcaObj.decrypt() 
# Any works, given it can be decrypted or encrypted as an HCA. Would do it. You can also pass a key to ".encrypt()", ".decrypt()" uses the init key.

For CPK extraction and building:

from PyCriCodecs import *
# Extraction:
CpkObj = CPK("filename.cpk")
CpkObj.extract() # Will extract files to a dir names "filename"
CpkObj.extract_file() # Extract a file from a given filename (or an ID for CPKMode 0)

# Building:
CPKBuilder("dirname", "outfile.cpk", CpkMode=1) # CpkMode is important sometimes, get your target mode by extracting a sample table. 
# Given a directory, it will take that directory as root, and builds a CPK for the directories and files inside.
# Output would be a cpk file as specified.

For USM extraction and Building:

-Note that USM building might be a little bit unstable due to bad code, feel free to open any issues if something did went wrong.

from PyCriCodecs import *
# Extraction:
usmObj = USM("filename.cpk") # or bytes, you can add a key by key="KEYINHEXGOESHERE"
usmObj.extract() # extracts all USM contents in the current directory. You can add a directory with extract(dirname = "Example")

# You can also demux the USM internally and manage with the output bytes all you want.
usmObj.demux() # Then you have access to output property.
usmObj.output # This is a dict containing all chunks in the USM, each key has a value of a list with bytearrays.

usmObj.get_metadata() # Not for the user specifically, but if you want to look at the info inside, this is one way.

# Building:
# Needs at least a video to be able to build one USM file, you can add audio pretty easily too.
usmObj = USMBuilder("filename.ivf", "filename.wav", key=0xKEYGOESINHERE, audio_codec="adx", encryptAudio=True) # Basic USM
# You can add a list of audio paths/filenames as well instead of filenames, and that will be added into audio streams in order.
usmObj.build() # Due to bad code, this is heavy on performance and will take some seconds based of the input files.
usmbytes = usmObj.get_usm() # Will return the USM file as bytes.

For ACB or AWB extraction:

from PyCriCodecs import *
# ACB Extraction:
acbObj = ACB("filename.acb") # It will attempt to open "filename.awb" as well if there are no sub-banks in the ACB.
acbObj.extract(dirname="dirname", decode=True, key=key) # You can turn off decoding by decode=False.
# AWB Extraction:
awbObj = AWB("filename.awb")
# You can either loop through the audios inside with:
for file in awbObj.getfiles():
    file # file bytes.
    open("file.hca or anything", wb).write(file)

# or you can call the extract function, not advised.
awbObj.extract()

Check the Wiki for my thoughts, plans, more options, and some details as well for documentation.

TODO List

Add ACB building.
Add correct ACB extraction.

Currently Known Bugs

USM Building is not stable, and currently does not work at all because I changed the ADX api.
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

vgmstream for HCA code.
VGAudio for ADX codec, and HCA encoding, both of which I ported into C++ but modified the ADX lib greatly.
K0lb3 for helping a lot with python and Cpython, as well as helping me writing some of the code.
bnnm for his various contributions on audio formats, helped me a lot with adding ADX and HCA support.
Nyagamon for a lot of what he did for criware formats.
donmai and his writeup of CriWare's UTF format.
9th for also helping me with some python knowledge.

Deficuet/PyCriCodecs