osu-beatmap-preview-py
osu-beatmap-preview 的
Python 原生扩展。渲染器通过 PyO3 直接运行在 Python 进程内，不需要下载、配置或启动额外的
可执行文件。
当前为早期开发版本。Rust 核心固定到经过绑定测试的具体提交，以确保 Python wheel 在各平台使用相同的渲染行为。
安装
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 用于临时覆盖输出倍率。
异步取消与并发
上游 Rust API 当前是同步接口，没有提供取消令牌。取消 generate_preview_async() 所在的
Python task 不会中止已经开始的原生渲染；Bot 集成时应使用 semaphore 限制并发。若需要真正的
超时中止，应先在上游 library API 增加协作式取消能力。
本地开发
uv sync
uv run maturin develop
uv run pytest
发布
推送 v* tag 后，GitHub Actions 会构建 Windows、Linux 和 macOS wheel，并通过 PyPI
Trusted Publishing 发布。发布前需要：
- 在 GitHub 创建名为
pypi的 environment； - 在 PyPI 为该 GitHub 仓库配置 Trusted Publisher；
- 确认对应版本已经同时写入
Cargo.toml和pyproject.toml。
许可证
本项目采用 MIT License。上游渲染器同样采用 MIT License，版权归其贡献者所有。
1 maintainer
Metadata
1 maintainer
Release files for osu-beatmap-preview-py 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| osu_beatmap_preview_py-0.1.4.tar.gz | 30.9 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| osu_beatmap_preview_py-0.1.4-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 16.5 MB
Release files / osu_beatmap_preview_py-0.1.4.tar.gz
| Download URL | osu_beatmap_preview_py-0.1.4.tar.gz |
|---|---|
| Size | 30.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a71523f81874f1ed92f9d85703476f67dc4c0eb1c6355f9f18154e6259a53140
|
|
BLAKE2b-256 checksum How to use checksums |
907e04a2ee6a2fd0f8e31beb7002fb41f38f8fcee1094e4a6366b502fcce2b44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / osu_beatmap_preview_py-0.1.4-cp310-abi3-win_amd64.whl
| Download URL | osu_beatmap_preview_py-0.1.4-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e31d46e0ec9a1b76d41f3b8c0067b7cf50d452a28de394e170b765eaae6077dd
|
|
BLAKE2b-256 checksum How to use checksums |
c9dfd07fc0e2de59b9a085ec2f0c7115698dc471a24db8769dc5df18725bbb7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
f35341dc5e6278d28d40c7e84952f451df7dac5180eda977499332cab6e18f88
|
|
BLAKE2b-256 checksum How to use checksums |
9261335926d5ce8cadce2a123d08cb65564d1e731f70010bf9e8a901b56c232e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | osu_beatmap_preview_py-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
97709368495086417bc6d1419afae9883896d55515d5127b9c07424d736ae049
|
|
BLAKE2b-256 checksum How to use checksums |
1adc6b14e0c9112919b19b75b715109686917da07c06e8177954fa054ceba05d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e9a6578bdb185ed4b4939673271adbe1fdc5e3e7da7b641223c7264325b0b42d
|
|
BLAKE2b-256 checksum How to use checksums |
02a603b1848a8c282b36fbac874bafe2fc8910ce8b3666085a801177f271cd11
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | osu_beatmap_preview_py-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
18a249ade69bdcf197d0d907d496300852f4a857ca56717be4ba628915e4ea43
|
|
BLAKE2b-256 checksum How to use checksums |
1bcccd87d702a2bc28b1141fa40c3cf1bc0851f51d79ff2b6bf5aef164497455
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency log
