baxtree/subaligner

什么是 Subaligner？

Subaligner 是一个开源的 Python 工具，用于将字幕文件与对应的视频或音频轨道进行同步。它可使用现代机器学习模型（如 OpenAI Whisper、HuggingFace Transformers）和经典音频处理库，实现 对齐 现有字幕、生成 新字幕（通过转录媒体内容），甚至 翻译 字幕。

---

核心功能

功能	工作原理（如 README 所述）	典型命令示例
单阶段对齐	快速全局偏移估计（低延迟）。	subaligner -m single -v video.mp4 -s subtitle.srt
双阶段对齐	两步流程：先进行全局偏移，再对每个字幕段进行精细调整（高延迟，高精度）。	subaligner -m dual -v video.mp4 -s subtitle.srt
转录	调用 Whisper（或其他基于 LLM 的语音转文本模型）从音频生成字幕。	subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle.srt
翻译	在转录后（或对现有字幕）使用 Helsinki‑NLP、Facebook‑MBart 或 M2M100 等模型进行翻译。	subaligner -m dual -v video.mp4 -s subtitle.srt -t eng,spa -tr helsinki-nlp
手动偏移	以秒为单位简单添加或减去偏移量。	subaligner -m shift --subtitle_path subtitle.srt -os 5.5
批量处理	对目录树中的多个视频/字幕进行对齐。	subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/
自定义模型训练	使用自己的视频-字幕对训练新的对齐模型。	subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY

---

安装概览

1. 系统依赖 – 必须安装 FFmpeg（apt-get install ffmpeg 或 brew install ffmpeg）。
2. Python 包 – pip install subaligner（推荐在虚拟环境中安装）。
3. 可选扩展：
   • subaligner[llm] – 包含 Whisper 和翻译模型。
   • subaligner[stretch] – 添加强制对齐工具（需要 eSpeak）。
   • subaligner[dev] / subaligner[harmony] – 开发和完整功能集。
4. Docker – 使用预构建镜像（docker pull baxtree/subaligner）可在无本地安装的情况下运行 CLI。

---

快速入门示例

# 将现有英文 SRT 与本地 MP4 文件对齐（双阶段以获得最佳精度）
subaligner -m dual -v video.mp4 -s subtitle.srt -o subtitle_aligned.srt

该命令读取视频，提取音频特征，预测全局偏移，然后优化每行字幕。结果写入 subtitle_aligned.srt。

---

工作原理（高层架构）

1. 特征提取 – 使用 librosa 和 TensorFlow 基础模型处理音频，获取嵌入向量。
2. 全局对齐 – 训练好的神经网络模型预测整个文件的单一时间偏移。
3. 并行分段对齐 – 将视频分割为短片段，每个片段独立对齐，实现细粒度修正。
4. 可选转录 – 选择 -m transcribe 时，Whisper（或其他 LLM）将语音转换为文本。
5. 可选翻译 – HuggingFace Transformers 模型翻译转录文本或原始字幕。

---

何时使用哪种模式

情况	推荐模式
需要 快速修复，字幕仅轻微不同步	single（全局偏移）
精确时间至关重要（如配音或字幕制作）	dual（全局 + 分段）
无字幕 – 需要 新转录	transcribe（通过 -mf 选择 Whisper 模型大小）
有某语言的转录文本，需要 翻译	dual/single + -t src,tgt + -tr <model>
需要自动处理 多个文件	subaligner_batch

---

可扩展性

• 自定义模型 – 使用 subaligner_train 在自己的数据上训练模型，然后在 CLI 中指向新模型。
• 提示工程 – -ip 标志可为 Whisper 添加全局提示，--use_prior_prompting 可将前一行字幕作为下一行的上下文。
• 词级时间戳 – 添加 --word_time_codes 可获得 JSON 输出，其中每个词都有独立的开始/结束时间，适用于下游编辑工具。

---

社区与支持

• 文档 – https://subaligner.readthedocs.io（从仓库自动生成）。
• CI / 测试覆盖率 – GitHub Actions 标记显示持续集成；Codecov 标记显示测试覆盖率。
• 引用 – 提供 Zenodo DOI 供学术使用。
• 贡献 – 使用 dev 扩展安装可获得测试和 lint 工具。

---

TL;DR

Subaligner 是一个基于 Python 的 CLI（及 Docker 镜像），结合经典音频处理、TensorFlow 模型以及大语言模型的语音识别/翻译后端，实现字幕对齐、生成与翻译。支持几乎所有字幕或媒体格式，提供快速全局对齐和高精度双阶段对齐，并可通过训练自定义模型进行扩展。