A major strength of rhythm gaming is its community-created charts. Over the last fifteen years, the osu!mania community has mapped tens of thousands of songs across nearly every electronic genre.
When developing Rhythmio, we wanted players to bring their existing beatmaps along rather than starting from scratch.
Rhythmio includes a client-side parser for osu!mania packages (.osz). You can drag and drop your downloaded song files directly into the browser to play immediately, without uploading your files to an external server.
Here is how the browser-based unpacking pipeline works and how custom beatmaps are cached locally.
1. How Client-Side .osz Import Works
An .osz file is a standard ZIP archive containing:
- One or more
.osutext files containing chart metadata and note timings - An audio file (
audio.mp3oraudio.ogg) - Background illustrations and jacket art
The In-Browser Unpacking Steps:
- File Drop: Dropping an
.oszfile onto the window triggers the HTML5 File API. - In-Memory Decompression: A background Web Worker unpacks the ZIP stream within browser memory.
- Chart Parsing: The
.osutext files are converted into Rhythmio’s internal chart format:[General]: audio filename and mode checks[Difficulty]: key count and timing scale[TimingPoints]: BPM changes and uninherited offsets[HitObjects]: lane assignments, timestamps, and hold lengths
Because files stay inside your local browser session, imports take under a second and keep your personal files private.
2. Local Storage and Zero-Traffic Caching (IndexedDB)
When you import a custom beatmap, you do not need to drag it in again every time you reload the page.
Rhythmio stores imported charts in the browser’s built-in IndexedDB database:
- Decompressed audio and chart data stay cached locally.
- When you return, your library loads directly from local disk storage without consuming network bandwidth.
- You can browse, search by title, sort by difficulty, or delete custom charts from the in-game song selection screen.
3. Supported Modes and Compatibility
Rhythmio supports standard vertical scrolling mania charts:
- Key Counts: Full support for 4K, 5K, 6K, and 7K charts. (Charts mapped for 8K+ or non-mania modes like taiko or catch are filtered out).
- Scroll Velocity (SV) Multipliers: Inherited timing points are supported, matching the chart author’s intended speed changes.
- Audio Formats: MP3, OGG Vorbis, and WAV files are supported natively.
4. How to Play in 3 Steps
- Find an
.oszfile on your computer. - Open Rhythmio in Chrome, Safari, Edge, or Firefox.
- Drag and drop the
.oszfile onto the song select screen. - Pick the newly imported track and start playing!
Wrapping Up
Supporting local osu!mania beatmaps allows players to enjoy their favorite custom charts with zero install requirements.
Thank you for reading our 10-part launch series. You can jump into a match, challenge a friend with a room link, or drop in your favorite tracks to test out the engine.
