Stt Skill — Development skill for Claude Code

stt-skill —— 音视频 → 中文字幕（Mac 本地，离线）

把一段音视频变成中文字幕。STT 全程在本机跑，不上传；翻译那一步交给任意生成模型。

音视频 ──▶ [STT 腿] ──▶ 英文文本/字幕 ──▶ [生成模型翻译] ──▶ 中文字幕
            ├ EG2 Transcribe / ANE         外接
            │   离线 · 540× · 无时间轴
            └ WhisperKit / CoreML+ANE
                离线 · 18–37× · 带时间轴 → 真 .srt

两条 STT 腿

源	走哪条腿	出什么
有 .vtt / .srt 字幕	不用 STT，直接切段	真 .srt（带时间轴）
没字幕，只要中文译稿	EG2 Transcribe（stt.sh）	.txt（无时间轴）
没字幕，要时间轴	WhisperKit（whisper_srt.sh）	真 .srt

• EG2 Transcribe 快得多（≈540× 实时），但 Copy text 只出无时间轴的纯文本， 且需要本机装有 Embedding Gemma Transcribe 那个 app —— 这条腿不可移植， 在本仓库里是作为「快路」保留的。
• WhisperKit 是可复现的那条：CoreML / Apple Neural Engine，实测 6:20 音频约 20 s （≈18× 实时；纯流水线 10.2 s ≈37×）。

安装

brew install whisperkit-cli ffmpeg
# yt-dlp 可选，用来抓素材

首次转写会自动下载模型到 `~/Documents/huggingface/models/argmaxinc/whisperkit-coreml/`（turbo 约 1.6 G）。 想更小更快可以换压缩版 `large-v3-v20240930_turbo_632MB`，WER 几乎不变。

用法

S=./scripts

# 1. 转写（带时间轴）
$S/whisper_srt.sh input.mp4 out.en.srt

# 2. 切段
$S/subs.py prepare out.en.srt -o segments.json

# 3. 翻译：读 segments.json，逐段译成中文，写成 translated.json
#      {"1":"第一段中文","2":"..."}   或   [{"i":1,"zh":"..."}, ...]
#      某条写成 null = 丢弃整条 cue（用来删掉 Whisper 在静音段的幻觉）

# 4. 回填时间轴
$S/subs.py assemble segments.json translated.json -o zh.srt

`subs.py` 只做「切段 → 回填」这两件机械活；**翻译刻意留给生成模型或人**。 `assemble` 会对漏译的段告警并保留英文——看到告警就是没译完。

已知坑

• whisperkit-cli 不加 --report 不写文件，只在 stdout 打纯文本。
• 不加 --skip-special-tokens，.srt 正文里会混进 <|startoftranscript|><|9.20|>。
• 静音 / 音乐段可能出幻觉（实测混进过俄语 Продолжение следует...）。
• 模型名要带前缀：large-v3-v20240930_turbo（仓库 argmaxinc/whisperkit-coreml）。
• 同一音轨两次转写，cue 数可能不同（VAD 分块有随机性）。

许可

MIT