Geef je Unity-NPC's een stem met ElevenAgents

Spelers kunnen nu naar een personage in je Unity-game lopen en hardop met het personage praten. De nieuwe ElevenAgents Unity SDK verbindt een scène met een ElevenLabs-stemagent. Deze luistert via de microfoon van de speler, speelt de stem van de agent af via een AudioSource en voert de sessie uit via de Conversation-API.

Dezelfde code werkt in de Editor, desktopbuilds en WebGL; iOS, Android en XR zijn in bèta.

Start een gesprek

Voor een sessie heb je de ID nodig van een agent die je in het ElevenLabs-dashboard hebt gemaakt en waarin de prompt en stem zijn opgeslagen. In ons GettingStarted-voorbeeld, dat bij de SDK is inbegrepen, opent een trigger collider rond het personage de sessie wanneer de speler binnenloopt en sluit deze wanneer de speler wegloopt:

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 retourneert zodra de verbinding open is en de audioapparaten klaar zijn, en kiest het juiste transport voor het buildtarget. EndSession doet niets als de sessie al is beëindigd.

Wat zit er in de SDK?

Stemmen die van het personage komen

Standaard wordt de stem van de agent in 2D afgespeeld. Geef je eigen AudioSource door als OutputAudioSource, zodat de stem in plaats daarvan van het personage komt.

GetOutputVolume() retourneert op elk platform het huidige niveau van de agent van 0 tot 1. Het voorbeeld gebruikt dit om de kubus te laten deinen terwijl deze praat; op dezelfde manier kun je er een mondanimatie mee aansturen.

Eén agent, veel personages

Dynamische variabelen vullen placeholders zoals {{mood}} in de prompt en het eerste bericht van de agent, zodat elk personage eigen waarden kan sturen wanneer de sessie begint. Waarden kunnen strings, getallen of booleans zijn. In het voorbeeld delen een gele, blije kubus en een rode, boze kubus één agent:

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

Voor grotere wijzigingen vervangen Overrides een deel van de configuratie van de agent voor één sessie, zoals het eerste bericht of de stem. Je moet elke override eerst inschakelen in de Security-instellingen van de agent.

Personages die weten wat er gebeurt

SendContextualUpdate vertelt de agent tijdens een gesprek over gamegebeurtenissen, zonder deze te onderbreken of een beurt toe te voegen die de speler niet heeft uitgesproken:

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

Personages die in de game handelen

Met clienttools kan de agent gamecode activeren. Definieer de tool in de instellingen van de agent en registreer vervolgens een handler onder dezelfde naam:

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

De SDK deserialiseert de parameters van de tool met Newtonsoft Json en stuurt alles wat de handler retourneert terug naar de agent. Handlers kunnen een Awaitable retourneren voor werk dat tijd kost en een ClientToolException gooien om de agent te vertellen waarom iets is mislukt.

Events en bedieningselementen

Events zoals UserTranscriptReceived, AgentResponded, ModeChanged en Interrupted worden uitgevoerd op de hoofdthread van Unity, zodat je de UI rechtstreeks vanuit deze events kunt bijwerken. Methoden bieden tekstinvoer met SendUserMessage, dempen met SetMicMuted, SetVolume, frequentiedata voor visualizers en het wisselen van invoer- of uitvoerapparaten tijdens een sessie. De Unity SDK-documentatie bevat ze allemaal.

Platformondersteuning

De SDK kiest het transport voor elk target.

• iOS en Android: vraag toestemming voor de microfoon voordat je een sessie start.
• WebGL: schakel Use WebAssembly.Table in bij Publishing Settings. De SDK laat de build mislukken met instructies als dit is uitgeschakeld. Play Mode werkt niet wanneer WebGL het actieve buildtarget is, dus test op een desktoptarget.
• WebGL-audio: de stem wordt afgespeeld via de Web Audio API, waardoor sommige instellingen van AudioSource, zoals mixerrouting en doppler, niet worden overgenomen. WebRTC-sessies negeren OutputAudioSource.

De compatibiliteitsnotities bevatten de volledige lijst.

Aan de slag

1. Maak een agent in het ElevenLabs-dashboard. Schakel voor een eerste test Authentication uit in de Security-instellingen, zodat de game alleen met de agent-ID verbinding kan maken.
2. Open in Unity Window > Package Manager > + > Install package from git URL en zet de release vast: https://github.com/elevenlabs/unity.git#v0.1.0
3. Importeer het GettingStarted-voorbeeld, plak je agent-ID erin en druk op Play.

Waarschuwing: Schakel Authentication weer in voordat je publiceert. Je eigen server vraagt dan een kortdurende signed URL aan en de game geeft deze door als SignedUrl in plaats van AgentId. Zet je ElevenLabs API-sleutel nooit in een gamebuild.

De handleiding om aan de slag te gaan duurt ongeveer 10 minuten en eindigt met een kubus die je begroet wanneer je dichterbij loopt. Lees voor al het andere de Unity SDK-documentatie en stuur bugs en feature requests naar GitHub issues.