Complete guide: creating beatmap using osumapper - kotritrona/osumapper GitHub Wiki

Time your song in osu!

In order to create a beatmap, osumapper needs the correct timing first, i.e. BPM and offset.

When a music file is imported to osu! editor, timing is the first thing it asks you to do.

The best way is to do it yourself. There are many tutorials for osu! timing, like the first one I found on youtube.

However, since doing it yourself goes against the idea of auto-mapping, I also suggest using Timing Analyzer by statementreply. Put it in the osu! folder and give it music file, then it calculates the BPM and offset. It works about 90% of the time.

PIC1

Maps with more than one timing sections are supported. More than 100 like LeaF Aleph-0 though, will probably make osumapper act weird.

After timing is completed, press Control+S to save and use this option to open the map folder.

PIC2

The folder contains an .osu file and a music file (audio.mp3). These files are needed for osumapper to generate the map.

A little more time in the osu! editor

You'll also want to set the difficulty settings in the Song Setup dialog, because I didn't let osumapper change them automatically.

Different beatmap makers tend to use different settings, but generally this is good for a random new map:

  • Circle Size: Most osu! maps use circle size 4.
  • Approach Rate: Set it to 8 for Hard level or 9 for Insane level map. Some people like 9.5 or 10.
  • Overall Difficulty: Probably around 6-8 for an Insane level.
  • Slider velocity (in the timing panel): The default value (1.4) is usually too slow. 1.8 is a good start for an Insane level map. (Always 1.4 for Taiko)

After this, press Control+S to save the file, and proceed to Colaboratory.

Using Colaboratory

Colaboratory (Colab) is an interactive programming platform supported by Google for researching machine learning.

By using Colab we can free ourselves from using our own computers to train models/make maps, which will probably make osu! laggy.

Link: https://colab.research.google.com/github/kotritrona/osumapper/blob/master/v7.0/Colab.ipynb

Running code

There are two ways to run code:

  1. Press Control+Enter in a code block to run all code in it
  2. Use Run All options in Runtime menu or press Control+F10 to run all code in the page

In this case, if you use the Run All option, it sometimes runs across a bug where the file upload fails to load.

It's better to manually run each block of code from top to bottom, until you upload the files. After that, you can use Run All.

The first time you run any code, it will pop a prompt like this. Press "RUN ANYWAY" to run code.

PIC3

When the code is running, the play button on the left will start to roll. When the rolling stops the code finishes running.

PIC4

Choose a pre-trained model

At first you can use a pre-trained model to create maps. Training a model is covered later in this guide.

To choose a model, change this part of code to one of the options explained above the code.

PIC5

Upload map and music file

The next block of code will ask you to upload .osu and music file. They are in the map folder previously created in osu!.

After uploading them, you can select "Runtime" -> "Run after" in the next block to run everything else.

PIC6

Changing the model parameters

You can change the model parameters by uncommenting these parts in the code, before running them:

PIC7

PIC8

PIC10

Remove the # in front to change these from comments to real code.

The most important model parameters are

  • note_density (in the "calculate map rhythm" part): it determines how many notes are placed on the map, which is the biggest factor for map difficulty.
  • max_ticks_for_ds (in the "map flow" part): set to 1 for a jump map, 2 for a non-jump map. It decides when the distance snap is turned on.
  • box_loss_border and box_loss_value: if the generated map has all the circles and sliders at the corners, increase these two parameters to fix them.
  • slider_regularizer: It makes the streams look nice. The modes are explained in this picture: https://i.imgur.com/itIxulE.jpg

Note that each model has different default parameters. Type model_params in an empty code block to view them.

PIC9

The GAN

The GAN part takes a long time to run. For a full length song it will take about 5-10 minutes depending on difficulty.

Play some osu! in the meantime. After it finishes training, downloads will pop up.

Put the generated .osu file in the map folder (replacing the one with timing only) to see the results in osu!.

If you're in the editor, you need to exit without saving and return to reload it.

Cleaning up

Uncomment this line to clean up if you want to make another map.

Only run it after the map is downloaded and immediately comment back, because it deletes the output file too.

