audio-transcribe

会議・ポッドキャストの文字起こし（FunASR + MiMo）

複数人が話す音声を、自動話者ダイアライゼーション、ホットワードバイアス、オプションの LLM によるクリーンアップを用いて、構造化された Markdown に文字起こしします。ASR エンジンは 2 系統から選べます。FunASR（Paraformer / SenseVoice / Whisper — 高速、低コスト、GPU または CPU、99 言語対応）と MiMo-V2.5-ASR（Xiaomi の 8B モデル、ローカル GPU 専用、固有名詞やコードスイッチングに強い）です。どちらも同じ VAD + 話者クラスタリングのスタックを使用します。

すべてのスクリプトはプラグインディレクトリから直接実行できます。コピーは不要です。各セッションの開始時に、次の省略形を定義してください。

SCRIPTS=${CLAUDE_PLUGIN_ROOT}/skills/audio-transcribe/scripts

対応言語

--lang	モデル	言語	ホットワード
zh（デフォルト）	SeACo-Paraformer	中国語（CER 1.95%）	対応
zh-basic	Paraformer-large	中国語	非対応
en	Paraformer-en	英語	非対応
auto	SenseVoiceSmall	自動検出：zh/en/ja/ko/yue	非対応
whisper	Whisper-large-v3-turbo	99 言語	非対応
mimo	MiMo-V2.5-ASR（ローカル 8B、GPU 専用）	zh/en/コードスイッチング/方言	非対応

すべてのプリセットに話者ダイアライゼーション（CAM++）と VAD（FSMN）が含まれます。 mimo は、MiMo のテキスト出力に対して FSMN VAD + CAM++ スタックを再利用します。

ダイアライゼーションに関する注意点： auto と whisper は文ごとのタイムスタンプを出力しないため、これらのプリセットでは話者ダイアライゼーションは機能しません。話者の識別が必要な場合（ポッドキャストや会議など）は、zh、zh-basic、en、または mimo を使用してください。

ワークフロー

文字起こしを開始する前に、必ずユーザーに次の項目を確認してください。

1. 音声ファイル — 録音のパス（必須）
2. 種類 — 会議、ポッドキャスト、インタビューのどれですか？（デフォルトに影響します）
3. 言語 — 何語で話されていますか？（デフォルト：中国語）
4. 話者の人数 — 参加者は何人ですか？（ダイアライゼーションの精度が向上します）
5. 話者名 — ポッドキャストの場合：ホストとゲストの名前。会議の場合：参加者リスト
6. 補足ファイル — 次のように質問してください。

   「精度向上のため、次のいずれかをお持ちですか？」

   • 参加者／ゲストのリスト — ホットワードと話者の対応付けに使用
   • 会議の議題またはエピソードのトピック — ホットワード（用語、名前）に使用
   • 参考資料（番組の概要、過去のメモ）— 話者の識別と ASR の修正に使用

録音の種類に応じてデフォルトを調整してください。

• 会議：デフォルトは --lang zh。補足ファイルについて確認します
• ポッドキャスト／インタビュー：デフォルトは --lang zh、--num-speakers 2。必ずホストとゲストの名前を確認し、役割には --speaker-context の使用を提案してください （--lang auto は使用しないでください。話者ダイアライゼーションに必要なタイムスタンプがありません）

⚠️ --speakers にはポッドキャストでの別名ではなく、話者の実名を指定してください。 --speakers に渡した値は、出力される文字起こしの話者ラベルとしてそのまま使用されます。必ずポッドキャストのフィード名やタイトルではなく、ホスト／ゲストの実名（例： 番組の概要にある「Host:」欄）を指定してください。

例：番組の概要に「Host: 张三（张三的播客）」とある場合は、--speakers '张三' を渡してください。「张三的播客」という別名ではありません。ASR が両方の形式を認識できるよう、実名と別名の両方を hotwords.txt に追加してください。

