Whistle 是一款只有 16.9 MB 的端侧语音识别（speech-to-text）模型，无需 GPU、无需任何依赖，通过命令行即可完成音频转写、逐词时间戳对齐，还能用一条needle whistle compare命令把 Whistle 和 Whisper 放在同一段音频上直接对比。本文带你从零上手，把这条命令行工作流完整跑通。

为什么值得试试 Whistle 🎙️

Whistle 面向手机、可穿戴设备、机器人、汽车和微控制器等场景，特点是"小"和"本地"：

• 体积极小：整个模型就是单个 whistle.cact 文件，仅 16.9 MB
• 零依赖运行：自带 C++ / WebAssembly 运行时，不依赖 GPU 和框架
• 多语言支持：英语、德语、法语、西班牙语、意大利语、荷兰语、波兰语共 7 种语言，默认自动检测语言
• 行为可靠：输入静音时返回空文本，而不是"编造"一句话

模型细节（16 kHz 采样率、单次 30 秒窗口、80 ms 帧长、cactus-quants 128 组量化等）都写在 config.json 里，可以按需查阅。

第一步：安装并跑通你的第一条转写命令 🚀

Whistle 的 Python 侧由cactus-needle包驱动：

pip install cactus-needle

16 kHz 的 WAV 或原始采样直接就能用；如果需要其它采样率或麦克风采集，再额外安装[mic]扩展即可。安装完成后，一行 Python 就能拿到转写结果：

import needle print(needle.transcribe("clip.wav")["text"]) # turn off the kitchen lights

每次调用都会返回文本、检测到的语言、首 token 延迟（毫秒）以及解码 token 速度。引擎和权重只会在首次运行时下载一次，之后走本地缓存。

第二步：一条命令拿到逐词时间戳 ⏱️

Whistle 对每个词都给出开始时间、结束时间和置信度，且时间戳直接来自解码器自身注意力对齐，可用于字幕高亮、按词跳转、精准剪辑等场景。

先下载对应平台的引擎二进制和模型文件：

needle download macos-arm64 needle download whistle

然后一条命令完成转写 + 时间戳输出：

./macos-arm64/needle --model whistle.cact --audio clip.wav --audio-word-timestamps

几个常用参数值得记住：

在 Python 侧等价写法是word_timestamps=True。如果你要处理的人名、地名、产品词经常识别错，用keywords=[...]传入词表，搜索阶段会优先匹配这些词——这就是官方的 keyword biasing 能力。

第三步：needle whistle compare 一键对比 Whisper 🆚

这是最省事的"考试"方式：

needle whistle compare

该命令会把Whistle、Whisper 和 Moonshine放在同一段音频上并排输出结果，直观看到差异。

官方在完整测试集上的 WER 基准（用 Whisper 的 normalizer 计分）显示：Whistle 在 86,174 条语句上完成评测，WER 与速度表现对得上同量级的 Whisper 与 Moonshine；在 Apple M4 Pro 上 10 秒音频的首 token 时延和 token 解码速度也在同一档。详细数字与统计口径说明见 README.md。

实用小贴士 📌

• 指定语言：自动检测不准时，用language="de"强制指定，比让模型猜更稳
• 长音频：30 秒以内单次直出，超过 30 秒会自动分窗处理；实时流可以用--audio-stream一直挂着
• 嵌入向量：needle.Whistle()支持embed(audio)，输出编码器嵌入（每 80 ms 一帧），可直接用于语音检索，完全不用解码文本
• 与 Needle 混跑：同一个引擎既能转语音又能跑文本对话，needle --model needle3.cact --model whistle.cact --audio clip.wav一次调用同时输出工具调用和语音字段

仓库文件速查 🗂️

一句话总结：pip install cactus-needle装好环境，needle whistle compare看差距，--audio-word-timestamps拿时间戳——Whistle 的端侧语音识别命令行工作流，三条命令就跑通了。