osu! PP 推荐谱面下载工具：从逆向 API 到桌面 GUI

GitHub → AlphaOsu-Download-Tool

这是什么#

AlphaOsu 是一个用机器学习帮你刷 PP 的网站——它会分析你的游玩数据，推荐你最有可能拿到 PP 的谱面。

但它没有批量下载功能。每次想下谱子，得一个一个点开 osu! 官网再下载，非常痛苦。

所以我就逆向了它的 API，做了一个基于 PyWebView 的桌面 GUI 工具——有界面、有封面图、支持筛选和批量下载，还能自定义保存目录。

逆向 API#

AlphaOsu 是一个 React SPA，接口藏在编译后的 JS bundle 里。

找到接口#

直接看打包后的 JS 文件，grep 关键词：

1
curl -s "https://alphaosu.keytoix.vip/assets/index.c1b1fee7.js" | grep -oP '"/api/v1/[^"]*"'

几个关键接口：

接口	用途
`POST /api/v1/login`	登录（只需 osu! 用户名）
`GET /api/v1/self/maps/recommend`	获取 PP 推荐谱面

登录#

登录非常简单，POST 一个用户名就行，不需要密码：

1
def login(username):
2
    """登录获取 uid —— AlphaOsu 用 osu! 用户名作为唯一标识"""
3
    result = api_post("/login", {"username": username})
4
    # 返回示例: {"uid": "37641269", "keyCount": 4, "gameMode": 0, "mod": ["NM"]}
5
    return result["data"]["uid"]

获取推荐（分页）#

API 用 current + pageSize 分页，next 字段指向下一页页码，-1 表示没有了。

1
def get_all_recommendations(uid, game_mode=0):
2
    """自动翻页获取全部推荐谱面
3

4
    API 每次返回 20 个，用 current 参数翻页。
5
    返回的 next 字段是下一页页码，-1 表示没有了。
6
    """
7
    all_maps = []
8
    current = 1
9

10
    while True:
11
        result = api_get("/self/maps/recommend", {
12
            "uid": uid,
13
            "gameMode": game_mode,   # 0=osu!standard
14
            "current": current,       # 页码（不是 offset！）
15
            "pageSize": 20,           # 每页数量
16
            "rule": 4,                # 推荐算法版本（JS里是 Sa.V4 = 4）
17
        })
18

19
        data = result["data"]
20
        all_maps.extend(data["list"])
21

22
        # next=-1 表示没有下一页了
23
        if data["next"] == -1:
24
            break
25
        current = data["next"]
26

27
    return all_maps

桌面 GUI 工具#

基于 PyWebView 构建，前端用 HTML/CSS/JS 渲染，Python 负责后端逻辑和文件下载。不需要浏览器，直接弹出一个原生窗口。

GitHub → zureealLV/AlphaOsu-Download-Tool

功能特性#

谱面卡片：每首歌显示封面图、曲名、星数、Mod、预测 PP、上榜概率等
多条件筛选：星数范围、Mod 类型、上榜概率、破纪录概率、隐藏已玩过的
批量下载：勾选想要的谱面，一键批量下载 .osz 文件
自定义目录：可以指定保存路径，直接下到 osu! 的 Songs 文件夹
下载源：使用 Sayobot 国内镜像，免登录、速度快

技术架构#

1
┌───────────────────────────────────────────┐
2
│         PyWebView Native Window           │
3
│  ┌─────────────────────────────────────┐  │
4
│  │       HTML / CSS / JavaScript       │  │
5
│  │  filters · table · covers · UI      │  │
6
│  └──────────────┬──────────────────────┘  │
7
│                 │ pywebview.api           │
8
│  ┌──────────────▼──────────────────────┐  │
9
│  │        Python Backend               │  │
10
│  │ login · get_page · choose_dir       │  │
11
│  │ download                            │  │
12
│  └──────────────┬──────────────────────┘  │
13
└─────────────────┼─────────────────────────┘
14
                  │ HTTPS
15
       ┌──────────▼──────────┐
16
       │   AlphaOsu API      │  ← ML 推荐数据
17
       └─────────────────────┘
18
       ┌─────────────────────┐
19
       │  Sayobot Mirror     │  ← .osz 下载
20
       └─────────────────────┘

PyWebView 在前端 JS 和 Python 之间搭了一座桥：前端调用 window.pywebview.api.xxx() 就能触发 Python 后端的函数，实现了登录、获取推荐、下载等操作，同时避免了浏览器环境下的 CORS 限制。

安装与运行#

1
# 克隆仓库
2
git clone https://github.com/zureealLV/AlphaOsu-Download-Tool.git
3
cd AlphaOsu-Download-Tool
4

5
# 安装依赖
6
pip install -r requirements.txt
7

8
# 运行
9
python main.py

下载源#

osu! 官网下载需要登录，但国内镜像 Sayobot 可以免登录直接下载：

1
# Sayobot 的下载接口，传入 beatmapset ID 即可
2
SAYOBOT_DL = "https://dl.sayobot.cn/beatmaps/download"
3

4
def download_beatmap(set_id, map_name, download_dir):
5
    """从 Sayobot 镜像下载 .osz 文件
6

7
    .osz 就是 osu! 的谱面包，双击就能导入游戏。
8
    """
9
    url = f"{SAYOBOT_DL}/{set_id}"
10
    with urllib.request.urlopen(req, timeout=120) as resp:
11
        data = resp.read()
12
        # 保存为 "413117 Ghost Rule.osz"
13
        with open(filepath, "wb") as f:
14
            f.write(data)

从封面 URL 提取 beatmapset ID#

API 返回的是单个难度的 beatmap ID，但下载需要 beatmapset ID。从封面 URL 里可以提取：

1
def extract_beatmapset_id(cover_url):
2
    """从封面 URL 提取 beatmapset ID
3

4
    输入: https://assets.ppy.sh/beatmaps/413117/covers/cover.jpg
5
    输出: 413117
6
    """
7
    match = re.search(r'/beatmaps/(\d+)/covers/', cover_url)
8
    return match.group(1) if match else None

客户端筛选#

API 不支持服务端筛选（传什么参数都没用），所以全部在客户端过滤：

1
def filter_maps(maps, config):
2
    """多条件筛选
3

4
    筛选条件：
5
    - 星数范围（默认 5.0 - 7.3）
6
    - 隐藏已玩过的（currentPP != None）
7
    - Mod 类型（默认只要 NM）
8
    - 上榜概率（默认 20% - 100%）
9
    - 破纪录概率（默认 20% - 100%）
10
    """
11
    filtered = []
12
    for m in maps:
13
        # 星数范围
14
        if m["difficulty"] < config.min_star or m["difficulty"] > config.max_star:
15
            continue
16
        # 隐藏已玩过 —— currentPP 不为 null 说明打过了
17
        if config.hide_played and m.get("currentPP") is not None:
18
            continue
19
        # Mod 过滤
20
        if config.mods:
21
            map_mods = set(m.get("mod", []))
22
            if not any(mod in map_mods for mod in config.mods):
23
                continue
24
        # 上榜概率 —— API 返回的是 0-1，要乘 100 变成百分比
25
        if m.get("passPercent") is not None:
26
            pct = m["passPercent"] * 100
27
            if pct < config.min_rank or pct > config.max_rank:
28
                continue
29
        # 破纪录概率
30
        if m.get("newRecordPercent") is not None:
31
            pct = m["newRecordPercent"] * 100
32
            if pct < config.min_record or pct > config.max_record:
33
                continue
34
        filtered.append(m)
35
    return filtered

音乐

音乐