osu! Map Finder

A high-performance command-line utility for searching, analyzing, and downloading osu! beatmaps based on advanced criteria and player profiles.

Installation

pipx install osu-finder

Configuration

Create a config.yaml file in your working directory to set up your API credentials and game paths:

credentials:
  client_id: "YOUR_CLIENT_ID"
  client_secret: "YOUR_CLIENT_SECRET"

paths:
  songs_folder: "C:/Users/YourName/AppData/Local/osu!/Songs"
  download_folder: "./downloads"

mirror:
  base_url: "[https://catboy.best](https://catboy.best)"
  osu_file_path: "/osu/{id}"
  osz_download_path: "/d/{id}"

active_preset: "default"

Usage

1. Search and Download

Run the finder using your active preset:

osu-finder

Use a specific preset:

osu-finder --preset preset_name

2. Profile Analysis

Generate a customized search preset based on a player's top performance records:

osu-finder -u Username --focus stream

Available focus modes: balanced, stream, jump, push, farm. Combine analysis and immediate execution:

osu-finder -u Username --focus farm --run-search

3. Blacklist Maps

Add an unwanted beatmap set ID to the global blacklist:

osu-finder --ban 1234567