oil-subtitle — скилл

---
name: oil-subtitle
description: >
  为本地 MP4、MOV 等视频转录、校对、预览并烧录准确的中文字幕，
  或把审校后的中文字幕翻译成同时间轴的英文 SRT。
  用户只要提供成片视频并要求加字幕、修字幕、生成 SRT/ASS、字幕进度条或英文字幕，
  就使用本 Skill。不要用它修改 .screenstudio 工程时间线；工程剪辑使用 screen-studio-editor。
---

# Oil Subtitle

只负责已经导出的视频字幕，不修改 Screen Studio 工程。

脚本负责 ASR、术语表、分行、疑点检测、章节、排版、人脸区域检测和 FFmpeg 烧录。Agent 是字幕正文唯一的语义校对者，负责通读转录稿、结合音频和必要画面修正错词、组织用户预览并检查最终结果。百炼模型不得自动改写字幕正文。

## API Key 配置入口

需要外部服务凭据时先读[API Key 配置与业务读取](references/api-key-setup.md)：复用已有安全入口；本机缺少 Key 时使用随附固定页面，保存后通过业务包装入口读取。内置能力与纯本地流程不要求配置 Key。

## 默认行为

- 默认只生成中文字幕。用户明确要求英文字幕时，才从审校后的中文字幕逐条翻译；不把英文翻译混入默认转录和烧录流程。默认使用 DashScope Python SDK 调用百炼 FunAudio ASR；字幕断句和长视频章节由百炼 Qwen 完成，全部共用一个 API Key。旧本地 Whisper 仅用于明确比较或远程服务不可用时的降级。
- ASR 自动应用外部 hotwords 和 glossary；随后由 Agent 通读整份转录稿并补充高置信错误。`review_subtitles.py` 只复制原文和生成疑点清单，自动改词数必须为 0。
- 型号、版本号、命令、文件名和界面文字需要结合口播上下文核对。画面中的项目名、窗口标题或侧边栏背景文字只有与口播属于同一指代时才能作为证据；看不清或无法确认时保留原文，交给用户预览。
- 用户在预览页保存字幕时，脚本只比较修改前后内容并生成待 Agent 审阅的 `manual-edit-review.json`，不得调用模型或自动写入 glossary。Agent 只把稳定、可复用且上下文安全的 ASR 映射写入个人 glossary；润色、删句、标点和一次性改写一律忽略。
- 字幕默认不显示标点；人工审阅过的 SRT 通过 `--srt-input` 直烧时保持文本、换行和时间码不变。
- 清理标点必须保留数字之间的小数点，包括评测分数和模型版本号。交付前同时核对审校稿、准备后的字幕和最终 SRT 中的关键数字，不能只检查 ASR 校对副本。
- 正常中文字幕默认在中文与英文或数字的边界补一个半角空格，例如 `使用Claude Code做AI实战` 显示为 `使用 Claude Code 做 AI 实战`。该规则在准备阶段统一写入预览字幕，并在烧录阶段幂等复用；用户不需要手工逐条加空格，纯空格变化也不进入错题本。
- 章节进度功能默认开启。视频严格超过三分钟时，在视频画面底部用半透明渐变阴影承载宽粒度章节进度；不增加实色画布，也不把每个小点拆成章节。
- 用户只要用自然语言说“关闭章节进度条”或同义表达，本次任务就在准备和烧录命令中都传 `--no-progress`，不生成章节，也不显示进度条；用户说“开启章节进度条”时传 `--progress`。这是单次任务开关，不要求用户修改配置文件。
- 正常烧录会识别持续出现的人脸区域并执行固定轻度美颜；用户要求保持原画时传 `--no-beauty`。
- 不覆盖已有 MP4、SRT 或 ASS。目标存在时使用新文件名，除非用户明确同意覆盖。

## 初始化

```bash
SKILL_DIR="<oil-subtitle 的绝对目录>"
PYTHON="$SKILL_DIR/.venv/bin/python3"
CONFIG="${OIL_SUBTITLE_CONFIG:-$HOME/.config/oil-subtitle/config.json}"
```

首次使用时运行：

```bash
bash "$SKILL_DIR/setup.sh"