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 25, 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 25, 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.1.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.1-cp310-abi3-win_amd64.whl (2.8 MB view details)

Uploaded CPython 3.10+Windows x86-64

osu_beatmap_preview_py-0.1.1-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.1-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.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: osu_beatmap_preview_py-0.1.1.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.1.tar.gz
Algorithm Hash digest
SHA256 90f51a40456f2f73b4cd3330887e43158cb721743b776eeff4e62aa29d3f9cfe
MD5 a0a5d2fc9ee93f57aae1431d178dbb94
BLAKE2b-256 29e4aa592ae6837950e0f10b13cdcd263836031b4fb809b3ee28b9d18e728174

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1.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.1-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 02795ad07114a7fa18cfc8e974f4b5bd24eeecac72de52ac44f81d44acabc9ab
MD5 7ad6354e0c0c7a6ae60652cf999e2ee4
BLAKE2b-256 62b5fde26e5c6a2a88a6624a769a07ae0ad00ed1db6930d2101da9c72f7e602d

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1-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.1-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.1-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e5de0e5aacf727a7a41bad683d6ab674673794a950282d755b92f15a08fe07f4
MD5 99943cf00f04b0db0ab805b1e8c51e9c
BLAKE2b-256 0e553e138ed8a26b6da4faaf9d89b4139a74f888d5a1e88febb5a2f71ac45ad8

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1-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.1-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.1-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 bd5dc8e63643a131373eaaa12740fc658cf8a2df1452111f3a4d1f534c8772e9
MD5 00f76663294ba012aa20b5877175d1db
BLAKE2b-256 7b9808c9362a4cf4337b3a8b11a8bb452afcef6301342a10161c239491912484

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1-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.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 76cb7c41188df293cccc7593307dfe19d4627d8a904b48b80dd99faa317f630b
MD5 14b6a7c54689df29a9baef65efc1aa7a
BLAKE2b-256 d852e0e6415954a837491c8b12140cbd57109f2a99b91a556b32b8c9fbecdbf2

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1-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.1-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.1-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 79db651131ffb7726d7ee53741c2b8e030b54e945e82f8f9374ea5cb7dcc9891
MD5 6de315da20cb1c81de0b59baa988045a
BLAKE2b-256 facae2e7b1c1849285191285e075f8e273a5c58471cf03bac099d8fdd14ba929

See more details on using hashes here.

Provenance

The following attestation bundles were made for osu_beatmap_preview_py-0.1.1-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

This release

0.1.1 This release

6 files

0.1.0

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