osu-tools-py

PyPI License

中文说明

A high-performance Python wrapper for ppy/osu-tools, powered by pythonnet.

This library allows you to calculate Performance Points (PP), Star Ratings (SR), and other difficulty attributes for osu! beatmaps directly from Python. It embeds the official C# DLLs (compiled from osu!lazer), ensuring results are identical to the official game algorithms.

Features:

  • 🚀 Accurate: Uses the actual C# code from osu!lazer for calculations.
  • 📦 Batteries Included: Comes with pre-compiled DLLs (no need to compile C# yourself).
  • 🖥️ Cross-Platform: Supports Windows, Linux, and macOS (Intel & Apple Silicon/M1/M2).
  • 🧩 Type Safe: Fully typed Python API with data classes.

📋 Prerequisites

Before installing the Python package, you must have the .NET 8 Runtime installed on your system.

📦 Installation

pip install osu-tools-py

🚀 Quick Start

1. Calculate osu!stable PP

To get PP values that match the official osu! website (osu!stable), you must follow two rules:

  1. Add the "CL" (Classic) mod to your mod list.
  2. Provide a legacy_total_score (any value > 0).
from osu_tools import OsuCalculator

# Initialize (loads .NET runtime)
calc = OsuCalculator()

# Example: Calculate Max PP for HDDT on Standard Mode
result = calc.calculate(
    file_path="beatmaps/12345.osu",
    mode=0,
    # Rule 1: Always include "CL" for Stable calculations
    mods=["HD", "DT", "CL"], 
    acc=100.0,
    # Rule 2: Provide a legacy score > 0 to enable Stable physics/scoring
    legacy_total_score=1000000 
)

if result.is_success:
    print(f"Stars: {result.stars:.2f}")
    print(f"PP:    {result.pp:.2f}")
    print(f"Aim:   {result.pp_aim:.2f}")
    print(f"Speed: {result.pp_speed:.2f}")
else:
    print(f"Error: {result.error}")

2. Calculate Real Score (from Replay/API)

When calculating a specific score for osu!stable, pass the hit statistics and ensure you include the Stable compatibility flags.

# Real stats from a score
stats = {
    'great': 450,
    'ok': 12,
    'meh': 1,
    'miss': 2
}

result = calc.calculate(
    file_path="beatmaps/12345.osu",
    mode=0,
    mods=["HD", "CL"], # Don't forget CL!
    combo=850,
    statistics=stats,
    legacy_total_score=1000000 # Required for Stable logic
)

print(f"Real PP: {result.pp:.2f}")
print(f"Real PPAcc: {result.pp_acc:.2f}") # PP from Accuracy

Batch Calculation

When calculating multiple scores for the same beatmap/mode/mods, use calculate_many() to reuse beatmap decoding and difficulty calculation:

results = calc.calculate_many([
    {"file_path": "beatmaps/12345.osu", "mode": 0, "mods": ["HD", "CL"], "acc": 100.0},
    {"file_path": "beatmaps/12345.osu", "mode": 0, "mods": ["HD", "CL"], "acc": 98.5, "misses": 1},
])

Lazer Calculation Example

If you want to calculate PP for the Lazer scoring system (where slider tails affect accuracy):

# Lazer calculation example
lazer_stats = {
    'great': 450,
    'ok': 10,
    'miss': 5,
    'slider_tail_hit': 200, # Lazer specific stat
    'large_tick_hit': 50    # Lazer specific stat
}

result = calc.calculate(
    file_path="beatmaps/12345.osu",
    mode=0,
    mods=[], 
    combo=800,
    statistics=lazer_stats,
)

Supported Inputs

  • Mods: Supports list of strings ["HD", "DT"], list of dicts [{"acronym": "HD"}], or objects.
  • Modes:
    • 0: osu! (Standard)
    • 1: osu!taiko
    • 2: osu!catch
    • 3: osu!mania

Return Data

The function returns a CalculationResult object:

@dataclass
class CalculationResult:
    mode: int
    stars: float
    pp: float
    pp_aim: float
    pp_speed: float
    pp_acc: float
    pp_flashlight: float
    max_combo: int
    error: Optional[str]
    # ...

🛠️ Building from Source

If you want to modify the C# logic or build the wheels yourself:

  1. Requirements:

    • Python 3.10+
    • .NET 8.0 SDK
    • uv (Python package manager)

  2. Clone:

    git clone --recursive https://github.com/yaowan233/osu-tools-py.git
cd osu-tools-py

  3. Build: The project uses GitHub Actions for matrix builds (Windows/Linux/macOS), but you can build locally:

    # 1. Compile C# DLLs
cd osu-tools/PerformanceCalculator
dotnet publish -c Release -o ../../src/osu_tools/lib

# 2. Build Python Wheel
cd ../..
uv build

⚠️ Troubleshooting

  1. RuntimeError: Failed to create a default .NET runtime:

    • Ensure you installed .NET 8 Runtime.
    • On Linux/macOS, ensure dotnet is in your PATH.

  2. PP seems lower than official site:

    • Did you add "CL" to your mods list?
    • Did you pass legacy_total_score=1000000?

📄 License

This project is licensed under the MIT License. Based on ppy/osu-tools (MIT) and pythonnet (MIT).

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.7)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yaowan233 from gravatar.com yaowan233

