tiptoi-tools 0.1.0__tar.gz

tiptoi_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Retailleau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiptoi_tools-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: tiptoi-tools
+Version: 0.1.0
+Summary: Tiptoi GME inspection and extraction tools.
+Author-email: Jeremy Retailleau <jeremy.retailleau@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/buddly27/tiptoi-tools
+Project-URL: Changelog, https://github.com/buddly27/tiptoi-tools/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/buddly27/tiptoi-tools/issues
+Keywords: tiptoi,gme,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.3.1
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: miniaudio<2,>=1.60
+Provides-Extra: dev
+Requires-Dist: ruff>=0.14.0; extra == "dev"
+Dynamic: license-file
+
+# tiptoi-tools
+
+Python CLI for inspecting, extracting, and building Ravensburger Tiptoi GME files.
+
+## Installation
+
+```bash
+pip install tiptoi-tools
+```
+
+## Usage
+
+```bash
+# Show file information
+tiptoi-tools file.gme info
+
+# Export to YAML and media files
+tiptoi-tools file.gme export
+
+# Build GME from YAML
+tiptoi-tools file.yaml build
+
+# Play audio by OID or media index
+tiptoi-tools file.gme play 123
+tiptoi-tools file.gme play @456
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `info` | Show GME file metadata and structure |
+| `export` | Export to YAML with media files |
+| `build` | Build GME from tttool-compatible YAML |
+| `play` | Play audio by OID or media index |
+| `scripts` | Browse and search scripts |
+| `games` | List games and their structure |
+| `oids` | Explore OID relationships |
+
+## Acknowledgments
+
+This project is inspired by and compatible with [tttool](https://github.com/entropia/tip-toi-reveng), the original Tiptoi reverse-engineering toolkit created by Joachim Breitner ([@nomeata](https://github.com/nomeata)). The GME file format documentation and YAML schema originate from the tttool project.
+
+## License
+
+MIT

tiptoi_tools-0.1.0/README.md

@@ -0,0 +1,46 @@
+# tiptoi-tools
+
+Python CLI for inspecting, extracting, and building Ravensburger Tiptoi GME files.
+
+## Installation
+
+```bash
+pip install tiptoi-tools
+```
+
+## Usage
+
+```bash
+# Show file information
+tiptoi-tools file.gme info
+
+# Export to YAML and media files
+tiptoi-tools file.gme export
+
+# Build GME from YAML
+tiptoi-tools file.yaml build
+
+# Play audio by OID or media index
+tiptoi-tools file.gme play 123
+tiptoi-tools file.gme play @456
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `info` | Show GME file metadata and structure |
+| `export` | Export to YAML with media files |
+| `build` | Build GME from tttool-compatible YAML |
+| `play` | Play audio by OID or media index |
+| `scripts` | Browse and search scripts |
+| `games` | List games and their structure |
+| `oids` | Explore OID relationships |
+
+## Acknowledgments
+
+This project is inspired by and compatible with [tttool](https://github.com/entropia/tip-toi-reveng), the original Tiptoi reverse-engineering toolkit created by Joachim Breitner ([@nomeata](https://github.com/nomeata)). The GME file format documentation and YAML schema originate from the tttool project.
+
+## License
+
+MIT

tiptoi_tools-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tiptoi-tools"
+version = "0.1.0"
+description = "Tiptoi GME inspection and extraction tools."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["tiptoi", "gme", "cli"]
+authors = [
+    { name = "Jeremy Retailleau", email = "jeremy.retailleau@gmail.com" }
+]
+dependencies = [
+    "click>=8.3.1,<9",
+    "PyYAML>=6.0.3,<7",
+    "miniaudio>=1.60,<2",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+tiptoi-tools = "tiptoi_tools.__main__:main"
+
+[project.urls]
+Repository = "https://github.com/buddly27/tiptoi-tools"
+Changelog = "https://github.com/buddly27/tiptoi-tools/blob/main/CHANGELOG.md"
+Issues = "https://github.com/buddly27/tiptoi-tools/issues"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.14.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+skip-magic-trailing-comma = false

tiptoi_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tiptoi_tools-0.1.0/src/tiptoi_tools/__main__.py

@@ -0,0 +1,10 @@
+import tiptoi_tools.command_line
+
+
+def main():
+    """Execute main command line interface passing command line arguments."""
+    tiptoi_tools.command_line.cli(prog_name="tiptoi-tools")
+
+
+if __name__ == "__main__":
+    main()

tiptoi_tools-0.1.0/src/tiptoi_tools/audio.py

@@ -0,0 +1,63 @@
+import time
+
+import miniaudio
+
+
+class AudioPlaybackError(Exception):
+    """Raised when audio playback fails."""
+
+
+def play_audio(data: bytes, verbose: bool = False) -> None:
+    """
+    Play audio data using miniaudio.
+
+    Args:
+        data: Raw audio bytes (decrypted)
+        verbose: If True, show additional playback info
+
+    Raises:
+        AudioPlaybackError: If playback fails
+    """
+    try:
+        # Decode audio - miniaudio auto-detects format
+        decoded = miniaudio.decode(data, output_format=miniaudio.SampleFormat.SIGNED16)
+
+        duration = decoded.num_frames / decoded.sample_rate
+
+        if verbose:
+            print(
+                f"    Audio: {decoded.sample_rate}Hz, "
+                f"{decoded.nchannels}ch, {duration:.2f}s"
+            )
+
+        # Start playback device
+        device = miniaudio.PlaybackDevice(
+            output_format=miniaudio.SampleFormat.SIGNED16,
+            nchannels=decoded.nchannels,
+            sample_rate=decoded.sample_rate,
+        )
+
+        # Use stream_memory for proper playback
+        stream = miniaudio.stream_memory(
+            data,
+            output_format=miniaudio.SampleFormat.SIGNED16,
+            nchannels=decoded.nchannels,
+            sample_rate=decoded.sample_rate,
+        )
+
+        device.start(stream)
+
+        # Wait for playback to complete
+        time.sleep(duration + 0.2)
+        device.close()
+
+    except miniaudio.DecodeError as e:
+        raise AudioPlaybackError(f"Failed to decode audio: {e}") from None
+    except miniaudio.MiniaudioError as e:
+        raise AudioPlaybackError(f"Playback error: {e}") from None
+
+
+def get_player_info() -> str:
+    """Return information about the audio backend."""
+    backends = miniaudio.get_enabled_backends()
+    return f"miniaudio (backends: {', '.join(b.name for b in backends)})"

tiptoi_tools-0.1.0/src/tiptoi_tools/binary.py

@@ -0,0 +1,169 @@
+import struct
+from typing import TypeAlias
+
+OID: TypeAlias = int
+
+
+def u8(data: bytes, offset: int) -> int:
+    """Read an unsigned 8-bit integer."""
+    return data[offset]
+
+
+def u16le(data: bytes, offset: int) -> int:
+    """Read a little-endian unsigned 16-bit integer."""
+    return struct.unpack_from("<H", data, offset)[0]
+
+
+def u32le(data: bytes, offset: int) -> int:
+    """Read a little-endian unsigned 32-bit integer."""
+    return struct.unpack_from("<I", data, offset)[0]
+
+
+def pack_u8(value: int) -> bytes:
+    """Pack an unsigned 8-bit integer to bytes."""
+    return bytes([value & 0xFF])
+
+
+def pack_u16le(value: int) -> bytes:
+    """Pack a little-endian unsigned 16-bit integer to bytes."""
+    return struct.pack("<H", value)
+
+
+def lo_u8(n: int) -> int:
+    """Extract the low byte of a 16-bit value."""
+    return n & 0xFF
+
+
+def hi_u8(n: int) -> int:
+    """Extract the high byte of a 16-bit value."""
+    return (n >> 8) & 0xFF
+
+
+def ascii_clean(b: bytes) -> str:
+    """Decode bytes as ASCII, replacing invalid characters."""
+    return b.decode("ascii", errors="replace")
+
+
+class BinaryReader:
+    """Sequential reader for binary data with automatic offset tracking."""
+
+    def __init__(self, data: bytes, offset: int = 0):
+        self.data = data
+        self.offset = offset
+
+    def u8(self) -> int:
+        """Read an unsigned 8-bit integer."""
+        v = self.data[self.offset]
+        self.offset += 1
+        return v
+
+    def u16(self) -> int:
+        """Read a little-endian unsigned 16-bit integer."""
+        v = u16le(self.data, self.offset)
+        self.offset += 2
+        return v
+
+    def u32(self) -> int:
+        """Read a little-endian unsigned 32-bit integer."""
+        v = u32le(self.data, self.offset)
+        self.offset += 4
+        return v
+
+    def bytes(self, n: int) -> bytes:
+        """Read n raw bytes."""
+        v = self.data[self.offset : self.offset + n]
+        self.offset += n
+        return v
+
+    def u16_array(self, count: int) -> list[int]:
+        """Read an array of u16 values."""
+        values = [u16le(self.data, self.offset + i * 2) for i in range(count)]
+        self.offset += count * 2
+        return values
+
+    def u32_array(self, count: int) -> list[int]:
+        """Read an array of u32 values."""
+        values = [u32le(self.data, self.offset + i * 4) for i in range(count)]
+        self.offset += count * 4
+        return values
+
+    def u16_list(self) -> list[int]:
+        """Read a length-prefixed list of u16 values."""
+        n = self.u16()
+        return self.u16_array(n)
+
+    def at(self, offset: int) -> "BinaryReader":
+        """Create a new reader at the given absolute offset."""
+        return BinaryReader(self.data, offset)
+
+    def skip(self, n: int) -> None:
+        """Skip n bytes."""
+        self.offset += n
+
+
+class BinaryWriter:
+    """Sequential writer for binary data with automatic offset tracking."""
+
+    def __init__(self):
+        self._data = bytearray()
+
+    @property
+    def offset(self) -> int:
+        """Current write position."""
+        return len(self._data)
+
+    def u8(self, value: int) -> None:
+        """Write an unsigned 8-bit integer."""
+        self._data.append(value & 0xFF)
+
+    def u16(self, value: int) -> None:
+        """Write a little-endian unsigned 16-bit integer."""
+        self._data.extend(struct.pack("<H", value))
+
+    def u32(self, value: int) -> None:
+        """Write a little-endian unsigned 32-bit integer."""
+        self._data.extend(struct.pack("<I", value))
+
+    def bytes(self, data: bytes) -> None:
+        """Write raw bytes."""
+        self._data.extend(data)
+
+    def u16_array(self, values: list[int]) -> None:
+        """Write an array of u16 values."""
+        for v in values:
+            self.u16(v)
+
+    def u32_array(self, values: list[int]) -> None:
+        """Write an array of u32 values."""
+        for v in values:
+            self.u32(v)
+
+    def u16_list(self, values: list[int]) -> None:
+        """Write a length-prefixed list of u16 values."""
+        self.u16(len(values))
+        self.u16_array(values)
+
+    def pad_to(self, target: int) -> None:
+        """Pad with zeros to reach target offset."""
+        if self.offset < target:
+            self._data.extend(b"\x00" * (target - self.offset))
+
+    def u8_at(self, offset: int, value: int) -> None:
+        """Patch a u8 at a specific offset."""
+        self._data[offset] = value & 0xFF
+
+    def u16_at(self, offset: int, value: int) -> None:
+        """Patch a u16 at a specific offset."""
+        self._data[offset : offset + 2] = struct.pack("<H", value)
+
+    def u32_at(self, offset: int, value: int) -> None:
+        """Patch a u32 at a specific offset."""
+        self._data[offset : offset + 4] = struct.pack("<I", value)
+
+    def bytes_at(self, offset: int, data: bytes) -> None:
+        """Patch bytes at a specific offset."""
+        self._data[offset : offset + len(data)] = data
+
+    def to_bytes(self) -> bytes:
+        """Return the written data as bytes."""
+        return bytes(self._data)