osu-beatmap-preview-py

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

当前为早期开发版本。依赖暂时固定到上游首次公开 Rust library API 的 commit；正式发布前， 应升级到包含该 API 的稳定上游版本。

安装

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",
)
print(result["preview-img"])

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

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

异步取消与并发

上游 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 发布。发布前需要：

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

许可证

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

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yaowan233 from gravatar.com yaowan233

Credits

Author: osu-beatmap-preview-py contributors

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python <3.14, >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

osu_beatmap_preview_py-0.1.0.tar.gz (27.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

osu_beatmap_preview_py-0.1.0-cp310-abi3-win_amd64.whl (2.8 MB view details)

Uploaded CPython 3.10+Windows x86-64

osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl (3.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl (2.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_11_0_arm64.whl (2.7 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl (2.8 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file osu_beatmap_preview_py-0.1.0.tar.gz.

File metadata

  • Download URL: osu_beatmap_preview_py-0.1.0.tar.gz
  • Upload date:
  • Size: 27.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for osu_beatmap_preview_py-0.1.0.tar.gz
Algorithm Hash digest
SHA256 587abe48d3bc7b2510431a706c21a2196addc2f043ef65248115bface0d3e318
MD5 6f4eea551c23e6af5aa4f113623df1d7
BLAKE2b-256 39c1a89641eb6958e56d651998fcf75cf67292ce49753eb8951dbd4a4f9707ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0.tar.gz:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_beatmap_preview_py-0.1.0-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d95bad8f7a0cae21354a3364a729a30fcd1c84d8e410595416cd7e887599107b
MD5 21d21b15881cbbaec899cc58521de9e4
BLAKE2b-256 9ab51f6dcea8626431019ca864c5d3d918a3a941b12bd6bd1e303601faaadedc

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3b793a97b6417b049e0d7e70305aba99c431bf457c98ca221bcb8ac7c0ce69f7
MD5 e1a69f163d5d4c977223027cee7232c4
BLAKE2b-256 9ff13cc218225723660fbf7fc8384e3df47630ea159a8ce8c68a2f0e521e4c99

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 24f8e8db2cfa184d43bdea140333e4fb20418aca13b73ae5452a34e7b030ff2e
MD5 411435e39e3c14bb68d702a4f394f3cb
BLAKE2b-256 afb79b5cfc95d302e193d7fa4333de93c2aaa94188ce7ecde0b879431820967c

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b17473e4ccc3a6a47fc7eae0d20d0e2fd0da556d3a8862bfed5231284da79459
MD5 d96eea362851820c6e8623b422ac2af3
BLAKE2b-256 adadad9dfadefd8c0626170125d2df68c63ed2598be2ed25530137acaa0a27cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 bde6cdf02f96a1e5706f8fdbe9573a77532d05dd5883097bb73c5799214d0475
MD5 8bd75111f3aa12dcd7e226186e94b857
BLAKE2b-256 f56417335e74ef08d32c2d51c40ab87a8415de4cdfe7ae0cc35efa511e39bc75

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on yaowan233/osu-beatmap-preview-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.2

6 files

0.1.1

6 files

This release

0.1.0 This release

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page