osu-sync

Sync beatmaps between osu!stable and osu!lazer

Features • Installation • Usage • Building • Contributing

---

About

osu-sync is a powerful command-line tool for managing your osu! beatmap library across both osu!stable and osu!lazer installations. It features a beautiful terminal UI with Catppuccin theming and supports bidirectional sync, collection management, media extraction, and more.

Why osu-sync?

• Bidirectional Sync - Sync beatmaps in either direction or both at once
• Smart Deduplication - Detects duplicates using multiple strategies (hash, metadata, audio fingerprint)
• Fast Scanning - Efficient file hashing with caching for 5x faster repeat scans
• Beautiful TUI - Clean terminal interface with Catppuccin Mocha theme
• Single Binary - Just one executable, no dependencies required

Features

Feature	Description
Beatmap Sync	Bidirectional sync with ETA, pause/resume, and skip list
Collection Sync	Sync collections with preview and merge duplicate detection
Statistics	View beatmap stats with HTML export and recommendations
Media Extraction	Extract audio (with ID3 tags) and backgrounds (with size filtering)
Replay Export	Export replays with filters, stats, and custom rename patterns
Backup/Restore	Incremental backups with compression and verification
Theme Support	Catppuccin Mocha, Dark, and Light themes

Installation

Download Binary (Recommended)

1. Download the latest osu-sync.exe from Releases
2. Place it anywhere on your system
3. Run it from terminal or double-click

Using Cargo

cargo install --git https://github.com/Finesssee/osu-sync

From Source

See Building section below.

Usage

Quick Start

# Run the TUI (default)
osu-sync

# Show help
osu-sync --help

Vision Commands (Optional)

# Capture current TUI state (text or JSON)
osu-sync --tui-snapshot
osu-sync --tui-snapshot --json

# Capture an osu! game window screenshot (Windows + vision feature only)
osu-sync --capture-game
osu-sync --capture-game stable
osu-sync --capture-game lazer

Note: --capture-game requires Windows and a build with the vision feature enabled.

TUI Navigation

Key	Action
↑/↓ or j/k	Navigate menu
Enter	Select option
Esc	Go back
q	Quit

Main Menu Options

1. Scan Installations - Detect osu!stable and osu!lazer paths
2. Sync Beatmaps - Synchronize beatmaps between installations
3. Collection Sync - Sync your beatmap collections
4. Statistics - View detailed beatmap statistics
5. Extract Media - Extract audio files and backgrounds
6. Export Replays - Export replay files with filtering
7. Backup - Create backups of your osu! data
8. Restore - Restore from a backup
9. Configuration - Configure paths and preferences

Configuration

Configuration is stored in:

• Windows: %APPDATA%\osu-sync\config.json
• Linux: ~/.config/osu-sync/config.json
• macOS: ~/Library/Application Support/osu-sync/config.json

Example Config

{
  "stable_path": "C:\\Users\\You\\AppData\\Local\\osu!",
  "lazer_path": "C:\\Users\\You\\AppData\\Roaming\\osu",
  "theme": "Catppuccin",
  "duplicate_strategy": "Hash"
}

Building

Prerequisites

• Rust 1.75 or later
• Git

Build Steps

# Clone the repository
git clone https://github.com/Finesssee/osu-sync.git
cd osu-sync

# Build release version
cargo build --release

# Binary will be at target/release/osu-sync.exe (Windows)
# or target/release/osu-sync (Linux/macOS)

Build with GUI Support (Optional)

cargo build --release --features gui

Build with Vision Capture (Optional, Windows only)

cargo build --release --features vision

Run Tests

cargo test

Project Structure

osu-sync/
├── crates/
│   ├── osu-sync-core/     # Core library (sync, parsing, etc.)
│   └── osu-sync-cli/      # TUI application
├── Cargo.toml             # Workspace configuration
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Run cargo fmt before committing
• Run cargo clippy and address warnings
• Add tests for new functionality
• Update documentation as needed

Roadmap

• Linux/macOS testing and support
• GUI mode with Iced framework
• Beatmap preview player
• Cloud sync integration
• Plugin system

FAQ

Where does osu-sync store its data?

Configuration and cache are stored in your system's standard config directory. On Windows, this is %APPDATA%\osu-sync.

Is it safe to use with my beatmaps?

Yes! osu-sync only reads from source installations and writes to target installations. It never modifies your original files. We recommend creating a backup first anyway.

Why is the first scan slow?

The first scan computes hashes for all beatmap files to enable deduplication. Subsequent scans use cached hashes and are much faster (~5x).

Does it work with osu!lazer's new storage format?

Yes! osu-sync reads osu!lazer's Realm database directly and understands its file storage structure.

Acknowledgments

• ppy/osu - The osu!lazer project
• Catppuccin - Beautiful pastel color scheme
• ratatui - Terminal UI framework
• osu-db - osu!stable database parsing

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ for the osu! community