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:
Latest release

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.2.tar.gz (27.9 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.2-cp310-abi3-win_amd64.whl (2.8 MB view details)

Uploaded CPython 3.10+Windows x86-64

osu_beatmap_preview_py-0.1.2-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.2-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.2-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.2-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.2.tar.gz.

File metadata

  • Download URL: osu_beatmap_preview_py-0.1.2.tar.gz
  • Upload date:
  • Size: 27.9 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.2.tar.gz
Algorithm Hash digest
SHA256 e1d2db3fe1419f6b9e22d88c7578cf1189a074c1dc59c7c57258803f6a6d8314
MD5 cde26b22b06513eb4210640ce54d77c5
BLAKE2b-256 37d8240e6a499a1dcce59813688a165789db8e3c4ab272f587769b2d7c47a0ce

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1343aa850f1bc62ef7cb605379af31c4ccac8c9fd4fe6b750f34034716979c61
MD5 1837483b7ff6c7e098a1060d1307a088
BLAKE2b-256 37763602c4ab1422941f80d7d44c0ef3e65253eb9d2b6d57c70afea98334d2a4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.2-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6f81f7f242547047f65e4fea72cc901ce5d849a05b2411615d979e7c661f12c8
MD5 41e10c923e7e06861bb4ef5ade3af6f5
BLAKE2b-256 82be1f17ac6c13b41a8718fa32275f2c9f4e9e3d8f74286c85e2471325206bbd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.2-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 f8ee55b021b70a0386ca4c29a9be6add19aae17f13ab6f22ab84890bddef3bb4
MD5 ce7e1194c404674d4257d64ff2a16e6d
BLAKE2b-256 c5831fb40a9ca85fa7da304217df0419977146d8370d977d1b7f78e15fe0a946

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 cfe60c1f1d3a3d322989f323fc34ced103a1f168fb44bf767e6437612dbd39cf
MD5 799285fc14885052cee90635c429c488
BLAKE2b-256 af361c52811ee1624abc1fbab94dede47f89352dd7e71ab7ccfa00a8a897f34e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for osu_beatmap_preview_py-0.1.2-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3a5096783e26cf95b1bc3f08e9d15d9cb08ad73565574e62f72839b6141dc7a1
MD5 75eb7e3989a2fae3b226d2a6ee7d2baf
BLAKE2b-256 342c670c9e978b6b69c1c4b5c17d81a653f4f7b5d503050b088362e14ee2bd27

See more details on using hashes here.

Provenance

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

This release

0.1.2 This release

6 files

0.1.1

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