osz2 1.0.0__tar.gz

osz2-1.0.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.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: osz2
+Version: 1.0.0
+Summary: A python library for reading osz2 files
+Author: Lekuru
+Author-email: contact@lekuru.xyz
+Keywords: osu,osz2,python,bancho
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: summary
+
+# 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.
+
+## Installation
+
+```bash
+pip install git+https://github.com/Lekuruu/osz2.py@main
+```
+
+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 cli.py <input.osz2> <output_directory>
+```
+
+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)
+```
+
+### 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)
+```

osz2-1.0.0/README.md

@@ -0,0 +1,86 @@
+# 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.
+
+## Installation
+
+```bash
+pip install git+https://github.com/Lekuruu/osz2.py@main
+```
+
+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 cli.py <input.osz2> <output_directory>
+```
+
+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)
+```
+
+### 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)
+```

osz2-1.0.0/osz2/__init__.py

@@ -0,0 +1,13 @@
+
+__author__ = "Lekuru"
+__email__ = "contact@lekuru.xyz"
+__version__ = "1.0.0"
+__license__ = "MIT"
+
+from .package import Osz2Package
+from .types import MetadataType
+from .file import File
+
+from .simple_cryptor import SimpleCryptor
+from .xxtea_reader import XXTEAReader
+from .xxtea import XXTEA

osz2-1.0.0/osz2/file.py

@@ -0,0 +1,13 @@
+
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class File:
+    filename: str
+    offset: int
+    size: int
+    hash: bytes
+    date_created: datetime
+    date_modified: datetime
+    content: bytes

osz2-1.0.0/osz2/package.py

