| name | generate-transcript |
| description | 本地把音频/视频文件或在线视频 URL 转录成文字稿(txt/srt/vtt/json)。基于 Apple Silicon 上的 mlx_whisper,支持中英文等多语言、自动语言检测、模型规格选择。当用户想要"转录""生成字幕/文稿/transcript""把这段音频/视频转成文字""提取台词""做 SRT 字幕",或给出一个音视频文件/YouTube 等链接要文字内容时使用。 |
| user_invocable | true |
generate-transcript
在本机(Apple Silicon / MLX)把音频、视频或在线视频链接转录成文字稿。纯本地、免费、不上传。
这是 ASR(语音识别)这一步;它不做翻译。要"翻译成另一种语言"时,先用本 skill 转录,再由你(Claude)翻译文字,需要配音则交给 IndexTTS2(TTS)。
何时用
- "把这段音频/视频转成文字" / "生成字幕" / "做个 SRT"
- 给了一个本地
.mp3/.wav/.m4a/.mp4/... 文件要文稿
- 给了一个 YouTube/Bilibili 等链接,只要里面的话
怎么用
统一调用脚本($SKILL_DIR 为本 skill 目录):
bash "$SKILL_DIR/scripts/transcribe.sh" <文件路径|URL> [model] [lang] [outdir]
参数:
model:tiny | small | medium | turbo | large-v3,或完整 HF repo id。默认 turbo。lang:zh | en | ja | ... 或 auto(自动检测)。默认 auto。outdir:输出目录。默认 ./transcripts。
产出:同名 .txt / .srt / .vtt / .tsv / .json(--output-format all)。
转录结束后脚本会自动跑验证门 verify_transcript.py(见下「验证产出」),抓到复读幻觉/漏转会以非 0 退出码报 FAIL。
例子
bash "$SKILL_DIR/scripts/transcribe.sh" talk.mp3
bash "$SKILL_DIR/scripts/transcribe.sh" 讲座.m4a large-v3 zh ./out
bash "$SKILL_DIR/scripts/transcribe.sh" "https://youtu.be/RNF0FvRjGZk" turbo en
选哪个模型
| 短名 | 参数量 | 中文 | 速度 | 适用 |
|---|
tiny | 39M | 弱(同音字/术语易错) | 最快 | 快速预览、英文清晰口播 |
small | 244M | 尚可 | 快 | 一般英文 |
medium | 769M | 好 | 中 | 较高要求 |
turbo(默认) | 809M | 强,接近 large | 比 large 快 ~8× | 多数场景的最佳平衡 |
large-v3 | 1550M | 最好 | 慢 | 中文/嘈杂/术语密集、要最高精度 |
经验:绝大多数场景默认 turbo,中文也包括在内。 turbo 在长音频上稳。tiny 会把 three→free、embedding→bedding 这类近音听错,中文错得更多。
⚠️ large-v3 有重复循环坍缩风险,不要无脑选它。 实测一段 22 分钟中文播客,large-v3 在两段真实语音上退化成"同一句无限复读"(8:42→18:13 复读 569 次 + 18:42→22:43 复读 241 次),62% 的字幕是幻觉;同一段音频 turbo 完整正确转出。large-v3 只在 turbo 明显听错、且你会跑验证门核对时才用。模型越大 ≠ 转录越好。
验证产出(必做,别只看开头)
这个 skill 最容易翻的车:whisper 在长段语音/静音/音乐上会退化成"同一句无限复读"的幻觉,或整段漏转。只扫开头几句一切正常,中间/结尾可能整段是垃圾。 所以转完必须验证,不能只采样开头就宣布完成。
脚本已内置自动验证;也可手动对任意 SRT/JSON 跑:
python3 "$SKILL_DIR/scripts/verify_transcript.py" 转录.json --audio 原音频.wav [--reference 参考.srt]
三道门(全部来自 whisper 自己的 JSON 元数据,无需额外模型):
- 覆盖率缺口 — 音频时长 vs 末条字幕结束时间。缺口大 ⇒ 漏转/被错误截断。
- 重复循环 — 连续相同文本 ≥4 条,或某句占比 >4% ⇒ 复读幻觉(报出时间区间)。
- 低置信聚集 —
compression_ratio>2.4(whisper 内置重复度指标)/ avg_logprob 过低 / no_speech_prob 过高。
退出码 2=FAIL。FAIL 时绝不直接交付:换 turbo 重跑、或先 ffmpeg 去头尾静音、或人工核对该段。有参考答案时加 --reference 比对覆盖时长。
教训:删/截字幕前,先确认那段到底有没有真实语音(对 ground-truth 或听原音),别把"我以为是静音/音乐"当依据 —— 复读幻觉常常正是发生在真实语音上。
注意事项(踩过的坑)
- 不要给
--language auto:mlx_whisper 不接受字面 auto;要自动检测就不传 --language。脚本已处理(lang=auto 时省略该参数)。
--output-format 不接受逗号列表:用 all 一次出全部格式,或多次调用。脚本用的是 all。- 脚本会先用 ffmpeg 统一转 16kHz 单声道 wav 再喂给 whisper,规避各种容器/编码解码问题。
- 输出文件名取自输入名:脚本把中间 wav 命名为
<原名>.wav,所以产物就是 <原名>.txt/.srt/...。
模型存放位置
tiny / small / medium / turbo 都在 HuggingFace 标准缓存 ~/.cache/huggingface/hub/(models--mlx-community--whisper-*),首次用某规格自动下载、之后复用,无需任何配置,mlx_whisper 自动发现。
large-v3 例外(Xet 坑):它的 weights.npz(~2.9GB)走 HF 的 Xet 后端,huggingface_hub 在受限网络下会卡死,直连 CDN 也频繁断流。所以本 skill 不让 mlx_whisper 自己拉,而是:
- 首次请求
large-v3 且本地缺失时,自动调用 scripts/fetch-large-v3.sh,经 hf-mirror.com 镜像 + curl 断点续传稳健下载到本地目录,再以本地路径加载——这条绕坑路径已固化在脚本里,任何人 clone 后都能复现。
- 默认目录
~/models/whisper-large-v3-mlx/,用 WHISPER_LARGE_V3_DIR 覆盖;镜像用 HF_ENDPOINT 覆盖(默认 https://hf-mirror.com)。
- 也可手动预下载:
bash scripts/fetch-large-v3.sh [目标目录]。
网络通畅、不需要镜像的用户,把 WHISPER_LARGE_V3_DIR 指向空目录后照样能下;或直接用 turbo(接近 large、快 ~8×),多数场景够用。
依赖
mlx_whisper(pip install mlx-whisper)— Apple Siliconffmpeg(brew install ffmpeg)yt-dlp(pip install yt-dlp)— 仅处理 URL 时需要
