whisper-transcribe/SKILL.md

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

Whisper Transcribe (mlx-whisper)

基本用法

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 不兼容。

视频先提音频再转写更稳定：

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	单字频率(≥20字) + 字符串周期(≥10次) + n-gram 去重率 + 字符密度，冷启动重转写 详情
空段修复	补回 Whisper 漏转写的大段空白	检测空文本段（≥15s）且非 VAD 静音区才冷启动重写；仍为空则删除 详情

提示词定制

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

构建方法

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

示例

# 日语播客（嘉宾浅見春那，主题婚礼）
--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 诊断修复 — 长音频中单字循环幻觉的根因与局部重转写方案
• Empty Segment Gap 诊断修复 — Whisper 漏转写空白段的根因与修复方案