liveavatar-integrate

LiveAvatar の統合

LiveAvatar を使うと、リアルタイムでリップシンクし、話し、反応し、アイコンタクトを保つビデオアバターを通じて、製品に人間らしい顔を与えられます。このスキルでは、現在の構成を評価し、最適な統合方法を提案して、その構築を段階的に支援します。

Step 1: ユーザーが利用しているものを確認する

方法を提案する前に、コンテキストを集めます。コードベースと会話から手がかりを探してください。コードベースから分かることは質問しないでください。

コードベースで探す手がかり

次の項目を自動的にスキャンしてください。検出できる場合はユーザーに質問しないでください。

手がかり	確認場所	意味
OpenAI / Anthropic / LLM SDK のインポート	package.json、requirements.txt、インポート	ユーザーが独自の LLM を利用しています
ElevenLabs / PlayHT / Deepgram TTS SDK	依存関係、インポート	ユーザーが独自の TTS を利用しています
Deepgram / Whisper / AssemblyAI STT SDK	依存関係、インポート	ユーザーが独自の STT を利用しています
LiveKit SDK（livekit-server-sdk、@livekit/）	依存関係	ユーザーが LiveKit インフラを利用しています
Agora SDK	依存関係	ユーザーが Agora インフラを利用しています
Pipecat のインポート	依存関係、インポート	ユーザーが Pipecat パイプラインを利用しています
ElevenLabs Agent / Conversational AI	依存関係、設定	ユーザーが ElevenLabs エージェントを利用しています
HEYGEN_API_KEY / LIVEAVATAR_API_KEY	.env、設定ファイル	ユーザーがすでに API キーを持っています
既存の LiveAvatar コード	インポート、api.liveavatar.com への API 呼び出し	既存の統合があります（新規設定ではなくデバッグ）
バックエンドなし / 静的サイト	ファイル構成（純粋な HTML/CSS/JS、サーバーなし）	埋め込みが唯一の選択肢です

質問する項目（まだ分からないことのみ）

コードベースのスキャンで不明点が残る場合は、ユーザーに質問してください。簡潔なチェックリストにまとめてください。一度に一つずつ質問しないでください。

To recommend the best LiveAvatar integration for your setup, I need to know:

1. **What's the goal?** (e.g., customer support avatar, sales demo, onboarding guide, talking head on landing page)
2. **Do you have your own AI pipeline?** (STT, LLM, TTS — or any combination)
3. **Do you need programmatic control** over the conversation (events, interrupts, custom logic), or just an avatar on a page?

コードベースや会話からすでに分かっている質問は省略してください。

Step 2: 最適な経路を選ぶ

集めた情報に基づいて、該当する経路を1つ選びます。**必ず、機能する最もシンプルな経路を選んでください。**複数の選択肢は提示せず、1つに決めてください。

判断ツリー

Has NO backend OR just wants an avatar on a page?
  → EMBED

Has NO existing AI stack (no STT, no LLM, no TTS)?
  → FULL MODE (standard)

Has their OWN LLM but no STT/TTS?
  → FULL MODE + Custom LLM

Has their OWN LLM + their own ElevenLabs TTS?
  → FULL MODE + Custom LLM + Custom TTS

Needs explicit mic control (walkie-talkie style)?
  → FULL MODE + Push-to-Talk

Has a COMPLETE pipeline (STT + LLM + TTS)?
  → LITE MODE

Has an ElevenLabs Conversational AI agent?
  → LITE MODE + ElevenLabs Plugin

Has their own LiveKit or Agora infrastructure?
  → LITE MODE + BYO WebRTC

最適な経路（1つ選んで実装）

経路	条件	実装ガイド
埋め込み	バックエンドがない、またはカスタムロジックが不要	references/embed-guide.md
FULL 標準	既存の AI スタックがない	references/full-mode-guide.md
FULL + カスタム LLM	独自の LLM があり、LiveAvatar の ASR + TTS を使いたい	references/full-mode-guide.md（カスタム LLM セクション）
FULL + カスタム TTS	独自の ElevenLabs 音声がある	references/full-mode-guide.md（カスタム TTS セクション）
FULL + プッシュ・トゥ・トーク	明示的なマイク制御が必要	references/full-mode-guide.md（プッシュ・トゥ・トーク セクション）
LITE 標準	STT + LLM + TTS のパイプラインがすでに揃っている	references/lite-mode-guide.md
LITE + ElevenLabs Plugin	ElevenLabs Conversational AI エージェントがある	references/lite-mode-guide.md（ElevenLabs Plugin セクション）
LITE + BYO WebRTC	独自の LiveKit / Agora がある	references/lite-mode-guide.md（BYO WebRTC セクション）

