dade 0.0.1__py3-none-any.whl

dade/__init__.py

@@ -0,0 +1,4 @@
+"""Extract and convert assets from a collection of PC and console video games."""
+from __future__ import annotations
+
+__version__ = '0.0.1'

dade/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m dade`` invocation."""
+from __future__ import annotations
+
+from dade.main import main
+
+main()

dade/amplitude/__init__.py

@@ -0,0 +1,6 @@
+"""Game unpacker and asset converter for PS2 Amplitude and FreQuency (Harmonix)."""
+from __future__ import annotations
+
+from .unpacker import AmplitudeUnpacker
+
+__all__ = ('AmplitudeUnpacker',)

dade/amplitude/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m dade.amplitude`` invocation."""
+from __future__ import annotations
+
+from dade.amplitude.main import main
+
+main()

dade/amplitude/main.py

@@ -0,0 +1,91 @@
+"""Command-line entry point for the Amplitude game unpacker."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+import asyncio
+
+from rich.console import Console
+import bascom
+import click
+
+from dade.amplitude.unpacker import AmplitudeUnpacker
+from dade.common.exceptions import InvalidFormatError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ('main',)
+
+console = Console()
+"""The shared Rich :py:class:`~rich.console.Console` used for the progress spinner.
+
+:meta hide-value:
+"""
+
+debug_option = bascom.debug_option({'dade.amplitude': {}, 'dade.common': {}, 'dade.harmonix': {}})
+"""Attach ``-d/--debug`` to a command and route it through :py:func:`bascom.setup_logging`.
+
+:meta hide-value:
+"""
+
+
+@click.command(context_settings={'help_option_names': ('-h', '--help')})
+@click.argument('input_', metavar='DISC', type=click.Path(exists=True, path_type=Path))
+@debug_option
+@click.option('-o',
+              '--output-dir',
+              type=click.Path(file_okay=False, path_type=Path),
+              default=Path(),
+              help='Output directory (created if missing).')
+@click.option('-j',
+              '--jobs',
+              type=click.IntRange(min=0),
+              default=0,
+              help='Number of concurrent workers; 0 uses all CPUs.')
+@click.option('--no-convert', is_flag=True, help='Extract assets without converting them.')
+@click.option('--no-gunzip',
+              is_flag=True,
+              help='Extract .gz entries verbatim instead of decompressing.')
+@click.option('--keep-gz',
+              is_flag=True,
+              help='Keep the original .gz entry alongside the decompressed output.')
+@click.option('--ignore-failures',
+              is_flag=True,
+              help='Log and skip a conversion failure instead of stopping.')
+@click.option('--delete',
+              is_flag=True,
+              help='Delete converted intermediate files (the source is never touched).')
+def main(input_: Path,
+         *,
+         output_dir: Path,
+         jobs: int = 0,
+         no_convert: bool = False,
+         no_gunzip: bool = False,
+         keep_gz: bool = False,
+         ignore_failures: bool = False,
+         delete: bool = False) -> None:
+    """Unpack a PS2 Amplitude disc and convert its assets."""  # noqa: DOC501
+    unpacker = AmplitudeUnpacker(input_)
+
+    async def run(on_status: Callable[[str], None] | None) -> dict[str, str]:
+        return await unpacker.unpack(output_dir,
+                                     convert=not no_convert,
+                                     delete=delete,
+                                     gunzip=not no_gunzip,
+                                     ignore_failures=ignore_failures,
+                                     jobs=jobs,
+                                     keep_gz=keep_gz,
+                                     on_status=on_status)
+
+    # With ``--debug`` the streaming debug log owns the terminal, so no live spinner is started.
+    try:
+        if click.get_current_context().params.get('debug', False):
+            stats = asyncio.run(run(None))
+        else:
+            with console.status('Unpacking...') as status:
+                stats = asyncio.run(run(status.update))
+    except (InvalidFormatError, ValueError) as e:
+        raise click.ClickException(str(e)) from e
+    for label, summary in stats.items():
+        click.echo(f'{label}: {summary}')

dade/amplitude/unpacker.py

@@ -0,0 +1,18 @@
+"""Developer-facing unpacker for the PS2 game Amplitude (Harmonix)."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from dade.harmonix.unpacker import Unpacker
+
+if TYPE_CHECKING:
+    from dade.harmonix.typing import ArkLayout
+
+__all__ = ('AmplitudeUnpacker',)
+
+
+class AmplitudeUnpacker(Unpacker):
+    """Unpacker for the PS2 game Amplitude (its magic-less ``GEN/MAIN.ARK`` layout)."""
+
+    ark_layout: ClassVar[ArkLayout] = 'amplitude'
+    game_name: ClassVar[str] = 'Amplitude'