--speakers と --reference の両方が指定されると、スクリプトは起動時にこの間違いを検出し、推奨する実名を示す ACTION REQUIRED ブロックを出力します。このブロックが表示された場合は、処理を停止し、フェーズ 3 の前に正しい --speakers の値を指定して再実行してください。この警告によってパイプラインは中断されません。

ユーザーから補足資料が提供された場合：

• 参加者名と重要な用語を抽出し、hotwords.txt を作成します（実名と別名の両方を含めます）
• 人物ごとのコンテキストを抽出し、speaker-context.json を作成します
• 元の参考資料を --reference で渡します
• 最良の結果を得るには、これら 3 つをすべて併用します

クイックスタート

1. 環境のセットアップ

AUTO_YES=1 bash $SCRIPTS/setup_env.sh
# Or force CPU:  AUTO_YES=1 bash $SCRIPTS/setup_env.sh cpu

セットアップスクリプトは、FunASR のスペクトラルクラスタリングにパッチを適用し、O(N²·k) の性能を実現します。これがないと、約 1 時間を超える録音では話者クラスタリング中に何時間も停止したような状態になります。

2. 文字起こしを実行する

出力ファイルは現在の作業ディレクトリに書き込まれます。

LLM によるクリーンアップ（フェーズ 3）はオプトインです。 デフォルトでは、外部サービスに接続せずローカルで文字起こしを実行します。LLM による ASR の修正と話者名の調整を有効にするには、--model <model-id> を指定します。次のような場合は、LLM によるクリーンアップを使用してください。

• 生の文字起こしに ASR の誤り（名前、専門用語など）が多い場合
• 公開できる品質に仕上げた出力が必要な場合
• 文脈から話者名を調整する必要がある場合

⚠️ データのプライバシー： --model を指定して LLM によるクリーンアップを有効にすると、文字起こしの一部が外部の LLM プロバイダー（モデル ID に応じて AWS Bedrock、Anthropic、または OpenAI）に送信されます。すべてのデータをローカルに保つには、--skip-llm を指定するか、--model を省略してください。Bedrock では、boto3 は標準の AWS 認証情報チェーン（IAM ロール、SSO、~/.aws/credentials、環境変数）を使用します。

# Chinese meeting with hotwords (local-only, no LLM)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang zh --num-speakers 9 --hotwords hotwords.txt

# English meeting with speaker names
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang en --speakers "Alice,Bob,Carol,Dave"

# Auto-detect language (zh/en/ja/ko/yue)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang auto --num-speakers 6

# Whisper for any language
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang whisper --num-speakers 4

# Enable LLM cleanup for polished output (requires --model)
# Bedrock (uses AWS credential chain: IAM role, SSO, ~/.aws/credentials)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang zh --num-speakers 9 --hotwords hotwords.txt \
    --provider bedrock --model us.anthropic.claude-sonnet-4-6

# Bedrock "global" cross-region profile (recent AWS deployments)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider bedrock --model global.anthropic.claude-sonnet-4-6

# Bedrock via litellm-style wrapper (supported; prefix is stripped for boto3)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider bedrock --model amazon-bedrock/global.anthropic.claude-sonnet-4-6

# Anthropic API (requires ANTHROPIC_API_KEY env var)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider anthropic --model claude-sonnet-4-6

# OpenAI-compatible API (requires OPENAI_API_KEY env var)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider openai --model gpt-4o

# Full pipeline with all supporting files + LLM (best quality)
python3 $SCRIPTS/transcribe.py episode.m4a \
    --lang zh --num-speakers 2 \
    --hotwords hotwords.txt \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json \
    --reference show-notes.md \
    --model us.anthropic.claude-sonnet-4-6

# Resume interrupted LLM cleanup
python3 $SCRIPTS/transcribe.py meeting.wav \
    --skip-transcribe --model us.anthropic.claude-sonnet-4-6

3. 話者ラベルを確認する

文字起こしで話者ラベルが入れ替わっている場合（ポッドキャストでよくあります）、検証スクリプトで LLM 分析を使って不一致を検出し、修正できます。

