parakeet

Parakeet：ローカル音声テキスト変換（MLX）

2 つの MLX エンジンが Metal GPU 上で完全オフラインで動作します。各スクリプトは依存関係をインラインで指定した uv run --script ファイルなので、管理する仮想環境はありません。

エンジン	モデル	強み	弱み
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	効果音に対して間投詞を幻覚することがある。トークン数の上限がないとループすることがある

証拠となるものはすべて、両方のエンジンで実行してください。両者の不一致が信頼度の指標になります。

コマンド

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 の理由が格納されます	ファイルを修正するか、対象から除外してください

音声としてあり得る 1 語の行（「Fire!」「Okay.」など）が sfx_likely になることはありません。 正規化では小文字に変換し、句読点を除去し、数詞（「One」→「1」）と綴りの異形（「manoeuvre」→「maneuver」）を統一します。

--out を指定すると、レコードは <out>.partial に順次書き込まれます。このファイルは実行が完了した場合にのみ名前が変更され、<out>.meta.json にはパラメーター、モデルのリビジョン、パッケージのバージョン、ホットワードリストのハッシュ、スクリプトの sha256、所要時間、件数が記録されます。問題のあるファイルが 1 つあってもバッチは終了しませんが、クリップでエラーが発生した場合、終了ステータスは 1 になります。スキーマと API に関する注記：references/parakeet-api.md。

短いクリップとレガシーゲームの音声

Star Wars Rebellion の WAVE リソース 351 件で測定したところ、276 件が 8-bit PCM、71 件が 16-bit PCM で、いずれも 11,025 Hz でした。さらに、16-bit、44.1 kHz のものが 4 件ありました。

• パディング。 2 秒未満のクリップには、前後それぞれ 0.75 秒の無音を追加します。短い音声クリップ 30 件では、単語の欠落はありませんでした。短い TACTICAL SFX での Parakeet の幻覚は、42 件中 23 件から 2 件に減りました（パディングなしの場合：「Me, me, me.」「Ha ha ha ha!」）。無効にするには --pad 0 を指定します。
• Qwen3 のループ。 2.3 秒の SFX クリップ 1 件で、Qwen3 は約 4.7 分間「Oh, oh, oh, ...」を生成し、デフォルトの上限である 8192 トークンに達しました。現在はトークン数を 12 * duration_s + 32 に制限し、上限に達したクリップには truncated のマークを付けます。
• ホットワードは対象を絞って使うツールであり、デフォルトで使うものではありません。 同じコーパスで測定しました。
  • ゲーム内のすべての UI 文字列を含む 1,196 語のリストを指定すると、Qwen3 は SFX でそのリストを読み上げ（「0 Points Available, 1 Construction Yards, ...」）、プリフィル時間も 2 倍になりました。出力全体の読み上げは検出されます（echo_stripped）が、実際の音声内の単語が削除されることはありません。
  • 固有名詞に絞った 43 語の用語集を指定すると、Qwen3 は 63 件すべての SFX クリップで空の出力を返しました。これは音声と SFX を分けるうえで最も明確な結果です。音声では「Censors」が「Sensors」に変わりましたが、「There is」の行が 3 件、「That is」に変わりました（Parakeet とホットワードなしの Qwen3 は「There is」で一致しています）。
  • ワークフロー：まずホットワードなしで実行し、その後、needs_listen のクリップだけに小規模な用語集を指定して再実行し、第三の意見として使います。SFX のトリアージが目的の場合は、全体の実行で用語集を使います。
• 音量レベル。 ffmpeg で 16 kHz のモノラルにリサンプリングし、ピークを -1 dBFS に正規化します。-60 dBFS 未満の音声は増幅しません。ノイズフロアを増幅すると幻覚につながるためです。

長い音声

5 分を超える録音は、約 60 秒ごとに最も静かな 100 ms のフレームで分割し、各セグメントを個別にデコードします。parakeet-mlx 0.5.2 独自のオーバーラップ式チャンク分割は使いません。418 秒のテストファイルでは、チャンク境界で文が 1 つ欠落し、別の文が 2 つ重複したためです。セグメント分割する方法では、クリップごとの正解データとの単語類似度が 0.985 で、行の欠落や重複もなく、リアルタイムの 88 倍の速度でした。Qwen3 では mlx-audio の内部チャンク分割（20 分のウィンドウ）を使います。

パフォーマンス（M4 Max、36 GB）

実行内容	結果
Parakeet のみ、351 クリップ／音声 975 秒	44 秒（リアルタイムの 22 倍。クリップごとの ffmpeg 処理が主な所要時間）
両エンジン、351 クリップ	91 秒（リアルタイムの 11 倍）：一致 270 件、needs_listen 20 件、sfx_likely 61 件
両エンジン＋43 語の用語集	124 秒（リアルタイムの 8 倍）

これらの所要時間は、各実行のサマリー行から取得しています。新しい実行では .meta.json にも記録されます。両エンジンを使った実行では、20 件のクリップが needs_listen でした。内訳は、TACTICAL SFX か音声か判定が必要な発話が 5 件（「Yeah.」や「Okay.」など、単語 1 つの発話として妥当なため保留）と、音声の行が 15 件です。その 15 件のうち 13 件では、Parakeet の解釈は不自然で、Qwen3 の解釈のほうが妥当でした（「Goal Group」と「Gold Group」、「Deaths are approaching」と「Death Star approaching」）。これらのクリップはまだ誰も聴いていないため、Qwen3 のテキストは有力な仮説であって、正解データではありません。1 件では両方とも誤っており（「Sensors」を「Census」／「Censors」と認識）、もう 1 件は表記のみが異なっていました（「Task Force V」と「Five」）。これらの行に対する Parakeet の min_conf は 0.65～0.98 だったため、信頼度だけではそのまま通過していたでしょう。

バッチジョブを同時に 2 つ実行しないでください。GPU を共有するため、競合した実行では所要時間が 5 倍になりました。初回ロードでは、各モデルにつき約 2.5 GB が ~/.cache/huggingface/hub にダウンロードされます。

Handy（プッシュ・トゥ・トーク音声入力）

Handy は、システム全体で使えるプッシュ・トゥ・トーク（Option-Space）に対応しています。brew upgrade --cask handy で 0.9.7 以降にアップグレードし、設定でモデルを選択してください。 handy-computer 組織は parakeet-unified-en-0.6b-gguf（NVIDIA 2026-04、オフラインとストリーミングに 1 つのモデルで対応）を公開しています。お使いの Handy のバージョンでこのモデルが一覧に表示されるか確認してください。ライブの多言語ストリーミングには、nvidia/nemotron-3.5-asr-streaming-0.6b（2026-06、40 のロケール対応）が現在の NVIDIA モデルです。Handy は音声入力用であり、バッチ処理の根拠資料には使いません。

レガシー

~/Programming/parakeet-dictate（NeMo/PyTorch のメニューバーアプリ、Voxtral バックエンド）は後継に置き換えられており、venv はありません。ここにあるものは、これにも PARAKEET_HOME にも依存していません。