@@ -0,0 +1,157 @@
+
+from osz2.xxtea_reader import XXTEAReader
+from osz2.xxtea import XXTEA
+from typing import Dict, List
+
+from .types import MetadataType
+from .file import File
+from .utils import *
+
+import datetime
+import hashlib
+import struct
+import io
+
+class Osz2Package:
+    def __init__(self, reader: io.BufferedReader, metadata_only: bool = False) -> None:
+        self.metadata: Dict[MetadataType, str] = {}
+        self.filenames: Dict[str, int] = {}
+        self.files: List[File] = []
+        self.key: bytes = b""
+
+        self.metadata_hash: bytes = b""
+        self.file_info_hash: bytes = b""
+        self.full_body_hash: bytes = b""
+
+        # Always read the header when initializing
+        self.read_header(reader)
+
+        if not metadata_only:
+            # Read the files if requested
+            self.read_files(reader)
+
+    @classmethod
+    def from_file(cls, path: str, metadata_only: bool = False) -> "Osz2Package":
+        with open(path, "rb") as f:
+            return cls(f, metadata_only)
+
+    @classmethod
+    def from_bytes(cls, data: bytes, metadata_only: bool = False) -> "Osz2Package":
+        with io.BytesIO(data) as f:
+            return cls(f, metadata_only)
+
+    def read_header(self, reader: io.BufferedReader) -> None:
+        magic = reader.read(3)
+        assert magic == b"\xECHO", "Not a valid osz2 package" # nice one echo
+
+        # Seek 17 bytes from the current position
+        # to skip unused version byte & IV data
+        reader.seek(17, 1)
+
+        self.metadata_hash = reader.read(16)
+        self.file_info_hash = reader.read(16)
+        self.full_body_hash = reader.read(16)
+
+        self.read_metadata(reader)
+        self.read_file_names(reader)
+
+        assert MetadataType.Creator in self.metadata, "Metadata is missing creator"
+        assert MetadataType.BeatmapSetID in self.metadata, "Metadata is missing beatmapset ID"
+
+        creator = self.metadata[MetadataType.Creator]
+        beatmapset_id = self.metadata[MetadataType.BeatmapSetID]
+
+        seed = f"{creator}yhxyfjo5{beatmapset_id}"
+        self.key = hashlib.md5(seed.encode()).digest()
+
+    def read_metadata(self, reader: io.BufferedReader) -> None:
+        buffer = reader.read(4)
+        count = struct.unpack("<I", buffer)[0]
+
+        for _ in range(count):
+            buf = reader.read(2)
+            meta_type = struct.unpack("<H", buf)[0]
+            meta_value = read_string(reader)
+
+            self.metadata[MetadataType(meta_type)] = meta_value
+
+            buffer += buf
+            buffer += write_string(meta_value)
+
+        hash = compute_osz_hash(buffer, count*3, 0xA7)
+        assert hash == self.metadata_hash, f"Hash mismatch, expected: {hash}, got: {self.metadata_hash}"
+
+    def read_file_names(self, reader: io.BufferedReader) -> None:
+        buffer = reader.read(4)
+        count = struct.unpack("<I", buffer)[0]
+
+        for _ in range(count):
+            filename = read_string(reader)
+            beatmap_id = struct.unpack("<I", reader.read(4))[0]
+            self.filenames[filename] = beatmap_id
+
+        for name, id in self.filenames.items():
+            print(f"{name}: {id}")
+
+    def read_files(self, reader: io.BufferedReader) -> None:
+        reader.seek(64, 1)
+
+        # Read encrypted i32 length
+        length = struct.unpack("<I", reader.read(4))[0]
+
+        # Decode length by encrypted length
+        for i in range(0, 16, 2):
+            length -= self.file_info_hash[i] | (self.file_info_hash[i+1] << 17)
+
+        file_info = reader.read()
+        file_offset = reader.seek(0, 1)
+        total_size = reader.seek(0, 2)
+        reader.seek(file_offset, 0)
+
+        key = bytes_to_uint32_array(self.key)
+        xxtea_reader = XXTEAReader(io.BytesIO(file_info), key)
+
+        # Parse file info using xxtea stream and proceed to read file contents
+        self.parse_files(xxtea_reader, file_offset, total_size)
+
+    def parse_files(self, reader: XXTEAReader, file_offset: int, total_size: int) -> None:
+        count = struct.unpack("<I", reader.read(4))[0]
+        curr_offset = struct.unpack("<I", reader.read(4))[0]
+
+        for i in range(count):
+            filename = read_string(reader)
+            file_hash = reader.read(16)
+
+            date_created_binary = struct.unpack("<Q", reader.read(8))[0]
+            date_modified_binary = struct.unpack("<Q", reader.read(8))[0]
+
+            # Convert from .NET DateTime.ToBinary() format
+            date_created = datetime_from_binary(date_created_binary)
+            date_modified = datetime_from_binary(date_modified_binary)
+
+            next_offset = 0
+            if count > i + 1:
+                next_offset = struct.unpack("<I", reader.read(4))[0]
+            else:
+                # This is the last file, so we calculate size differently
+                # using total file size minus file offset
+                next_offset = total_size - file_offset
+
+            file_length = next_offset - curr_offset
+
+            file = File(
+                filename,
+                curr_offset,
+                file_length,
+                file_hash,
+                date_created,
+                date_modified,
+                content=bytes(),
+            )
+            self.files.append(file)
+            curr_offset = next_offset
+
+        # After reading the file info, read the actual file contents
+        for i in range(len(self.files)):
+            length = struct.unpack("<I", reader.read(4))[0]
+            self.files[i].content = reader.read(length)

osz2-1.0.0/osz2/simple_cryptor.py

