86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
---
|
||
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 | 单字频率(≥20字) + 字符串周期(≥10次) + n-gram 去重率 + 字符密度，冷启动重转写 [详情](references/token-repetition-loop.md) |
|
||
| **空段修复** | 补回 Whisper 漏转写的大段空白 | 检测空文本段（≥15s）且非 VAD 静音区才冷启动重写；仍为空则删除 [详情](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 漏转写空白段的根因与修复方案
|