koagaroon/ssaHdrify-tauri
GitHub: koagaroon/ssaHdrify-tauri
一款基于Tauri和Rust的跨平台字幕处理工具，专注于解决HDR视频播放时字幕色彩失真问题，提供色彩转换、时间调整、字体嵌入及批量重命名功能。
Stars: 13 | Forks: 0
# SSA HDRify
[](LICENSE) [](https://github.com/koagaroon/ssaHdrify-tauri/releases) 
### 浅色主题（中文）/ Light Theme (Chinese)
| HDR 转换 / HDR Convert | 时间轴偏移 / Time Shift |
| :----------------------------------------------------------------: | :-----------------------------------------------------------------: |
| 
| 
|
| 字体嵌入 / Font Embed | 批量重命名 / Batch Rename |
| :---------------------------------------------------------------: | :-----------------------------------------------------------------: |
| 
| 
|
### 深色主题（英文）/ Dark Theme (English)
| HDR 转换 / HDR Convert | 时间轴偏移 / Time Shift |
| :---------------------------------------------------------------: | :----------------------------------------------------------------: |
| 
| 
|
| 字体嵌入 / Font Embed | 批量重命名 / Batch Rename |
| :--------------------------------------------------------------: | :----------------------------------------------------------------: |
| 
| 
|
## 目录 | Contents
- [下载 | Download](#下载--download)
- [功能 | Features](#功能--features)
- [使用方法 | Usage](#使用方法--usage)
- [CLI 使用 | CLI Usage](#cli-使用--cli-usage)
- [使用场景 | Background](#使用场景--background)
- [HDR 转换原理 | How HDR Conversion Works](#hdr-转换原理--how-hdr-conversion-works)
- [从源码构建 | Build from Source](#从源码构建--build-from-source)
- [架构 | Architecture](#架构--architecture)
- [致谢 | Credits](#致谢--credits)
- [许可证 | License](#许可证--license)
## 下载 | Download
从 [Releases](https://github.com/koagaroon/ssaHdrify-tauri/releases/latest) 页面下载最新 exe 文件：
- **`ssahdrify_*.exe`** — 图形界面（GUI），适合手动操作
- **`ssahdrify-cli_*.exe`** — 命令行（CLI），适合 pipeline / 批处理 / 脚本化场景
macOS / Linux 用户请参考下方「从源码构建」。
从 [Releases](https://github.com/koagaroon/ssaHdrify-tauri/releases/latest) 页面下载最新 exe 文件：
- **`ssahdrify_*.exe`** — 图形界面（GUI），适合手动操作
- **`ssahdrify-cli_*.exe`** — 命令行（CLI），适用于 pipeline / 批处理 / 脚本化场景
macOS / Linux 用户，请参阅下方的「从源码构建」。
## 功能 | Features
| 标签页 / Tab | 功能 / Function |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HDR 色彩转换 / HDR Color Conversion** | 为字幕附加对应的 BT.2100 PQ 或 HLG 色彩空间数据 / 为字幕附加匹配的 BT.2100 PQ 或 HLG 色彩空间数据 |
| **时间轴偏移 / Timing Shift** | 批量偏移字幕时间戳；可指定时间点后才开始偏移，并支持实时预览 / 批量偏移字幕时间戳；偏移可从选定的时间戳开始，并支持实时预览 |
| **字体嵌入 / Font Embedding** | 自动检测字幕用到的字体，与系统字体库或本地字体源匹配，并以子集化形式嵌入 ASS 文件 / 自动检测字幕中引用的字体，与系统字体库或本地字体源进行匹配，并以子集化形式嵌入 ASS 文件 |
| **批量重命名 / Batch Rename** | 自动匹配视频文件和字幕文件，按视频文件名重命名字幕；同一视频文件有多个对应字幕时，用户可自由选择字幕文件，手动调整配对 / 自动匹配视频文件和字幕文件，并按视频文件名重命名副本；当视频有多个候选字幕时，用户可以手动选择并调整配对 |
## 使用方法 | Usage
### HDR 色彩转换 / HDR Color Conversion
1. 选择 EOTF 曲线（PQ 或 HLG）/ 选择 EOTF 曲线（PQ 或 HLG）
2. 设置字幕目标亮度（默认 203 nits）/ 设置字幕目标亮度（默认：203 nits）
3. 选择字幕文件（支持多选）/ 选择字幕文件（支持多选）
4. 点击转换 / 点击转换
5. 默认输出文件扩展名为 `.hdr.ass`（可修改）/ 默认输出扩展名为 `.hdr.ass`（可自定义）
### 时间轴偏移 / Timing Shift
1. 选择字幕文件 / 选择字幕文件
2. 输入偏移量（毫秒），选择方向：「提前」或「延后」/ 输入偏移量（毫秒），然后选择方向：更快 或 更慢
3. 可选：启用阈值过滤，仅偏移特定时间点后的字幕 / 可选：启用阈值，仅偏移特定时间戳之后的字幕
4. 实时预览调整效果 / 实时预览调整效果
5. 导出 / 导出
### 字体嵌入 / Font Embedding
1. 点击「选择字幕文件 / Select Subtitle File」选择 ASS 字幕文件 / 点击 **选择字幕文件** 选择一个 ASS 文件
2. 工具自动检测字幕用到的字体，先尝试从系统字体库匹配 / 工具自动检测字幕中引用的字体，并首先尝试与系统字体库匹配
3. 主面板实时显示本地来源覆盖（覆盖 N / M）和尚未匹配的字体；每条字体标注来源（本地 / 系统）和匹配状态（已找到 / 缺失）/ 主面板实时显示本地源覆盖率（覆盖：N / M）并列出仍缺失的字体；每个检测到的字体都标注其来源（本地 / 系统）和状态（已找到 / 缺失）
4. 点击「嵌入已选字体」，字体数据（子集化后）写入 ASS 文件 / 点击 **嵌入选定字体**，将子集化后的字体数据写入 ASS 文件
字幕组排版常用的字体大多未安装在系统中。点击「字体来源 / Font Sources」即可打开本地来源管理面板，添加你想扫描的文件夹，无需安装到系统即可参与匹配。
在字幕组排版中常用的字体大多未安装在系统中。点击 **字体来源** 打开本地源管理器，然后添加您想扫描的文件夹——无需系统级安装。
文件夹大小不限，扫描过程会实时显示已读取的字体数量并支持随时取消；选择包含超过 5000 个文件或体积超过 1 GB 的目录前，会弹出确认对话框。
任何大小的文件夹均可接受；扫描过程实时显示找到的字体数量，并可随时取消。在选择一个异常大的目录（5000+ 个文件或 > 1 GB）之前，会弹出确认对话框。
### 批量重命名 / Batch Rename
1. 拖入一个包含视频和字幕的文件夹（或点击「选择文件 / Select Files」手动选择）；程序将按照文件格式自动归类 / 拖入一个包含视频和字幕的文件夹（或点击 **选择文件** 手动选择）；应用程序会按格式自动分类文件
2. 系统按字幕组命名习惯做剧集号正则配对，预填配对表 / 应用程序使用字幕组剧集正则表达式预先配对，并填充配对表
3. 若应用错配或漏配，从该行下拉框直接手动选取字幕，选中后自动勾选进入重命名队列 / 如果应用程序配对错误或遗漏，通过该行的下拉菜单更换字幕；选择后该行会自动勾选进入重命名队列
4. 选择输出策略：原文件直接改名 / 复制到当前目录 / 复制到自定义目录 / 选择输出策略：就地重命名、复制到视频所在目录，或复制到自定义目录
5. 点击运行；若目标路径已存在采用相同规则重命名的同名文件，会弹出确认覆盖对话框 / 点击运行；如果目标路径已存在由重命名规则生成的同名文件，会先弹出覆盖确认对话框
## CLI 使用 | CLI Usage
`ssahdrify-cli` 是 GUI 的命令行（CLI）版本，从同一份源代码构建。四个核心功能（HDR 转换 / 时间轴偏移 / 字体嵌入 / 批量重命名）与 GUI 版对等；CLI 额外提供 `chain`（一次调用串联多步、仅终端步落盘）和 `refresh-fonts`（持久化字体缓存）两个子命令。
`ssahdrify-cli` 是 GUI 的命令行（CLI）版本，基于相同源代码构建。四个核心功能（HDR 转换 / 时间轴偏移 / 字体嵌入 / 批量重命名）与 GUI 版匹配；CLI 还额外暴露了 `chain`（一次调用串联多步，仅最后一步写入磁盘）和 `refresh-fonts`（持久化字体缓存）——这两个命令目前仅 CLI 可用。
### 快速示例 | Quick Examples
```
# HDR 色彩转换（PQ 曲线）/ HDR conversion (PQ curve)
ssahdrify-cli hdr --eotf pq input.ass
# 时间轴偏移 +500ms / Timing shift +500ms
ssahdrify-cli shift --offset +500ms input.ass
# 字体嵌入：从指定文件夹搜索字体 / Font embed: search a folder for fonts
ssahdrify-cli embed --font-dir "C:/Fonts" input.ass
# 持久化字体缓存：先一次性扫描，后续 embed 复用 / Persistent font cache: scan once, reuse on every embed
ssahdrify-cli refresh-fonts --font-dir "C:/Fonts"
ssahdrify-cli embed input.ass # uses cache automatically
# 链式调用：HDR 转 + 时间轴偏移单次完成，仅终端步落盘 / Chain: HDR + shift in one shot, only terminal step writes
ssahdrify-cli chain hdr --eotf pq + shift --offset +500ms input.ass
# 批量重命名：默认复制到视频所在目录 / Batch rename (default: copy sub next to video)
ssahdrify-cli rename "C:/My Series"
```
### 全部子命令 | All Subcommands
每个子命令都支持 `--help` 查看完整参数。
每个子命令都支持 `--help` 查看完整的参数参考。
```
ssahdrify-cli --help
ssahdrify-cli hdr --help
ssahdrify-cli shift --help
ssahdrify-cli embed --help
ssahdrify-cli rename --help
ssahdrify-cli refresh-fonts --help
ssahdrify-cli chain --help
```
### 全局选项 | Global Options
| 选项 / Option | 说明 / Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--lang ` | 输出语言；不指定时按系统区域设置自动检测（zh* → zh，否则 en）/ 输出语言；省略时根据操作系统区域设置自动检测（zh* → zh，否则 en） |
| `--json` | 输出机器可读 JSON 报告 / 输出机器可读的 JSON 报告 |
| `--verbose` | 显示更多进度细节 / 显示更多进度细节 |
| `--quiet` | 抑制常规进度输出 / 抑制常规进度输出 |
| `--dry-run` | 预演计划工作但不写文件 / 预览计划执行的工作，但不写入文件 |
| `--overwrite` | 允许覆盖已存在的输出文件 / 替换现有输出文件，而不是跳过 |
| `--output-dir ` | 重定向输出到指定目录 / 将输出重定向到特定目录 |
| `--no-cache` | 跳过本次运行的字体缓存；缓存文件保持不变 / 本次运行跳过字体缓存；缓存文件保持不变 |
| `--cache-file ` | 覆盖默认的缓存文件路径 / 覆盖默认的缓存文件路径（操作系统默认：参见下方缓存位置） |
| `--fail-fast` | 任一文件失败即中止后续输入；已成功写出的文件保留；失败文件可能留下部分写入产物 / 第一个文件失败时即中止批处理；先前成功的输出保留，但失败的输入本身可能在其目标位置留下部分写入的产物 |
### 字体缓存 | Font Cache
`embed` 子命令每次启动都需要扫描 `--font-dir` 里的所有字体文件来构建查表（通常几秒到几十秒，5000+ 字体级别可达分钟级）。**持久化字体缓存**让你只扫描一次：第一次跑 `refresh-fonts` 把元数据写到磁盘上的 SQLite 文件，之后所有 `embed` 调用都自动用这份缓存做查表，跳过扫描。fan-sub 团队按集打包时尤其有用。
`embed` 子命令通常在每次调用时重新扫描每个 `--font-dir` 以构建其查找表（几秒到几十秒；5000+ 字体集合可能需要几分钟）。**持久化字体缓存**让您只需扫描一次：首次运行 `refresh-fonts` 将元数据写入磁盘上的 SQLite 文件，之后所有 `embed` 调用都重用此缓存。对于分批编码剧集的字幕组团队尤其有用。
#### 工作流 | Workflow
```
# 一次性扫描字体目录，构建缓存 / Scan once to build the cache
ssahdrify-cli refresh-fonts --font-dir "C:/Fonts/Anime" --font-dir "C:/Fonts/Latin"
# 后续 embed 自动用缓存（不再扫描） / Subsequent embed uses cache (no scan)
ssahdrify-cli embed input.ass
# 仍可加 --font-dir 临时混入额外字体源（cache + 额外目录合并） /
# 您仍可通过传递 --font-dir 来将额外目录与缓存合并
ssahdrify-cli embed --font-dir "C:/Fonts/Project-Specific" input.ass
# 强制不用缓存 / Force no-cache for one run
ssahdrify-cli --no-cache embed --font-dir "C:/Fonts" input.ass
# 字体目录变了之后刷新缓存 / Refresh cache when fonts changed
ssahdrify-cli refresh-fonts --font-dir "C:/Fonts/Anime" --font-dir "C:/Fonts/Latin"
```
#### 缓存位置 | Cache Location
默认按操作系统选择（与 GUI 缓存独立，避免锁竞争）：
- Windows: `%APPDATA%/ssaHdrify/cli_font_cache.sqlite3`
- macOS: `$HOME/Library/Application Support/ssaHdrify/cli_font_cache.sqlite3`
- Linux: `${XDG_DATA_HOME:-$HOME/.local/share}/ssaHdrify/cli_font_cache.sqlite3`
`--cache-file ` 可覆盖。
操作系统特定默认值（与 GUI 缓存分开以避免锁竞争）：
- Windows: `%APPDATA%/ssaHdrify/cli_font_cache.sqlite3`
- macOS: `$HOME/Library/Application Support/ssaHdrify/cli_font_cache.sqlite3`
- Linux: `${XDG_DATA_HOME:-$HOME/.local/share}/ssaHdrify/cli_font_cache.sqlite3`
使用 `--cache-file ` 进行覆盖。
#### 漂移检测 | Drift Detection
`embed` 启动时会对缓存做轻量验证：用 `stat()` 检查每个已缓存文件夹的 mtime，如果跟缓存里记录的不一致（说明你添加 / 删除 / 替换 / 重命名了字体文件），CLI 在 stderr 列出哪些文件夹改了，自动 fallback 到无缓存模式（这次 embed 走 `--font-dir` 或系统字体），并提示你跑 `refresh-fonts` 更新。**永远不会自动重建缓存**——缓存动作必须由 `refresh-fonts` 显式触发。
`embed` 在启动时运行轻量级的缓存验证：对每个缓存的文件夹执行一次 `stat()` 检查 mtime 是否发生漂移。如果检测到漂移（您添加了 / 删除了 / 替换了 / 重命名了字体文件），CLI 会在 stderr 列出已更改的文件夹，透明地回退到无缓存模式运行（本次运行使用 `--font-dir` 或系统字体），并告知您运行 `refresh-fonts`。**缓存永远不会被静默重建**——缓存的修改始终通过 `refresh-fonts` 显式进行。
#### 限制 | Limitations
- 每个 `--font-dir` 一层深扫描（不递归），与 `embed --font-dir` 语义一致。树状字体目录请逐层显式传入。
- 每个 binary（GUI / CLI）使用各自独立的缓存文件，避免 SQLite 锁竞争；同一 binary 同时只读写一个缓存文件（默认路径或 `--cache-file` 覆盖路径）。`chain` 当前不调用缓存（embed 步永远走显式 `--font-dir` 或系统字体），未来扩展。
- Schema 升级（不同 release 之间）不自动 migrate；版本不匹配时 CLI 显式提示删文件重跑 `refresh-fonts`。
- 每个 `--font-dir` 按一层深度扫描（非递归），与 `embed --font-dir` 语义一致。对于树状字体目录，请显式传入每个叶文件夹。
- 每个二进制文件（GUI / CLI 使用独立路径以避免 SQLite 锁竞争）；单个二进制文件一次只打开一个缓存（默认路径或 `--cache-file` 覆盖路径）。`chain` 在 v1 中不查询缓存（其 embed 步骤总是使用显式的 `--font-dir` 或系统字体）；未来版本会扩展。
- 跨发布版本没有自动的 schema 迁移——版本不匹配会以显式的 "删除缓存文件并重新运行 `refresh-fonts`" 提示形式出现。
## 使用场景 | Background
SSA/ASS 字幕本身不含色彩空间元数据，因此渲染器会按 SDR 模式处理，使字幕看起来过饱和、过亮。播放 HDR 视频时，显示设备会进入 HDR 模式，但字幕却仍以 SDR 方式呈现，色差问题由此产生。
SSA/ASS 字幕本身不包含色彩空间元数据，因此渲染器会将其作为 SDR 内容处理——使其看起来过饱和和过亮。播放 HDR 视频时，显示器进入 HDR 模式，但字幕仍以 SDR 方式渲染，从而导致明显的色彩不匹配。
_相关讨论 / 相关讨论: [libass/libass#297](https://github.com/libass/libass/issues/297)_
相关工具 / 相关工具: 视频与字幕的重命名工作流的另一个选项是 [arition/SubRenamer](https://github.com/arition/SubRenamer)（按字母序+下标配对）。本项目的批量重命名（Tab 4）走基于字幕组命名习惯的正则配对路径，独立实现。
对于字幕和视频的重命名工作流，[arition/SubRenamer](https://github.com/arition/SubRenamer) 是另一个选项（按字母索引配对）。本项目的批量重命名（选项卡 4）使用了独立实现的、基于字幕组命名习惯的正则表达式配对方法。
## HDR 转换原理 | How HDR Conversion Works
```
SSA/ASS 字幕颜色 (sRGB)
├─ 1. sRGB → rec2100-linear（Color.js 色彩空间转换）
├─ 2. 亮度缩放：Y × (targetBrightness / 203)
├─ 3. rec2100-linear → rec2100pq 或 rec2100hlg
└─ 4. 输出 RGB
```
```
SSA/ASS subtitle colors (sRGB)
├─ 1. sRGB → rec2100-linear (Color.js color space conversion)
├─ 2. Luminance scaling: Y × (targetBrightness / 203)
├─ 3. rec2100-linear → rec2100pq or rec2100hlg
└─ 4. Output RGB
```
### 精度说明 | Accuracy Note
PQ 模式经过验证，与 Python 原版（colour-science）逐像素一致。HLG 模式使用手动实现的 BT.2100 逆 OOTF + OETF（绕过 Color.js 的 rec2100hlg 空间），同样与 Python 原版完全匹配。
PQ 模式经验证与 Python 版本（colour-science）逐像素一致。HLG 模式使用手动实现的 BT.2100 逆 OOTF + OETF（绕过 Color.js 的 rec2100hlg 空间），同样与 Python 版本完全匹配。
由于字幕混合链路与 HDR 显示环境的复杂性（HDMI 元数据协商、显示器色调映射等），实际效果仅能做到"红是红的，蓝是蓝的"，不适用于严格颜色准确性场景。
由于字幕混合管道和 HDR 显示环境（HDMI 元数据协商、显示器色调映射等）的复杂性，实际结果只能确保 "红是红，蓝是蓝" 的正确性水平——不适用于严格的颜色准确性要求。
## 从源码构建 | Build from Source
### 前置条件 | Prerequisites
- [Node.js](https://nodejs.org/) (v20+)
- [Rust 工具链 / Rust 工具链](https://rustup.rs/) (1.77.2+)
- Windows: WebView2 (Windows 10/11 已预装 / 预装于 Windows 10/11)
- macOS / Linux: 参考 / 参阅 [Tauri 前置条件](https://v2.tauri.app/start/prerequisites/)
### 开发 | Development
```
cd ssaHdrify-tauri
npm install
npm run tauri dev
```
### 构建 | Production Build
```
npm run tauri build
```
便携式 exe 产出于 `src-tauri/target/release/ssahdrify.exe`，可直接运行——无需安装步骤。
便携式 exe 生成于 `src-tauri/target/release/ssahdrify.exe` —— 可直接运行，无需安装步骤。
### 测试 | Testing
```
npm run test:run # 前端单元测试 / Frontend unit tests
cargo test --manifest-path src-tauri/Cargo.toml # Rust 后端测试 / Rust backend tests
```
## 架构 | Architecture
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Shared TypeScript engine │
│ - 4 features: HDR Convert, Time Shift, Font Embed, Batch Rename │
│ - Color.js (PQ/HLG color math), ass-compiler (font collection) │
│ - Custom subtitle parser, fan-sub regex pairing engine │
└──────────────┬───────────────────────────────────────┬───────────────────────┘
│ │
imported as React modules bundled via esbuild (IIFE)
│ │
┌──────────────┴───────────────┐ ┌─────────────────────┴───────────────────────┐
│ GUI binary │ │ CLI binary │
│ ssahdrify.exe ~10 MB │ │ ssahdrify-cli.exe ~37-58 MB │
│ │ │ │
│ Tauri 2 + React + │ │ clap (argv parsing) │
│ Tailwind frontend │ │ deno_core / V8 (embedded engine.js) │
│ - 4 tabs │ │ - 4 subcommands │
│ - i18n (zh/en), │ │ - --json mode for pipelines │
│ dark/light/auto theme │ │ - env_logger (stderr warnings) │
│ - FontSourceModal UI │ │ - sys-locale (--lang auto) │
└──────────────┬───────────────┘ └─────────────────────┬───────────────────────┘
│ │
Tauri IPC deno_core ops
│ │
└────────────────────┬──────────────────┘
│
┌───────────────────────────────────┴──────────────────────────────────────────┐
│ Shared Rust crates │
│ - font-kit (system font discovery + matching) │
│ - fontcull / fontcull-skrifa (subsetting + name-table reader) │
│ - chardetng + encoding_rs (encoding detection + conversion) │
│ - serde / serde_json (serialization) │
│ - rusqlite (user font index) │
└──────────────────────────────────────────────────────────────────────────────┘
```
## 致谢 | Credits
- 原项目 / 原始项目: [ying](https://github.com/ying) (2021), [gky99/ssaHdrify](https://github.com/gky99/ssaHdrify) (2024-2025)
- Hdr icons created by Freepik - Flaticon
## 许可证 | License
Copyright (C) 2021 ying
Copyright (C) 2024-2025 gky99
Copyright (C) 2026 koagaroon
本项目采用 [GNU 通用公共许可证 v3.0 或更高版本](LICENSE) 授权。
本项目采用 [GNU 通用公共许可证 v3.0 或更高版本](LICENSE) 授权。
### 来源与衍生作品 | Origin and Derivative Work
本项目是 [ssaHdrify](https://github.com/gky99/ssaHdrify) 的 Tauri 桌面重写版，原项目由 ying (2021) 创建，后由 gky99 (2024-2025) 维护。原项目同样采用 GPL-3.0 授权。
本项目是 [ssaHdrify](https://github.com/gky99/ssaHdrify) 的 Tauri 桌面重写版，
原始项目由 ying (2021) 创建，后由 gky99 (2024-2025) 维护。
原始项目同样采用 GPL-3.0 授权。
HDR 色彩转换算法使用 TypeScript（基于 [Color.js](https://colorjs.io/)）重新实现，参考了 Python 版本的方案（使用 [colour-science](https://www.colour-science.org/)）。未逐字复制代码——实现是全新的，但出于许可证目的视为衍生作品。
HDR 色彩转换算法使用 TypeScript（基于
[Color.js](https://colorjs.io/)）重新实现，参考了 Python 版本的方案
（使用 [colour-science](https://www.colour-science.org/)）。没有
逐字复制代码——实现是全新的，但出于许可证目的，
本项目被视为衍生作品。
### 算法归属 | Algorithm Attribution
`src/features/font-embed/font-collector.ts` 中的字体收集算法受 [Aegisub](https://github.com/Aegisub/Aegisub) 的 FontCollector 设计（BSD-3-Clause）启发。未复制 Aegisub 代码，实现为本项目原创 TypeScript。
`src/features/font-embed/font-collector.ts` 中的字体收集算法
受 [Aegisub](https://github.com/Aegisub/Aegisub) 的 FontCollector
设计（BSD-3-Clause）启发。没有复制 Aegisub 的代码；该实现是
为本项目编写的原创 TypeScript。
### 第三方依赖 | Third-Party Dependencies
所有依赖均使用与 GPL-3.0 兼容的许可证。
所有依赖项均使用与 GPL-3.0 兼容的许可证。
#### 运行时依赖（随应用分发）| Runtime (shipped with the application)
| 组件 / Component | 许可证 / License | 用途 / Usage |
| --------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| [Tauri](https://tauri.app/) | MIT OR Apache-2.0 | 桌面应用框架 / 桌面应用框架 |
| [React](https://react.dev/) | MIT | UI 框架 / UI 框架 |
| [Color.js](https://colorjs.io/) | MIT | HDR 色彩空间转换 (PQ/HLG) / HDR 色彩空间转换 |
| [ass-compiler](https://github.com/weizhenye/ass-compiler) | MIT | ASS 字幕解析（字体收集）/ ASS 字幕解析（用于字体收集） |
| [font-kit](https://github.com/servo/font-kit) | MIT OR Apache-2.0 | 跨平台系统字体发现 (Rust) / 跨平台系统字体发现 |
| [fontcull](https://github.com/bearcove/fontcull) | MIT | 字体子集化（含 fontcull-klippa、fontcull-skrifa）/ 字体子集化（包含 fontcull-klippa、fontcull-skrifa） |
| [chardetng](https://github.com/hsivonen/chardetng) | MIT OR Apache-2.0 | 编码检测 (Firefox 引擎) / 编码检测（Firefox 引擎） |
| [encoding_rs](https://github.com/hsivonen/encoding_rs) | MIT OR Apache-2.0 | 编码转换 / 编码转换 |
| [serde](https://serde.rs/) | MIT OR Apache-2.0 | Rust 序列化 / Rust 序列化 |
| [deno_core](https://github.com/denoland/deno) | MIT | 嵌入式 V8 JS 运行时（CLI）/ 嵌入式 V8 JS 运行时（CLI） |
| [V8](https://v8.dev/) | BSD-3-Clause | JavaScript 引擎（经 deno_core 嵌入，CLI）/ JavaScript 引擎（通过 deno_core 嵌入，CLI） |
| [clap](https://github.com/clap-rs/clap) | MIT OR Apache-2.0 | CLI 参数解析（CLI）/ CLI 参数解析（CLI） |
| [env_logger](https://github.com/rust-cli/env_logger) | MIT OR Apache-2.0 | CLI 日志后端 stderr（CLI）/ CLI 日志后端（输出到 stderr，CLI） |
| [sys-locale](https://github.com/1Password/sys-locale) | MIT OR Apache-2.0 | OS 区域设置检测（驱动 `--lang` 自动检测，CLI）/ 操作系统区域设置检测（驱动 `--lang` 自动检测，CLI） |
#### 捆绑字体（随应用分发）| Bundled Fonts (shipped with the application)
| 字体 / Font | 许可证 / License | 用途 / Usage |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Inter](https://rsms.me/inter/) · © The Inter Project Authors | [SIL Open Font License 1.1](src/assets/fonts/inter/LICENSE.txt) · OFL-1.1 | 英文界面正文与标题 / 英文界面正文与标题 |
| [Smiley Sans 得意黑](https://github.com/atelier-anchor/smiley-sans) · © 2022–2024 [atelierAnchor](https://atelier-anchor.com) | [SIL Open Font License 1.1](src/assets/fonts/smiley-sans/LICENSE.txt) · OFL-1.1 | 中文界面标题展示字体（仅作标题用）/ 中文模式应用程序标题展示字体（仅用于标题） |
#### 构建时依赖（不随应用分发）| Build-time only (not shipped)
| 组件 / Component | 许可证 / License | 用途 / Usage |
| --------------------------------------------- | ---------------- | ----------------------------------------------------------------- |
| [Tailwind CSS](https://tailwindcss.com/) | MIT | CSS 工具框架 / CSS 工具框架 |
| [TypeScript](https://www.typescriptlang.org/) | Apache-2.0 | 类型检查 / 类型检查 |
| [Vite](https://vite.dev/) | MIT | 构建工具 / 构建工具 |
| [ESLint](https://eslint.org/) | MIT | 代码检查 / 代码检查 |
| [Prettier](https://prettier.io/) | MIT | 代码格式化 / 代码格式化 |
| [Vitest](https://vitest.dev/) | MIT | 单元测试 / 单元测试 |
| [esbuild](https://esbuild.github.io/) | MIT | engine.js 打包（CLI 嵌入用）/ 为 CLI 嵌入打包 engine.js |
| |
| 字体嵌入 / Font Embed | 批量重命名 / Batch Rename |
| :---------------------------------------------------------------: | :-----------------------------------------------------------------: |
| | |
### 深色主题（英文）/ Dark Theme (English)
| HDR 转换 / HDR Convert | 时间轴偏移 / Time Shift |
| :---------------------------------------------------------------: | :----------------------------------------------------------------: |
| | |
| 字体嵌入 / Font Embed | 批量重命名 / Batch Rename |
| :--------------------------------------------------------------: | :----------------------------------------------------------------: |
| | |
## 目录 | Contents
- [下载 | Download](#下载--download)
- [功能 | Features](#功能--features)
- [使用方法 | Usage](#使用方法--usage)
- [CLI 使用 | CLI Usage](#cli-使用--cli-usage)
- [使用场景 | Background](#使用场景--background)
- [HDR 转换原理 | How HDR Conversion Works](#hdr-转换原理--how-hdr-conversion-works)
- [从源码构建 | Build from Source](#从源码构建--build-from-source)
- [架构 | Architecture](#架构--architecture)
- [致谢 | Credits](#致谢--credits)
- [许可证 | License](#许可证--license)
## 下载 | Download
从 [Releases](https://github.com/koagaroon/ssaHdrify-tauri/releases/latest) 页面下载最新 exe 文件：
- **`ssahdrify_*.exe`** — 图形界面（GUI），适合手动操作
- **`ssahdrify-cli_*.exe`** — 命令行（CLI），适合 pipeline / 批处理 / 脚本化场景
macOS / Linux 用户请参考下方「从源码构建」。
从 [Releases](https://github.com/koagaroon/ssaHdrify-tauri/releases/latest) 页面下载最新 exe 文件：
- **`ssahdrify_*.exe`** — 图形界面（GUI），适合手动操作
- **`ssahdrify-cli_*.exe`** — 命令行（CLI），适用于 pipeline / 批处理 / 脚本化场景
macOS / Linux 用户，请参阅下方的「从源码构建」。
## 功能 | Features
| 标签页 / Tab | 功能 / Function |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HDR 色彩转换 / HDR Color Conversion** | 为字幕附加对应的 BT.2100 PQ 或 HLG 色彩空间数据 / 为字幕附加匹配的 BT.2100 PQ 或 HLG 色彩空间数据 |
| **时间轴偏移 / Timing Shift** | 批量偏移字幕时间戳；可指定时间点后才开始偏移，并支持实时预览 / 批量偏移字幕时间戳；偏移可从选定的时间戳开始，并支持实时预览 |
| **字体嵌入 / Font Embedding** | 自动检测字幕用到的字体，与系统字体库或本地字体源匹配，并以子集化形式嵌入 ASS 文件 / 自动检测字幕中引用的字体，与系统字体库或本地字体源进行匹配，并以子集化形式嵌入 ASS 文件 |
| **批量重命名 / Batch Rename** | 自动匹配视频文件和字幕文件，按视频文件名重命名字幕；同一视频文件有多个对应字幕时，用户可自由选择字幕文件，手动调整配对 / 自动匹配视频文件和字幕文件，并按视频文件名重命名副本；当视频有多个候选字幕时，用户可以手动选择并调整配对 |
## 使用方法 | Usage
### HDR 色彩转换 / HDR Color Conversion
1. 选择 EOTF 曲线（PQ 或 HLG）/ 选择 EOTF 曲线（PQ 或 HLG）
2. 设置字幕目标亮度（默认 203 nits）/ 设置字幕目标亮度（默认：203 nits）
3. 选择字幕文件（支持多选）/ 选择字幕文件（支持多选）
4. 点击转换 / 点击转换
5. 默认输出文件扩展名为 `.hdr.ass`（可修改）/ 默认输出扩展名为 `.hdr.ass`（可自定义）
### 时间轴偏移 / Timing Shift
1. 选择字幕文件 / 选择字幕文件
2. 输入偏移量（毫秒），选择方向：「提前」或「延后」/ 输入偏移量（毫秒），然后选择方向：更快 或 更慢
3. 可选：启用阈值过滤，仅偏移特定时间点后的字幕 / 可选：启用阈值，仅偏移特定时间戳之后的字幕
4. 实时预览调整效果 / 实时预览调整效果
5. 导出 / 导出
### 字体嵌入 / Font Embedding
1. 点击「选择字幕文件 / Select Subtitle File」选择 ASS 字幕文件 / 点击 **选择字幕文件** 选择一个 ASS 文件
2. 工具自动检测字幕用到的字体，先尝试从系统字体库匹配 / 工具自动检测字幕中引用的字体，并首先尝试与系统字体库匹配
3. 主面板实时显示本地来源覆盖（覆盖 N / M）和尚未匹配的字体；每条字体标注来源（本地 / 系统）和匹配状态（已找到 / 缺失）/ 主面板实时显示本地源覆盖率（覆盖：N / M）并列出仍缺失的字体；每个检测到的字体都标注其来源（本地 / 系统）和状态（已找到 / 缺失）
4. 点击「嵌入已选字体」，字体数据（子集化后）写入 ASS 文件 / 点击 **嵌入选定字体**，将子集化后的字体数据写入 ASS 文件
字幕组排版常用的字体大多未安装在系统中。点击「字体来源 / Font Sources」即可打开本地来源管理面板，添加你想扫描的文件夹，无需安装到系统即可参与匹配。
在字幕组排版中常用的字体大多未安装在系统中。点击 **字体来源** 打开本地源管理器，然后添加您想扫描的文件夹——无需系统级安装。
文件夹大小不限，扫描过程会实时显示已读取的字体数量并支持随时取消；选择包含超过 5000 个文件或体积超过 1 GB 的目录前，会弹出确认对话框。
任何大小的文件夹均可接受；扫描过程实时显示找到的字体数量，并可随时取消。在选择一个异常大的目录（5000+ 个文件或 > 1 GB）之前，会弹出确认对话框。
### 批量重命名 / Batch Rename
1. 拖入一个包含视频和字幕的文件夹（或点击「选择文件 / Select Files」手动选择）；程序将按照文件格式自动归类 / 拖入一个包含视频和字幕的文件夹（或点击 **选择文件** 手动选择）；应用程序会按格式自动分类文件
2. 系统按字幕组命名习惯做剧集号正则配对，预填配对表 / 应用程序使用字幕组剧集正则表达式预先配对，并填充配对表
3. 若应用错配或漏配，从该行下拉框直接手动选取字幕，选中后自动勾选进入重命名队列 / 如果应用程序配对错误或遗漏，通过该行的下拉菜单更换字幕；选择后该行会自动勾选进入重命名队列
4. 选择输出策略：原文件直接改名 / 复制到当前目录 / 复制到自定义目录 / 选择输出策略：就地重命名、复制到视频所在目录，或复制到自定义目录
5. 点击运行；若目标路径已存在采用相同规则重命名的同名文件，会弹出确认覆盖对话框 / 点击运行；如果目标路径已存在由重命名规则生成的同名文件，会先弹出覆盖确认对话框
## CLI 使用 | CLI Usage
`ssahdrify-cli` 是 GUI 的命令行（CLI）版本，从同一份源代码构建。四个核心功能（HDR 转换 / 时间轴偏移 / 字体嵌入 / 批量重命名）与 GUI 版对等；CLI 额外提供 `chain`（一次调用串联多步、仅终端步落盘）和 `refresh-fonts`（持久化字体缓存）两个子命令。
`ssahdrify-cli` 是 GUI 的命令行（CLI）版本，基于相同源代码构建。四个核心功能（HDR 转换 / 时间轴偏移 / 字体嵌入 / 批量重命名）与 GUI 版匹配；CLI 还额外暴露了 `chain`（一次调用串联多步，仅最后一步写入磁盘）和 `refresh-fonts`（持久化字体缓存）——这两个命令目前仅 CLI 可用。
### 快速示例 | Quick Examples
```
# HDR 色彩转换（PQ 曲线）/ HDR conversion (PQ curve)
ssahdrify-cli hdr --eotf pq input.ass
# 时间轴偏移 +500ms / Timing shift +500ms
ssahdrify-cli shift --offset +500ms input.ass
# 字体嵌入：从指定文件夹搜索字体 / Font embed: search a folder for fonts
ssahdrify-cli embed --font-dir "C:/Fonts" input.ass
# 持久化字体缓存：先一次性扫描，后续 embed 复用 / Persistent font cache: scan once, reuse on every embed
ssahdrify-cli refresh-fonts --font-dir "C:/Fonts"
ssahdrify-cli embed input.ass # uses cache automatically
# 链式调用：HDR 转 + 时间轴偏移单次完成，仅终端步落盘 / Chain: HDR + shift in one shot, only terminal step writes
ssahdrify-cli chain hdr --eotf pq + shift --offset +500ms input.ass
# 批量重命名：默认复制到视频所在目录 / Batch rename (default: copy sub next to video)
ssahdrify-cli rename "C:/My Series"
```
### 全部子命令 | All Subcommands
每个子命令都支持 `--help` 查看完整参数。
每个子命令都支持 `--help` 查看完整的参数参考。
```
ssahdrify-cli --help
ssahdrify-cli hdr --help
ssahdrify-cli shift --help
ssahdrify-cli embed --help
ssahdrify-cli rename --help
ssahdrify-cli refresh-fonts --help
ssahdrify-cli chain --help
```
### 全局选项 | Global Options
| 选项 / Option | 说明 / Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--lang 标签：GUI工具, HDR转换, React, Rust, SSA字幕, Syscalls, Tauri, 可视化界面, 多媒体处理, 字体嵌入, 字幕处理, 字幕编辑, 批处理, 批量重命名, 时间轴偏移, 网络流量审计, 自动化攻击, 视频字幕