mcpField
L
liveavatar-debug

liveavatar-debug

github.com/heygen-com開発161.0k 回インストール7 週間前に更新
リポジトリ

liveavatar-debug について

LiveAvatar Debugging Guideは、無音、音声の歪み、セッション開始失敗、イベント未受信などを症状別に扱う、LiveAvatar統合向けのトラブルシューティングスキルです。FULLとLITEのデバッグに使え、プロトコル、音声形式、認証の確認手順を示します。

主な機能

  1. 01症状別のトラブルシューティング手順
  2. 02FULLモードのコンテキストとイベント確認
  3. 03LITEの音声形式と接続状態の検証
  4. 04トークンとセッション開始の認証を区別
  5. 05セッションタイムアウトとサンドボックスの確認

活用シーン

  1. 01無音や発話に反応しないアバターの調査
  2. 02LITEモードの音声の歪みの修正
  3. 03401エラーやセッション開始失敗の診断
  4. 04WebSocketイベント未着の調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/heygen-com/liveavatar-agent-skills --skill liveavatar-debug

インストール後、Claude Code で/liveavatar-debugを入力して読み込まれたか確認します。

詳細

LiveAvatar デバッグガイド

LiveAvatar 連携で発生する症状別のトラブルシューティングです。該当する症状を確認し、対処方法に従ってください。

アバターが無音／音声に反応しない

最も可能性が高い原因：FULL Mode で context_id が設定されていない。

context_id がない場合、アバターは制限モードに入り、動画をストリーミングするものの、ユーザー入力を無視します。エラーは発生しません。

対処方法： prompt フィールドを含むコンテキストを POST /v1/contexts で作成します。返された context_id をセッショントークンの avatar_persona に含めてください。

その他の原因：

  • ブラウザーのマイク権限がブロックされている（iframe の allow="microphone" を確認してください）
  • プッシュ・トゥ・トークが有効なのに、PTT イベントが送信されていない
  • OS レベルでマイクがミュートされている

音声が乱れる、または歪む（LITE Mode）

最も可能性が高い原因：音声形式が正しくない。

必要な形式：PCM 16 ビット符号付き、24KHz、Base64。形式が間違っていてもエラーは返されません。

チェックリスト：

  • サンプルレートが正確に 24,000 Hz である
  • 生の PCM である（WAV／MP3／OGG のヘッダーがない）
  • 16 ビット符号付きであり、8 ビットや 32 ビット浮動小数点ではない
  • Base64 でエンコードされている
  • チャンクが 1MB 未満である

簡単なテスト： 正常な 440Hz のテストトーンを送信します。正常に機能するのに TTS では機能しない場合は、TTS の出力をリサンプリングしてください。

401 エラー／セッションを開始できない

最も可能性が高い原因：認証ヘッダーが正しくない。

エンドポイント正しい認証
POST /v1/sessions/tokenX-API-KEY: <api_key>
POST /v1/sessions/startAuthorization: Bearer <session_token>

よくある間違い：/start で API キーを使用する、/token で Bearer トークンを使用する、API キーを Bearer 形式で指定する。

イベントを受信できない（FULL Mode）

  • 正しいトピックを購読していますか？agent-control に送信し、agent-response から受信します
  • LiveKit ルームに接続されていますか？接続状態を確認してください
  • JSON を正しく解析していますか？イベントには event_type、event_id、session_id が含まれます

WebSocket イベントが通知なく破棄される（LITE Mode）

最も可能性が高い原因：connected より前に送信している。

コマンドを送信する前に、{"type": "session.state_updated", "state": "connected"} を待ってください。

以下も確認してください：

  • 正しいイベント名を使用していますか？LITE では avatar.*（FULL のイベント名）ではなく、agent.* を使用します
  • WebSocket はまだ開いていますか？5 分間操作がないとタイムアウトします

セッションがタイムアウトする

5 分間操作がないと、セッションは終了します。

  • FULL： Bearer <session_token> を指定して POST /v1/sessions/keep-alive を呼び出します
  • LITE： WebSocket 経由で {"type": "session.keep_alive", "event_id": "..."} を送信します

2〜3 分ごとに送信してください。

サンドボックスが起動しない

  • セッショントークンで is_sandbox: true が設定されている
  • アバター ID が dd73ea75-1218-4ef3-92ce-606d5f7fbc0a（セッション用）または 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0（埋め込み用）である
  • サンドボックスモードで別のアバターを使用していない

約 1 分で自動終了するのは想定された動作です。

画像アバターで失敗する／音声がない

画像アバターには自動生成される音声がありません。avatar_persona で voice_id を指定してください。GET /v1/voices で音声を確認できます。

カスタム LLM／TTS が機能しない

LLM のチェックリスト：

  • シークレット：secret_type: "LLM_API_KEY"
  • 設定：model、secret_id、base_url が正しい
  • セッショントークンに llm_configuration_id がある
  • エンドポイントが OpenAI の /chat/completions プロトコルに対応している

TTS のチェックリスト：

  • シークレット：secret_type: "ELEVENLABS_API_KEY"
  • POST /v1/voices/third_party で音声をインポートしている
  • 返された LiveAvatar の voice_id（ElevenLabs の ID ではない）を使用している

CORS／ネットワークエラー

  • API 呼び出しはブラウザーではなく、バックエンドから行ってください
  • LiveKit と WebSocket のために、送信方向の wss:// を許可してください
  • *.livekit.cloud、api.liveavatar.com、embed.liveavatar.com を許可してください

基本的な進め方

  1. 課金の問題を切り分けるため、まずサンドボックスモードを使用します
  2. セッションの状態を確認します：GET /v1/sessions/{id}
  3. トランスクリプトを確認します：GET /v1/sessions/{id}/transcript
  4. クレジットを確認します：GET /v1/users/credits
  5. FULL と LITE のイベントシステムを混在させていないことを確認します

コメント

Markdown 対応