dade/bit192/__init__.py

@@ -0,0 +1,21 @@
+"""
+Tone Sphere (bit192labs) toolkit.
+
+``bit192`` holds the game-specific pieces that sit on top of the generic Marmalade support in
+:mod:`marmalade`:
+
+- :func:`~dade.bit192.cz.decrypt` - undo Tone Sphere's ``.cz`` XOR layer to recover a Derbh
+  archive.
+- :func:`~dade.bit192.extract.extract` - unpack and decode every asset from an
+  ``.xapk``/``.apk``/``.obb``.
+- :func:`dade.bit192.audio.wrap_wav` - wrap Tone Sphere's headerless 16-bit PCM as WAV.
+- :class:`dade.bit192.save.SaveFile` - read and edit ``save.bin`` (e.g. unlock DLC).
+"""
+from __future__ import annotations
+
+from .audio import wrap_wav
+from .cz import decrypt
+from .extract import extract
+from .save import SaveFile
+
+__all__ = ('SaveFile', 'decrypt', 'extract', 'wrap_wav')

dade/bit192/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m bit192`` invocation."""
+from __future__ import annotations
+
+from dade.bit192.main import main
+
+main()

dade/bit192/audio.py

@@ -0,0 +1,75 @@
+"""
+Raw PCM helper for Tone Sphere.
+
+Tone Sphere ships some sounds as headerless little-endian 16-bit PCM (``.raw``) played through
+Marmalade's ``s3eSound`` at 44100 Hz stereo (the rate/channel count are this game's choice, not a
+Marmalade constant). This module wraps such data in a canonical WAV container so it plays anywhere.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from dade.common.wav import wrap_pcm
+
+__all__ = ('DEFAULT_CHANNELS', 'DEFAULT_RATE', 'wrap_raw_file', 'wrap_wav')
+
+DEFAULT_RATE = 44100
+"""Tone Sphere's ``s3eSound`` sample rate (Hz).
+
+:meta hide-value:
+"""
+DEFAULT_CHANNELS = 2
+"""Tone Sphere's channel count (stereo).
+
+:meta hide-value:
+"""
+_BITS = 16
+
+
+def wrap_wav(pcm: bytes, rate: int = DEFAULT_RATE, channels: int = DEFAULT_CHANNELS) -> bytes:
+    """
+    Wrap headerless 16-bit PCM in a WAV container.
+
+    Parameters
+    ----------
+    pcm : bytes
+        Little-endian signed 16-bit PCM samples (interleaved if stereo).
+    rate : int
+        Sample rate in Hz.
+    channels : int
+        Channel count (1 = mono, 2 = stereo).
+
+    Returns
+    -------
+    bytes
+        A complete RIFF/WAVE file.
+    """
+    block = channels * (_BITS // 8)
+    data = pcm[:len(pcm) - (len(pcm) % block)] if block else pcm
+    return wrap_pcm(data, rate=rate, channels=channels, bits=_BITS)
+
+
+def wrap_raw_file(raw_path: str | Path,
+                  rate: int = DEFAULT_RATE,
+                  channels: int = DEFAULT_CHANNELS) -> Path:
+    """
+    Write a ``.wav`` next to a headerless ``.raw`` file.
+
+    Parameters
+    ----------
+    raw_path : str or pathlib.Path
+        Path to the ``.raw`` PCM file.
+    rate : int
+        Sample rate in Hz.
+    channels : int
+        Channel count.
+
+    Returns
+    -------
+    pathlib.Path
+        The written ``.wav`` path.
+    """
+    src = Path(raw_path)
+    dst = src.with_suffix('.wav')
+    dst.write_bytes(wrap_wav(src.read_bytes(), rate=rate, channels=channels))
+    return dst

dade/bit192/commands/__init__.py

@@ -0,0 +1 @@
+"""Command exports."""

dade/bit192/commands/decrypt_cz.py

@@ -0,0 +1,33 @@
+"""``tonesphere decrypt-cz`` - undo the ``.cz`` XOR layer to recover a Derbh archive."""
+from __future__ import annotations
+
+from pathlib import Path
+import logging
+
+import click
+
+from dade.bit192 import cz
+
+from .utils import console, debug_option
+
+__all__ = ('decrypt_cz',)
+
+log = logging.getLogger(__name__)
+
+
+@click.command(name='decrypt-cz')
+@click.argument('source', type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.argument('dest', type=click.Path(dir_okay=False, path_type=Path))
+@debug_option
+def decrypt_cz(source: Path, dest: Path) -> None:
+    """
+    Decrypt SOURCE (a ``.cz`` file) to DEST (a Derbh ``.dz`` archive).
+
+    Unpack DEST afterwards with ``marm extract-dz``.
+    """
+    log.debug('Decrypting %s to %s.', source, dest)
+    data = cz.decrypt(source.read_bytes())
+    if data[:4] != b'DTRZ':
+        console.print('[yellow]Warning:[/yellow] the result is not a Derbh archive (wrong keys?).')
+    dest.write_bytes(data)
+    console.print(f'[green]Decrypted {source.name} to {dest}.[/green]')

dade/bit192/commands/extract.py

@@ -0,0 +1,42 @@
+"""``tonesphere extract`` - unpack and decode every Tone Sphere asset."""
+from __future__ import annotations
+
+from pathlib import Path
+import logging
+
+import click
+
+from dade.bit192.extract import extract as extract_assets
+
+from .utils import console, debug_option
+
+__all__ = ('extract',)
+
+log = logging.getLogger(__name__)
+
+
+@click.command(name='extract')
+@click.argument('inputs',
+                nargs=-1,
+                required=True,
+                type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option('--keep-group-bin',
+              is_flag=True,
+              help='Keep raw .group.bin files alongside their decoded folders.')
+@click.option('-o',
+              '--out',
+              required=True,
+              type=click.Path(file_okay=False, path_type=Path),
+              help='Output directory.')
+@debug_option
+def extract(inputs: tuple[Path, ...], out: Path, *, keep_group_bin: bool) -> None:
+    """
+    Extract and decode every asset from INPUTS into the output directory.
+
+    INPUTS is an ``.xapk``/``.apkm`` bundle, or an ``.apk``, optionally with its ``.obb``. Archives
+    are unpacked, ``.group.bin`` resources are decoded to open formats in place, and ``.raw`` PCM is
+    wrapped as ``.wav``.
+    """
+    log.debug('Extracting %d input(s) into %s.', len(inputs), out)
+    root = extract_assets(inputs, out, keep_group_bin=keep_group_bin)
+    console.print(f'[green]Extracted all assets to {root}.[/green]')

dade/bit192/commands/save.py

@@ -0,0 +1,145 @@
+"""``tonesphere save`` - inspect and edit ``save.bin``."""
+from __future__ import annotations
+
+from pathlib import Path
+import logging
+
+import click
+
+from dade.bit192.save import DLC_OFFSETS, SaveFile
+
+from .utils import console, debug_option
+
+__all__ = ('save',)
+
+log = logging.getLogger(__name__)
+
+
+@click.group()
+def save() -> None:
+    """Inspect and edit a Tone Sphere ``save.bin``."""
+
+
+@save.command(name='device-id')
+@click.argument('save_path', type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@debug_option
+def device_id(save_path: Path) -> None:
+    """Print the device id cached in SAVE_PATH (DLC tokens are bound to it)."""
+    found = SaveFile.load(save_path).device_id
+    console.print(f'Device ID: {found}.' if found else 'No device id is cached; run the game once.')
+
+
+@save.command(name='unlock-dlc')
+@click.argument('save_path', type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option('-o',
+              '--out',
+              type=click.Path(dir_okay=False, path_type=Path),
+              help='Write to this path instead of overwriting SAVE_PATH.')
+@click.option('-p',
+              '--pack',
+              'packs',
+              multiple=True,
+              type=click.Choice(sorted(DLC_OFFSETS)),
+              help='Unlock only this pack (repeatable). Default: all packs.')
+@debug_option
+def unlock_dlc(save_path: Path, out: Path | None, packs: tuple[str, ...]) -> None:
+    """
+    Write DLC ownership tokens into SAVE_PATH.
+
+    Tokens are ``MD5(device_id + pack)``, so the save must come from the target device (its device
+    id is read straight out of the file). The integrity hash is never verified on load, so no
+    checksum fix-up is needed for local use.
+    """
+    sf = SaveFile.load(save_path)
+    log.debug('Editing save with device id %r.', sf.device_id)
+    unlocked = [*packs] if packs else sf.unlock_all_dlc()
+    for name in packs:
+        sf.unlock_dlc(name)
+    dest = out or save_path
+    sf.save(dest)
+    console.print(f'[green]Unlocked {", ".join(unlocked)} and wrote {dest}.[/green]')
+
+
+@save.command(name='unlock-songs')
+@click.argument('save_path', type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option('-o',
+              '--out',
+              type=click.Path(dir_okay=False, path_type=Path),
+              help='Write to this path instead of overwriting SAVE_PATH.')
+@debug_option
+def unlock_songs(save_path: Path, out: Path | None) -> None:
+    """
+    Unlock every regular (non-DLC) song in SAVE_PATH.
+
+    Sets the whole song unlock-flag array, so every ``UnlockNum``-gated song becomes visible without
+    meeting its ``CondChart``/``CondStar`` condition. DLC episodes need device-bound tokens instead;
+    use ``unlock-dlc`` (or ``unlock-all``) for those.
+    """
+    sf = SaveFile.load(save_path)
+    count = sf.unlock_all_songs()
+    dest = out or save_path
+    sf.save(dest)
+    console.print(f'[green]Set {count} song unlock flags and wrote {dest}.[/green]')
+
+
+@save.command(name='unlock-all')
+@click.argument('save_path', type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option('-o',
+              '--out',
+              type=click.Path(dir_okay=False, path_type=Path),
+              help='Write to this path instead of overwriting SAVE_PATH.')
+@debug_option
+def unlock_all(save_path: Path, out: Path | None) -> None:
+    """
+    Unlock everything in SAVE_PATH: every regular song and every DLC pack.
+
+    Combines ``unlock-songs`` and ``unlock-dlc``. DLC tokens are device-bound, so the save must come
+    from the target device (its device id is read straight out of the file).
+    """
+    sf = SaveFile.load(save_path)
+    log.debug('Editing save with device id %r.', sf.device_id)
+    count = sf.unlock_all_songs()
+    packs = sf.unlock_all_dlc()
+    dest = out or save_path
+    sf.save(dest)
+    console.print(
+        f'[green]Set {count} song flags and unlocked {", ".join(packs)}; wrote {dest}.[/green]')
+
+
+@save.command(name='generate')
+@click.argument('out', type=click.Path(dir_okay=False, path_type=Path))
+@click.option('-i',
+              '--device-id',
+              default='',
+              help='Device id for DLC tokens ("iOS" on iOS; the ANDROID_ID/SSAID on Android).')
+@click.option('-f',
+              '--from-save',
+              type=click.Path(exists=True, dir_okay=False, path_type=Path),
+              help='Copy the device id from an existing save instead of passing --device-id.')
+@click.option('--no-dlc', is_flag=True, help='Unlock songs only; do not write DLC tokens.')
+@debug_option
+def generate(out: Path, device_id: str, from_save: Path | None, *, no_dlc: bool) -> None:
+    """
+    Generate a fresh, fully-unlocked ``save.bin`` at OUT (from a zero-initialised save).
+
+    Every regular song is unlocked unconditionally. DLC tokens are device-bound
+    (``MD5(device_id + pack)``), so supply the target device's id via ``--device-id`` or copy it
+    from an existing save with ``--from-save``; on iOS the id is always ``"iOS"``. Songs do not
+    depend on the device id. The integrity hash is never verified on load, so the result loads
+    as-is.
+    """
+    resolved_id = SaveFile.load(from_save).device_id if from_save is not None else device_id
+    sf = SaveFile.blank()
+    sf.set_device_id(resolved_id)
+    log.debug('Generating save with device id %r.', resolved_id)
+    count = sf.unlock_all_songs()
+    if no_dlc:
+        sf.save(out)
+        console.print(f'[green]Generated {out} with {count} songs unlocked (DLC skipped).[/green]')
+        return
+    packs = sf.unlock_all_dlc()
+    sf.save(out)
+    console.print(f'[green]Generated {out}: {count} song flags + {len(packs)} DLC packs.[/green]')
+    if not resolved_id:
+        console.print('[yellow]Note:[/yellow] no device id was set, so the DLC tokens will not '
+                      'match a real device. Pass --device-id or --from-save to bind them.')

dade/bit192/commands/utils.py

@@ -0,0 +1,22 @@
+"""Shared helpers for the ``tonesphere`` command-line tool."""
+from __future__ import annotations
+
+from rich.console import Console
+import bascom
+
+__all__ = ('console', 'debug_option')
+
+console = Console()
+"""
+Shared Rich :py:class:`~rich.console.Console` used by command-side output.
+
+:meta hide-value:
+"""
+
+debug_option = bascom.debug_option({'dade.bit192': {}, 'dade.common': {}, 'dade.marmalade': {}})
+"""Attach ``-d/--debug`` to a leaf command and route it through :py:func:`bascom.setup_logging`.
+
+When set, both the ``bit192`` and ``marmalade`` loggers switch to ``DEBUG`` for the command.
+
+:meta hide-value:
+"""

dade/bit192/cz.py

@@ -0,0 +1,88 @@
+"""
+``.cz`` decryption.
+
+A ``.cz`` file is an ordinary Marmalade Derbh (DTRZ) archive wrapped in two layered repeating-key
+XOR ciphers that bit192labs added on top of the SDK::
+
+    plain[i] = cz[i] ^ KEY1[i % len(KEY1)] ^ KEY2[i % len(KEY2)]
+
+The two keys are hard-coded constants lifted from the game binary (``FUN_4a06bd68``; key tables at
+``0x4a18c3e0`` and ``0x4a18c3c8``). They are exposed here as :data:`KEY1` / :data:`KEY2` and used as
+the defaults, but :func:`decrypt` accepts arbitrary keys so the same XOR scheme can be reused.
+
+Decrypting a ``.cz`` yields the ``DTRZ`` bytes that :func:`marmalade.derbh.unpack` reads.
+"""
+from __future__ import annotations
+
+__all__ = ('KEY1', 'KEY2', 'decrypt', 'looks_like_cz')
+
+KEY1 = bytes((0xE9, 0xBD, 0xA8, 0x08, 0xE3, 0x9B, 0x59, 0x0C, 0xBC, 0xEF, 0xEF, 0x3C, 0xC2, 0x23,
+              0xEA, 0x01, 0xFA, 0x59, 0x5B, 0xAA, 0x00, 0x00))
+"""First XOR key (22 bytes), from the Tone Sphere binary at ``0x4a18c3e0``.
+
+:meta hide-value:
+"""
+KEY2 = bytes((0xAC, 0x3E, 0x11, 0x19, 0x20, 0x00, 0x10, 0x6A, 0x6D, 0x24, 0x5B, 0x4F, 0x99, 0x14,
+              0xA3, 0x4E, 0x00, 0x00))
+"""Second XOR key (18 bytes), from the Tone Sphere binary at ``0x4a18c3c8``.
+
+:meta hide-value:
+"""
+
+_DTRZ = b'DTRZ'
+
+
+def decrypt(data: bytes, key1: bytes = KEY1, key2: bytes = KEY2) -> bytes:
+    """
+    Decrypt ``.cz`` bytes to the underlying ``DTRZ`` archive.
+
+    The cipher is its own inverse (XOR), so this also re-encrypts.
+
+    Parameters
+    ----------
+    data : bytes
+        Encrypted ``.cz`` contents.
+    key1 : bytes
+        First repeating XOR key. Defaults to :data:`KEY1`.
+    key2 : bytes
+        Second repeating XOR key. Defaults to :data:`KEY2`.
+
+    Returns
+    -------
+    bytes
+        Decrypted contents (a ``DTRZ`` archive for valid Tone Sphere input).
+
+    Raises
+    ------
+    ValueError
+        If either key is empty.
+    """
+    n1, n2 = len(key1), len(key2)
+    if not n1 or not n2:
+        msg = 'XOR keys must be non-empty.'
+        raise ValueError(msg)
+    out = bytearray(len(data))
+    for i, b in enumerate(data):
+        out[i] = b ^ key1[i % n1] ^ key2[i % n2]
+    return bytes(out)
+
+
+def looks_like_cz(data: bytes, key1: bytes = KEY1, key2: bytes = KEY2) -> bool:
+    """
+    Return ``True`` if *data* decrypts to a ``DTRZ`` archive with the given keys.
+
+    Parameters
+    ----------
+    data : bytes
+        Candidate ``.cz`` contents.
+    key1 : bytes
+        First repeating XOR key. Defaults to :data:`KEY1`.
+    key2 : bytes
+        Second repeating XOR key. Defaults to :data:`KEY2`.
+
+    Returns
+    -------
+    bool
+        Whether the first four decrypted bytes are the ``DTRZ`` magic.
+    """
+    return decrypt(data[:4], key1, key2) == _DTRZ