syncsub · 字幕按内嵌时间轴对齐

简体中文 | English

把外挂源字幕对齐到目标视频内嵌字幕轨的时间轴上。

适用场景：你有一份翻译质量好但时间轴对不上的字幕（来自另一个版本的视频），目标视频自带一条时间轴正确的内嵌字幕。本工具用目标视频的内嵌字幕作参考，用 alass 把源字幕对齐过去，输出一份时间轴正确的新字幕。

• macOS：Finder 选中视频 + 字幕 → 右键快捷操作或快捷键 ⌃⌥⌘S
• Windows：把视频 + 字幕拖进窗口（顺序不限）
• 核心判别、对齐、命名逻辑两端共用（Python）
• 界面与提示按系统语言自动切换中英文（可用环境变量 SYNCSUB_LANG=zh|en 强制）

---

工作原理

1. 用 ffprobe 自动判别哪个是视频、哪个是字幕（顺序无关）。
2. 列出视频的内嵌字幕轨；多条时让你选择。
3. 用 ffmpeg 抽出所选内嵌字幕作为参考时间轴。
4. 用 alass 把源字幕对齐到该参考时间轴。
5. 输出到源字幕所在目录，并在文件管理器中定位。

---

第一步：下载本工具

在本页面顶部点击绿色的 「Code」 按钮 → 「Download ZIP」，下载后解压。你会得到一个名为 syncsub-main 的文件夹。

下面 macOS 和 Windows 的安装脚本，都需要在这个解压出来的文件夹里运行。

---

macOS 用户：一步步安装

第 1 步：装 Homebrew（已装过可跳过）

打开「终端」App（在「启动台」或用 Spotlight ⌘空格 搜「终端」），把下面这行粘贴进去回车，按提示操作：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

第 2 步：运行安装脚本

在「终端」里输入 cd （cd 后面有个空格），然后把第一步解压出来的 syncsub-main 文件夹直接拖进终端窗口（会自动填好路径），回车。再粘贴这行回车：

bash scripts/install-macos.sh

脚本会自动装好 ffmpeg、alass 和本工具，并把 Finder 快捷操作装好。看到「安装完成」即可。

第 3 步：设置快捷键

打开 系统设置 → 键盘 → 键盘快捷键 → 服务 → 通用，找到 「字幕按内嵌时间轴对齐」，点右侧设为 ⌃⌥⌘S（Control + Option + Command + S）。

怎么用

在「访达 / Finder」里，同时选中 1 个视频 + 1 个字幕（按住 ⌘ 点第二个），然后：

• 按快捷键 ⌃⌥⌘S，或
• 右键 → 快捷操作 → 「字幕按内嵌时间轴对齐」

完成后，访达会自动跳到生成好的新字幕。

---

Windows 用户：一步步安装

方式 A（推荐，开箱即用）：下载安装包

去本仓库的 Releases 页面下载 syncsub-setup.exe，双击 → 一路下一步 → 完成。

• 不需要装 Python，也不用自己下载任何东西，ffmpeg / alass 都已打包在里面。
• 装完会在「开始菜单」（以及可选的桌面、「发送到」）里出现「字幕按内嵌时间轴对齐」。
• 如果弹出蓝色「Windows 已保护你的电脑」，点「更多信息」→「仍要运行」。

方式 B（脚本安装，体积小）：

1. 装 Python：去 python.org/downloads 装 Python 3.9+，第一屏务必勾选 「Add Python to PATH」。
2. 在仓库点绿色 Code → Download ZIP 解压，打开 syncsub-main 文件夹，双击 install-windows.cmd。它会联网下载 ffmpeg、alass，装好工具并建快捷方式。

怎么用

方式一（推荐）：开始菜单打开 「字幕按内嵌时间轴对齐」，把 1 个视频 + 1 个字幕 拖进窗口（顺序不限），按「开始对齐」。

方式二：在资源管理器里选中视频 + 字幕两个文件 → 右键 → 发送到 → 字幕按内嵌时间轴对齐。

完成后窗口会显示输出路径，点「在文件管理器中显示」即可定位新字幕。

---

进阶：命令行用法（两端通用）

安装后终端里可直接用：

syncsub SOURCE_SUB VIDEO [OUTPUT_SUB]   # 对齐
syncsub --list VIDEO                    # 列出视频里的内嵌字幕轨
syncsub --sub N SOURCE_SUB VIDEO        # 指定用第 N 条内嵌轨

---

输出命名规则

输出名 = 视频名(去扩展名) + "." + 语言标签 + ".synced." + 源字幕扩展名

• 语言标签取源字幕文件名（去扩展名后）最后一个 . 之后的部分。
• 源字幕没有语言标签时，回退为 视频名.synced.扩展名。

示例：

	文件名
源字幕	The Bear S05E01 ...-FLUX.chs.简体&英文.ass
目标视频	The.Bear.S05E01.Soda.2160p...H.265-NTb.mkv
输出	The.Bear.S05E01.Soda.2160p...H.265-NTb.简体&英文.synced.ass

---

支持格式

字幕：.srt .ass .ssa .sub .idx　　视频：任何含视频流的容器（.mkv / .mp4 等）。

源字幕 .srt 和 .ass 都支持，输出保持源字幕的原格式和扩展名。

关于参考时间轴：从视频里抽出来当参考的那条内嵌字幕轨，必须是文本字幕（srt / ass 这类）。如果视频内嵌的是图形字幕（PGS、VobSub），无法抽成文本参考，抽取会失败并提示换一条轨——这与你的源字幕是 ass 还是 srt 无关。

---

常见问题

• 视频没有内嵌字幕轨 → 工具会提示；本工具依赖内嵌轨作参考，无内嵌轨无法使用。
• 抽轨失败 → 换一条字幕轨重试（某些图形字幕如 PGS 无法抽成文本参考）。
• 同步失败 → 会显示 alass 日志末 30 行，便于排查。

---

License

GPL-3.0-or-later。本项目调用并可分发 ffmpeg、alass，二者许可见各自项目。