Unity SDK

ElevenAgents Unity SDK एक Unity सीन को ElevenLabs एजेंट से कनेक्ट करता है। यह खिलाड़ी का माइक्रोफ़ोन कैप्चर करता है, एजेंट की वॉइस को AudioSource से वापस स्ट्रीम करता है और सेशन को एक ही Conversation API के ज़रिए उपलब्ध कराता है, जो Editor, डेस्कटॉप स्टैंडअलोन प्लेयर्स और WebGL बिल्ड्स में एक जैसा व्यवहार करता है।

ज़रूरी शर्तें

• Unity 6.3 LTS (6000.3.0f1) या उसके बाद का वर्शन। SDK Unity 6.3 में पेश किए गए scriptable-audio APIs का इस्तेमाल करता है।
• Api Compatibility Level को .NET Standard 2.1 पर सेट करें, जो Unity 2023.1 और उसके बाद के वर्शन के लिए डिफ़ॉल्ट है।
• एक ElevenLabs अकाउंट और एजेंट। डैशबोर्ड में बनाएं या क्विकस्टार्ट अपनाएं।

प्लेटफ़ॉर्म सपोर्ट

SDK सक्रिय बिल्ड टारगेट के लिए ट्रांसपोर्ट अपने-आप चुनता है। WebRTC सिर्फ़ WebGL पर उपलब्ध है; हर दूसरे टारगेट पर ConnectionType.WebRTC, NotSupportedException थ्रो करता है।

इंस्टॉलेशन

Unity में Window > Package Manager खोलें, + > Install package from git URL चुनें और रिपॉज़िटरी URL पेस्ट करें:

https://github.com/elevenlabs/unity.git

Package Manager, अपनी डिपेंडेंसी Input System और Newtonsoft Json के साथ पैकेज को ElevenAgents (io.elevenlabs.agents) के रूप में इंस्टॉल करता है।

क्विकस्टार्ट

यह सेक्शन एक खाली सीन में वॉइस एजेंट जोड़ता है। Play Mode में जाने पर एजेंट बात करना शुरू करता है और बाहर आने पर सेशन समाप्त हो जाता है।

using System;
using ElevenLabs.Agents;
using ElevenLabs.Protocol;
using UnityEngine;
public sealed class AgentConversation : MonoBehaviour
{
    [SerializeField]
    private string agentId = "agent_7101k5zvyjhmfg983brhmhkd98n6";
    private Conversation conversation;
    private async void Start()
    {
        try
        {
            conversation = await Conversation.StartSessionAsync(
                new ConversationOptions { AgentId = agentId }
            );
        }
        catch (Exception ex)
        {
            Debug.LogError($"Failed to start session: {ex.Message}");
            return;
        }
        Debug.Log($"Connected: {conversation.ConversationId}");
        conversation.UserTranscriptReceived += OnUserTranscript;
        conversation.AgentResponded += OnAgentResponse;
        conversation.ErrorOccurred += message => Debug.LogError(message);
        conversation.Disconnected += details => Debug.Log($"Disconnected: {details.Reason}");
    }
    private void OnUserTranscript(UserTranscriptArgs args) =>
        Debug.Log($"User: {args.UserTranscript}");
    private void OnAgentResponse(AgentResponseArgs args) =>
        Debug.Log($"Agent: {args.AgentResponse}");
    private void OnDestroy()
    {
        _ = conversation?.EndSession();
    }
}

पब्लिक और प्राइवेट एजेंट

var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions { AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6" }
);

AgentId, SignedUrl या ConversationToken में से ठीक एक सेट करें। अपनी खुद की सिस्टम में बातचीत को खिलाड़ी से जोड़ने के लिए UserId सेट करें।

स्पेशल ऑडियो

डिफ़ॉल्ट रूप से SDK, अपने बनाए हुए छिपे AudioSource से एजेंट की वॉइस चलाता है। वॉइस को सीन में रखने के लिए अपना AudioSource, OutputAudioSource के रूप में पास करें:

[SerializeField]
private AudioSource voiceSource; // Spatial Blend = 1 for 3D audio
var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions
    {
        AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
        OutputAudioSource = voiceSource,
    }
);

SDK सोर्स का spatial blend, rolloff, mixer routing और पोज़िशन बनाए रखता है। सेशन समाप्त होने पर यह सोर्स की clip, loop और volume सेटिंग्स को वापस बहाल करता है।

एजेंट की वॉइस से माउथ ऐनिमेशन जैसे विज़ुअल इफ़ेक्ट को चलाने के लिए, हर फ़्रेम conversation.GetOutputVolume() पढ़ें। यह हर प्लेटफ़ॉर्म पर 0 और 1 के बीच वैल्यू रिटर्न करता है।

पर्सनलाइज़ेशन

एजेंट के प्रॉम्प्ट और पहले संदेश में प्लेसहोल्डर भरने के लिए डायनामिक वेरिएबल्स और एक सेशन के लिए एजेंट कॉन्फ़िगरेशन के हिस्से बदलने के लिए ओवरराइड्स इस्तेमाल करें:

