Mapperatorinator: Spectrogram-Driven osu! Beatmap Generation

The gap Mapperatorinator fills in osu! mapping

Mapping an osu! beatmap is a manual, time-consuming task. A mapper listens to a song, places hit objects, adjusts timing, and tunes difficulty across gamemodes. Mapperatorinator aims to generate a complete beatmap from the audio itself. The README states the goal plainly: to automatically generate rankable quality osu! beatmaps from any song with a high degree of customizability. The target user is a mapper who wants a structured draft to edit, or someone experimenting with how a song might be mapped in a particular style. The project is a multi-model framework, not a single neural network, and it accepts spectrogram inputs rather than raw audio waveforms. It covers all osu! gamemodes and also includes a separate modding assistant called MaiMod. The author notes the project builds on osuT5 and osu-diffusion, and that development consumed roughly 5700 hours of GPU compute across 261 runs. Those figures describe the author's training effort, not the compute you need to run inference. The README also carries an explicit instruction: use this tool responsibly and always disclose the use of AI in your beatmaps. That is a policy statement from the project, not a legal requirement, but it signals the expected use case is assistive rather than fully automated publishing.

How spectrogram input becomes a playable beatmap

The architecture is a pipeline rather than a monolith. Audio enters as a spectrogram, and the framework generates beatmap elements from that representation. The README describes Mapperatorinator as a multi-model framework, and the topic list includes classifier, diffusion, and transformers, which matches the stated lineage from osuT5 and osu-diffusion. Reading the repository layout, inference is driven by inference.py, which loads configuration from configs/inference/default.yaml. The config exposes generation parameters such as gamemode, difficulty, style (including year, mapper ID, and descriptors), timing, hitsounds, and a super timing option. Those parameters are the control surface: the model does not pick a style on its own, you specify one. The Web UI mirrors the same options, which tells you the command-line and GUI paths converge on the same configuration schema. One detail in the README is worth noting for data flow: if you provide a beatmap_path, the UI automatically determines the audio_path and output_path from it. That means an existing beatmap can act as the anchor for a new generation, with the audio and output locations inferred rather than typed. The README does not document the internal checkpoint layout or the exact model count, so anything beyond the multi-model description is not confirmable from the supplied material.

Installing and running inference on your own hardware

The README gives a specific installation sequence. Clone the repository, optionally create a virtual environment, and install dependencies. Python 3.10 is required, and the README warns that later versions might not be compatible with the dependencies. You also need Git, ffmpeg, CUDA 13.0 for NVIDIA GPUs or ROCm for AMD GPUs on Linux, and PyTorch 2.10 installed with GPU support via the official Get Started guide. The remaining Python dependencies come from pip install -r requirements.txt. The recommended entry point is the Web UI: run python web-ui.py from the cloned directory. The README says this starts a local web server and opens the UI automatically, with buttons for Start Inference, Cancel Inference, and Open Output Folder. For command-line use, run inference.py with Hydra override syntax. The README shows the shape of the call: python inference.py followed by keys such as audio_path and output_path, and points to configs/inference/default.yaml for all available parameters. The exact full argument list is truncated in the README excerpt, so treat the config file as the authoritative reference rather than the example snippet. For cloud use, the project provides a Colab notebook at colab/mapperatorinator_inference.ipynb, and a separate notebook for MaiMod. If you have no compatible GPU, the Colab route is the practical option.

Where the framework stops and the mapper starts

The stated goal is rankable quality, but the README also instructs users to disclose AI use in their beatmaps. Those two statements sit in tension. A fully automatic rankable map would not need a disclosure prompt framed as responsible use. The realistic reading is that Mapperatorinator produces a draft that a human reviews, edits, and takes responsibility for. The style controls reinforce this: you set year, mapper ID, and descriptors, which means the output imitates a target style rather than inventing one. If your goal is a map that sounds like a specific mapper from a specific era, the parameter set is designed for that. If your goal is a novel mapping approach, the framework is pointed the other way. The hardware requirements are also a hard boundary. CUDA 13.0 or ROCm on Linux is required, and the README frames the local instructions around GPU support. CPU-only inference is not described. Python 3.10 is another constraint: the README warns later versions might not be compatible, so a modern Python 3.12 environment is a risk, not a default. Finally, the project is a moving target. The latest release is v32.0.0, dated 2026-05-23, and the last push is 2026-08-13. A version number in the thirties over a project of this age suggests frequent breaking changes. Pin your version if you depend on specific config keys.

