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

You can automatically generate and populate your configuration file from any directory using the initialization command:

osu-finder --init

Alternatively, you can provide parameters directly via arguments:

osu-finder --init --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_CLIENT_SECRET" --songs-folder

This will create a config.yaml file with the following structure:

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}"

network:
  proxy_url: "http://user:pass@proxy:port"
  fallback_to_direct: true

active_preset: "default"
blacklist: []

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