Convert osu! beatmaps into properly tagged MP3 files
Windows • macOS • Linux
Features • Installation • Usage • Screenshots • License
- Batch Export - Process and tag multiple beatmaps simultaneously.
- Metadata Tagging - Automatically applies ID3 tags including Artist, Title, and Album info.
- Cover Art Extraction - Extracts beatmap backgrounds and embeds them as album art.
- Spotify Integration - Shows which songs are available on Spotify with clickable badges.
- Modern Interface - Clean glassmorphism design built with Avalonia.
- Context Actions - Right-click support to view maps online, open local folders, or export backgrounds.
- Incremental Scanning - Only scans for new beatmap folders on subsequent launches.
- Audio Previews - Preview map audio by hovering over cards.
- Path Persistence - Automatically remembers and loads your Songs folder.
- Companella! Integration - Detects (Companella!) for play count statistics.
- Update Checker - Notifies you of new releases on startup.
- Anonymous Telemetry - Optional usage statistics to assist with development.
- Windows: Windows 10/11
- macOS: macOS 10.15 or newer
- Linux: Distributions supporting GLibc (Ubuntu, Fedora, etc.)
- .NET 8.0 Runtime (Optional if using the self-contained installer)
- Go to the Releases page.
- Download the version for your OS:
- Windows: osu-tag-win-installer.exe or .zip
- macOS: osu-tag-mac.zip (Needs (Sentinel))
- Linux: osu-tag-linux.zip
- Launch the application.
- Select Songs Folder - Point the application to your osu! Songs directory.
- Scan and Select - The app scans your maps; click cards to select them for export.
- Context Menu - Right-click any card to view details on the osu! website or open the file location.
- Convert - Click "Start" to generate the tagged MP3 files.
- Framework: Avalonia UI (.NET 8.0)
- Image Processing: SixLabors.ImageSharp
- Audio Tagging: TagLibSharp
- Audio Playback: MiniAudio
# Clone the repository
git clone https://github.com/kaanreal/osu-tag.git
cd osu-tag
# Set Spotify API credentials (optional - for Spotify integration)
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
# Build and run
cd src/osu!tag
dotnet build
dotnet run- Spotify Search Logic - Inspired by osu-find-songs
MIT License – See LICENSE for details.
This was planned to be an simple osu! project but it grew and grew to the point of teaching me things. Even if its AI :)
Built for the osu! community