osu! Database Parser

A robust C++ tool for parsing the osu!.db binary file and exporting beatmap metadata to CSV format. This tool is designed to handle modern osu!.db versions (tested with 20251128) and provides a reliable way to extract beatmap information.

Background

This tool was initially created to assist with the development of the beatmap-downloader project. Its primary purpose was to verify and debug the database parsing logic (specifically in features/database/database.cpp) to ensure accurate extraction of beatmapid from the osu!.db file.

Features

• Robust Parsing: correctly handles variable-length fields and optional data blocks present in modern osu!.db files.
• CSV Export: Exports all parsed beatmap data to beatmaps.csv for easy analysis in Excel or other tools.
  • Includes human-readable labels for Ranked Status (e.g., Ranked, Loved) and Game Mode (e.g., Standard, Mania).
  • Properly escapes strings and serializes complex lists (Star Ratings, Timing Points).
• Error Recovery: Includes basic heuristic recovery to attempt to continue parsing if a beatmap entry is malformed (though the current parser is stable).
• Clean Output: Provides concise console feedback with progress indicators.

Prerequisites

• Windows OS (due to current build script, but code is cross-platform compatible C++).
• Visual Studio 2022 (or Build Tools for Visual Studio) with C++ workload installed.
• An osu!.db file (usually located in your osu! installation folder, e.g., %localappdata%\osu!).

Usage

1. Place your osu!.db file in the same directory as the executable (dbtool.exe).

2. Run the executable from the command line:

   dbtool.exe

3. The program will parse the database and generate a beatmaps.csv file in the same directory.

4. Open beatmaps.csv to view the extracted data.

Technical Details

The parser implements the osu!.db file structure as described in the osu! wiki. It specifically handles:

• ULEB128 variable-length integers.
• Double/Single precision floats for difficulty stats.
• Int-Double pairs for star ratings (custom serialization in CSV).
• Timing Points (custom serialization in CSV).

License

This project is open-source. Feel free to modify and use it for your own osu! related tools.