---
name: whisper-transcribe
description: "使用 mlx-whisper（Apple Silicon 优化）转写音频。支持逐字时间轴、智能断句、静音过滤、幻觉清理。提示词必填，按场景构建。"
---

# Whisper Transcribe (mlx-whisper)

## 基本用法

```bash
PYTHONPATH="" ~/.local/venvs/default/bin/python3 \
  ~/.hermes/skills/productivity/whisper-transcribe/scripts/whisper_transcribe.py \
  <音频> --initial-prompt "<提示词>" --language ja --output-format all
```

> Hermes TUI 环境需加 `PYTHONPATH=""`，否则 Hermes 自身 venv 的 numpy C 扩展与 Python 3.12 不兼容。

视频先提音频再转写更稳定：
```bash
ffmpeg -y -i 输入.webm -af "loudnorm=I=-16:TP=-1.5:LRA=11" -ar 16000 -ac 1 -f wav 输出.wav
PYTHONPATH="" ~/.local/venvs/default/bin/python3 \
  ~/.hermes/skills/productivity/whisper-transcribe/scripts/whisper_transcribe.py \
  输出.wav --initial-prompt "..." --language ja --output-format all
```

## 参数

| 参数 | 默认 | 说明 |
|------|------|------|
| `--model` | `turbo` | turbo / small / medium |
| `--language` | `ja` | 语言代码 |
| `--output-format` | `txt` | txt / srt / json / all |
| `--initial-prompt` | **必填** | 提示词，按场景列出关键词 |
| `--max-line-duration` | `5.0` | 单行字幕最大秒数 |
| `--no-word-ts` | off | 禁用逐字时间轴 |
| `--no-smart-split` | off | 禁用智能断句 |
| `--no-vad-filter` | off | 禁用静音过滤 |
| `--no-clean` | off | 禁用幻觉清理 |
| `--verbose` | off | 显示进度 |

## 字幕质量增强（默认开启）

| 功能 | 作用 | 原理 |
|------|------|------|
| **逐字时间轴** | 获得每个词的精确起止时间 | `word_timestamps=True` |
| **智能断句** | 修复黏连（一句字幕几秒不消失） | 检测词间停顿 >0.3s，达 `--max-line-duration` 强制切断 |
| **静音过滤** | 剔除音乐段的幽灵字幕 | ffmpeg `silencedetect` 预扫描，字幕 70% 以上在静音区则丢弃 |
| **幻觉清理** | 删除尾部复读幻觉 | 检测末尾连续重复 / 填充词 |
| **循环检测** | 修复单字 & 短句 token loop | 单字频率 + 字符串周期性检测，冷启动重转写；逆序遍历防索引漂移 [详情](references/token-repetition-loop.md) |
| **空段修复** | 补回 Whisper 漏转写的空白段 | 检测空文本段（≥2s），冷启动重转写；重试仍为空则删除 [详情](references/empty-segment-gap.md) |

## 提示词定制

**每次根据音频内容从零构建，不要套模板。** 决定转写质量最关键的一步。

### 构建方法

1. 从标题提取：节目名、期号、嘉宾、主题关键词
2. 按场景补充术语：声优访谈→作品/角色名，技术讲座→技术栈，音乐现场→乐队/曲名
3. 写成逗号分隔的 10-20 个关键词

### 示例

```bash
# 日语播客（嘉宾浅見春那，主题婚礼）
--initial-prompt "野良犬ラジオ、浅見春那、結婚式、あいのなかで、ゲスト、トーク番組、声優、川瀬光平、パーソナリティ、対談"

# 中文技术会议
--initial-prompt "项目复盘、技术评审、架构设计、前端、后端、API、数据库、性能优化"

# 日语音乐现场 MC
--initial-prompt "ライブ、MC、バンド、メンバー紹介、曲紹介、挨拶、観客、拍手"
```

> 专有名词（人名、乐队名）务必写进 prompt。例如「浅見春那」无 prompt → 「浅見春菜」。  
> **注意**：prompt 能大幅提高准确率，但非常用汉字（如「那」）仍可能被 Whisper 的声学模型覆盖——prompt 是引导而非强制。对此类人名需在后期手动修正。

## 关键技巧

- mlx-whisper 内部自带滑动窗口，长音频自动稳定处理，无需手动分段
- 脚本自动做 16kHz 降采样 + 响度标准化 + 幻觉清理
- 默认输出 SRT 已智能断句 + 静音过滤，可直接导入剪辑软件
- 修改脚本注意陷阱：浮点取整用 `int(round(x * 1000))`、silencedetect 结尾配对不要用 `zip()`、除零防护、负数时间戳 clamp
- [Token Repetition Loop 诊断修复](references/token-repetition-loop.md) — 长音频中单字循环幻觉的根因与局部重转写方案
- [Empty Segment Gap 诊断修复](references/empty-segment-gap.md) — Whisper 漏转写空白段的根因与修复方案