osz2 1.1.0__tar.gz

osz2-1.1.0/LICENSE

@@ -0,0 +1,8 @@
+
+Copyright (c) 2025 Levi <contact@lekuru.xyz>, ascenttree
+
+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.

osz2-1.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: osz2
+Version: 1.1.0
+Summary: A python library for reading osz2 files
+Author: ascenttree
+Author-email: Lekuru <contact@lekuru.xyz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Lekuruu/osz2.py
+Keywords: osu,osz2,python,bancho
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: bsdiff4
+Dynamic: license-file
+
+# osz2.py
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![GitHub License](https://img.shields.io/github/license/Lekuruu/osz2.py)](https://github.com/Lekuruu/osz2.py/blob/main/LICENSE)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Lekuruu/osz2.py/.github%2Fworkflows%2Fbuild.yml)](https://github.com/Lekuruu/osz2.py/actions/workflows/build.yml)
+
+osz2.py is a Python library for reading osz2 files. It's a direct port of the existing [Osz2Decryptor](https://github.com/xxCherry/Osz2Decryptor) project by [xxCherry](https://github.com/xxCherry) and [osz2-go](https://github.com/Lekuruu/osz2-go) by me. The Python port itself was done by [@ascenttree](https://github.com/ascenttree); all credit goes to them. I took part in code refactoring and optimizing the performance by moving the heavy crypto primitives into a native C extension (`osz2.crypto`) on top of [NumPy](https://numpy.org/), bringing encryption time down to ~100 ms  instead of 25 seconds.
+
+This project *won't* provide beatmap parsing support. You will have to implement that by yourself, if you decide to use this library for implementing the beatmap submission system.
+
+## Installation
+
+```bash
+pip install osz2
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Lekuruu/osz2.py
+cd osz2.py
+pip install -e .
+```
+
+## Usage
+
+This repository provides a command-line interface for easy testing:
+
+```bash
+python -m osz2 decrypt <input.osz2> <output_directory>
+```
+
+```bash
+python -m osz2 encrypt <target_directory> <output.osz2>
+```
+
+But that's not all!  
+Here is an example of how to use osz2.py as a library:
+
+```python
+from osz2 import Osz2Package, MetadataType
+
+# Parse package from file
+package = Osz2Package.from_file("beatmap.osz2")
+
+# Access metadata
+print("Title:", package.metadata.get(MetadataType.Title))
+print("Artist:", package.metadata.get(MetadataType.Artist))
+print("Creator:", package.metadata.get(MetadataType.Creator))
+print("Difficulty:", package.metadata.get(MetadataType.Difficulty))
+
+# Access files
+for file in package.files:
+    print(f"File: {file.filename}, Size: {len(file.content)} bytes")
+
+# Extract specific files
+for file in package.files:
+    if not file.filename.endswith(".osu"):
+        continue
+
+    with open(file.filename, "wb") as f:
+        f.write(file.content)
+
+# Create a regular .osz package
+with open("beatmap.osz", "wb") as f:
+    f.write(package.create_osz_package())
+```
+
+### Metadata-only Mode
+
+If you only need to read metadata without extracting files, you can use the `metadata_only` parameter:
+
+```python
+# Only parse metadata
+package = Osz2Package.from_file("beatmap.osz2", metadata_only=True)
+
+# Access metadata
+print("Title:", package.metadata.get(MetadataType.Title))
+print("BeatmapSet ID:", package.metadata.get(MetadataType.BeatmapSetID))
+```
+
+### Alternative Constructors
+
+```python
+# From file path
+package = Osz2Package.from_file("beatmap.osz2")
+
+# From bytes
+with open("beatmap.osz2", "rb") as f:
+    data = f.read()
+    package = Osz2Package.from_bytes(data)
+
+# From an io.BufferedReader-like object, e.g. a file stream
+with open("beatmap.osz2", "rb") as f:
+    package = Osz2Package(f)
+```
+
+### Exporting an osz2 package
+
+You can initialize and export osz2 packages from a directory:
+
+```python
+from osz2 import Osz2Package, MetadataType
+
+# Initialize package from a directory containing beatmap files
+package = Osz2Package.from_directory("./my_beatmap_folder")
+
+# Export to osz2 format
+osz2_data = package.export()
+
+with open("output.osz2", "wb") as f:
+    f.write(osz2_data)
+```
+
+### Applying a patch
+
+When developing an implementation of the beatmap submission system, this could come in handy:
+
+```python
+# Assuming you have a source osz2 file and a patch file
+osz2_file = b"..."
+patch_file = b"..."
+
+updated_osz2 = osz2.apply_bsdiff_patch(osz2_file, patch_file)
+osz2 = Osz2Package.from_bytes(updated_osz2)
+```
+
+### Using osu!stream .osf2 files
+
+I have not tested this, but in theory this should work by passing in `KeyType.OSF2` when initializing the osz2 package:
+
+```python
+osf2 = Osz2Package.from_file("beatmap.osf2", key_type=KeyType.OSF2)
+```
+
+You can also specify this when using the command-line interface:
+
+```bash
+python -m osz2 <input.osz2> <output_directory> --key-type osf2
+```
+
+## Building the crypto.c extension
+
+If you change any code under `osz2/crypto.c`, rebuild the module in place before running tests:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+Or, if you only need the extension locally:
+
+```bash
+python setup.py build_ext --inplace
+```
+
+The resulting shared object is picked up automatically by the package import system.

osz2-1.1.0/README.md

@@ -0,0 +1,158 @@
+# osz2.py
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![GitHub License](https://img.shields.io/github/license/Lekuruu/osz2.py)](https://github.com/Lekuruu/osz2.py/blob/main/LICENSE)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Lekuruu/osz2.py/.github%2Fworkflows%2Fbuild.yml)](https://github.com/Lekuruu/osz2.py/actions/workflows/build.yml)
+
+osz2.py is a Python library for reading osz2 files. It's a direct port of the existing [Osz2Decryptor](https://github.com/xxCherry/Osz2Decryptor) project by [xxCherry](https://github.com/xxCherry) and [osz2-go](https://github.com/Lekuruu/osz2-go) by me. The Python port itself was done by [@ascenttree](https://github.com/ascenttree); all credit goes to them. I took part in code refactoring and optimizing the performance by moving the heavy crypto primitives into a native C extension (`osz2.crypto`) on top of [NumPy](https://numpy.org/), bringing encryption time down to ~100 ms  instead of 25 seconds.
+
+This project *won't* provide beatmap parsing support. You will have to implement that by yourself, if you decide to use this library for implementing the beatmap submission system.
+
+## Installation
+
+```bash
+pip install osz2
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Lekuruu/osz2.py
+cd osz2.py
+pip install -e .
+```
+
+## Usage
+
+This repository provides a command-line interface for easy testing:
+
+```bash
+python -m osz2 decrypt <input.osz2> <output_directory>
+```
+
+```bash
+python -m osz2 encrypt <target_directory> <output.osz2>
+```
+
+But that's not all!  
+Here is an example of how to use osz2.py as a library:
+
+```python
+from osz2 import Osz2Package, MetadataType
+
+# Parse package from file
+package = Osz2Package.from_file("beatmap.osz2")
+
+# Access metadata
+print("Title:", package.metadata.get(MetadataType.Title))
+print("Artist:", package.metadata.get(MetadataType.Artist))
+print("Creator:", package.metadata.get(MetadataType.Creator))
+print("Difficulty:", package.metadata.get(MetadataType.Difficulty))
+
+# Access files
+for file in package.files:
+    print(f"File: {file.filename}, Size: {len(file.content)} bytes")
+
+# Extract specific files
+for file in package.files:
+    if not file.filename.endswith(".osu"):
+        continue
+
+    with open(file.filename, "wb") as f:
+        f.write(file.content)
+
+# Create a regular .osz package
+with open("beatmap.osz", "wb") as f:
+    f.write(package.create_osz_package())
+```
+
+### Metadata-only Mode
+
+If you only need to read metadata without extracting files, you can use the `metadata_only` parameter:
+
+```python
+# Only parse metadata
+package = Osz2Package.from_file("beatmap.osz2", metadata_only=True)
+
+# Access metadata
+print("Title:", package.metadata.get(MetadataType.Title))
+print("BeatmapSet ID:", package.metadata.get(MetadataType.BeatmapSetID))
+```
+
+### Alternative Constructors
+
+```python
+# From file path
+package = Osz2Package.from_file("beatmap.osz2")
+
+# From bytes
+with open("beatmap.osz2", "rb") as f:
+    data = f.read()
+    package = Osz2Package.from_bytes(data)
+
+# From an io.BufferedReader-like object, e.g. a file stream
+with open("beatmap.osz2", "rb") as f:
+    package = Osz2Package(f)
+```
+
+### Exporting an osz2 package
+
+You can initialize and export osz2 packages from a directory:
+
+```python
+from osz2 import Osz2Package, MetadataType
+
+# Initialize package from a directory containing beatmap files
+package = Osz2Package.from_directory("./my_beatmap_folder")
+
+# Export to osz2 format
+osz2_data = package.export()
+
+with open("output.osz2", "wb") as f:
+    f.write(osz2_data)
+```
+
+### Applying a patch
+
+When developing an implementation of the beatmap submission system, this could come in handy:
+
+```python
+# Assuming you have a source osz2 file and a patch file
+osz2_file = b"..."
+patch_file = b"..."
+
+updated_osz2 = osz2.apply_bsdiff_patch(osz2_file, patch_file)
+osz2 = Osz2Package.from_bytes(updated_osz2)
+```
+
+### Using osu!stream .osf2 files
+
+I have not tested this, but in theory this should work by passing in `KeyType.OSF2` when initializing the osz2 package:
+
+```python
+osf2 = Osz2Package.from_file("beatmap.osf2", key_type=KeyType.OSF2)
+```
+
+You can also specify this when using the command-line interface:
+
+```bash
+python -m osz2 <input.osz2> <output_directory> --key-type osf2
+```
+
+## Building the crypto.c extension
+
+If you change any code under `osz2/crypto.c`, rebuild the module in place before running tests:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+Or, if you only need the extension locally:
+
+```bash
+python setup.py build_ext --inplace
+```
+
+The resulting shared object is picked up automatically by the package import system.

osz2-1.1.0/osz2/__init__.py

@@ -0,0 +1,17 @@
+
+__author__ = "Lekuru"
+__email__ = "contact@lekuru.xyz"
+__version__ = "1.1.0"
+__license__ = "MIT"
+
+from .patch import apply_bsdiff_patch
+from .metadata import MetadataType
+from .package import Osz2Package
+from .keys import KeyType
+from .file import File
+
+from .simple_cryptor import SimpleCryptor
+from .xxtea_reader import XXTEAReader
+from .xxtea_writer import XXTEAWriter
+from .xxtea import XXTEA
+from .xtea import XTEA

osz2-1.1.0/osz2/__main__.py

@@ -0,0 +1,186 @@
+
+from typing import Tuple, Dict, Union, Optional
+from osz2.metadata import MetadataType
+from osz2.package import Osz2Package
+from osz2.keys import KeyType
+from pathlib import Path
+
+import argparse
+import sys
+import os
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="osz2", description="A tool to decrypt, extract, and create osz2 files")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    decrypt_parser = subparsers.add_parser("decrypt", help="Decrypt and extract an osz2 file")
+    decrypt_parser.add_argument("input", help="The path to the osz2 file to decrypt")
+    decrypt_parser.add_argument("output", help="The path to put the extracted files")
+    decrypt_parser.add_argument("--key-type", choices=["osz2", "osf2"], default="osz2", help="The key generation method")
+    decrypt_parser.add_argument("--create-osz", action="store_true", help="Also create a regular .osz package")
+
+    encrypt_parser = subparsers.add_parser("encrypt", help="Create an osz2 package from a directory")
+    encrypt_parser.add_argument("input", help="The path to the directory containing files")
+    encrypt_parser.add_argument("output", help="The output path for the osz2 file")
+    encrypt_parser.add_argument("--key-type", choices=["osz2", "osf2"], default="osz2", help="The key generation method")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        return
+
+    key_type = KeyType(args.key_type)
+
+    if args.command == "decrypt":
+        osz2 = decrypt_osz2(args.input, key_type)
+        save_osz2(osz2, args.output)
+
+        if not args.create_osz:
+            return
+
+        osz_data = osz2.create_osz_package(exclude_disallowed_files=False)
+        with open(f"{args.output}/{osz2.osz_filename}", "wb") as f:
+            f.write(osz_data)
+
+    elif args.command == "encrypt":
+        encrypt_directory(
+            args.input,
+            args.output,
+            key_type
+        )
+
+def decrypt_osz2(filepath: str, key_type: KeyType) -> Osz2Package:
+    if not os.path.exists(filepath):
+        print(f"Error: Input file does not exist: {filepath}", file=sys.stderr)
+        sys.exit(1)
+
+    print("Reading osz2 package...")
+    return Osz2Package.from_file(filepath, key_type=key_type)
+
+def save_osz2(package: Osz2Package, output: str) -> None:
+    Path(output).mkdir(exist_ok=True)
+    print(f"Extracting {len(package.files)} files to {output}")
+
+    for file in package.files:
+        output_path = os.path.join(output, file.filename)
+
+        if (dir := Path(output_path).parent) != ".":
+            dir.mkdir(parents=True, exist_ok=True)
+
+        with open(output_path, "wb") as f:
+            f.write(file.content)
+
+        print(f"  -> {file.filename} ({len(file.content)} bytes)")
+
+def encrypt_directory(
+    directory: str,
+    output: str,
+    key_type: KeyType
+) -> None:
+    if not os.path.exists(directory):
+        print(f"Error: Input directory does not exist: {directory}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Creating osz2 package from directory: {directory}")
+    package = Osz2Package.from_directory(directory, key_type)
+
+    # Try to parse beatmap metadata and apply it to package
+    for beatmap in package.beatmap_files:
+        _, content = parse_beatmap(beatmap.content.decode("utf-8-sig"))
+        beatmap_id = content.get('Metadata', {}).get('BeatmapID', None)
+
+        if beatmap_id is not None:
+            package.beatmap_ids[beatmap.filename] = int(beatmap_id)
+
+        apply_metadata(package, content)
+
+    print(f"Exporting package with {len(package.files)} files...")
+
+    with open(output, "wb") as f:
+        data = package.export()
+        f.write(data)
+
+    print(f"Saved to: {output}")
+
+def apply_metadata(package: Osz2Package, beatmap: Dict[str, dict]) -> None:
+    if 'Metadata' not in beatmap:
+        print("Error: No 'Metadata' section found in beatmap")
+        sys.exit(1)
+
+    if 'General' not in beatmap:
+        print("Error: No 'General' section found in beatmap")
+        sys.exit(1)
+
+    metadata_section = beatmap['Metadata']
+    title = metadata_section.get('TitleUnicode') or metadata_section.get('Title', '')
+    artist = metadata_section.get('ArtistUnicode') or metadata_section.get('Artist', '')
+    creator = metadata_section.get('Creator', '')
+    source = metadata_section.get('Source', '')
+    tags = metadata_section.get('Tags', '')
+    beatmapset_id = metadata_section.get('BeatmapSetID', -1)
+
+    general_section = beatmap['General']
+    preview_time = general_section.get('PreviewTime', 0)
+
+    package.metadata[MetadataType.Title] = str(title)
+    package.metadata[MetadataType.Artist] = str(artist)
+    package.metadata[MetadataType.Creator] = str(creator)
+    package.metadata[MetadataType.Source] = str(source)
+    package.metadata[MetadataType.Tags] = str(tags)
+    package.metadata[MetadataType.BeatmapSetID] = str(beatmapset_id)
+    package.metadata[MetadataType.PreviewTime] = str(preview_time)
+
+def parse_beatmap(content: str) -> Tuple[int, Dict[str, dict]]:
+    sections: Dict[str, Union[dict, list]] = {}
+    current_section = None
+    beatmap_version = 0
+
+    for line in content.splitlines():
+        if line.startswith('osu file format'):
+            beatmap_version = int(line.removeprefix('osu file format v'))
+            continue
+
+        if (line.startswith('[') and line.endswith(']')):
+            # New section
+            current_section = line.removeprefix('[').removesuffix(']')
+            continue
+
+        if current_section is None:
+            continue
+
+        if not line:
+            continue
+
+        if current_section in ('General', 'Editor', 'Metadata', 'Difficulty'):
+            if current_section not in sections:
+                sections[current_section] = {}
+
+            # Parse key, value pair
+            key, value = (
+                split.strip() for split in line.split(':', maxsplit=1)
+            )
+
+            # Try to parse float/int
+            value = parse_number(value) or value
+
+            sections[current_section][key] = value
+            continue
+
+        if current_section not in sections:
+            sections[current_section] = []
+
+        # Append to list
+        sections[current_section].append(line)
+
+    return beatmap_version, sections
+
+def parse_number(value: str) -> Optional[Union[int, float]]:
+    for cast in (int, float):
+        try:
+            return cast(value.strip())
+        except ValueError:
+            continue
+
+if __name__ == "__main__":
+    main()

osz2-1.1.0/osz2/constants.py

@@ -0,0 +1,29 @@
+
+# "knownPlain" constant derived from FastRandom(1990)
+# https://github.com/ppy/osu-stream/blob/master/osu!stream/Helpers/osu!common/MapPackage.cs#L64
+KNOWN_PLAIN = bytearray([
+   0x55, 0xAA, 0x74, 0x10, 0x2B, 0x56, 0xB3, 0x9E,
+   0x25, 0x9E, 0xFE, 0xB7, 0xBE, 0x06, 0xFC, 0xF2,
+   0xB6, 0x3C, 0x6F, 0x47, 0x7E, 0x38, 0x69, 0x43,
+   0x80, 0x89, 0x25, 0x00, 0xCC, 0xB6, 0xFE, 0x12,
+   0xA9, 0xB2, 0x4A, 0x2C, 0x96, 0xD5, 0xEA, 0x26,
+   0x42, 0x31, 0xAF, 0x0A, 0x0D, 0xAE, 0x00, 0xED,
+   0xFE, 0x96, 0xA6, 0x94, 0x99, 0xA7, 0x90, 0xE4,
+   0x68, 0xBF, 0xC6, 0x97, 0x5B, 0x1B, 0x5E, 0x7F
+])
+
+# A list of all allowed file extensions in an .osz package
+# Did not cause any issues when testing on titanic
+ALLOWED_FILE_EXTENSIONS = (
+    "osu", "osz", "osb", "osk", "png", "mp3",
+    "wav", "ogg", "jpg", "wmv", "flv", "flac",
+    "avi", "ini",  "m4v", "mpg", "mov", "webm",
+    "ogv", "mpeg", "3gp", "mkv", "mp4", "jpeg",
+)
+
+# osu! officially only uses ".avi", ".flv" and ".mpg" for
+# video files, so lets hope this won't cause any issues
+VIDEO_FILE_EXTENSIONS = (
+    "wmv", "flv", "avi", "m4v", "mpg", "mov",
+    "webm", "ogv", "mpeg", "3gp", "mkv", "mp4",
+)