---
name: subtitle-toolkit
slug: subtitle-toolkit-user-fde90bf4
displayName: 字幕工作台
version: 1.0.0
summary: 处理已有的字幕文件（SRT/VTT）——清洗噪音、合并碎句、校正时间轴、双语合并、导出纯文本与 Markdown，批量可跑，不依赖任何第三方库。
license: MIT
tags:
  - 字幕
  - SRT
  - VTT
  - 视频
  - 后期
  - 转写
display_name: 字幕工作台
description: |-
  处理已有的字幕文件。当用户拿到 SRT/VTT/ASS 字幕要做清洗（去 HTML 标签、去口吃重复、去语气词）、合并过短碎句、整体平移时间轴（对不上画面）、双语字幕合并、导出纯文本或 Markdown 稿件、批量处理多个字幕文件时使用。也用于把字幕转成会议纪要、访谈稿、课程笔记。注意：本技能处理的是已有的字幕文件，**不负责从音频生成字幕**（那是语音识别的活）。
description_zh: 处理已有 SRT/VTT 字幕：清洗、合并碎句、校正时间轴、双语合并、导出文本稿件。
---

# 字幕工作台

处理**已经存在的**字幕文件。语音识别产出的原始字幕通常很脏：一句话被切成七八段、夹着 HTML 标签、时间轴整体偏移、充满"嗯""那个"——这个技能专门收拾这些。

**边界**：它不生成字幕。要从音频出字幕，先用语音识别工具，产出的 SRT 再交给本技能处理。

## 何时触发

- 字幕对不上画面：「整体快了两秒」
- 字幕太碎：「一句一句跳得太快，帮我合并下」
- 字幕很脏：有 `<i>` 标签、有重复的"嗯""就是"
- 要导出稿件：「把字幕导出成纯文本」「转成访谈稿」
- 双语字幕要合并成一条
- 批量处理一堆字幕文件

## 工作流

### 1. 先看一眼字幕状况

```bash
python3 scripts/subtitle.py input.srt --stats
```

输出条数、总时长、平均每条时长、最短/最长条。
**平均时长低于 1.2 秒**说明切得太碎，需要合并。

### 2. 按需处理

常用操作可以串联：

```bash
# 清洗 + 合并碎句 + 导出纯文本
python3 scripts/subtitle.py input.srt --clean --merge 0.4 --export txt

# 时间轴整体后移 2.5 秒（字幕比画面快）
python3 scripts/subtitle.py input.srt --offset +2.5 -o fixed.srt

# 清洗后导出 Markdown 稿件
python3 scripts/subtitle.py input.srt --clean --merge 0.5 --export md -o draft.md
```

参数说明：

| 参数 | 作用 |
|------|------|
| `--stats` | 只看统计，不改动 |
| `--clean` | 去 HTML 标签、去口吃重复、压缩空白 |
| `--merge N` | 合并间隔小于 N 秒的相邻字幕 |
| `--min-dur N` | 过短的单条并入下一条（默认 0.8 秒） |
| `--offset ±N` | 整体平移时间轴，正数为延后 |
| `--export txt/md/csv` | 导出格式 |
| `-o PATH` | 输出路径，不给则打印到屏幕 |

**默认不覆盖原文件**——必须显式给 `-o`。

### 3. 双语合并

两份字幕（中英）合并成一条双行：

```bash
python3 scripts/subtitle.py zh.srt --bilingual en.srt -o merged.srt
```

按时间轴对齐，中文在上、英文在下。

### 4. 转成稿件

导出 txt/md 后，可以进一步整理成访谈稿、会议纪要、课程笔记——
这一步交给模型做：分段、加小标题、提炼要点。

## 支持的时间格式

| 格式 | 分隔符 | 示例 |
|------|-------|------|
| SRT | 逗号 | `00:01:23,456` |
| VTT | 点号 | `00:01:23.456` |
| 简写 | 无毫秒 | `01:23` 或 `1:23.4` |

脚本自动识别，不用手动指定。

## 注意事项

- **编码**：字幕常见 GBK 乱码，脚本按 UTF-8 读、失败自动试 GBK。导出统一 UTF-8
- **时间轴平移是线性的**：如果视频是变速（如 1.2 倍速），线性偏移不够，需要按比例缩放——这种情况提醒用户改用剪映等工具重导出
- **合并会丢信息**：合并后原时间边界消失，导出字幕前先备份
- 批量处理用 shell 循环：
  ```bash
  for f in *.srt; do python3 scripts/subtitle.py "$f" --clean --merge 0.4 -o "clean_$f"; done
  ```