# Whisper Transcribe

[mlx-whisper](https://github.com/ml-explore/mlx-examples/tree/main/whisper) 增强版字幕生成工具。
Apple Silicon 本地运行，无需 GPU 服务器或第三方 API。

## 特性

- **本地推理** — MLX 框架，Apple Silicon 原生加速，无外部 API 依赖
- **逐字时间轴** — 每个词的精确起止时间，支持智能断句
- **静音过滤** — ffmpeg `silencedetect` 预扫描，剔除音乐段的幽灵字幕
- **幻觉清理** — 检测尾部复读/填充词，自动清除
- **循环检测** — 检测单字/短句级 token loop，冷启动重转写修复
- **空段修复** — 补回 Whisper 漏转写的空白段
- **多种输出** — txt / srt / json

## 依赖

- macOS (Apple Silicon)
- [mlx-whisper](https://pypi.org/project/mlx-whisper/)
- ffmpeg / ffprobe

```bash
pip install mlx-whisper
brew install ffmpeg
```

## 用法

```bash
python3 whisper_transcribe.py <音频文件> \
  --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 | 显示进度 |

### 提示词

提示词决定转写质量。每次根据音频内容从零构建，不套模板。

**构建方法：** 从标题提取节目名、期号、嘉宾、主题 → 按场景补充术语 → 写成逗号分隔的 10-20 个关键词。

```bash
# 日语播客
--initial-prompt "野良犬ラジオ、浅見春那、結婚式、ゲスト、トーク番組、声優"

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

> 专有名词务必写进 prompt。prompt 能大幅提高准确率，但不能完全覆盖非常用汉字。

### 视频预处理

```bash
ffmpeg -y -i 输入.webm \
  -af "loudnorm=I=-16:TP=-1.5:LRA=11" \
  -ar 16000 -ac 1 -f wav 输出.wav
```

## 输出

默认与输入文件同目录。支持格式：

- **txt** — 纯文本，每行一段
- **srt** — 标准字幕格式，含序号和时间轴
- **json** — 完整数据结构，含逐字时间轴
- **all** — 同时输出以上三种

## 字幕质量增强

| 功能 | 原理 |
|------|------|
| **逐字时间轴** | `word_timestamps=True` |
| **智能断句** | 词间停顿 >0.3s 拆分，`max_line_duration` 强制切断 |
| **静音过滤** | ffmpeg 预扫静音区，70%+ 在静音内的段丢弃 |
| **幻觉清理** | 从尾部向前检测重复段和填充词 |
| **循环检测** | 单字频率 / 字符串周期性 / n-gram 去重率，冷启动重转写 |
| **空段修复** | 15 秒+长空白且非 VAD 静音区才重试，仍为空则删除 |

## 技术细节

- 内部使用 `mlx-community/whisper-large-v3-turbo`（fp16，~1.5GB）
- mlx-whisper 自带滑动窗口，无需外部手动分段
- 预处理自动做 16kHz 降采样 + 响度标准化
- 逆序遍历替换区间，防止索引漂移 Bug

## License

MIT

---

Created by [KISEKI](https://git.gfgt.fun/gitroot) via [Hermes Agent](https://hermes-agent.nousresearch.com).