Mapperatorinator, a spectrogram-to-beatmap model whose two dependency lists disagree

Python 3.10, CUDA 13.0, and a warning about later versions

The environment floor is stated with a caveat attached. Use Python 3.10, and the note says later versions might not be compatible with the dependencies, which is why the virtual environment step is marked optional and still recommended. Beyond Python the requirements are Git, ffmpeg, and either CUDA 13.0 for an NVIDIA GPU or ROCm for an AMD GPU on Linux, followed by PyTorch 2.10 installed so that both `torch` and `torchaudio` come with GPU support matching the compute platform you just installed. That combination is recent enough that the driver and container base image are part of the setup rather than an assumption. Setup is otherwise conventional:

git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator

followed by a virtual environment and a single requirements install.

The two dependency lists pin Transformers to different versions

The requirements file pins everything exactly, which is the right instinct for a training project: Accelerate, pydub, nnAudio, PyYAML, Hydra, TensorBoard, wandb, Lightning, pandas, pyarrow, einops, peft, datasets, torchcodec, the Hub client, and rosu-pp-py, the last being the official osu! beatmap parser and difficulty calculator. But the Dockerfile installs a shorter list, and one entry differs: the requirements file asks for `transformers==4.57.3` while the image installs `transformers==4.53.3`. The image also omits matplotlib, rich, the Qt webview pair, Flask, the Hub client, and the transfer helper. So a local install and a container install are not the same environment, and a bug that only reproduces in one of them is a plausible outcome rather than a surprise.

`flash-attn` is compiled inside the image with four build jobs

The image starts from a PyTorch base tagged for CUDA 13.0 with cuDNN 9 in the development variant, installs Git and ffmpeg, and then does two things worth noting. It installs a pinned ninja, and it builds a pinned `flash-attn` from source with build isolation disabled and `MAX_JOBS=4` set explicitly. Capping the job count is what tells you this is a multi-minute compile step rather than a wheel download, and doing it with isolation off means the build sees the base image's own torch rather than a freshly resolved one. Every pip call in the file passes a flag allowing installation into the system environment. The last line appends a shell prompt marker to the root profile so the container identifies itself in the terminal, which is a small courtesy and also a reminder that everything here runs as root.

Compose mounts a datasets directory from outside the repository

The Compose file reserves every NVIDIA device the host has, sets a shared memory size of sixteen gigabytes, and uses host networking. Two things stand out. The first volume mounts the repository into the working directory, and the second mounts a sibling directory called `datasets` from outside the repository tree, which means a fresh clone plus `compose up` will not find your data where the container expects it. The second is the comment on the image line: the build is left active and a fixed image name is commented out, so every start rebuilds unless you edit it. Two experiment-tracking variables are passed through from the host, along with the project path. A development container definition sits at the top level as well, for anyone who prefers an editor-driven setup to Compose.

The web UI is a wrapper around one script, and it derives paths for you

One command starts the graphical path:

python web-ui.py

That launches a local web server and opens the interface in a new window, and the README is explicit about what it is: a wrapper around the inference script, for convenience rather than for new capability. The form covers input and output paths with browse buttons, plus generation parameters including gamemode, difficulty, style, timing, and specific features such as hitsounds and super timing, mirroring the command line. One convenience is genuinely useful: supply a beatmap path and the interface works out the audio path and the output path itself, so two of the fields can stay blank. There are buttons to start, to cancel a run in progress, and to open the finished output folder. Everything advanced is still on the command line.

The command line is Hydra, so every parameter is an overridable key

Generation runs through a script that takes named arguments, and the configuration system underneath is Hydra with its override syntax, with every available parameter living in one defaults file under the configs directory. That choice is what makes the web UI possible: a form field is an override of a key, so the interface is generated from the same surface the CLI exposes rather than from a parallel copy of the settings. It also means the settings are inspectable and scriptable, which matters for a project whose stated goal is a high degree of customizability. The same reasoning explains why the optional `beatmap_path` argument exists: pointing the tool at an existing `.osu` file lets it fill in metadata rather than inventing it, which is the bridge between the generation tool and the modding one.

Two upstream models are vendored into the tree

The repository is described as built upon osuT5 and a diffusion project, and both appear as directories at the top level rather than as dependencies, so their code sits inside this tree. Alongside them are directories whose purpose the names only hint at: a classifier, a template, and something called rcomplexion. There is also a script for computing a Fréchet inception distance, which is how you measure whether generated output resembles the training distribution rather than whether it is good, and a script for pushing to the Hub. Colab notebooks sit in their own directory for the two inference paths, which is the route the README suggests first if you would rather not set up a GPU at all. The single tagged release is v32.0.0, so the project's own versioning runs in the thirties.

The author's compute bill is stated in the README

One sentence tells you what this cost to build: roughly 5700 hours of GPU compute spread across 261 runs, on a 4060 Ti with rented 4090 instances from a marketplace. It is included next to the credit for the two upstream models, and it is a more useful number than any accuracy claim because it tells you the scale of exploration behind the weights rather than the scale of the final run. The same section carries the one instruction that matters most for anyone planning to publish the output: use the tool responsibly, and always disclose the use of AI in your beatmaps. The most recent tag is v32.0.0 from 2026-05-23 and the branch was last pushed on 2026-08-13, so the published version and the current source are not the same thing.

Editorial conclusion

Mapperatorinator fits a mapper or modder who wants a starting point from a track rather than from nothing, and who is prepared to disclose that AI was involved. The vendored upstream models mean you are not assembling a pipeline from published checkpoints, and the modding path exists for existing maps as well as generation. It is a poor fit if you cannot supply a CUDA 13 or ROCm machine with a current PyTorch build, or if you want reproducible dependencies, because the requirements file and the Dockerfile pin the same transformer library to different versions. Before you build, pick one environment and stick to it, and read the author's own compute figure before you plan your own.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. OliBomby/Mapperatorinator on GitHub
4. README
5. Releases