hca: Improve WAV compatibility

Author: mos9527

PyCriCodecsEx/__init__.py

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

PyCriCodecsEx/hca.py

@@ -209,32 +209,28 @@ def _Pyparse_header(self) -> None:
                     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)

README.md

@@ -1,60 +1,9 @@
-# PyCriCodecsEx
+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
-```
+Detailed documentation, installation instructions are available at https://mos9527.com/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

docs/source/index.rst

@@ -1,3 +1,5 @@
+.. include:: styles.rst
+
 PyCriCodecsEx documentation
 ===========================
 
@@ -6,9 +8,92 @@ This site contains automatically generated API documentation for every format `P
 Most if not all features are verified to work with either commercial games, or official SDK tools. However issues are to be
 expected - submit bug reports or feature requests on the `Issue Tracker <https://github.com/mos9527/PyCriCodecsEx/issues>`_.
 
-PyCriCodecsEx is a fork of `Youjose/PyCriCodecs <https://github.com/Youjose/PyCriCodecs>`_. You can refer to the original repository
+PyCriCodecsEx is a fork of `Youjose/PyCriCodecs <https://github.com/Youjose/PyCriCodecs>`_. Refer to the original repository
 and its `Wiki <https://github.com/Youjose/PyCriCodecs/wiki/Docs-and-Thoughts>`_ for more information.
 
+The GitHub repository is available at `mos9527/PyCriCodecsEx <https://github.com/mos9527/PyCriCodecsEx>`_
+
+Installation
+============
+PyCriCodecsEx is available on `PyPI <https://pypi.org/project/PyCriCodecsEx/>`_
+
+.. code-block:: bash
+
+   pip install PyCriCodecsEx
+
+For USM features, you need `ffmpeg` installed and available in your PATH, and install the `[usm]` extra - which installs `ffmpeg-python <https://github.com/kkroening/ffmpeg-python>`_.
+
+To make sure `ffmpeg` is available, you can refer to `ffmpeg-python's instructions <https://github.com/kkroening/ffmpeg-python?tab=readme-ov-file#installing-ffmpeg>`_.
+
+.. code-block:: bash
+
+   pip install PyCriCodecsEx[usm]
+
+
+Support Status
+========
+
+
+
+USM Sofdec2 (Encode & Decode)
+-----------------------------
+
+**Audio Stream**
+
+Decoding and Encoded format can be the following:
+
+* |check| HCA
+* |check| ADX
+
+**Video Stream**
+
+**NOTE**: You definitely want to tweak these encode settings a bit.
+
+* |check| Sofdec Prime (MPEG1, from ``.m1v`` container)
+
+  * Prepare source file with: ``ffmpeg -i <input_file> -c:v mpeg1video -an <output_file>.m1v``
+
+* |check| H264 (from ``.h264`` raw container)
+
+  * Prepare source file with: ``ffmpeg -i <input_file> -c:v libx264 -an <output_file>.h264``
+
+* |check| VP9 (from ``.ivf`` container)
+
+  * Prepare source file with: ``ffmpeg -i <input_file> -c:v libvpx -an <output_file>.ivf``
+
+CPK
+---
+* |check| Unpacking
+* |check| Packing
+
+ACB Cue sheets (also AWB)
+-------------------------
+* |check| Cue extraction support for most ACBs
+* |check| Cue waveform(s) encoding with ADX/HCA support
+* |check| Comprehensive Cue metadata editing support (via Python API)
+
+ADX Audio Codec
+---------------
+* |check| Decoding
+* |check| Encoding
+
+HCA Audio Codec
+---------------
+* |check| Decoding (up to version 3.0)
+* |check| Encoding (up to version 3.0)
+
+Roadmap
+=======
+* |uncheck| Interface for encode tasks (most probably done in a separate project)
+* |uncheck| 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.
+
 .. include:: USM.rst
 
 .. include:: CPK.rst

docs/source/styles.rst

@@ -0,0 +1,10 @@
+..
+    https://stackoverflow.com/questions/6904552/how-to-create-a-checklist-in-restructuredtext-rest
+
+.. |check| raw:: html
+
+    <input checked=""  disabled="" type="checkbox">
+
+.. |uncheck| raw:: html
+
+    <input disabled="" type="checkbox">

setup.py

@@ -39,7 +39,7 @@ def build_extensions(self):
     description="Criware formats library for Python",
     long_description=open("README.md", "r", encoding="utf-8").read(),
     long_description_content_type="text/markdown",
-    url='https://github.com/mos9527/PyCriCodecsEx',
+    url='https://mos9527.github.io/PyCriCodecsEx/',
     packages=["PyCriCodecsEx"],
     ext_modules=[Extension(
         'CriCodecsEx',