Skip to main content

osu-orz

Python bindings for ORZ, a lossless compression format for osu! replays.

import osu_orz

orz = osu_orz.compress(osr_bytes)  # an .osr file
assert osu_orz.decompress(orz) == osr_bytes

# bare replay data (the LZMA stream osu! stores for a score) has no header, so say what it is
orz = osu_orz.compress(replay_data, mode=osu_orz.Mode.OSU_RELAX)
assert osu_orz.decompress(orz) == replay_data

Modes

compress reads an .osr's game mode and Relax from its header. Bare replay data needs mode in place of the header, and an .osr must not be given one, so the two can never disagree.

Mode Replay
OSU, TAIKO, CATCH, MANIA the game mode, without Relax
OSU_RELAX, TAIKO_RELAX, CATCH_RELAX the game mode with Relax (osu!mania has none)

The values are the mode numbers ORZ files store. Autopilot replays are OSU: the encoder recognises the autopilot path from the frames itself. The mode picks the coder and its priors, so a wrong mode only makes the .orz bigger: the frames come back the same under every mode, and replay data osu! wrote comes back byte for byte.

What comes back

decompress rebuilds the input compress was given:

  • the replay frames exactly;
  • the .osr fields around them exactly (header, life bar, timestamp, score id);
  • the replay data's LZMA bytes, compressed again the way osu! compresses them. Replay data osu! wrote comes back byte for byte. Data written by other software comes back with the same frames, compressed like osu! would.

Some replay data is stored as it is, and comes back byte for byte:

  • data the codec can not code as frames (not LZMA, or text that is not osu!'s frames);
  • data whose coded frames would be no smaller than its LZMA;
  • with check_round_trip=True, data whose coded frames do not decode back to it. compress then decodes what it wrote before returning it, which is slower but keeps a coding bug from turning into a replay that decodes wrong.

Errors raise osu_orz.OrzError (a ValueError): an .osr given a mode, anything else without one that is not an .osr, an .orz given to compress, or an .orz that is damaged, cut short or made by a newer format version. A mode that is not a Mode raises ValueError. Both functions release the GIL, so threads compress in parallel.

decompress(orz, skip_crc=True) gives back what a file decodes to even when it fails its CRC check (damaged, or written by an incompatible build), to recover what is left of it.

Format stability

ORZ is format version 0 (osu_orz.FORMAT_VERSION) and can still change incompatibly between releases. Until the format is versioned, decode an .orz with the osu-orz version that wrote it.

Platform

Linux on x86-64 (SSE 4.2) with CPython 3.12 or newer. The codec uses x86 CRC instructions, so other architectures do not build yet.

Building from source

git clone --recursive https://github.com/cmyui/osu-orz
pip install './osu-orz[test]'
pytest osu-orz/tests

This needs a C++20 compiler (GCC 11 or newer, or Clang). The build compiles the codec with -ffp-contract=off: .orz files only decode when every build does its float maths exactly as written, so do not build it with -ffast-math.

Releasing

Bump version in pyproject.toml and merge to main. CI then builds and tests the wheel, tags v{version}, makes a GitHub release and publishes to PyPI.

License

MIT. The ORZ codec in extern/osu_replay_zip is MIT licensed by rumoi; wheels include both licenses.

Metadata

Release files for osu-orz 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for osu-orz 0.1.1
File Size Uploaded Provenance Actions
osu_orz-0.1.1.tar.gz 3.9 MB With provenance Details for osu_orz-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for osu-orz 0.1.1
File Interpreter ABI Platform Actions
osu_orz-0.1.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for osu_orz-0.1.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Total release size: 7.0 MB

Release files / osu_orz-0.1.1.tar.gz

Download URL osu_orz-0.1.1.tar.gz
Size 3.9 MB
Tags Source
SHA-256 checksum
How to use checksums
aa90b67457e0f17c95f7ba3075dcab3a646e82437f9a4e67bf490f42695d55cf
BLAKE2b-256 checksum
How to use checksums
f48c2ae2310d49a2dccaf45c9fe3c166be5793e68bfa90bd08e1187b0a9241cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / osu_orz-0.1.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL osu_orz-0.1.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 3.1 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
de46e7dab674db06dd1bf5e2d424b534fa861321d1542c01db8021b4886b7673
BLAKE2b-256 checksum
How to use checksums
cadb4105637145abf695c19b55fc920704925e2ad2e88f73fe9a2b6691969533
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for osu-orz 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for osu_orz-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page