docs: clarify subtitle synchronization

README.md

@@ -2,6 +2,11 @@
 
 [简体中文](README.zh-CN.md)
 
+[![CI](https://github.com/IronJKZ/fixsub/actions/workflows/ci.yml/badge.svg)](https://github.com/IronJKZ/fixsub/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/IronJKZ/fixsub)](https://github.com/IronJKZ/fixsub/releases/latest)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 `fixsub` is a macOS-first command-line tool that finds, validates, synchronizes, and applies Chinese subtitles for a movie stored in a local folder.
 
 > Status: `0.1.0` is an early public release. Use `--dry-run` first with valuable media libraries.
@@ -10,13 +15,14 @@
 
 - Searches ASSRT and SubHD for Chinese subtitle candidates for the video in the current folder.
 - Downloads and extracts supported subtitle files, then normalizes them to UTF-8.
-- Uses `ffprobe` to choose a reference audio stream and can validate timing with `ffsubsync`.
+- Uses `ffprobe` to select the reference audio stream, then automatically aligns each eligible candidate to the movie audio with `ffsubsync`; low-quality synchronizations are rejected.
+- Supports manual whole-timeline adjustment with `fixsub adjust --seconds`, including automatic backup and adjustment metadata.
 - Ranks candidates, preserves an existing final subtitle before replacement, and writes an Infuse-compatible Chinese subtitle beside the video.
 - Records runtime artifacts and diagnostics under `.fixsub/` so a run can be inspected afterwards.
 
 ## How it works
 
-Run `fixsub` from a folder containing the target movie. The tool detects a supported local video, derives search queries, asks the enabled providers for results, ranks them, probes and selects the reference audio, then downloads, extracts, and normalizes subtitle files. It rejects non-Chinese candidates, validates and optionally synchronizes candidates, ranks the decisions, backs up any previous final subtitle, and writes `<video_stem>.zh.<ext>` when a suitable result is found.
+Run `fixsub` from a folder containing the target movie. The tool detects a supported local video, derives search queries, asks the enabled providers for results, ranks them, probes and selects the reference audio, then downloads, extracts, and normalizes subtitle files. It rejects non-Chinese candidates. By default, it attempts audio-based synchronization with `ffsubsync` for each eligible candidate; `--no-sync` explicitly skips this step. It ranks the decisions, backs up any previous final subtitle, and writes `<video_stem>.zh.<ext>` when a suitable result is found.
 
 This is a one-movie-folder workflow. If the folder contains more than one supported video, the largest file is selected; use a dedicated folder when that is not the intended movie.
 
@@ -37,15 +43,42 @@ This is a one-movie-folder workflow. If the folder contains more than one suppor
 
 `ffprobe` is supplied by `ffmpeg`. `unar` handles `.rar` and `.7z` archives; `.zip` extraction is built in. `fixsub` is macOS-first and does not make non-macOS compatibility guarantees.
 
+## Supported formats
+
+| Kind | Formats |
+| --- | --- |
+| Video | `.mkv`, `.mp4`, `.m4v`, `.avi`, `.mov` |
+| Subtitle | `.srt`, `.ass`, `.ssa` |
+| Download/archive | Direct subtitle files, `.zip`, `.rar`, `.7z` |
+
+Direct subtitle downloads and `.zip` extraction work without `unar`; `.rar` and `.7z` extraction require `unar`.
+
 ## Installation
 
-Install from a source checkout in editable mode:
+### End-user installation
+
+Clone the repository and install `fixsub` in a virtual environment:
+
+```bash
+git clone https://github.com/IronJKZ/fixsub.git
+cd fixsub
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install .
+python3 -m pip install ffsubsync
+```
+
+The final command installs the `ffs` executable used by the default audio-synchronization workflow. No PyPI package is published, so installation currently starts from a source checkout.
+
+### Contributor installation
+
+For tests and local package builds, use an editable development install:
 
 ```bash
 python3 -m pip install -e ".[dev]"
 ```
 
-No PyPI package is published. Install the required macOS tools from the Requirements section, and install `ffsubsync` when you want audio-based synchronization rather than the deliberately riskier `--no-sync` mode.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.
 
 ## Authentication
 

README.zh-CN.md

@@ -2,6 +2,11 @@
 
 [English](README.md)
 
+[![CI](https://github.com/IronJKZ/fixsub/actions/workflows/ci.yml/badge.svg)](https://github.com/IronJKZ/fixsub/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/IronJKZ/fixsub)](https://github.com/IronJKZ/fixsub/releases/latest)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 `fixsub` 是一款优先支持 macOS 的命令行工具，用于为本地电影搜索、验证、同步并应用中文字幕。
 
 > 状态：`0.1.0` 是早期公开版本。对重要媒体库操作前，请先使用 `--dry-run`。
@@ -10,13 +15,14 @@
 
 - 为当前文件夹中的视频从 ASSRT 和 SubHD 搜索中文字幕候选项。
 - 下载并解压受支持的字幕文件，然后将其规范化为 UTF-8。
-- 使用 `ffprobe` 选择参考音轨，并可通过 `ffsubsync` 验证时间轴。
+- 使用 `ffprobe` 选择参考音轨，然后通过 `ffsubsync` 根据电影音频自动校准每个合格的候选字幕；低质量同步结果会被拒绝。
+- 支持使用 `fixsub adjust --seconds` 手动整体提前或延后字幕，并自动备份原字幕、记录调整元数据。
 - 对候选项排序，在替换前保留已有的最终字幕，并在视频旁写入兼容 Infuse 的中文字幕。
 - 将运行产物和诊断信息记录在 `.fixsub/` 下，便于事后检查。
 
 ## 工作流程
 
-请在包含目标电影的文件夹中运行 `fixsub`。工具会检测受支持的本地视频、生成搜索词、向启用的字幕源请求结果、对结果排序、探测并选择参考音轨，然后下载、解压并规范化字幕文件。随后它会排除非中文字幕候选项、验证并可选地同步候选项、对决策排序、备份之前的最终字幕，并在找到合适结果时写入 `<video_stem>.zh.<ext>`。
+请在包含目标电影的文件夹中运行 `fixsub`。工具会检测受支持的本地视频、生成搜索词、向启用的字幕源请求结果、对结果排序、探测并选择参考音轨，然后下载、解压并规范化字幕文件。随后它会排除非中文字幕候选项。默认情况下，它会通过 `ffsubsync` 根据电影音频校准每个合格的候选字幕；`--no-sync` 会明确跳过这一步。工具会对决策排序、备份之前的最终字幕，并在找到合适结果时写入 `<video_stem>.zh.<ext>`。
 
 这是一个单电影文件夹工作流程。若文件夹中包含多个受支持的视频，将选择最大的文件；若这不是目标电影，请使用单独的文件夹。
 
@@ -37,15 +43,42 @@
 
 `ffprobe` 由 `ffmpeg` 提供。`unar` 用于处理 `.rar` 和 `.7z` 压缩包；`.zip` 解压为内置能力。`fixsub` 优先支持 macOS，不保证在非 macOS 系统上的兼容性。
 
+## 支持的格式
+
+| 类型 | 格式 |
+| --- | --- |
+| 视频 | `.mkv`、`.mp4`、`.m4v`、`.avi`、`.mov` |
+| 字幕 | `.srt`、`.ass`、`.ssa` |
+| 下载/压缩包 | 直接字幕文件、`.zip`、`.rar`、`.7z` |
+
+直接下载的字幕和 `.zip` 解压不需要 `unar`；解压 `.rar` 和 `.7z` 需要 `unar`。
+
 ## 安装
 
-从源码检出目录以可编辑模式安装：
+### 普通用户安装
+
+克隆仓库，并在虚拟环境中安装 `fixsub`：
+
+```bash
+git clone https://github.com/IronJKZ/fixsub.git
+cd fixsub
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install .
+python3 -m pip install ffsubsync
+```
+
+最后一条命令会安装默认音频同步流程使用的 `ffs` 可执行文件。项目尚未发布 PyPI 包，因此当前需要从源码检出目录安装。
+
+### 贡献者安装
+
+如需运行测试和本地构建包，请使用可编辑的开发环境安装：
 
 ```bash
 python3 -m pip install -e ".[dev]"
 ```
 
-项目未发布 PyPI 包。请安装“系统要求”中的必需 macOS 工具；若要使用基于音频的同步而不是风险更高的 `--no-sync` 模式，请安装 `ffsubsync`。
+贡献流程请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ## 身份验证