# Dry-run: check if host/guest are swapped
python3 $SCRIPTS/verify_speakers.py podcast_raw_transcript.json \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json

# Apply the fix
python3 $SCRIPTS/verify_speakers.py podcast_raw_transcript.json \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json --fix

# Multi-speaker meeting: full reassignment
python3 $SCRIPTS/verify_speakers.py meeting_raw_transcript.json \
    --speakers "Alice,Bob,Carol,Dave" \
    --speaker-context speaker-context.json --fix

# Then regenerate the markdown with corrected labels
python3 $SCRIPTS/transcribe.py original.m4a \
    --skip-transcribe --clean-cache

スクリプトは最初の 5 分間を分析し（--minutes で設定可能）、ポッドキャスト（話者 2 人、入れ替わりを検出）か会議（話者 N 人、全面的に再割り当て）かを自動検出します。

音声の前処理

スクリプトは入力音声を自動的に 16kHz のモノラル FLAC に変換し、音声が失われていないことを検証します（無音による切り詰めを検出します）。

形式	4時間14分の会議	品質	推奨
FLAC	219MB	可逆	デフォルトで最も安全
Opus	55MB	非可逆	長いファイルでは切り詰めのリスクがあります
WAV	465MB	可逆	使用できますが、ファイルサイズが大きくなります
元の M4A	173MB	ソース	そのまま直接使用することもできます

長時間の録音を分割しないでください — 分割すると話者 ID の一貫性が損なわれます。

MiMo-V2.5-ASR（オプション、GPU 専用）

--lang mimo を指定すると、Xiaomi の MiMo-V2.5-ASR を CUDA GPU 上でローカルに実行します。次のような場合に使用してください。

• 中国語音声で MiMo と Paraformer を比較評価したい場合。
• 録音にコードスイッチング、方言（呉語、広東語、閩南語、四川語）、歌詞、または他のプリセットでは誤認識される珍しい固有名詞が多く含まれる場合。

要件：

• CUDA ≥12.0 および ≥20 GB の VRAM（16 GB のカードでは推論中に OOM が発生します）。
• Python 3.12（setup_env.sh によって適用されます）。
• 約 20 GB の重みのダウンロード（初回のみ）と flash-attn==2.7.4.post1 のコンパイル（CUDA ツールキットの nvcc が必要で、10～30 分かかります）。

インストール（オプトイン）：

# One-time: install MiMo on top of the standard environment
AUTO_YES=1 INSTALL_MIMO=1 \
    MIMO_WEIGHTS_PATH=/mnt/models/hf \
    bash $SCRIPTS/setup_env.sh

実行：

python3 $SCRIPTS/transcribe.py podcast.m4a \
    --lang mimo --num-speakers 2 \
    --mimo-weights-path /mnt/models/hf

失敗後に再開する：

python3 $SCRIPTS/transcribe.py podcast.m4a \
    --lang mimo --resume-mimo --mimo-weights-path /mnt/models/hf

制限事項：

• ホットワードのバイアス付けには対応していません（MiMo にその API がないため、--hotwords は無視されます）。
• CPU へのフォールバックはありません。
• 同じ GPU 上では Paraformer より推論が遅くなります（8B モデルと約 0.3B モデルの比較）。A100 での RTF は約 0.1～0.2 です。

主なフラグ