Step 3: 推奨内容を伝える

経路を選んだら、推奨する内容とその理由を2～3文でユーザーに伝えてください。例：

現在の構成を踏まえると、カスタム LLM を使う FULL Modeをおすすめします。LLM 用に OpenAI をすでに統合しているため、それを接続し、ASR、TTS、動画は LiveAvatar に任せましょう。これにより、音声パイプラインを作り直さずに会話型アバターを利用できます。

その後、references/ にある対応するガイドを使って、すぐに実装を進めてください。

ステップ 4：実装

該当するリファレンスガイドを読み、実装してください。すべてのガイドは同じ構成です。

1. 前提条件 — コードを書く前に作成・収集するもの
2. セッションのライフサイクル — curl コマンドとコードを使った手順
3. イベント — 送受信する内容
4. 追加機能 — モード固有のオプション機能
5. サンドボックステスト — 本番稼働前の無料テスト
6. 注意点 — 問題が発生する原因と回避方法

すべての経路に適用される原則

バックエンドとフロントエンドの分離は必須です。 X-API-KEY は秘密情報なので、バックエンドだけで扱います。フロントエンドには livekit_client_token のみを渡します（ブラウザーで安全に使用できます）。クライアントコードに API キーがある場合は、作業を止めて構成を見直してください。

アバターが会話できるかどうかはコンテキスト次第です。 FULL Mode では、context_id がないとアバターは無言になります。エラーは発生しません。必ず、"You are a helpful assistant." のような簡単なものでもよいので、まずコンテキストを作成してください。

FULL と LITE はまったく異なるプロトコルです。 FULL は LiveKit データチャネル（avatar.* / user.*）、LITE は WebSocket（agent.* / session.*）を使用します。両者を混在させないでください。

まずサンドボックスから始めてください。 is_sandbox: true とアバター ID dd73ea75-1218-4ef3-92ce-606d5f7fbc0a を指定します。無料で、セッションは約 1 分間です。準備ができたら本番用アバターに切り替えてください。

LITE Mode：既存のパイプラインへの組み込み

LITE のユーザーは、ほとんどの場合、すでに会話システムを運用しています。パイプラインを作り直すよう求めないでください。 代わりに、既存のコンポーネントを LITE のターンサイクルに対応付けます。

1. 現在のフローを把握します。 コードを読んで、現在の会話ターンの処理方法を理解します。ユーザーの音声はどこから入力され、LLM にどう渡され、TTS の出力はどのように届けられるでしょうか。イベントループ、メッセージハンドラー、ターンマネージャーを探してください。
2. 統合ポイントを見つけます。 既存のフローで、次の 3 つのタイミングにフックする必要があります。
   • ユーザーが話し始める／話し終える → agent.start_listening / agent.stop_listening を追加します
   • TTS が音声を生成する → 現在の音声出力の代わりに（またはそれに加えて）、PCM 出力を WebSocket 経由で agent.speak のチャンクとして送ります
   • 応答が完了する → agent.speak_end を送信し、agent.speak_ended を待ちます
3. 置き換えるのではなく、適応させます。 ターンマネージャーがすでに機能している場合は、そこに LiveAvatar の呼び出しを追加します。WebSocket 経由でブラウザーに TTS をストリーミングしている場合は、同じストリームを利用します。目標は、既存の音声フローと同期したアバター動画を得るために必要な変更を最小限に抑えることです。
4. 最後に音声形式を確認します。 配線が完了したら、TTS の出力が PCM 16-bit 24KHz であることを確認します。そうでない場合は、TTS プロバイダーの出力形式を設定するか、統合ポイントでリサンプリングを追加してください。

ステップ 5：フィードバックの収集

統合コードを書き終えたら、すぐにこの手順を開始してください。 ユーザーが動作を確認したり、完了したと伝えたりするのを待たないでください。また、ユーザーが諦めた場合や、同じステップで 3 回以上失敗した場合も開始してください。

実施内容： liveavatar-feedback スキルに従ってください。このスキルでは、会話からコンテキストを収集し、送信する内容をユーザーに提示し、明示的な同意を得て、フィードバックを送信する手順を案内します。

簡潔に進めてください。 実装メッセージの最後に短く一度だけ確認してください。ユーザーが断ったり、無視したりした場合は、無理に求めないでください。

参照先

• references/embed-guide.md — Embed の実装
• references/full-mode-guide.md — FULL Mode の実装、イベント、追加機能
• references/lite-mode-guide.md — LITE Mode の実装、イベント、音声形式、追加機能