OSU File - Osu! Script File Format, How to Create & Open It?
What is an OSU file?
An OSU file is a game script written for osu! rhythm game. It contains information about a beatmap used in the game such as the difficulty level, the song to be played, and the timings of the hit objects to which the player has to sync with the music. It lets rhythm game players to develop custom challenges and share with the game community.
MIME Type of OSR File Format: x-osu-beatmap
OSU File Format
OSU files are saved as plain text files to disc and its structure is very clearly defined in the OSU file format by osu!.
Sections in OSU File
A typical OSU file has the follwoing sections.
| Section | Description | Content type |
|---|---|---|
| [General] | General information about the beatmap | key: value pairs |
| [Editor] | Saved settings for the beatmap editor | key: value pairs |
| [Metadata] | Information used to identify the beatmap | key:value pairs |
| [Difficulty] | Difficulty settings | key:value pairs |
| [Events] | Beatmap and storyboard graphic events | Comma-separated lists |
| [TimingPoints] | Timing and control points | Comma-separated lists |
| [Colours] | Combo and skin colours | key : value pairs |
| [HitObjects] | Hit objects | Comma-separated lists |
Key Characteristics of OSU Files
| Characteristic | Description |
|---|---|
| File Extension | .osu |
| Primary Variants | Standard osu! beatmap files (all game modes), osu!taiko beatmap files (Taiko mode), osu!catch beatmap files (Catch the Beat mode), and osu!mania beatmap files (Mania mode) |
| Format Type | Plain text file using the INI file format with section-based organization; stores beatmap data in human-readable format; includes [General], [Editor], [Metadata], [Difficulty], [Events], [TimingPoints], and [HitObjects] sections |
| Primary Use | Defining all gameplay elements for an osu! rhythm game beatmap; stores timing data, hit object placements, difficulty settings, song metadata, and visual event information |
| Main Feature | Highly customizable plain text format enabling precise beatmap creation and editing; supports four distinct game modes (osu!, Taiko, Catch the Beat, Mania); includes detailed hit object definitions with support for circles, sliders, spinners, and long notes |
| Security Profile | Safe for game use; contains no executable code; can be safely edited with any text editor; human-readable format allows for direct modification and fine-tuning of beatmap parameters |
| Compatibility | Native to osu! game client (Windows, macOS, Linux); can be edited with any text editor; OSZ packages contain the OSU file along with audio (MP3/OGG) and image (JPG/PNG) assets; can be converted to other rhythm game formats using community tools |
Opening OSU Files in osu!
OSU files are automatically used when playing a beatmap in osu!:
Install an OSZ file by double-clicking it
The game extracts the OSU file and associated assets
Select the beatmap from the song selection menu
The OSU file provides the gameplay instructions
Editing OSU Files
To edit an OSU file:
Extract the OSU file from the OSZ archive
Open the file with any text editor (Notepad++, Visual Studio Code, etc.)
Modify the desired sections and values
Save the file and test the changes in osu!
Creating New OSU Files
New OSU files are typically created using the osu! beatmap editor:
Launch osu! and open the beatmap editor
Select a song file
Use the editor to place hit objects
The editor generates the OSU file automatically
Share the beatmap set as an OSZ file
Converting OSU Files
OSU files can be converted to other formats using specialized tools:
osu! to StepMania – Convert to SM format
osu! to Quaver – Convert to QS format
Frequently Asked Questions (FAQ)
Q1: What does OSU stand for in the osu! game?
A1: OSU stands for osu! beatmap, which is the file format used to store all gameplay data for a playable beatmap in the rhythm game .
Q2: How do I open and edit an OSU file?
A2: You can open and edit OSU files with any text editor like Notepad, Notepad++, or Visual Studio Code, as they are stored in plain text using the INI format .
Q3: What is the difference between an OSU file and an OSZ file?
A3: An OSU file is the beatmap file containing gameplay data, while an OSZ file is a ZIP archive containing the OSU file along with audio and image assets .
Q4: Can I create an OSU file without using the osu! game?
A4: While you can create OSU files manually with a text editor, it is much easier to use the built-in beatmap editor in osu!, which generates the file automatically .
Q5: What game modes are supported by OSU files?
A5: OSU files support four game modes: standard osu! (clicking circles), Taiko (drumming), Catch the Beat (fruit catching), and Mania (keyboard rhythm) .