フラグ	用途
--lang	zh（デフォルト）、zh-basic、en、auto、whisper
--hotwords	ホットワードのファイルまたは文字列 — ASR の認識にバイアスをかけます（中国語のみ）
--reference F	LLM による ASR 修正用の参照ファイル
--num-speakers N	想定する話者数（話者ダイアライゼーションの精度を向上）
--speakers "A,B,C"	初出順に実名を割り当てます
--speaker-context F	LLM 向けの話者ごとの役割を記述した JSON
--no-detect-gender	話者の性別の自動検出を無効にします（CAM++ 性別分類器）
--speaker-genders "A:female,B:male"	話者ごとの性別を上書きします（位置指定の female,male も使用できます）
--audio-format	flac（デフォルト）、opus、wav
--device cpu	CPU モードを強制します
--batch-size N	メモリに合わせて調整します（CPU では 60、GPU の OOM 時は 100）
--phase1-only	Phase 1（VAD + ASR + 話者ダイアライゼーション）の後に終了し、Phase 2 と 3 をスキップします
--json-out PATH	生の文字起こし JSON を指定したパスに書き込みます（デフォルトの命名規則を上書き）
--skip-transcribe	保存済みの *_raw_transcript.json から再開します
--skip-llm	LLM によるクリーンアップをスキップします（--model を省略した場合のデフォルト）
--model ID	指定したモデルで LLM によるクリーンアップを有効にします（Bedrock／Anthropic／OpenAI を自動検出）
--title "..."	出力ドキュメントのタイトル
--clean-cache	完了後に LLM チャンクキャッシュを削除します
--output PATH	出力ファイルのカスタムパス
--model-cache-dir	ModelScope のモデルキャッシュディレクトリ（約 3 GB、デフォルト：~/.cache/modelscope/）
--mimo-audio-tag	MiMo の言語ヒント：<chinese>（デフォルト）、<english>、<auto>
--mimo-batch N	MiMo 呼び出しごとの VAD セグメントの同時処理数（デフォルトは 1。H100／80 GB では増やせます）
--mimo-weights-path DIR	MiMo の重みのキャッシュディレクトリ（デフォルト：$HF_HOME → ~/.cache/huggingface）
--resume-mimo	実行途中の失敗後、*_mimo_partial.json から MiMo の Phase 1 を再開します

出力

• <stem>-transcript.md — 話者ラベルとタイムスタンプを含む最終版 Markdown
• <stem>_raw_transcript.json — Phase 1 の生の出力（再開／分析用）

話者ダイアライゼーションのヒント

FunASR の CAM++ は、音響的に似ている話者を統合してしまうことがあります。精度を向上させるには、次の方法を試してください。

1. --num-speakers N — 想定する話者数を指定します
2. --hotwords — 参加者の名前を含めます（中国語の名前が最も効果的です）
3. --speaker-context — LLM による話者分割用に、人物ごとのキーワードを指定します
4. キーワード照合 — *_raw_transcript.json を検索し、特徴的なフレーズを探します

話者の性別

デフォルトで有効です。検出された各話者は、3D-Speaker の CAM++ 性別分類器（iic/speech_campplus_two_class_gender_16k）によって male／female に分類されます。 結果は Speaker List の表で各名前の横に表示され、LLM によるクリーンアップのプロンプトにも挿入されるため、代名詞（他／她、he／she）が修正されます。

組み合わせて指定した場合の優先順位：

1. --speaker-genders "Alice:female,Bob:male"（明示的な CLI 指定）— 常に優先されます
2. 主播（女）：韩梅梅 や Host (male): Alice のような参照テキストのヒント — 自動検出結果を上書きします
3. CAM++ による自動検出 — フォールバック

性別が不要で、約 500 MB のモデルのダウンロードと追加の推論時間を節約したい場合は、--no-detect-gender で無効にしてください。

CPU のみ／メモリの少ないマシン

リソースに制約のあるマシンでは、長時間の録音を処理すると、実行タイムアウトや OOM による強制終了が発生することがあります。回避策については references/pipeline-details.md を参照してください。

• systemd-run または nohup を使い、エージェントのタイムアウトによる終了を回避します
• スワップや --lang zh-basic（軽量モデル）を使って OOM を防ぎます

追加リソース

• references/pipeline-details.md — アーキテクチャ、モデルの仕様、ベンチマーク、話者の役割の検証、ホットワードの有効性、クラスタリングのパッチ
• scripts/transcribe.py — メインの文字起こしパイプライン
• scripts/verify_speakers.py — 話者ラベルの検証と修正
• scripts/llm_utils.py — 共通 LLM インフラストラクチャ（Bedrock／Anthropic／OpenAI）
• scripts/setup_env.sh — 環境のセットアップ（venv + 依存関係 + パッチ）