Whisper Transcribe

mlx-whisper 增强版字幕生成工具。 Apple Silicon 本地运行，无需 GPU 服务器或第三方 API。

特性

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

依赖

• macOS (Apple Silicon)
• mlx-whisper
• ffmpeg / ffprobe

pip install mlx-whisper
brew install ffmpeg

用法

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 个关键词。

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

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

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

视频预处理

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 via Hermes Agent.