ROCM - Rust osu! Collection Manager

A concise and efficient tool for managing osu! collections, detecting and downloading missing beatmaps, and removing missing beatmap hashes from collection.db. Using Sayobot as download source with multi-threaded support.

collection.db originally stores beatmap hashes, and removes them when you remove beatmaps from one collection in osu! client, but does not remove them if you delete beatmaps directly. This leads to missing beatmaps in your collections.

ROCM helps you

• analyze your collection.db file.
• identify and download these missing beatmaps efficiently.
• remove missing beatmap hashes from collection.db with flexible options.
• Select part of collections to download/delete missing beatmaps (TODO).

✨ Features

• 🚀 Built on osynic_osudb high-performance parser
• 📊 Automatic analysis of osu!.db and collection.db
• 🔍 Precise identification of missing beatmaps in collections
• ⚡ Async concurrent downloads with rate limiting
• ⏭️ Smart skip for already downloaded beatmaps
• 📂 Configurable download directory (defaults to osu! Songs folder)
• 📈 Real-time progress display
• 🗑️ Flexible removal options: by ID, range, all missing, or API-not-found hashes
• 💾 Automatic backup before modifying collection.db

📦 Installation

git clone https://github.com/yourusername/osu-collection-manager
cd osu-collection-manager
cargo build --release

⚙️ Configuration

Create config.toml in the project root or <your-config-path>/ROCM/:

[osu]
path = "C:/osu!"                         # osu! installation path
api_token = "your_api_token_here"        # osu! API Token (v1)

[network]
# proxy = "http://127.0.0.1:7890"        # Optional: proxy address (commented out - enable if needed)

[download]
workers = 5                              # Optional: concurrent downloads
delay_ms = 1000                          # Optional: download delay (ms)
directory = "D:/osu!/Songs"              # Optional: download directory (defaults to <osu_path>/Songs)

Configuration File Path:

Platform	Value	Example
Linux	$XDG_CONFIG_HOME or $HOME/.config	/home/alice/.config
macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

How to Get API Token: osu! website → Account Settings → OAuth → Legacy API → Create new application

Important

REMEMBER: DO NOT SHARE YOUR API TOKEN WITH ANYONE ELSE.

Note

Valid osu! API Token required to fetch beatmap info from hashes

Download source is Sayobot, fast access in China

Set reasonable workers and delay to avoid rate limiting

🚀 Usage

View Statistics

cargo run -- stats
# or use short form
cargo run -- s

List Missing Beatmaps

# List all missing beatmaps with numbered output
cargo run -- list
# or use short form
cargo run -- l

Download Missing Beatmaps

# Download three types of beatmaps
cargo run -- download --type <full|novideo|mini>

# or use short form
cargo run -- d --type <full|novideo|mini>

# Skip already downloaded beatmaps
cargo run -- download --skip-existing
cargo run -- d -s  # short form

# Custom workers and delay
cargo run -- download --type novideo --workers 10 --delay 500

# Combine options
cargo run -- d -t novideo -w 10 -d 500 -s

Remove Missing Beatmap Hashes

Remove missing beatmap hashes from collection.db (automatically creates backup):

# Remove by beatmapset ID(s)
cargo run -- remove by-id 123456 789012
# or use short form
cargo run -- r by-id 123456

# Remove by number range from 'list' output (indicated by 'No.')
# First, run: cargo run -- list
# Then remove by range (similar to youtube-dl -f)
cargo run -- remove range "1-5"        # Remove mapsets 1 through 5
cargo run -- r range "1,3,5"           # Remove mapsets 1, 3, and 5
cargo run -- r range "1-5,10-15"       # Remove mapsets 1-5 and 10-15

# Remove all missing beatmap hashes
cargo run -- remove all
cargo run -- r all --yes  # Skip confirmation

# Remove hashes not found in API
cargo run -- remove not-found
cargo run -- r not-found --yes  # Skip confirmation

📝 Example Output

osu! path: "C:\\osu!"
Loading osu!.db...
Local beatmaps: 15432
Loading collection.db...
Collection beatmaps: 2847
Missing beatmaps: 156

Fetching beatmapset IDs via API...
Need to download 89 beatmapsets
Checking download path: "D:\\osu!\\Songs"
Skipping 32 already downloaded beatmapsets
Will download 57 beatmapsets

Download progress [████████████████████████████] 57/57
Download complete

🛠️ Command Line Options

osu-collection-manager <COMMAND>

Commands:
  stats (s)     Display statistics
  list (l)      List missing beatmaps
  download (d)  Download missing beatmaps
  remove (r)    Remove missing beatmap hashes from collection.db
  help          Print help information

Global Options:
  -h, --help  Show help information

Download Command Options:
  -t, --type <TYPE>        Download type: full, novideo, mini [default: novideo]
  -w, --workers <WORKERS>  Concurrent downloads [default: 5]
  -d, --delay <DELAY>      Download delay in ms [default: 1000]
  -s, --skip-existing      Skip already downloaded beatmaps

Remove Command Subcommands:
  by-id <IDS...>           Remove by beatmapset ID(s)
  range <RANGE>            Remove by number range (e.g., "1-5", "1,3,5", "1-5,10-15")
  all [--yes]              Remove all missing hashes (--yes to skip confirmation)
  not-found [--yes]        Remove hashes not found in API (--yes to skip confirmation)

Project Structure

  src/
  ├── main.rs          # Entry point and main workflow
  ├── api.rs           # API client
  ├── cli.rs           # Command line argument definitions
  ├── config.rs        # Configuration management
  ├── db.rs            # Database operations
  ├── downloader.rs    # Download functionality
  └── helpers.rs       # Helper functions

🙏 Acknowledgments

• osynic_osudb - Excellent osu!/collection/scores db parser library
• Sayobot - Beatmap download service provider