parakeet

Parakeet：本地语音转文本（MLX）

两个 MLX 引擎都在 Metal GPU 上完全离线运行。每个脚本都是带内联依赖的 uv run --script 文件，因此无需维护 venv。

引擎	模型	优势	劣势
parakeet	mlx-community/parakeet-tdt-0.6b-v2	速度快，提供逐词置信度，遇到非语音时返回空结果	不支持词汇偏置
qwen3	mlx-community/Qwen3-ASR-1.7B-8bit	开放权重模型中 WER 最佳（4.95，Open ASR Leaderboard 2026-09-19），支持 hotwords	遇到音效时会幻觉出感叹词；没有 token 上限时可能循环输出

对所有将作为证据的内容都运行这两个引擎。它们的结果分歧可作为置信度信号。

命令

S=~/.claude/skills/parakeet/scripts

# One file -> text on stdout (parakeet engine; --engine both prints status<TAB>parakeet<TAB>qwen3)
$S/transcribe.py clip.wav

# Batch: files or directories -> JSONL manifest (both engines by default)
$S/batch_transcribe.py clips/ --out manifest.jsonl
$S/batch_transcribe.py clips/ --context-file vocab.txt       # Qwen3 hotwords, one per line
$S/batch_transcribe.py a.wav --engine qwen3 --language auto  # or a name / ISO code (fr, French)
$S/batch_transcribe.py a.wav --engine parakeet --beam 4      # beam search

# Setup check (fast), or full round trip with synthesized speech (downloads ~5 GB once)
$S/check_setup.py
$S/check_setup.py --load

# Terminal dictation: record until Enter, then transcribe
$S/dictate.py

# OpenAI-compatible server (warm models; model ids: parakeet-tdt-0.6b, qwen3-asr)
$S/parakeet_server.py --port 8384 --preload parakeet

格式：任何 ffmpeg 能解码的格式（wav，包括 8-bit/ADPCM、mp3、m4a、flac、ogg、aac、webm、aiff）。

批量输出与状态

每条 JSONL 记录都包含源文件的 sha256、duration_s、sample_rate_src、codec、解码检查结果（samples、peak_dbfs、gain_db、length_mismatch），以及每个引擎的 text、model 和 HF revision。Parakeet 会添加 words[{w,start,end,conf}] 和 min_conf。Qwen3 会添加 truncated 和 echo_stripped（触发时还会包含 raw_text）。使用 --engine both 时，每条记录都会有一个 status：

状态	含义	操作
agreed	规范化后的转录文本一致，Parakeet min_conf ≥ --min-conf（0.5），且未设置任何标记	结果得到佐证；仍需将其作为 ASR 证据引用
needs_listen	其他任何包含词语的情况：结果不一致、置信度低或缺失、Qwen3 结果被截断或剥除了回声、长度不匹配	引用前由人工聆听
sfx_likely	Parakeet 结果为空；Qwen3 只生成了感叹词（“Oh.”、“Whoa.” 或循环重复这些词），或只复述了其热词	视为非语音
silent	两个引擎的结果都为空	非语音
error	解码或转录失败；error 包含 ffmpeg 给出的原因	修复文件或将其排除

看似合理语音内容的单词行（“Fire!”、“Okay.”）绝不会被标记为 sfx_likely。 规范化会将文本转为小写、去除标点，并统一数字词（“One” → “1”）和拼写变体（“manoeuvre” → “maneuver”）。

使用 --out 时，记录会写入 <out>.partial。仅在运行完成后，该文件才会被重命名；<out>.meta.json 会记录参数、模型修订版本、软件包版本、热词列表哈希、脚本的 sha256、计时信息和计数。单个文件出错不会中止整个批次，但只要有任何片段出错，退出状态就为 1。架构和 API 说明：references/parakeet-api.md。

短音频片段与旧游戏音频

在 351 个 Star Wars Rebellion WAVE 资源上测得：276 个为 8 位 PCM，71 个为 16 位，采样率均为 11,025 Hz；另有 4 个为 44.1 kHz 的 16 位音频。

