testing-whisper

用途

testing-whisper 用于对 WAV 音频文件进行语音可懂度测试。它调用 OpenAI Whisper 对音频进行转写，报告语音是否清晰可懂，并可选地与预期文本进行对比，计算词错误率（WER）。该技能主要面向 TTS（文本转语音）输出质量验证、质量门禁和回归测试等场景。

主要能力

使用 OpenAI Whisper 转写一个或多个 WAV 音频文件。
支持通过 --expected 参数提供预期文本，并计算词错误率（WER）。
支持 --json 参数以 JSON 格式输出结果，便于程序化处理。
输出每个文件的转写文本、时长、RMS、峰值、静音比例等音频质量指标。
支持批量测试多个 TTS 变体，生成对比结果。

使用方式

安装

Whisper 通过 uv 工具安装：

uv tool install openai-whisper

由于目标机器可能缺少 ffmpeg，技能要求始终使用 Python API 方式，通过 scipy 加载 WAV 文件，从而绕过 ffmpeg 依赖。

运行转写

使用以下命令执行转写脚本：

uv run --no-project --with openai-whisper --with scipy --python 3.11 \
  python3 ~/.claude/skills/testing-whisper/transcribe.py \
  [--model tiny|base|small|medium|large-v3] \
  [--language en] \
  [--expected "expected text"] \
  [--json] \
  file1.wav [file2.wav ...]

参数说明

--model：Whisper 模型大小，默认 large-v3。
--language：语言提示，默认 en。
--expected：预期转写文本。提供后会计算词错误率（WER）。
--json：以 JSON 格式输出结果，而非人类可读文本。
位置参数：一个或多个 WAV 文件路径。

模型选择

模型	显存	使用场景
large-v3	~10 GB	默认。TTS 评估、质量门禁、回归测试
medium	~5 GB	GPU 显存受限，精度尚可
small	~2 GB	仅用于快速冒烟测试
base	~1 GB	不推荐用于 TTS——幻觉率高
tiny	~1 GB	不推荐用于 TTS——不可靠

对于 TTS 质量验证，应使用 large-v3。较小的模型在合成语音上会产生幻觉或漏词，不适合判断输出质量。

在相同的 Qwen3-TTS 1.7B 声音克隆输出上观察到：

large-v3："That's one tank. Flash attention pipeline."（关键短语被捕获）
base："That's one thing, flash attention pipeline."（接近但产生了幻觉）

对于质量较差的 0.6B 输出，base 幻觉出 "Charging Wheel"，而 large-v3 给出 "Flat, splashes."，如实反映较差的质量，而不是编造看似合理的词。

输出格式

对每个文件，打印：

filename.wav:
  transcription: "Hello world, this is a test."
  duration: 2.96s
  rms: 0.0866
  peak: 0.6832
  silence: 49.2%
  [wer: 0.0%]  (if --expected provided)

结果解读

转写结果	含义
与预期文本匹配	音频清晰且正确
部分匹配	音频包含部分语音，但存在质量问题
空字符串 ""	音频不可懂（噪声、静音或垃圾内容）
幻觉文本	模型在噪声中听到了某些内容（Whisper 常见，尤其是较小模型）

音频质量指标

RMS < 0.01：基本为静音。
silence > 80%：大部分为静音，可能没有语音。
peak < 0.05：非常安静，可能不包含有用音频。

TTS 特定模式

声音克隆的 TTS 输出通常具有以下特征：

开头含糊、结尾清晰：在短参考音频上进行 ICL 声音克隆时常见。模型需要几帧才能“锁定”目标声音。
关键短语保留：即使 WER 较高，领域特定术语（如 "flash attention pipeline"）通常仍能清晰呈现。
较小模型产生更差的音频：0.6B 模型产生的输出可懂度显著低于 1.7B——Whisper 会反映这一点。

批量测试（TTS 变体对比）

当针对预期文本测试多个 TTS 输出时：

uv run --no-project --with openai-whisper --with scipy --python 3.11 \
  python3 ~/.claude/skills/testing-whisper/transcribe.py \
  --expected "Hello world, this is a test." \
  variant1.wav variant2.wav variant3.wav

这会生成一个对比表，显示哪些变体产生了可懂的语音。

Docker / NGC 容器使用

在 NGC 容器内的 GPU 机器上测试时（例如用于 CUDA flash-attn 构建），ffmpeg 不可用且 apt 可能很慢。有两种变通方法：

静态 ffmpeg 二进制文件（快速，无需 apt）：

curl -sL https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-arm64-static.tar.xz \
  | tar xJ --strip-components=1 -C /usr/local/bin/ --wildcards "*/ffmpeg" "*/ffprobe"
pip install openai-whisper

使用 scipy 加载器（本脚本默认——无需 ffmpeg）：

pip install openai-whisper scipy
python3 ~/.claude/skills/testing-whisper/transcribe.py --model large-v3 output.wav

脚本通过 scipy 直接加载 WAV 文件，完全绕过 Whisper 的 ffmpeg 依赖。这适用于 WAV 文件（TTS 输出的标准格式）。

适用场景

TTS 语音合成输出的可懂度验证。
语音质量门禁与回归测试。
多个 TTS 变体之间的批量对比。
在缺少 ffmpeg 的环境（如 NGC 容器）中对 WAV 文件进行转写。

限制

仅支持 WAV 格式音频文件。
默认模型 large-v3 需要约 10 GB 显存。
较小模型（base、tiny）在 TTS 评估中不可靠，容易产生幻觉。
未提供关于收费、价格或平台支持范围的信息。