Requires

Python <3.14, >=3.10

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

osu_tools_py-0.1.6-py3-none-win_amd64.whl (32.9 MB view details)

Uploaded Python 3Windows x86-64

osu_tools_py-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (38.0 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

osu_tools_py-0.1.6-py3-none-macosx_11_0_arm64.whl (40.4 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

osu_tools_py-0.1.6-py3-none-macosx_10_15_x86_64.whl (40.8 MB view details)

Uploaded Python 3macOS 10.15+ x86-64

File details

Details for the file osu_tools_py-0.1.6-py3-none-win_amd64.whl.

File metadata

  • Download URL: osu_tools_py-0.1.6-py3-none-win_amd64.whl
  • Upload date:
  • Size: 32.9 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for osu_tools_py-0.1.6-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 af2d526df4b29ecb85b9a46b460b7b1a9373f1936baf050b15327256270d060a
MD5 d1565048ea73e70b673f5fe883981fb5
BLAKE2b-256 101de40d9537a8ac5c30e429e1b6f2c033bb2da2d6a93b3c4c270c2602793443

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_tools_py-0.1.6-py3-none-win_amd64.whl:

Publisher: release.yml on yaowan233/osu-tools-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_tools_py-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for osu_tools_py-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 609ee7e803486faa712a3346860d2f5a471306bea3109898ab6aa2ceb705c566
MD5 0c6e745c5ec761d048eb09bfecaaaa98
BLAKE2b-256 c6e088bff9de54e2f435d4d49d24310ec00d28dc19efe686dc42ca224387d64b

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_tools_py-0.1.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on yaowan233/osu-tools-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_tools_py-0.1.6-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for osu_tools_py-0.1.6-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3a8571afa347af85ac6dd17146835914046adf728402e3e7d9860701b21e6922
MD5 225a77e6af04a771b7507f80d5846bb2
BLAKE2b-256 cafdc39c82efe96af40e29900876685ef6c1209afaaf3ab1dc26a6a530195647

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_tools_py-0.1.6-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on yaowan233/osu-tools-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_tools_py-0.1.6-py3-none-macosx_10_15_x86_64.whl.

File metadata

File hashes

Hashes for osu_tools_py-0.1.6-py3-none-macosx_10_15_x86_64.whl
Algorithm Hash digest
SHA256 03dda60c5841edc27e4cda5fea0f25edf4232df6335aed595c8bb88aa827283b
MD5 c01683336489f52b2bea8f478d40a005
BLAKE2b-256 ac4cb813471def68dddfe7d76e9e28e085395f9fed108879f5af445f4415f790

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_tools_py-0.1.6-py3-none-macosx_10_15_x86_64.whl:

Publisher: release.yml on yaowan233/osu-tools-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.7

4 files

This release

0.1.6 This release

4 files

0.1.5

4 files

0.1.4

4 files

0.1.3

4 files

0.1.2

4 files

0.1.1

4 files

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