cleanup

Making Taiko maps

For Taiko maps you need to uncomment this part at the second last block of code. It applies taiko hitsounds (d/k/D/K) on the map.

PIC11

Making Catch maps

Simply use the "catch" model. It's trained with Catch mode maps.

However, since no one knows how to play it, I'm not sure if the generated maps are good or not. Please give opinions.

Making Mania maps

Mania mode uses a different notebook (page of code) because there are many things needed to specially set up.

https://colab.research.google.com/github/kotritrona/osumapper/blob/master/v7.0/mania_Colab.ipynb

The only difference is you have to set the osu! map to mania mode and correct key count in Song Setup.

PIC12

After that, do the same as the guide above.

Installing osumapper on your computer

I'll introduce installation for Windows 10 in this guide.

Linux installation is basically the same, except using a different install script.

Anaconda and Node.js

Download Anaconda here: https://www.anaconda.com/products/individual (Download link at the bottom of the page)

Download Node.js here: https://nodejs.org/en/download/

Clone repository

Press the big green Code button on the main page and select Download ZIP to download the code.

You can also install Git and use git clone to clone this repository.

Install osumapper

Use the Anaconda Prompt (it will show up in the start menu) and cd to the folder v7.0.

Run install.bat to install osumapper dependencies.

After the install is finished, use the Jupyter Notebook (it will also show up in the start menu) to run the .ipynb files.

Training models

Creating Maplist

First of all, you need to create a file maplist.txt that contains paths to .osu files you want to train with.

I have created a helper tool to make this list. Run node gen_maplist.js to start it.

PIC13

Use the Filters to find maps you want. "Reverse" means the filter condition is reversed, i.e. filters to maps that don't satisfy the condition.

Click "Next Search" to apply filters, "Reset Search" to reset, "Add to maplist" to add the filtered maps to the list on the right, and "Save maplist" to save the list for osumapper training.

"Remove Submode" removes taiko, catch and mania maps from the list.

To find only taiko, catch or mania maps, you need to use the "Game Mode" filter where Taiko is 1, Catch is 2 and Mania is 3.

Start training

Run 01_Training.ipynb to start training. Press Ctrl+Enter to run every block of code.

For taiko and mania training, there are some code you need to uncomment before training.

PIC14

PIC15

Making maps locally

Run 02_Mapmaking.ipynb to make maps in the local Jupyter Notebook.

Most of it is the same as the Colab one, except instead of uploading .osu and music you only need to write the .osu path here.

local

Generated map will be under the osumapper\v7.0 folder.

Auto timing (Fully automatic beatmap creation)

In the above mentioned block of code, uncomment the timing part and set a music file path to do automatic timing with Timing Analyzer.

.osu file will be automatically generated with metadata read from the music file (ID3) and mostly random difficulty settings.

We have finally achieved fully automatic beatmap creation.

Training on Colab

Train the model on Colab with this notebook:

https://colab.research.google.com/github/kotritrona/osumapper/blob/master/v7.0/Colab_Training.ipynb

First of all, you still need to download and install it on your computer.

Run the first block of code in 01_Training.ipynb, after which it will generate a bunch of .npz files under the mapdata\ folder.

Upload these files into your Google Drive under a NPZ\ folder in "My Drive".

PIC18

After that, simply run every block of code in the notebook.

It will ask you for an auth code in one of the blocks to connect to your Google Drive (so it can use the NPZ files).

PIC16

When it finishes training, downloads will pop up.

PIC17

Using your saved models in the Colab page

When you train a model in the Colab_Training notebook, it will replace the default model in addition to the download.

Use the default model then to create maps using the trained model.

For saved models, you can upload them somewhere that can be directly downloaded, e.g. Github, then use code like

!curl [raw github url to "saved_rhythm_model"] > models/default/rhythm_model
!curl [raw github url to "flow_dataset.npz"] > models/default/flow_dataset.npz

to replace the default model.

Other

If you run into any problem or bug, please report them in the Issues tab here or via discord.

The link for discord is mentioned in the Colab page.