Metadata-Version: 2.4
Name: osu-beatmap-preview-py
Version: 0.1.10
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
License-File: LICENSE
Summary: Python bindings for the osu-beatmap-preview renderer
Author: osu-beatmap-preview-py contributors
License: MIT
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/yaowan233/osu-beatmap-preview-py
Project-URL: Issues, https://github.com/yaowan233/osu-beatmap-preview-py/issues
Project-URL: Repository, https://github.com/yaowan233/osu-beatmap-preview-py

# osu-beatmap-preview-py

[`osu-beatmap-preview`](https://github.com/2710165659/osu-beatmap-preview) 的
Python 原生扩展。渲染器通过 PyO3 直接运行在 Python 进程内，不需要下载、配置或启动额外的
可执行文件。

> 当前为早期开发版本。0.1.10 使用上游 v1.4.2 的固定提交
> [`121f44a`](https://github.com/2710165659/osu-beatmap-preview/commit/121f44a6fa5b988ce8db58d0a0005d06bb14e89e)。
> core、CLI 和构建资源随仓库分发，确保各平台 wheel 使用相同的渲染行为。
> 本次更新包含太鼓判定圆、完整空心转盘及击打数统计，Catch 自动接盘与 FL 跟随，以及故事板显示修复。

## 安装

```bash
pip install osu-beatmap-preview-py
```

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

## 使用

```python
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 渐隐同时作用于本体、白边和红圈。

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

### 四种模式的 GIF / MP4 模组

| 模式 | 支持的模组 |
| --- | --- |
| Standard | `EZ`、`HR`、`HD`、`FL`、`AT`、`TC`、`DA`、`DT`、`HT`、`NC`、`DC` |
| Taiko | `EZ`、`HR`、`HD`、`FL`、`SW`、`CS`、`DT`、`HT`、`NC`、`DC` |
| Catch | `EZ`、`HR`、`HD`、`FL`、`AT`、`DT`、`HT`、`NC`、`DC` |
| Mania | `HD`、`FL`、`1K`–`10K`、`DS`、`IN`、`HO`、`CS`、`DT`、`HT`、`NC`、`DC` |

组合中的每个模组都必须受当前模式支持；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` 显示自动游玩光标，Catch 的 `AT` 显示自动接盘、Dash 拖尾和香蕉雨路线。
太鼓 PNG 转盘显示总击打数与时长，GIF 和 MP4 显示完整空心转盘、剩余击打数及完成淡出。
四模式 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 增加协作式取消能力。

## 本地开发

```bash
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，版权归其贡献者所有。

