Mustaff is a Python-based tool that automatically generates rhythm game beatmaps by analyzing the temporal (beat/onset) and spectral (pitch/volume) features of audio files. It supports multiple output formats including osu!mania and custom JSON, and provides a command-line interface, a graphical user interface, and an interactive rhythm game preview engine.
- Audio Analysis — Powered by
librosafor onset detection, beat tracking, pitch extraction (pYIN), and RMS energy analysis - Beat Mapping — Pitch-to-column mapping with histogram equalization for balanced distribution across lanes; energy-based hold note (LN) generation; auto-resolve hold/short-note column conflicts
- Multi-Format Export — osu!mania (
.osu, 1K–9K) and custom JSON beatmap formats - Interactive Preview — Real-time falling-note preview with audio playback, auto-hit effects, seekable timeline, and dynamic canvas rendering
- Double Hit (Chord) — Optionally merge simultaneous notes into chord hits with configurable RMS energy threshold; resolves column conflicts by relocating to free lanes
- Multiple Interfaces — Python API, CLI tool, and tkinter-based GUI with threaded generation and progress reporting
- Python 3.9 or higher
- Audio playback support (pygame mixer)
Pre-built executables for Windows, macOS, and Linux are available via GitHub Releases.
| Platform | CLI | GUI |
|---|---|---|
| Windows | mustaff-cli.exe |
mustaff-gui.exe |
| macOS | mustaff-cli |
mustaff-gui |
| Linux | mustaff-cli |
mustaff-gui |
No Python installation is required. Download the archive for your platform, extract, and run directly.
git clone https://github.com/ChidcGithub/Mustaff.git
cd Mustaff
pip install -e .pip install -r requirements.txt# Generate a 4K osu!mania beatmap with preview image
mustaff-cli "song.mp3" --keys 4 --format both --preview -o ./output
# 7K beatmap with custom difficulty
mustaff-cli "song.flac" --keys 7 --format osu --difficulty "Hard" -o ./maps
# ML generation with an explicit backend (auto = priority fallback)
mustaff-cli "song.mp3" --ml --ml-backend mert --ml-stars 5 -o ./output
# View all options
mustaff-cli --helpfrom mustaff.analyzer import AudioAnalyzer
from mustaff.mapper import BeatMapper
from mustaff.exporters.osu_mania import OsuManiaExporter
# Analyze audio
analyzer = AudioAnalyzer()
analyzer.load("song.mp3").analyze()
# Map to notes
features = analyzer.get_note_features()
mapper = BeatMapper(keys=4)
notes = mapper.map_notes(features)
# Export
exporter = OsuManiaExporter(
notes=notes,
bpm=analyzer.tempo,
keys=4,
title="Song Title",
artist="Artist",
version="Normal",
)
exporter.export("song.osu")python -m mustaff.gui.appLaunch the graphical interface, select an audio file, adjust parameters, and click Generate. With 生成方式 set to ML 模型, the ML 后端 dropdown lists all detected backends (v3/mert/raw/v2, ✓ = weights found) and switches between them; click 重新检测 to rescan training/output/. Use Play Preview to enter the interactive falling-note preview mode.
Mustaff/
├── mustaff/
│ ├── __init__.py
│ ├── analyzer.py # Audio analysis core (librosa)
│ ├── mapper.py # Beat mapping logic
│ ├── cli.py # Command-line interface
│ ├── preview.py # Static preview image generation
│ ├── gui/
│ │ ├── app.py # Main GUI application
│ │ └── preview_player.py # Interactive rhythm game preview engine
│ └── exporters/
│ ├── base.py
│ ├── osu_mania.py # osu!mania .osu exporter
│ └── json_exporter.py # Custom JSON exporter
├── tests/
├── examples/
├── requirements.txt
├── pyproject.toml
└── README.md
| Module | Technology |
|---|---|
| Onset Detection | librosa.onset.onset_detect |
| Beat Tracking | librosa.beat.beat_track |
| Pitch Extraction | librosa.pyin (pYIN algorithm) |
| Energy Analysis | RMS via librosa.feature.rms |
| Column Mapping | Histogram equalization (quantile-based distribution) |
| Audio Playback | pygame.mixer.music |
| GUI Rendering | tkinter.Canvas with dynamic resize |
| Static Preview | matplotlib (dark theme) |
Beyond the rule-based pipeline, Mustaff can generate charts with pre-trained ML models (--ml / GUI menu). Weights live in raining/output/ and are auto-selected in this order:
| Backend | Weights | Notes |
|---|---|---|
| v3 (default) | placement_v3_best.pt + selection_v3_best.pt | Beat-grid Transformer + combo LSTM on hand-crafted features |
| v5-mert (experimental) | placement_mert_best.pt + selection_mert_best.pt | Frozen MERT-v1-95M encoder (per-beat 8x768) + same beat-grid structure; needs ransformers and MERT weights at inference. Wins on selection (combo acc 0.436 vs 0.429) but placement still below v3 |
| v4-raw (experimental) | placement_raw_best.pt + selection_raw_best.pt | Raw-waveform conv frontend + same beat-grid structure |
| v2 (fallback) | placement_best.pt + selection_best.pt | Frame-level CNN/LSTM |
Set MUSTAFF_ML_BACKEND=mert|raw|v3|v2 to force a backend. At the current dataset scale (2,912 beatmap sets) the three-way A/B on the test split shows v3 placement still leads (slot F1 0.678 vs mert 0.536 / raw 0.481) while mert selection slightly beats v3 (combo acc 0.436 vs 0.429), so v3 remains the default; see raining/output/eval_ab_*.json and raining/ scripts for reproduction.
This project uses GitHub Actions to automatically build and release cross-platform executables on every push to the main branch.
| Workflow | Status |
|---|---|
| Build & Release | |
To trigger a new release, push a tag:
git tag v0.1.0
git push origin v0.1.0This project is licensed under the MIT License.