@@ -0,0 +1,51 @@
+
+from typing import List
+
+class SimpleCryptor:
+    def __init__(self, key: bytes) -> None:
+        self.key = key
+
+    def encrypt_bytes(self, buf: bytearray) -> None:
+        byte_key = self.uint32_slice_to_byte_slice(self.key)
+        prev_encrypted = 0
+
+        for i in range(len(buf)):
+            sum_val = buf[i] + (byte_key[i % 16] >> 2)
+            buf[i] = ((sum_val % 256) + 256) % 256
+            buf[i] ^= self.rotate_left(byte_key[15 - i % 16], (prev_encrypted + len(buf) - i) % 7)
+            buf[i] = self.rotate_right(buf[i], (~prev_encrypted & 0xFFFFFFFF) % 7)
+            prev_encrypted = buf[i]
+
+    def decrypt_bytes(self, buf: bytearray) -> None:
+        byte_key = self.uint32_slice_to_byte_slice(self.key)
+        prev_encrypted = 0
+
+        for i in range(len(buf)):
+            tmp_e = buf[i]
+            buf[i] = self.rotate_left(buf[i], (~prev_encrypted & 0xFFFFFFFF) % 7)
+            buf[i] ^= self.rotate_left(byte_key[15 - i % 16], (prev_encrypted + len(buf) - i) % 7)
+            diff = buf[i] - (byte_key[i % 16] >> 2)
+            buf[i] = ((diff % 256) + 256) % 256
+            prev_encrypted = tmp_e
+
+    @staticmethod
+    def rotate_left(val: int, n: int) -> int:
+        val &= 0xFF
+        n &= 0x07
+        return ((val << n) | (val >> (8 - n))) & 0xFF
+
+    @staticmethod
+    def rotate_right(val: int, n: int) -> int:
+        val &= 0xFF
+        n &= 0x07
+        return ((val >> n) | (val << (8 - n))) & 0xFF
+
+    @staticmethod
+    def uint32_slice_to_byte_slice(u32s: List[int]) -> List[int]:
+        bytes_list = []
+        for u32 in u32s:
+            bytes_list.append(u32 & 0xFF)
+            bytes_list.append((u32 >> 8) & 0xFF)
+            bytes_list.append((u32 >> 16) & 0xFF)
+            bytes_list.append((u32 >> 24) & 0xFF)
+        return bytes_list

osz2-1.0.0/osz2/types.py

@@ -0,0 +1,27 @@
+
+from enum import IntEnum
+
+class MetadataType(IntEnum):
+    Title = 0
+    Artist = 1
+    Creator = 2
+    Version = 3
+    Source = 4
+    Tags = 5
+    VideoDataOffset = 6
+    VideoDataLength = 7
+    VideoHash = 8
+    BeatmapSetID = 9
+    Genre = 10
+    Language = 11
+    TitleUnicode = 12
+    ArtistUnicode = 13
+    Difficulty = 14
+    PreviewTime = 15
+    ArtistFullName = 16
+    ArtistTwitter = 17
+    SourceUnicode = 18
+    ArtistURL = 19
+    Revision = 20
+    PackID = 21
+    Unknown = 9999

osz2-1.0.0/osz2/utils.py

@@ -0,0 +1,57 @@
+
+import datetime
+import hashlib
+import struct
+import io
+
+def bytes_to_uint32_array(data: bytes) -> list[int]:
+    return [x[0] for x in struct.iter_unpack("<I", data)]
+
+def read_string(reader: io.BufferedReader) -> str:
+    length = read_uleb128(reader)
+    return reader.read(length).decode('utf-8')
+
+def write_string(string: str) -> bytes:
+    buf = write_uleb128(len(string))
+    return buf + string.encode('utf-8')
+
+def read_uleb128(reader: io.BufferedReader) -> int:
+    result = 0
+    shift = 0
+
+    while True:
+        b = reader.read(1)
+        result |= b[0]&0x7F << shift
+        if b[0]&0x80 == 0:
+            break
+        shift += 7
+
+    return result
+
+def write_uleb128(value: int) -> bytes:
+    buf = bytearray()
+    while value >= 0x80:
+        buf.append(value | 0x80)
+        value >>= 7
+    buf.append(value)
+    return bytes(buf)
+
+def compute_osz_hash(buffer: bytes, pos: int, swap: int) -> bytes:
+    buf = buffer
+    if pos >= 0 and pos < len(buffer):
+        buf = bytearray(buffer)
+        buf[pos] ^= swap
+
+    hash = bytearray(hashlib.md5(buf).digest())
+    for i in range(8):
+        hash[i], hash[i+8] = hash[i+8], hash[i]
+
+    hash[5] ^= 0x2D
+    return bytes(hash)
+
+def datetime_from_binary(time: int) -> datetime.datetime:
+    n_ticks = time & 0x3FFFFFFFFFFFFFFF
+    secs = n_ticks / 1e7
+    d1 = datetime.datetime(1, 1, 1)
+    t1 = datetime.timedelta(seconds=secs)
+    return d1 + t1

osz2-1.0.0/osz2/xxtea.py

