Mapperatorinator
An AI framework for generating and modding osu! beatmaps for all gamemodes from spectrogram inputs.
Install / Use
/learn @OliBomby/MapperatorinatorREADME
Mapperatorinator
Try the generative model here, or MaiMod here. Check out a video showcase here.
Mapperatorinator is multi-model framework that uses spectrogram inputs to generate fully featured osu! beatmaps for all gamemodes and assist modding beatmaps. The goal of this project is to automatically generate rankable quality osu! beatmaps from any song with a high degree of customizability.
This project is built upon osuT5 and osu-diffusion. In developing this, I spent about 2500 hours of GPU compute across 142 runs on my 4060 Ti and rented 4090 instances on vast.ai.
Use this tool responsibly. Always disclose the use of AI in your beatmaps.
Installation
The instruction below allows you to generate beatmaps on your local machine, alternatively you can run it in the cloud with the colab notebook.
1. Clone the repository
git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator
2. (Optional) Create virtual environment
Use Python 3.10, later versions will might not be compatible with the dependencies.
python -m venv .venv
# In cmd.exe
.venv\Scripts\activate.bat
# In PowerShell
.venv\Scripts\Activate.ps1
# In Linux or MacOS
source .venv/bin/activate
3. Install dependencies
-
Python 3.10
-
PyTorch: Make sure to follow the Get Started guide so you install
torchandtorchaudiowith GPU support. Select the correct Compute Platform version that you have installed in the previous step. -
and the remaining Python dependencies:
pip install -r requirements.txt
Web GUI (Recommended)
For a more user-friendly experience, consider using the Web UI. It provides a graphical interface to configure generation parameters, start the process, and monitor the output.
Launch the GUI
Navigate to the cloned Mapperatorinator directory in your terminal and run:
python web-ui.py
This will start a local web server and automatically open the UI in a new window.
Using the GUI
- Configure: Set input/output paths using the form fields and "Browse" buttons. Adjust generation parameters like gamemode, difficulty, style (year, mapper ID, descriptors), timing, specific features (hitsounds, super timing), and more, mirroring the command-line options. (Note: If you provide a
beatmap_path, the UI will automatically determine theaudio_pathandoutput_pathfrom it, so you can leave those fields blank) - Start: Click the "Start Inference" button to begin the beatmap generation.
- Cancel: You can stop the ongoing process using the "Cancel Inference" button.
- Open Output: Once finished, use the "Open Output Folder" button for quick access to the generated files.
The Web UI acts as a convenient wrapper around the inference.py script. For advanced options or troubleshooting, refer to the command-line instructions.
Command-Line Inference
For users who prefer the command line or need access to advanced configurations, follow the steps below. Note: For a simpler graphical interface, please see the Web UI (Recommended) section above.
Run inference.py and pass in some arguments to generate beatmaps. For this use Hydra override syntax. See configs/inference_v29.yaml for all available parameters.
python inference.py \
audio_path [Path to input audio] \
output_path [Path to output directory] \
beatmap_path [Path to .osu file to autofill metadata, and output_path, or use as reference] \
gamemode [Game mode to generate 0=std, 1=taiko, 2=ctb, 3=mania] \
difficulty [Difficulty star rating to generate] \
mapper_id [Mapper user ID for style] \
year [Upload year to simulate] \
hitsounded [Whether to add hitsounds] \
slider_multiplier [Slider velocity multiplier] \
circle_size [Circle size] \
keycount [Key count for mania] \
hold_note_ratio [Hold note ratio for mania 0-1] \
scroll_speed_ratio [Scroll speed ratio for mania and ctb 0-1] \
descriptors [List of beatmap user tags for style] \
negative_descriptors [List of beatmap user tags for classifier-free guidance] \
add_to_beatmap [Whether to add generated content to the reference beatmap instead of making a new beatmap] \
start_time [Generation start time in milliseconds] \
end_time [Generation end time in milliseconds] \
in_context [List of additional context to provide to the model [NONE,TIMING,KIAI,MAP,GD,NO_HS]] \
output_type [List of content types to generate] \
cfg_scale [Scale of the classifier-free guidance] \
super_timing [Whether to use slow accurate variable BPM timing generator] \
seed [Random seed for generation] \
Example:
python inference.py beatmap_path="'C:\Users\USER\AppData\Local\osu!\Songs\1 Kenji Ninuma - DISCO PRINCE\Kenji Ninuma - DISCOPRINCE (peppy) [Normal].osu'" gamemode=0 difficulty=5.5 year=2023 descriptors="['jump aim','clean']" in_context=[TIMING,KIAI]
Interactive CLI
For those who prefer a terminal-based workflow but want a guided setup, the interactive CLI script is an excellent alternative to the Web UI.
Launch the CLI
Navigate to the cloned directory. You may need to make the script executable first.
# Make the script executable (only needs to be done once)
chmod +x cli_inference.sh
# Run the script
./cli_inference.sh
Using the CLI
The script will walk you through a series of prompts to configure all generation parameters, just like the Web UI.
It uses a color-coded interface for clarity. It provides an advanced multi-select menu for choosing style descriptors using your arrow keys and spacebar. After you've answered all the questions, it will display the final command for your review. You can then confirm to execute it directly or cancel and copy the command for manual use.
Generation Tips
- You can edit
configs/inference_v29.yamland add your arguments there instead of typing them in the terminal every time. - All available descriptors can be found here.
- Always provide a year argument between 2007 and 2023. If you leave it unknown, the model might generate with an inconsistent style.
- Always provide a difficulty argument. If you leav
Related Skills
next
A beautifully designed, floating Pomodoro timer that respects your workspace.
product-manager-skills
41PM skill for Claude Code, Codex, Cursor, and Windsurf: diagnose SaaS metrics, critique PRDs, plan roadmaps, run discovery, and coach PM career transitions.
devplan-mcp-server
3MCP server for generating development plans, project roadmaps, and task breakdowns for Claude Code. Turn project ideas into paint-by-numbers implementation plans.
