105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# 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
|