Encodes the theoretically highest-quality Vorbis file under 208 kbps (by default) with no clipping, specifically for osu!.
libvorbis has no "VBR at N kbps" mode. Quality mode (-q:a) is the one you
want, but the bitrate it lands on depends on the song, so picking q by hand
means either leaving quality unused or going over the limit. qualitymaxx
searches for the highest q that fits, measures each candidate the way Mapset
Verifier does, and then spends whatever budget is left.
$ qualitymaxx --align audio.ogg master.flac audio.ogg
...
done: audio.ogg
q:a 6.00 | gain -2.30 dB | 207.9 kbps | sample peak -0.021523 dBFS | residual offset vs ref 0.005 ms (0 samples, corr 0.972)
encoder: system libvorbis | optivorbis
- Searches
-q:ato two decimals, running several encodes per round. - If budget is left below the next q step, spends it on libvorbis's
impulse-block bias (
-iblock), which gives transients more bits. - With
--align REF, lines the output up with the audio a map was timed on, to the sample, so it can replace that file without retiming. - Decodes the result, and if it goes over 0 dBFS, lowers the level by exactly the overshoot and searches again (see Loudness).
- Downsamples sources above 48 kHz, with SoX 16.2 if installed, otherwise with ffmpeg's soxr, or ffmpeg's own resampler if it was built without soxr.
- Passes every encode through OptiVorbis if installed: same decoded audio, about 3% smaller, and the search spends that 3% on a higher q.
- Can use aoTuV instead of stock libvorbis (Linux and macOS).
It refuses lossy input, never writes over the input file, and writes the output only after checking it.
- bash 3.2 or newer
- ffmpeg and ffprobe built with libvorbis (CI tests 8.0 and 9.0)
- Python 3.6 or newer, plus numpy for
--align
Get ffmpeg, Python and numpy. On Linux, install ffmpeg, python3 and
python3-numpy from your package manager. On macOS, Homebrew's own ffmpeg
is built without libvorbis, so use the homebrew-ffmpeg tap (it builds
from source, which takes a while):
brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-libsoxr
brew install numpy
Then download the script:
curl -fL --create-dirs -o ~/.local/bin/qualitymaxx https://raw.githubusercontent.com/digitalis-p/qualitymaxx/main/qualitymaxx
chmod +x ~/.local/bin/qualitymaxx
Or clone the repository and put qualitymaxx on your PATH. The stock
macOS /bin/bash is enough.
Optional extras, installed under ~/.local/opt (nothing system-wide):
qualitymaxx --install-sox # SoX 16.2 (sox-vulkan) release build, checksum-pinned
qualitymaxx --install-optivorbis # needs cargo
qualitymaxx --build-aotuv # needs a C toolchain and libogg
Steps 1 to 3 are a one-time setup. (WSL works too: follow the macOS / Linux steps inside it.)
1. Install Git for Windows. Download it from gitforwindows.org and run the installer. Clicking Next on every page is fine. This gives you Git Bash, the window qualitymaxx runs in.
2. Install ffmpeg and Python. Press the Windows key, type powershell,
open it, and paste these lines one at a time, pressing Enter after each:
winget install -e --id Gyan.FFmpeg --accept-source-agreements --accept-package-agreements
winget install -e --id Python.Python.3.13 --accept-source-agreements --accept-package-agreements
Then close PowerShell and open it again (new programs aren't found until you do), and paste:
py -m pip install numpy
3. Download qualitymaxx. Press the Windows key, type git bash, open
it, and paste this line (in Git Bash, paste with Shift+Insert or
right-click → Paste):
curl -fL --create-dirs -o ~/bin/qualitymaxx https://raw.githubusercontent.com/digitalis-p/qualitymaxx/main/qualitymaxx
Close Git Bash, open it again, and type qualitymaxx --version. It should
answer qualitymaxx 1.1.0.
4. Encode. Open your map's folder (osu!stable: in the editor, File →
Open Song Folder; lazer: in the editor, File → Edit externally). Right-click
an empty spot in the folder and choose Open Git Bash here (on Windows 11
it's under "Show more options"). Type qualitymaxx , with a space at the
end, then drag your FLAC file from Explorer into the Git Bash window, which
types its location for you. Finish the line with audio.ogg and press Enter:
qualitymaxx '/c/Users/you/Downloads/song.flac' audio.ogg
If the map is already timed to an existing audio file, add --align and
that file's name, so the new ogg lines up with it exactly:
qualitymaxx --align audio.mp3 '/c/Users/you/Downloads/song.flac' audio.ogg
It takes a minute or two. When it ends with done: audio.ogg and a line
showing the kbps, the file is ready. If the map used a different audio file
before, point each difficulty at audio.ogg (lazer: Setup → Resources →
Audio track; stable: File → Open .osu in Notepad and change the
AudioFilename: line), and on lazer click "Finish editing and import
changes" in osu! when you're done.
If something goes wrong
| Message | What to do |
|---|---|
qualitymaxx: command not found |
Close Git Bash and open it again. If it still happens, redo step 3. |
ffmpeg not found |
Close Git Bash and open it again. If that doesn't help, restart the computer. |
Python 3.6+ not found |
Redo the Python line of step 2, then reopen Git Bash. |
--align needs numpy |
Run py -m pip install numpy in PowerShell. |
INPUT is mp3, a lossy format |
You need a lossless file (FLAC or WAV). Converting an mp3 to ogg makes it worse and isn't rankable. |
weak correlation |
The FLAC is a different version of the song than the map's audio (a different edit, cut or mix). |
qualitymaxx [options] INPUT [OUTPUT] [TARGET_KBPS]
OUTPUT defaults to INPUT with an .ogg extension, TARGET_KBPS to 208.
qualitymaxx master.flac # master.ogg, at most 208 kbps
qualitymaxx master.flac audio.ogg 192
qualitymaxx --align audio.mp3 master.flac audio.ogg # same timing as the map's mp3
qualitymaxx --align audio.ogg master.flac audio.ogg # replace audio.ogg in place
| Option | |
|---|---|
--align REF |
Time-align the output to REF. Stops if REF doesn't correlate with INPUT. |
--force-align |
Apply the measured offset even when the correlation is weak. |
--allow-lossy |
Accept an mp3, aac, opus or vorbis input. |
--encoder libvorbis|aotuv |
Encoder library (default libvorbis). |
--resampler sox|soxr |
Resampler for sources above 48 kHz (default sox, falls back to soxr). |
--cross-wall[=DB] |
Trade up to DB of level (default 1.0) for q 7.00 when it only just misses. Off by default. |
-j N, --jobs N |
Encodes per round (default: number of CPUs). |
| Environment | |
|---|---|
NOCLIP=0 |
Turn off the clipping guard. |
PEAK_MODE=true |
Guard on true peak (dBTP) instead of sample peak. |
CEILING_DB |
Guard ceiling, default 0. |
IBLOCK_SEARCH=0 |
Skip the impulse-block search. |
PARALLEL |
Same as -j. Ignored if it isn't a number, since GNU parallel uses it too. |
ALIGN_WINDOW |
Seconds of audio --align correlates, default 60. |
AOTUV_PREFIX, SOX_PREFIX, OPTIVORBIS_PREFIX |
Where the extras live. |
SOXR_PRECISION, SOXR_CUTOFF |
ffmpeg soxr settings, default 28 and 0.98. |
The header of the script explains each of these in more detail.
Lossy encoding adds noise, so a master that peaks at 0 dBFS decodes above it.
Players that convert to integer PCM clip those samples. The clipping guard
avoids that by lowering the level until the decoded file stays under the
ceiling, which with loud modern masters is often 1 to 3 dB quieter than the
source. NOCLIP=0 keeps the source level.
| 0 | Output written. |
| 1 | Nothing written: lossy input, no q fits the target, still clipping after four passes, alignment off after encoding, or a tool failed. |
| 2 | Bad arguments. |
- The bitrate is ffprobe's
format.bit_rate, file size × 8 / duration, which is what Mapset Verifier reports. - A FLAC or WAV made from an mp3 gets past the lossy check. A spectrogram shows it: a flat wall somewhere around 16 to 20 kHz.
--aligncan't cut the song for you. INPUT has to be the same edit as REF.- ffmpeg rounds
-q:adown to steps of 1/118, so q 6.99 is encoded as 6.983. The summary shows both. - aoTuV needs an ffmpeg that loads libvorbis as a shared library. A test encode checks this, and the script falls back to stock libvorbis if not.
- The output carries no tags.
bash tests/run.sh
On macOS, /bin/bash tests/run.sh tests the stock bash 3.2. CI runs the
tests on Linux, macOS and Windows.
Qualitymaxxer by the fart lord does the same search as a Python program with a file picker. This is a separate implementation.
MIT, see LICENSE.