using System.Collections.Generic;
using ElevenLabs.Protocol;
var options = new ConversationOptions
{
    AgentId = "agent_7101k5zvyjhmfg983brhmhkd98n6",
    DynamicVariables = new Dictionary<string, object>
    {
        ["player_name"] = "Ada",
        ["quest_stage"] = 3,
    },
    Overrides = new ConversationConfigOverride
    {
        Agent = new ConversationConfigOverrideAgent
        {
            FirstMessage = "Welcome back, {{player_name}}.",
        },
        Tts = new ConversationConfigOverrideTts { VoiceId = "JBFqnCBsd6RMkjVDRZzb" },
    },
};

डायनामिक वेरिएबल वैल्यू स्ट्रिंग, नंबर या बूलियन होनी चाहिए। सर्वर के स्वीकार करने से पहले हर ओवरराइड को एजेंट की Security सेटिंग्स में सक्षम करना होगा।

क्लाइंट टूल्स

क्लाइंट टूल्स, एजेंट को आपके गेम में ऐक्शन ट्रिगर करने देते हैं। एजेंट की सेटिंग्स में टूल परिभाषित करें, फिर उसी नाम से हैंडलर रजिस्टर करें:

using Newtonsoft.Json;
public sealed class OpenDoorParams
{
    [JsonProperty("door_id")]
    public string DoorId { get; set; }
}
conversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

SDK, Newtonsoft Json के साथ टूल पैरामीटर को TParams में deserialize करता है, इसलिए पैरामीटर का नाम प्रॉपर्टी नाम से अलग होने पर [JsonProperty] इस्तेमाल करें। रिटर्न वैल्यू टूल रिज़ल्ट के रूप में serialize होती है। असिंक्रोनस हैंडलर के लिए Awaitable<TResult> रिटर्न करें। एजेंट को खास विफलता बताने के लिए errorType के साथ ClientToolException थ्रो करें; किसी भी अन्य exception को सामान्य error के रूप में रिपोर्ट किया जाता है।

रजिस्टर किए गए हैंडलर के बिना टूल कॉल करने पर ErrorOccurred ट्रिगर होता है, या अगर आपने इसे subscribe किया है तो UnhandledClientToolCall।

इवेंट्स

StartSessionAsync से रिटर्न हुए Conversation के इवेंट्स को subscribe करें। SDK इन्हें Unity के main thread पर ट्रिगर करता है।

Connected इवेंट, StartSessionAsync के रिटर्न होने से पहले ट्रिगर होता है, इसलिए कॉल पूरा होने पर सीधे ConversationId और Status पढ़ें। पैकेज चेंजलॉग में इवेंट्स की पूरी सूची है।

मेथड्स

उदाहरण के लिए, जब खिलाड़ी किसी नए क्षेत्र में प्रवेश करे तो उसकी मौजूदा लोकेशन एजेंट को भेजें:

conversation.SendContextualUpdate("The player entered the abandoned lighthouse.");

WebGL बिल्ड्स

WebGL बिल्ड्स को एक अतिरिक्त Player Setting चाहिए। Player Settings > WebGL > Publishing Settings में Use WebAssembly.Table चालू करें। यह सेटिंग बंद होने पर SDK निर्देशों के साथ बिल्ड को विफल कर देता है।

WebGL पर Unity में कोई scriptable audio pipeline नहीं है, इसलिए SDK ब्राउज़र के Web Audio API से एजेंट की वॉइस चलाता है और आपके OutputAudioSource की वॉल्यूम, पोज़िशन और स्पेशल सेटिंग्स को मिरर करता है। इसलिए AudioSource.GetOutputData और OnAudioFilterRead, WebGL पर साइलेंस रिटर्न करते हैं। इसके बजाय GetOutputVolume() और GetOutputByteFrequencyData() इस्तेमाल करें।

पूरी WebGL कंपैटिबिलिटी मैट्रिक्स के लिए COMPATIBILITY.md देखें।

समस्या निवारण

• StartSessionAsync, ArgumentException थ्रो करता है। AgentId, SignedUrl या ConversationToken में से ठीक एक सेट करें।
• मान्य एजेंट ID के लिए सेशन कनेक्ट नहीं हो पाता। एजेंट को ऑथेंटिकेशन चाहिए। ऑथेंटिकेशन बंद करें या signed URL से कनेक्ट करें।
• ओवरराइड का कोई असर नहीं होता। एजेंट की Security सेटिंग्स में उससे मेल खाता ओवरराइड सक्षम करें।
• खिलाड़ी को WebGL पर कुछ सुनाई नहीं देता। ब्राउज़र तब तक ऑडियो सस्पेंड रखते हैं, जब तक खिलाड़ी पेज के साथ इंटरैक्ट नहीं करता। क्लिक या की प्रेस के बाद सेशन शुरू करें।
• WebGL पर माइक्रोफ़ोन उपलब्ध नहीं है। ब्राउज़र सिर्फ़ HTTPS पर या localhost से सर्व किए गए पेजों को माइक्रोफ़ोन एक्सेस देते हैं।

GitHub पर बग रिपोर्ट करें और फ़ीचर का अनुरोध करें।