ElevenAgentsでUnityのNPCに声を与える

プレイヤーはUnityゲーム内のキャラクターに近づき、声をかけられるようになりました。新しいElevenAgents Unity SDKは、シーンをElevenLabsの音声エージェントに接続します。プレイヤーのマイクから音声を聞き取り、エージェントの声をAudioSourceから再生し、Conversation APIを通じてセッションを実行します。

同じコードがEditor、デスクトップビルド、WebGLで動作します。iOS、Android、XRはベータ版です。

会話を始める

セッションには、ElevenLabsダッシュボードで作成したエージェントのIDが必要です。エージェントにはプロンプトと音声が設定されています。SDKに含まれるGettingStartedサンプルでは、キャラクターの周囲にあるトリガーコライダーにプレイヤーが入るとセッションが始まり、出ると終了します。

private Conversation activeConversation;

private void OnTriggerEnter(Collider other) => _ = StartTalkingAsync();
private void OnTriggerExit(Collider other) => _ = StopTalkingAsync();

private async Awaitable StartTalkingAsync()
{
    var options = new ConversationOptions { AgentId = agentId };
    activeConversation = await Conversation.StartSessionAsync(options);
}

private async Awaitable StopTalkingAsync()
{
    if (activeConversation == null)
        return;
    await activeConversation.EndSession();
    activeConversation = null;
}

接続が確立され、オーディオデバイスの準備が整うとStartSessionAsyncから結果が返され、ビルドターゲットに適したトランスポートが選択されます。セッションがすでに終了している場合、EndSessionは何もしません。

SDKの機能

キャラクターから聞こえる声

デフォルトでは、エージェントの声は2Dで再生されます。独自のAudioSourceをOutputAudioSourceとして渡すと、代わりにキャラクターから声が聞こえるようになります。

GetOutputVolume()は、すべてのプラットフォームでエージェントの現在の音量レベルを0〜1の範囲で返します。サンプルでは、話している間キューブを上下に動かすために使っています。同じ方法で口のアニメーションも制御できます。

1つのエージェントを複数のキャラクターで利用

動的変数は、エージェントのプロンプトと最初のメッセージにある{{mood}}のようなプレースホルダーに値を入れます。これにより、各キャラクターはセッションの開始時に固有の値を送信できます。値には文字列、数値、ブール値を使用できます。サンプルでは、黄色い楽しげなキューブと赤い怒ったキューブが1つのエージェントを共有します。

var options = new ConversationOptions
{
    AgentId = agentId,
    OutputAudioSource = audioSource,
    DynamicVariables = new Dictionary<string, object>
    {
        ["color"] = "red",
        ["mood"] = "angry",
    },
};

さらに大きな変更を加える場合は、Overridesを使って、最初のメッセージや音声など、1つのセッションにおけるエージェント設定の一部を置き換えます。各オーバーライドは、事前にエージェントのセキュリティ設定で有効にする必要があります。

状況を把握するキャラクター

SendContextualUpdateを使うと、会話を中断したり、プレイヤーが発言していないターンを追加したりせずに、会話の途中でゲーム内イベントをエージェントに伝えられます。

activeConversation.SendContextualUpdate("The player picked up the cellar key.");

ゲーム内で行動するキャラクター

クライアントツールを使うと、エージェントからゲームコードを呼び出せます。エージェントの設定でツールを定義し、同じ名前でハンドラーを登録します。

activeConversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

SDKはNewtonsoft Jsonを使ってツールのパラメーターをデシリアライズし、ハンドラーから返された内容をエージェントに送ります。時間のかかる処理では、ハンドラーからAwaitableを返せます。また、ClientToolExceptionをスローして、失敗した理由をエージェントに伝えられます。

イベントと操作

UserTranscriptReceived、AgentResponded、ModeChanged、InterruptedなどのイベントはUnityのメインスレッドで発生するため、イベントから直接UIを更新できます。メソッドには、SendUserMessageによるテキスト入力、SetMicMutedによるミュート、SetVolume、ビジュアライザー向けの周波数データ、セッション中の入出力デバイスの切り替えなどがあります。詳しくはUnity SDKドキュメントをご覧ください。

対応プラットフォーム

SDKはターゲットごとに適切なトランスポートを選択します。

• iOSとAndroid：セッションを開始する前に、マイクの使用許可をリクエストしてください。
• WebGL：Publishing SettingsでUse WebAssembly.Tableを有効にしてください。無効になっている場合、SDKは手順を表示してビルドを失敗させます。WebGLがアクティブなビルドターゲットになっている間はPlay Modeが動作しないため、デスクトップターゲットでテストしてください。
• WebGLオーディオ：音声はWeb Audio APIを通じて再生されるため、ミキサールーティングやドップラーなど、一部のAudioSource設定は引き継がれません。WebRTCセッションではOutputAudioSourceが無視されます。

全項目は互換性に関する注意事項で確認できます。

始める

1. ElevenLabsダッシュボードでエージェントを作成します。初回テストでは、ゲームがエージェントIDだけで接続できるように、セキュリティ設定で認証を無効にしてください。
2. UnityでWindow > Package Manager > + > Install package from git URLの順に開き、リリースを固定します：https://github.com/elevenlabs/unity.git#v0.1.0
3. GettingStartedサンプルをインポートし、エージェントIDを貼り付けて、Playを押します。

警告：リリース前に認証を再び有効にしてください。その後、独自のサーバーから有効期間の短い署名付きURLをリクエストし、ゲームではAgentIdの代わりにSignedUrlとして渡します。ElevenLabsのAPIキーは、決してゲームのビルドに含めないでください。

スタートガイドは約10分で完了し、近づくと挨拶するキューブを作成できます。その他の情報はUnity SDKドキュメントをご覧ください。バグや機能リクエストはGitHub Issuesへお寄せください。