fix: restore resilient subtitle delivery

* docs: design resilient subtitle output

* docs: plan resilient subtitle output

* fix: prepare current SubHD downloads

* fix: force low-confidence subtitle synchronization

* fix: deliver low-confidence subtitle repairs

* fix: require parseable subtitle output

Author: IronJKZ

README.md

@@ -105,7 +105,7 @@ From a folder containing a movie, run:
 fixsub
 ```
 
-The default provider set is ASSRT plus SubHD. A final subtitle is written only when the selected candidate is not poor; otherwise inspect the saved candidates and diagnostics.
+The default provider set is ASSRT plus SubHD. When at least one usable Chinese candidate exists, `fixsub` writes the highest-ranked candidate and records its confidence and selection outcome in the console and metadata.
 
 ### Safe preview
 
@@ -122,7 +122,7 @@ fixsub --providers subhd
 fixsub --providers assrt,subhd
 ```
 
-Use `fixsub --providers subhd` to avoid ASSRT credentials. Use `fixsub --providers assrt,subhd` to explicitly select both providers (also the default). Provider search or download failures are logged and the run can continue with other available providers, but provider outages can leave no usable candidate.
+Use `fixsub --providers subhd` to avoid ASSRT credentials. Use `fixsub --providers assrt,subhd` to explicitly select both providers (also the default). SubHD downloads use its prepared-download flow before fetching the final file. Provider search or download failures are logged and the run can continue with other available providers, but provider outages can leave no usable candidate.
 
 ### Audio and synchronization
 
@@ -131,7 +131,9 @@ fixsub --audio a:0
 fixsub --no-sync
 ```
 
-By default, `fixsub` probes audio with `ffprobe`, selects a reference stream, and tries `ffsubsync` for each candidate. `fixsub --audio a:0` forces the stream passed to `ffsubsync`. `fixsub --no-sync` skips audio synchronization and ranks original candidates only; use it only when necessary because structural timestamp checks cannot establish dialogue or audio alignment. A failed or low-quality synchronization makes a candidate poor and prevents automatic application.
+By default, `fixsub` probes audio with `ffprobe`, selects a reference stream, and tries `ffsubsync` for each candidate. `fixsub --audio a:0` forces the stream passed to `ffsubsync`. `fixsub --no-sync` skips audio synchronization and ranks original candidates only; use it only when necessary because structural timestamp checks cannot establish dialogue or audio alignment.
+
+`fixsub` first asks `ffsubsync` to skip low-quality alignments. If that conservative pass explicitly refuses the alignment, `fixsub` retries once in forced mode. When at least one usable Chinese candidate exists, the best candidate is written even if confidence remains low; the console and metadata identify forced synchronization or original fallback. A hard stop remains when no candidate can be downloaded, extracted, parsed, or accepted as Chinese.
 
 ### Candidate and language controls
 
@@ -188,8 +190,8 @@ Before opening an issue, remove `.fixsub/logs/fixsub.log`, `.fixsub/metadata/res
 - **A `.rar` or `.7z` archive cannot be extracted:** install archive support with `brew install unar` and retry. `.zip` files do not need `unar`.
 - **ASSRT reports missing credentials:** run `fixsub auth set`, check `fixsub auth status`, or set a temporary `ASSRT_TOKEN`. Use `fixsub --providers subhd` if you do not intend to use ASSRT.
 - **A provider is unavailable or no candidate is found:** retry later, select another provider, and inspect `.fixsub/logs/fixsub.log`; provider results and downloads can change independently of the tool.
-- **Candidates are rejected as low confidence:** inspect `.fixsub/candidates/` and `.fixsub/metadata/results.json`. Low structural timing scores or failed synchronization intentionally prevent automatic output.
-- **Synchronization fails:** install `ffsubsync`, confirm `ffprobe` can read the video, choose the correct stream with `fixsub --audio a:0`, and inspect the log. `fixsub --no-sync` is available only as a manual-risk fallback.
+- **A low-confidence subtitle is applied:** inspect `.fixsub/candidates/`, `.fixsub/synced/`, and `.fixsub/metadata/results.json`. The console and metadata identify whether it used forced synchronization or the original fallback.
+- **Synchronization fails:** install `ffsubsync`, confirm `ffprobe` can read the video, choose the correct stream with `fixsub --audio a:0`, and inspect the log. `fixsub` ranks and applies the original fallback when it remains the best usable candidate.
 
 ## Development
 

README.zh-CN.md

