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 사이 값으로 반환합니다. 샘플에서는 이를 사용해 말하는 동안 큐브가 위아래로 움직이게 하며, 같은 방식으로 입 애니메이션을 구동할 수도 있습니다.

하나의 에이전트, 여러 캐릭터

동적 변수는 에이전트의 프롬프트와 첫 메시지에 있는 {{mood}} 같은 플레이스홀더를 채우므로, 각 캐릭터는 세션이 시작될 때 고유한 값을 보낼 수 있습니다. 값으로는 문자열, 숫자 또는 불리언을 사용할 수 있습니다. 샘플에서는 행복한 노란 큐브와 화난 빨간 큐브가 하나의 에이전트를 공유합니다:

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

더 큰 변경이 필요하다면 Overrides를 사용해 첫 메시지나 음성처럼 한 세션에만 적용되는 에이전트 구성 일부를 대체할 수 있습니다. 각 오버라이드는 먼저 에이전트의 Security 설정에서 활성화해야 합니다.

상황을 파악하는 캐릭터

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를 throw할 수 있습니다.

이벤트 및 제어

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만으로 연결할 수 있도록 Security 설정에서 Authentication을 끄세요.
2. Unity에서 Window > Package Manager > + > Install package from git URL를 열고, 다음 릴리스를 고정하세요: https://github.com/elevenlabs/unity.git#v0.1.0
3. GettingStarted 샘플을 가져오고 에이전트 ID를 붙여 넣은 다음 Play를 누르세요.

경고: 출시하기 전에 Authentication을 다시 켜세요. 그러면 자체 서버에서 유효 기간이 짧은 signed URL을 요청하고, 게임은 AgentId 대신 이를 SignedUrl로 전달합니다. 게임 빌드에 ElevenLabs API 키를 절대 넣지 마세요.

시작 가이드는 약 10분이 걸리며, 다가가면 인사하는 큐브를 만드는 것으로 마무리됩니다. 그 외의 내용은 Unity SDK 문서를 읽고, 버그 및 기능 요청은 GitHub 이슈로 보내세요.