osu-beatmap-preview-py

osu-beatmap-preview 的 Python 原生扩展。渲染器通过 PyO3 直接运行在 Python 进程内，不需要下载、配置或启动额外的 可执行文件。

当前为早期开发版本。0.1.9 使用上游 main 的固定提交 0045d40 （v1.4.0 之后），core、CLI 和构建资源随仓库分发，确保各平台 wheel 使用相同的渲染行为。 本次更新包含 NC/DC、Standard AT、故事板与背景视频，以及 Aspire 谱面的音频混合和音画同步修复。

安装

pip install osu-beatmap-preview-py

PyPI 发布后，pip 会为受支持的平台安装预编译 wheel，不要求用户安装 Rust。没有预编译 wheel 的平台从源码安装时仍需要 Rust 和 C++ 工具链。

使用

from osu_beatmap_preview import generate_preview_async

result = await generate_preview_async(
    4498112,
    format="gif",
    mods="hd+hr",
    times="preview+60",
    duration_time=8,
    fps=30,
    scale=1.5,
)
print(result["preview-img"])

generate_preview() 是同步接口，适合脚本；NoneBot、FastAPI 等异步应用应使用 generate_preview_async()，避免阻塞事件循环。

convert 仅用于将 osu!standard 谱面转换成 taiko、ctb 或 mania。原生非 standard 谱面不要传入 convert。

times 使用 + 分隔多个秒数，也支持 preview；duration_time 控制 GIF 片段或 MP4 区间时长。config 可传配置文件路径或内联 JSON/YAML，scale 用于临时覆盖输出倍率。

CTB GIF 模组

原生 CTB 和 standard 转 CTB 的 GIF 支持 hd、ez、hr、dt、ht。 HD 会让水果、水滴及香蕉在到达判定线前渐隐；支持 hd+ez、hd+hr、hd+dt、hd+ht。 ez+hr 和 dt+ht 是互斥组合。PNG 静态图支持 EZ、HR，不支持 HD、DT、HT。 Hyperdash（红果）的外圈默认使用红色 #FF0000，可通过 skin.HYPER_DASH 配置 RGB 颜色； 水果本体继续使用谱面 Combo 颜色，HD 渐隐同时作用于本体、白边和红圈。

result = await generate_preview_async(
    3994408,
    format="gif",
    mods="hd+dt",
    times="preview",
    duration_time=3,
    fps=20,
)

四种模式的 GIF / MP4 模组

组合中的每个模组都必须受当前模式支持；Mania 的 HD+FL 互斥，其余三种模式可组合使用。 HD+TC、IN+HO、EZ+HR、DT+HT 互斥；mania 的键数模组和 DS 只影响 standard 转谱。 GIF 和 MP4 使用相同的模组支持规则，GIF 在 15、30、60 fps 下也会保持请求的播放时长。

DT/HT 的 MP4 音乐保调变速，可用 dt1.25、ht0.9 指定倍速；NC/DC 默认以 1.5x / 0.75x 播放，也可指定倍速，音乐音高倍率固定为 1.5 / 0.75，NC 还叠加节拍鼓点。 速度模组不能混用。 Standard 的 AT 显示自动游玩光标。四模式 MP4 可通过 render.<mode>.mp4.style.ENABLE_STORYBOARD 和 ENABLE_BACKGROUND_VIDEO 启用故事板及背景视频， 两项默认关闭；<mode> 为 standard、taiko、catch 或 mania。

Taiko HD 隐藏普通音符和连打刻度，保留连打条与气球；Mania HD 让音符头、长按主体 在判定线附近渐隐，遮罩随连击扩大。HD 不会遮住 Mania 判定线、键道背景或 SV 提示。 Catch HD 在 Kiai 区段持续保留淡淡的物件轮廓，不随 BPM 闪烁；区段结束后恢复普通 HD。 圆形预览样式暂用约 30% 不透明度近似轮廓亮度，不逐像素复刻皮肤的 lighting 纹理。

FL 在 Standard 跟随自动光标（滑条期间额外暗化），在 Catch 跟随接盘，在 Taiko 固定于判定区； Mania FL 只保留中部横向可视带。Standard、Taiko、Catch 在 100/200 combo 时缩小光圈。 预览没有玩家输入或回放，轨迹用谱面物件之间的插值估算，连击按无 miss 进度计算； Standard 的光圈跟随延迟使用连续阻尼近似，Catch 香蕉雨期间沿用相邻水果的插值路线。 Taiko、Catch、Mania 的 PNG 是静态概览，不支持 HD/FL；Standard 的 PNG 快照支持二者。

异步取消与并发

上游 Rust API 当前是同步接口，没有提供取消令牌。取消 generate_preview_async() 所在的 Python task 不会中止已经开始的原生渲染；Bot 集成时应使用 semaphore 限制并发。若需要真正的 超时中止，应先在上游 library API 增加协作式取消能力。

本地开发

uv sync
uv run maturin develop
uv run pytest
cargo test -p osu-beatmap-preview-core -p osu-beatmap-preview-cli

发布

推送 v* tag 后，GitHub Actions 会构建 Windows、Linux 和 macOS wheel，并通过 PyPI Trusted Publishing 发布。发布前需要：

1. 在 GitHub 创建名为 pypi 的 environment；
2. 在 PyPI 为该 GitHub 仓库配置 Trusted Publisher；
3. 确认对应版本已经同时写入 Cargo.toml 和 pyproject.toml。

许可证

本项目采用 MIT License。上游渲染器同样采用 MIT License，版权归其贡献者所有。