py-roller

把英文 plain lyrics 对齐到歌曲，输出 LRC。歌词文本应包含可能出现的完整行，但不必按实际演唱顺序排列，也不必写全重复次数。

0.10.2：Whisper large-v3 发现歌词实例，CTC 细化时间；提供面向 Rolling Pebble 的 Protocol v2。0.10 系列重写不兼容 0.9 CLI、配置或协议。

从 0.10.0 升级后先运行 py-roller models migrate，将已有模型导入统一目录，避免重新下载。当前默认采用完整有序歌词对齐；需要原来的自由匹配行为时显式指定 --alignment-mode unordered。

安装

需要 Python 3.10–3.12、FFmpeg。源码安装还需要 C++17 编译器；macOS 可使用 Xcode Command Line Tools，Windows 使用 MSVC C++ Build Tools。神经依赖的实际可用平台以对应 PyTorch/CTranslate2 版本为准。

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'
py-roller models download
py-roller doctor

可选人声分离：python -m pip install -e '.[vocals]'。核心模型需数 GiB 磁盘空间，安装 Python 包不包含模型。源码发布准备完成不等于 PyPI 已发布。

对齐一首歌

py-roller align song.flac lyrics.txt -o output/song
py-roller align song.flac lyrics.txt -o output/song-vocals --audio-mode vocals
py-roller align song.flac complete-lyrics.txt -o output/song-ordered --alignment-mode ordered
# 同样支持
python -m pyroller align song.flac lyrics.txt -o output/song

lyrics.txt 为 UTF-8 无时间戳歌词，一行一句；忽略 [Chorus] 等段落标题。输出目录必须不存在，防止覆盖已有结果。失败后用新的输出目录重试，已完成的模型窗口会复用缓存。

默认使用原声。Demucs 可能把机器人声或特殊唱法当作伴奏移除，应由调用者明确选择。当前仅支持英文、行级 LRC，不承诺精确逐词卡拉 OK 时间。

默认 ordered 模式要求输入完整且顺序、重复次数准确，保留每次输入行并按顺序定位。unordered 模式将输入当作歌词集合，允许重排和重复。可用 PYROLLER_ALIGNMENT_MODE=unordered 切回自由匹配，显式 --alignment-mode 优先。未能定位的输入行保存在 alignment.json 的 unaligned_lines 中，不生成虚假的 LRC 时间。

输出

文件	用途
`result.lrc`	最终歌词起点
`alignment.json`	稳定 Protocol v2 结果，供应用接入
`events.jsonl`	进度、完整预览快照和终态
`preview.lrc`	最近一次中间预览，可能不存在
`coarse.lrc`	CTC 修正前的粗时间
`result.json`	内部候选与声学诊断，不属于稳定接口
`run.json`	配置、模型/音频身份、缓存路径、耗时及状态

final 只表示计算完成；所有行仍需人工确认。end 用于展示，不是精确的人声结束点。

Rolling Pebble / Python 接入

python -m pyroller run --request request.json

标准输出为纯 JSONL，日志写标准错误。应用应按 request_id 和 sequence 接收事件，每次 snapshot 替换整份歌词列表，在 completed 后读取 alignment.json 或 LRC。

from pyroller.engine import EngineConfig, align

result = align("song.flac", "lyrics.txt", "output/song",
               EngineConfig(offline=True), request_id="job-001")
for line in result["lines"]:
    print(line["start"], line["text"])

文档

开发验证

python -m pytest
python -m pip install -e '.[release]'
python -m build
python scripts/check_release.py dist
python -m twine check dist/*

运行时代码位于 pyroller/，测试位于 tests/，离线研究工具位于 research/。歌曲、模型和历史缓存不进入发布包。模型依次加载以控制内存；第一份预览需等待完整 CTC 处理和第一个 Whisper 窗口，这不是实时麦克风识别服务。

Metadata

Release files for py-roller 0.10.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-roller 0.10.2
File	Size	Uploaded
py_roller-0.10.2.tar.gz	97.9 kB	Oct 16, 2026	Details

Release files / py_roller-0.10.2.tar.gz

Download URL	py_roller-0.10.2.tar.gz
Size	97.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`c638e03c140c12f1d813c5d3bd35208553978786f93a4bd4d5ab3ba2f5effdc9`
BLAKE2b-256 checksum How to use checksums	`a5921a41112ede50c2085e67052eb3a29d0fdcba6ef2b4a08b6f885aef9a1d30`
Upload date	Oct 16, 2026
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.