• 填充。 时长不足 2 s 的片段会在两端各添加 0.75 s 静音。在 30 个短语音片段中，这没有漏掉任何词。对于短 TACTICAL SFX，Parakeet 的幻觉从 42 个片段中的 23 个降到了 2 个（未填充时：“我，我，我。”“哈哈哈哈！”）。使用 --pad 0 可禁用。
• Qwen3 循环。 在一个 2.3 s 的 SFX 片段上，Qwen3 输出了约 4.7 分钟的“哦，哦，哦，……”，直至达到其默认的 8192 个 token 上限。现在 token 数上限设为 12 * duration_s + 32，达到上限的片段会标记为 truncated。
• 热词是有针对性的工具，不是默认选项。 在同一语料上测得：
  • 包含所有游戏 UI 字符串的 1,196 项词条会让 Qwen3 在 SFX 上复述列表（“0 点可用，1 个建造船坞，……”），并使预填充时间翻倍。系统会检测整段输出的复述（echo_stripped），但绝不会移除真实语音中的词语。
  • 一份包含 43 个专有名词的精简提示词让 Qwen3 在全部 63 个 SFX 片段上都返回空结果，这是最清晰的语音／SFX 区分。在语音上，它将“Censors”改成了“Sensors”，但也把三句“There is”改成了“That is”（Parakeet 和未使用提示词的 Qwen3 都识别为“There is”）。
  • 工作流：先不使用热词运行，然后仅对 needs_listen 片段使用一份简短提示词重新运行，将结果作为第三种意见。若目标是筛查 SFX，则在完整运行中使用提示词。
• 音量。 ffmpeg 会将音频重采样为 16 kHz 单声道，并将峰值归一化到 -1 dBFS。低于 -60 dBFS 的音频不会放大，因为放大底噪会导致幻觉。

长音频

超过 5 分钟的录音会在每个约 60 s 的位置附近，选取最安静的 100 ms 帧处切分，每个片段独立解码。不会使用 parakeet-mlx 0.5.2 自带的重叠分块器：在一个 418 s 的测试文件上，它在分块边界漏掉了一句话，并重复了另外两句。分段处理的结果与逐片段真实标注相比，词语相似度为 0.985，没有漏行或重复行，速度为实时的 88 倍。Qwen3 使用 mlx-audio 的内部切块（20 分钟窗口）。

性能（M4 Max，36 GB）

运行方式	结果
仅 Parakeet，351 个片段／975 s 音频	44 s（实时的 22 倍；逐片段 ffmpeg 处理占主要耗时）
两种引擎，351 个片段	91 s（实时的 11 倍）：270 个一致，20 个 needs_listen，61 个 sfx_likely
两种引擎 + 43 项提示词	124 s（实时的 8 倍）

这些耗时来自各次运行自身的摘要行。较新的运行也会将其记录在 .meta.json 中。在双引擎运行中，20 个片段标记为 needs_listen：5 个 TACTICAL SFX 或语音判断（包括“Yeah.”和“Okay.”，因其可能是合理的单词句而暂时保留），以及 15 句语音。在这 15 句中，有 13 句 Parakeet 的识别不合理，而 Qwen3 的识别更合理（“Goal Group”与“Gold Group”，“Deaths are approaching”与“Death Star approaching”）。目前还没有人听过这些片段，因此 Qwen3 的文本只是有力的推测，并非真实标注。有一个片段两者都识别错误（将“Sensors”识别成“Census”／“Censors”），另有一个片段仅格式不同（“Task Force V”与“Five”）。这些语句的 Parakeet min_conf 为 0.65–0.98，因此仅凭置信度会将它们判定为通过。

不要同时运行两个批处理任务：它们共用 GPU，而一次资源竞争导致运行时间延长了 5 倍。首次冷启动时，每个模型会向 ~/.cache/huggingface/hub 下载约 2.5 GB。

Handy（按住说话听写）

Handy 支持系统范围的按住说话功能（Option-Space）。使用 brew upgrade --cask handy 升级到 0.9.7 或更高版本，然后在 Settings 中选择模型。handy-computer 组织发布了 parakeet-unified-en-0.6b-gguf（NVIDIA 2026-04，在一个模型中支持离线和流式处理）；请确认你的 Handy 版本是否列出了该模型。对于实时多语言流式处理，nvidia/nemotron-3.5-asr-streaming-0.6b（2026-06，支持 40 种语言环境）是目前最新的 NVIDIA 模型。Handy 用于听写，不适用于批量取证。

旧版

~/Programming/parakeet-dictate（NeMo/PyTorch 菜单栏应用，Voxtral 后端）已被取代，且没有 venv。这里没有任何内容依赖它或 PARAKEET_HOME。