Osu Qb

What Osu Qb Actually Is

Osu Qb is a lightweight balance utility people use to adjust the stats and ratings on their osu! beatmaps without opening the full editor. The idea is simple: you feed it a .osu file, it recalculates attributes like star rating, approach rate, drain time, and CS based on whatever numbers you want, then spits out a modified version. Most people use it during the mapping process to fine-tune a map's difficulty range before submitting, or to fix a map that got flagged for being too far off from its intended OD/AP range. I've been dealing with osu! mapping tools for years and honestly the whole ecosystem has gotten messy. There's a dozen repos on GitHub, some are abandoned, some work on Windows and not Mac, some only run through Python 3.9 specifically. Osu Qb sits somewhere in the middle — not the fanciest tool, not the most popular either, but it does what it claims to do without requiring you to install half a dozen dependencies.

Getting Osu Qb

The project lives on GitHub under the name osu-qb or similar variations depending on who forked it last. You want the Python-based version, not the Cone unless you know what you're doing. Clone the repo, make sure you have Python 3.10 or newer, run pip install -r requirements.txt, and you're basically set. The main executable is just a script you point at a .osu file. I usually clone it directly into my mapping folder so I don't lose track of it when GitHub decides to reorganize repos again. You run the script from the command line and pass it arguments for whichever stats you want to modify. The basic syntax looks something like this: python qb.py input.osu --ar 9 --od 8 --cs 3.8 --hp 6 --output fixed.osu

It reads the original file, changes those values in the metadata section, recalculates the star rating using the official osu! algorithm, and writes out a new file. That's it. No fancy GUI, no web interface, just command line manipulation of the beatmap attributes. The thing nobody tells you about this process is that recalculating stars isn't just a straightforward lookup. The osu! difficulty calculator parses every single hit object, checks timing, spacing, stream velocity, combo length, and a bunch of other factors. A map with 2000 objects and a star rating of 9.4 will take noticeably longer to process than a short 500-object map at 3 stars. If you're batch-processing a whole folder of maps, budget maybe 30 to 90 seconds per map depending on complexity. I learned that the hard way when I tried to recalculate an entire beatmap pack during a pre-submission review and thought my script had frozen for twenty minutes.

The Real Problem I Hit

Here's something that tripped me up recently and probably will trip you up too. Osu Qb recalculates star rating based on the modified attributes, but it doesn't adjust the actual placement or timing of hit objects. So if you change AR from 9 to 10 and OD from 8 to 9, the calculator will give you a higher star rating, but the map itself hasn't changed. The approach circles shrink and the drain bar shortens visually, which means gameplay feel shifts even though every circle is in the same spot at the same time. This caused a real issue for me when I was adjusting a friend's old hardmap that had been submitted with custom slider velocities. After running it through Qb with higher OD, the recalculated stars jumped by about 0.6, but the actual gameplay had become noticeably harder because the streams were now compressed into a tighter time window with less reaction time. We had to go back and manually adjust slider velocities down slightly to compensate, then reran Qb to get the stars back to the target range. Took about 20 minutes of back and forth that Qb alone couldn't solve.

Advanced Usage That Actually Matters

Most people stop at changing AR OD and CS. But Qb also lets you tweak GS (Game Size), modify drain time explicitly, and set custom BPM values that affect how the calculator interprets timing. The --bpm flag is particularly useful because if a map has misaligned BPM changes in the metadata, the difficulty calculator will produce garbage results. I've seen maps where a single wrong BPM tag at the top of the file caused the star rating to be off by over a full point compared to what the online calculator showed. There's also a batch mode if you pipe multiple files through it. Not well documented but it works if you just loop through your folder and run the command on each one. I use a small bash script that processes my entire submission folder and logs any maps where the star rating shifted more than 0.3 from the original, since that usually flags something that needs manual review.

When Osu Qb Falls Apart

Let me be clear about the limitations. This tool does not validate your map. It does not check for broken combo breaks, unsnappable sliders, or timing issues. It does not touch hit objects at all beyond what's necessary to recalculate attributes. If your map has formatting errors in the metadata section, the script might silently produce incorrect output or crash entirely depending on the parser version you're running. It also doesn't handle osu!mania, osu!taiko, or osu!catch maps. The calculator it uses is strictly for standard mode. If you're mapping for other gamemodes you need different tools entirely. Another thing worth noting: the star rating calculation it uses is based on an older version of the osu! difficulty calculator. As of my last check, the official osu!site uses a slightly updated algorithm that can produce different results from what Qb outputs. The difference is usually small — 0.1 to 0.2 stars at most — but if you're right on the edge of a difficulty tier boundary, it matters. I always cross-check any map that lands within 0.15 stars of a tier cutoff against the online difficulty calculator before submitting.

Alternatives Worth Considering

If you just need to preview how a map will rate without modifying files, the built-in difficulty calculator in the osu! client does most of what Qb does without any setup. If you want something more automated with validation built in, there are other tools in the community like osu!mania diffcalc and various map validation suites that wrap around similar functionality but add error checking on top. Qb is fastest if you already know your map is clean and just need to adjust attributes quickly. It's not the best choice if you're doing a full quality check before submission. The bottom line is that Osu Qb is a niche utility that does one thing reasonably well. It's not going to replace the official tools or save you from bad mapping, but when you need to tweak stats on a clean map file in under a minute, it works. Just don't expect it to fix your map for you.