sub-align 文档
2026-08-09  / project  / sub-align #docs

该页面由AI翻译并经过人工校对，你可能想要 查看原文

Sub-align

GitHub

用 WhisperX 强制对齐，将 .srt / .lrc / .txt 字幕（或直接生成字幕）对齐到音视频——每条 cue 可独立调整时间，而不只是整条时间轴做一次全局偏移。

为什么不只做全局偏移？

像 ffsubsync 这类工具通常在语音活动与字幕「出现」时刻之间找一个恒定偏移（或拉伸）。对整轨漂移效果不错，但开头/结尾静音或局部时间误差仍可能让某些行偏早或偏晚。

sub-align 会按输入类型选择策略，再跑 WhisperX 音素 / 词级强制对齐，让每一行对照音频精修：

输入 策略
仅媒体 Whisper ASR → 词级对齐 → 切成带时间的 cue
.txt 剧本 ASR 只用于搜索窗口 → 对原文行强制对齐
.srt / .lrc 可选全局偏移 → 用 --margin 扩大窗口 → 强制对齐

局限： 字幕文本须大致与口述内容一致。对齐不会翻译，也不会改正错误用词。

更多细节：docs/pipeline.md · 场景与参数：docs/usage.md

安装

需要 **Python 3.10+**，且 ffmpeg 在 PATH 中。首次运行会下载 WhisperX 对齐模型（占用磁盘 / 内存）。

1
2
3
pip install 'sub-align[align]'
# or
uv pip install 'sub-align[align]'

Extras [align]、[cpu]、[gpu] 都会安装 WhisperX。若需要特定 CPU/CUDA wheel，请先安装匹配的 PyTorch：

1
2
3
4
5
6
7
# CPU
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install 'sub-align[cpu]'

# CUDA (example: cu124)
uv pip install torch --index-url https://download.pytorch.org/whl/cu124
uv pip install 'sub-align[gpu]'

开发

1
2
3
4
5
uv venv
uv sync --group dev                 # unit tests / lint (no WhisperX)
uv sync --group dev --extra align   # full local alignment
uv run pytest
uv run ruff check src tests

用法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Timed subtitles: auto global offset + per-cue refine
sub-align media.mp4 subs.srt --language zh -o out.srt

# Lyrics (LRC): same strategy as SRT
sub-align audio.wav lyrics.lrc --language en --margin 1.0

# Untimed script: ASR windows, then force-align original lines
sub-align media.mkv script.txt --language en --model small

# Skip podcast intro/outro before aligning a script
sub-align media.mp3 script.txt --language en --trim-start 13 --trim-end 5

# Known whole-track shift (skips auto-offset ASR)
sub-align media.mkv subs.srt --language en --offset 12.5

# Audio only: transcribe + word-align into an SRT
sub-align lecture.mp4 --language en -o lecture.asr.srt

务必传入 --language（如 en、zh）或 --detect-language。

--model、--margin、--offset、--fill-gaps、--trim-*、仅音频时的行数限制，以及 Whisper 模型体积 / VRAM 速查，见 docs/usage.md。

Python API

1
2
3
4
5
6
7
8
9
from sub_align import align_file

align_file(
    media="a.mp4",
    subtitle="a.srt",   # omit for audio-only transcription
    output="a.aligned.srt",
    language="zh",
    device="auto",
)

工作原理（简述）

  1. 将媒体加载为 16 kHz 单声道音频（经 WhisperX / ffmpeg）；可选 --trim-start / --trim-end。
  2. 解析语言（--language 或 tiny 模型检测）。
  3. 按输入类型构建搜索窗口（.txt 用 ASR token 匹配；.srt/.lrc 用偏移 + margin 精修；仅媒体则完整 ASR）。
  4. 运行 WhisperX 强制对齐；将词时间映射回原文 cue；裁剪重叠；可选 --fill-gaps；写出 .srt 或 .lrc。

完整流程图与技术说明：docs/pipeline.md。

License

MIT

上一页
2026-08-09  / project  / sub-align #docs
下一页