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
.osrfields 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.compressthen 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.