@@ -105,7 +105,7 @@ macOS 钥匙串是首选的持久化存储方式。临时的 `ASSRT_TOKEN` 环
 fixsub
 ```
 
-默认字幕源是 ASSRT 加 SubHD。仅当选中的候选项不属于低质量结果时才会写入最终字幕；否则请检查已保存的候选项和诊断信息。
+默认字幕源是 ASSRT 加 SubHD。只要至少存在一个可用的中文字幕候选项，`fixsub` 就会写入排名最高的候选项，并在控制台和元数据中记录其置信度和选择结果。
 
 ### 安全预览
 
@@ -122,7 +122,7 @@ fixsub --providers subhd
 fixsub --providers assrt,subhd
 ```
 
-使用 `fixsub --providers subhd` 可避免使用 ASSRT 凭据。使用 `fixsub --providers assrt,subhd` 可显式选择两个字幕源（也是默认值）。字幕源的搜索或下载失败会被记录，运行可继续使用其他可用字幕源；但字幕源故障可能导致没有可用候选项。
+使用 `fixsub --providers subhd` 可避免使用 ASSRT 凭据。使用 `fixsub --providers assrt,subhd` 可显式选择两个字幕源（也是默认值）。SubHD 下载会先走其准备下载流程，再获取最终文件。字幕源的搜索或下载失败会被记录，运行可继续使用其他可用字幕源；但字幕源故障可能导致没有可用候选项。
 
 ### 音轨与同步
 
@@ -131,7 +131,9 @@ fixsub --audio a:0
 fixsub --no-sync
 ```
 
-默认情况下，`fixsub` 会通过 `ffprobe` 探测音轨、选择参考流，并对每个候选项尝试 `ffsubsync`。`fixsub --audio a:0` 会强制传给 `ffsubsync` 的流。`fixsub --no-sync` 会跳过音频同步，仅对原始候选项排序；仅应在必要时使用，因为结构化时间戳检查无法证明对白或音频对齐。同步失败或低质量同步会使候选项被视为低质量，因而不会自动应用。
+默认情况下，`fixsub` 会通过 `ffprobe` 探测音轨、选择参考流，并对每个候选项尝试 `ffsubsync`。`fixsub --audio a:0` 会强制传给 `ffsubsync` 的流。`fixsub --no-sync` 会跳过音频同步，仅对原始候选项排序；仅应在必要时使用，因为结构化时间戳检查无法证明对白或音频对齐。
+
+`fixsub` 会先要求 `ffsubsync` 跳过低质量对齐；如果保守同步明确拒绝该对齐，则自动以强制模式重试一次。只要至少存在一个可用的中文字幕候选项，即使置信度仍然较低，也会写入排名最高的候选项；控制台和元数据会明确标记强制同步或原字幕回退。只有在没有候选项能够下载、解压、解析或通过中文内容检查时才会停止且不写入字幕。
 
 ### 候选数量与语言标签
 
@@ -188,8 +190,8 @@ fixsub --debug
 - **无法解压 `.rar` 或 `.7z` 压缩包：** 使用 `brew install unar` 安装解压支持后重试。`.zip` 文件不需要 `unar`。
 - **ASSRT 提示缺少凭据：** 运行 `fixsub auth set`，检查 `fixsub auth status`，或设置临时 `ASSRT_TOKEN`。若不打算使用 ASSRT，请使用 `fixsub --providers subhd`。
 - **字幕源不可用或找不到候选项：** 请稍后重试、选择其他字幕源，并检查 `.fixsub/logs/fixsub.log`；字幕源结果和下载状态会独立于工具发生变化。
-- **候选项因低置信度被拒绝：** 检查 `.fixsub/candidates/` 和 `.fixsub/metadata/results.json`。低结构化时间轴评分或同步失败会有意阻止自动输出。
-- **同步失败：** 安装 `ffsubsync`，确认 `ffprobe` 能读取视频，使用 `fixsub --audio a:0` 选择正确的流，并检查日志。`fixsub --no-sync` 仅作为需要人工承担风险的后备选项。
+- **已应用低置信度字幕：** 检查 `.fixsub/candidates/`、`.fixsub/synced/` 和 `.fixsub/metadata/results.json`。控制台和元数据会标记它使用的是强制同步还是原字幕回退。
+- **同步失败：** 安装 `ffsubsync`，确认 `ffprobe` 能读取视频，使用 `fixsub --audio a:0` 选择正确的流，并检查日志。若原字幕仍是排名最高的可用候选项，`fixsub` 会将其作为回退写入。
 
 ## 开发