# Generate Transcript

> 本地把音频/视频文件或在线视频 URL 转录成文字稿(txt/srt/vtt/json)。基于 Apple Silicon 上的 mlx_whisper,支持中英文等多语言、自动语言检测、模型规格选择。当用户想要"转录""生成字幕/文稿/transcript""把这段音频/视频转成文字""提取台词""做 SRT 字幕",或给出一个音视频文件/YouTube 等链接要文字内容时使用。

- **Type:** Skill
- **Install:** `agentstack add skill-crazynomad-skills-generate-transcript`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [crazynomad](https://agentstack.voostack.com/s/crazynomad)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [crazynomad](https://github.com/crazynomad)
- **Source:** https://github.com/crazynomad/skills/tree/master/generate-transcript

## Install

```sh
agentstack add skill-crazynomad-skills-generate-transcript
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# generate-transcript

在本机(Apple Silicon / MLX)把音频、视频或在线视频链接转录成文字稿。纯本地、免费、不上传。

这是 ASR(语音识别)这一步;**它不做翻译**。要"翻译成另一种语言"时,先用本 skill 转录,再由你(Claude)翻译文字,需要配音则交给 IndexTTS2(TTS)。

## 何时用

- "把这段音频/视频转成文字" / "生成字幕" / "做个 SRT"
- 给了一个本地 `.mp3/.wav/.m4a/.mp4/...` 文件要文稿
- 给了一个 YouTube/Bilibili 等链接,只要里面的话

## 怎么用

统一调用脚本(`$SKILL_DIR` 为本 skill 目录):

```bash
bash "$SKILL_DIR/scripts/transcribe.sh"  [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
# 本地文件, 自动语言, turbo
bash "$SKILL_DIR/scripts/transcribe.sh" talk.mp3

# 中文音频, 要最高精度
bash "$SKILL_DIR/scripts/transcribe.sh" 讲座.m4a large-v3 zh ./out

# YouTube 链接, 英文, 默认 turbo
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 跑:

```bash
python3 "$SKILL_DIR/scripts/verify_transcript.py" 转录.json --audio 原音频.wav [--reference 参考.srt]
```

三道门(全部来自 whisper 自己的 JSON 元数据,无需额外模型):
1. **覆盖率缺口** — 音频时长 vs 末条字幕结束时间。缺口大 ⇒ 漏转/被错误截断。
2. **重复循环** — 连续相同文本 ≥4 条,或某句占比 >4% ⇒ 复读幻觉(报出时间区间)。
3. **低置信聚集** — `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 Silicon
- `ffmpeg`(`brew install ffmpeg`)
- `yt-dlp`(`pip install yt-dlp`)— 仅处理 URL 时需要

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [crazynomad](https://github.com/crazynomad)
- **Source:** [crazynomad/skills](https://github.com/crazynomad/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-crazynomad-skills-generate-transcript
- Seller: https://agentstack.voostack.com/s/crazynomad
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.