@@ -0,0 +1,173 @@
+
+from .simple_cryptor import SimpleCryptor
+import struct
+
+MAX_WORDS = 16
+MAX_BYTES = MAX_WORDS * 4
+TEA_DELTA = 0x9E3779B9
+
+class XXTEA:
+    def __init__(self, key: bytes) -> None:
+        self.cryptor = SimpleCryptor(key)
+        self.key = key
+        self.n = 0
+
+    def decrypt(self, buffer: bytearray, start: int, count: int) -> None:
+        self.encrypt_decrypt(buffer, start, count, False)
+
+    def encrypt(self, buffer: bytearray, start: int, count: int) -> None:
+        self.encrypt_decrypt(buffer, start, count, True)
+
+    def encrypt_decrypt(self, buffer: bytearray, buf_start: int, count: int, encrypt: bool) -> None:
+        full_word_count = count // MAX_BYTES
+        left_over = count % MAX_BYTES
+
+        for i in range(full_word_count):
+            offset = buf_start + i * MAX_BYTES
+            if encrypt:
+                self.encrypt_fixed_word_array(buffer, offset)
+            else:
+                self.decrypt_fixed_word_array(buffer, offset)
+
+        if left_over == 0:
+            return
+
+        leftover_start = buf_start + full_word_count * MAX_BYTES
+        self.n = left_over // 4
+
+        if self.n > 1:
+            if encrypt:
+                self.encrypt_words(buffer, leftover_start)
+            else:
+                self.decrypt_words(buffer, leftover_start)
+
+            left_over -= self.n * 4
+            if left_over == 0:
+                return
+
+            leftover_start += self.n * 4
+
+        remaining = buffer[leftover_start:leftover_start + left_over]
+
+        if encrypt:
+            self.cryptor.encrypt_bytes(remaining)
+        else:
+            self.cryptor.decrypt_bytes(remaining)
+
+        buffer[leftover_start:leftover_start + left_over] = remaining
+
+    def encrypt_words(self, data: bytearray, offset: int) -> None:
+        if len(data) - offset < self.n * 4:
+            return
+
+        v = [struct.unpack_from('<I', data, offset + i * 4)[0] for i in range(self.n)]
+
+        rounds = 6 + 52 // self.n
+        sum_val = 0
+        z = v[self.n - 1]
+
+        while rounds > 0:
+            sum_val = (sum_val + TEA_DELTA) & 0xFFFFFFFF
+            e = (sum_val >> 2) & 3
+
+            for p in range(self.n - 1):
+                y = v[p + 1]
+                v[p] = (v[p] + ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+                z = v[p]
+
+            y = v[0]
+            p = self.n - 1
+            v[self.n - 1] = (v[self.n - 1] + ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+            z = v[self.n - 1]
+            rounds -= 1
+
+        for i in range(self.n):
+            struct.pack_into('<I', data, offset + i * 4, v[i])
+
+    def decrypt_words(self, data: bytearray, offset: int) -> None:
+        if len(data) - offset < self.n * 4:
+            return
+
+        v = [struct.unpack_from('<I', data, offset + i * 4)[0] for i in range(self.n)]
+
+        rounds = 6 + 52 // self.n
+        sum_val = (rounds * TEA_DELTA) & 0xFFFFFFFF
+        y = v[0]
+
+        while True:
+            e = (sum_val >> 2) & 3
+
+            for p in range(self.n - 1, 0, -1):
+                z = v[p - 1]
+                v[p] = (v[p] - ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+                y = v[p]
+
+            z = v[self.n - 1]
+            p = 0
+            v[0] = (v[0] - ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+            y = v[0]
+
+            sum_val = (sum_val - TEA_DELTA) & 0xFFFFFFFF
+            if sum_val == 0:
+                break
+
+        for i in range(self.n):
+            struct.pack_into('<I', data, offset + i * 4, v[i])
+
+    def encrypt_fixed_word_array(self, data: bytearray, offset: int) -> None:
+        if len(data) - offset < MAX_BYTES:
+            return
+
+        v = [struct.unpack_from('<I', data, offset + i * 4)[0] for i in range(MAX_WORDS)]
+
+        rounds = 6 + 52 // MAX_WORDS
+        sum_val = 0
+        z = v[MAX_WORDS - 1]
+
+        while rounds > 0:
+            sum_val = (sum_val + TEA_DELTA) & 0xFFFFFFFF
+            e = (sum_val >> 2) & 3
+
+            for p in range(MAX_WORDS - 1):
+                y = v[p + 1]
+                v[p] = (v[p] + ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+                z = v[p]
+
+            y = v[0]
+            p = MAX_WORDS - 1
+            v[MAX_WORDS - 1] = (v[MAX_WORDS - 1] + ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+            z = v[MAX_WORDS - 1]
+            rounds -= 1
+
+        for i in range(MAX_WORDS):
+            struct.pack_into('<I', data, offset + i * 4, v[i])
+
+    def decrypt_fixed_word_array(self, data: bytearray, offset: int) -> None:
+        if len(data) - offset < MAX_BYTES:
+            return
+
+        v = [struct.unpack_from('<I', data, offset + i * 4)[0] for i in range(MAX_WORDS)]
+
+        rounds = 6 + 52 // MAX_WORDS
+        sum_val = (rounds * TEA_DELTA) & 0xFFFFFFFF
+        y = v[0]
+
+        while True:
+            e = (sum_val >> 2) & 3
+
+            for p in range(MAX_WORDS - 1, 0, -1):
+                z = v[p - 1]
+                v[p] = (v[p] - ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+                y = v[p]
+
+            z = v[MAX_WORDS - 1]
+            p = 0
+            v[0] = (v[0] - ((((z >> 5) ^ (y << 2)) + ((y >> 3) ^ (z << 4))) ^ ((sum_val ^ y) + (self.key[(p & 3) ^ e] ^ z)))) & 0xFFFFFFFF
+            y = v[0]
+
+            sum_val = (sum_val - TEA_DELTA) & 0xFFFFFFFF
+            if sum_val == 0:
+                break
+
+        for i in range(MAX_WORDS):
+            struct.pack_into('<I', data, offset + i * 4, v[i])

osz2-1.0.0/osz2/xxtea_reader.py

@@ -0,0 +1,13 @@
+
+from osz2.xxtea import XXTEA
+from io import BytesIO
+
+class XXTEAReader:
+    def __init__(self, reader: BytesIO, key: list[int]) -> None:
+        self.reader: BytesIO = reader
+        self.xxtea: XXTEA = XXTEA(key)
+
+    def read(self, n: int) -> bytes:
+        read = bytearray(self.reader.read(n))
+        self.xxtea.decrypt(read, 0, n)
+        return bytes(read)

osz2-1.0.0/osz2.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: osz2
+Version: 1.0.0
+Summary: A python library for reading osz2 files
+Author: Lekuru
+Author-email: contact@lekuru.xyz
+Keywords: osu,osz2,python,bancho
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: summary
+
+# 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.
+
+## Installation
+
+```bash
+pip install git+https://github.com/Lekuruu/osz2.py@main
+```
+
+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 cli.py <input.osz2> <output_directory>
+```
+
+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)
+```
+
+### 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)
+```

osz2-1.0.0/osz2.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+setup.py
+osz2/__init__.py
+osz2/file.py
+osz2/package.py
+osz2/simple_cryptor.py
+osz2/types.py
+osz2/utils.py
+osz2/xxtea.py
+osz2/xxtea_reader.py
+osz2.egg-info/PKG-INFO
+osz2.egg-info/SOURCES.txt
+osz2.egg-info/dependency_links.txt
+osz2.egg-info/top_level.txt

osz2-1.0.0/osz2.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

osz2-1.0.0/osz2.egg-info/top_level.txt

@@ -0,0 +1 @@
+osz2

osz2-1.0.0/setup.cfg

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

osz2-1.0.0/setup.py

@@ -0,0 +1,21 @@
+
+import setuptools
+import osz2
+import os
+
+current_directory = os.path.dirname(os.path.abspath(__file__))
+
+with open(os.path.join(current_directory, "README.md"), "r") as f:
+    long_description = f.read()
+
+setuptools.setup(
+    name="osz2",
+    version=osz2.__version__,
+    author=osz2.__author__,
+    author_email=osz2.__email__,
+    description="A python library for reading osz2 files",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    packages=setuptools.find_packages(),
+    keywords=["osu", "osz2", "python", "bancho"],
+)