Mapperatorinator compared with osuT5 and osu-diffusion

Mapperatorinator is built on osuT5 and osu-diffusion, so the honest comparison is with its own ancestors. osuT5 is a transformer-based approach to beatmap generation, and osu-diffusion applies diffusion to the same problem. Mapperatorinator combines multiple models under one framework and adds a Web UI, a unified Hydra config, all-gamemode coverage, and the MaiMod modding assistant. The difference in approach is scope and packaging rather than a fundamentally different generation method. If you want a single research model to study or fine-tune, going directly to osuT5 or osu-diffusion gives you a smaller surface area and fewer dependencies. If you want a tool that generates maps across gamemodes with a graphical interface and a documented config file, Mapperatorinator wraps those pieces into one installable project. The trade-off is that you inherit the full dependency stack, including CUDA 13.0 and PyTorch 2.10, and the version churn that comes with a framework consolidating several models. The README does not provide benchmark comparisons between Mapperatorinator and its predecessors, so any quality claim in either direction would be unsupported.

Licence, maintenance, and upgrade exposure

The repository is MIT licensed, which permits commercial and private use with attribution and without copyleft obligations. That covers the code. It does not automatically cover model weights or training data, and the README does not state a separate licence for the checkpoints. If you plan to redistribute generated beatmaps or the models themselves, check the release assets and any model card before assuming MIT applies end to end. This is not legal advice; it is a pointer to the gap between a repository licence and an artifact licence. Maintenance cost is the other factor. The project ships frequent major versions, with v32.0.0 as the most recent release and a push date of 2026-08-13, so the codebase is active. Active development means config keys can move between versions. The README directs you to configs/inference/default.yaml for all available parameters, which is also the file most likely to change. If you build automation on top of inference.py, pin the commit or release and re-read that config on upgrade. The dependency chain, Python 3.10, CUDA 13.0, PyTorch 2.10, and ffmpeg, is the heavier ongoing cost. Each of those has its own upgrade cadence, and the README's warning about Python versions suggests the project does not track the newest Python releases quickly.

Who should adopt Mapperatorinator, and what to check first

Adopt it if you are an osu! mapper with a CUDA 13.0 or ROCm-capable GPU, a Python 3.10 environment, and a willingness to edit generated output. The style parameters (year, mapper ID, descriptors) and the Web UI make it practical for producing drafts in a target style, and the all-gamemode coverage means you are not limited to standard. Do not adopt it if you need CPU-only inference, if you are locked to a newer Python version, or if you expect a finished rankable map without human review. The README's own disclosure instruction argues against the last case. The Colab notebook is the low-commitment way to evaluate output quality before installing anything locally. Before you commit to a local install, verify three things: that the v32.0.0 release notes match the config keys in configs/inference/default.yaml, that the model checkpoints you need are downloadable, and that your GPU driver supports the CUDA 13.0 or ROCm version the README requires. MaiMod is a separate notebook and a separate concern; if modding assistance is your actual goal, evaluate that path independently rather than assuming the main inference setup covers it.

Editorial conclusion

Mapperatorinator suits mappers who want a configurable first draft and are prepared to edit the output before ranking. It is a poor fit for anyone without an NVIDIA or AMD GPU or a Python 3.10 environment, and for anyone expecting a rankable map with no human editing. Before committing, verify that the v32.0.0 release notes match the config keys in configs/inference/default.yaml, and confirm the model checkpoints you intend to use are still downloadable.

Official sources

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