> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Unity SDK

> **Info**
>
> ElevenAgents कैसे काम करता है, इसकी जानकारी के लिए [ElevenAgents ओवरव्यू](/docs/hi/eleven-agents/overview) देखें।

[ElevenAgents Unity SDK](https://github.com/elevenlabs/unity) एक 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 अकाउंट और एजेंट। [डैशबोर्ड](https://elevenlabs.io/app/agents) में बनाएं या [क्विकस्टार्ट](/docs/hi/eleven-agents/quickstart) अपनाएं।

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

| टारगेट                                                          | ट्रांसपोर्ट                            | स्टेटस                        |
| --------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| Editor (Play Mode), डेस्कटॉप स्टैंडअलोन (macOS, Windows, Linux) | Native WebSocket                       | समर्थित                       |
| WebGL                                                           | JS ब्रिज के ज़रिए `@elevenlabs/client` | समर्थित (WebSocket और WebRTC) |
| iOS, Android, XR                                                | Native WebSocket                       | टेस्ट नहीं किया गया           |

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

> **Note**
>
> SDK माइक्रोफ़ोन अनुमति नहीं मांगता। iOS और Android पर सेशन शुरू करने से पहले इसे खुद मांगें।

## इंस्टॉलेशन

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

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

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

> **Tip**
>
> पैकेज में दो सैंपल आते हैं। उन्हें **Package Manager** > **ElevenAgents** >
> **Samples** से इंपोर्ट करें। **QuickStart** एक MonoBehaviour है जो लाइव ट्रांसक्रिप्ट दिखाता है।
> **GettingStarted** स्पेशल ऑडियो और डायनामिक वेरिएबल्स वाला walk-up-and-talk सीन है।
> चरण-दर-चरण गाइड के लिए [Getting started walkthrough](https://github.com/elevenlabs/unity/blob/main/Docs~/GETTING_STARTED.md) देखें।

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

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

#### एक पब्लिक एजेंट बनाएं

[ElevenLabs डैशबोर्ड](https://elevenlabs.io/app/agents) में एजेंट बनाएं। एजेंट की **Security** सेटिंग्स में **Authentication** बंद करें, ताकि गेम सिर्फ़ एजेंट ID से कनेक्ट हो सके। एजेंट ID कॉपी करें।

जिन एजेंट के लिए ऑथेंटिकेशन ज़रूरी है, उनके लिए [पब्लिक और प्राइवेट एजेंट](#public-and-private-agents) देखें।

#### SDK इंस्टॉल करें

[इंस्टॉलेशन](#installation) में बताए अनुसार git URL से पैकेज इंस्टॉल करें।

#### कन्वर्सेशन स्क्रिप्ट जोड़ें

`Assets/Scripts/AgentConversation.cs` बनाएं:

**`AgentConversation.cs`**

```csharp title="AgentConversation.cs"
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();
    }
}
```

कनेक्शन खुलने और ऑडियो डिवाइस तैयार होने पर `Conversation.StartSessionAsync` रिटर्न करता है। `EndSession` idempotent है, इसलिए सेशन पहले ही खत्म हो चुका हो तब भी इसे `OnDestroy` से कॉल करना सुरक्षित है।

#### सीन चलाएं

एक खाली GameObject बनाएं, `AgentConversation` कंपोनेंट जोड़ें और **Agent Id** फ़ील्ड में अपनी एजेंट ID पेस्ट करें। Play Mode में जाएं और ऑपरेटिंग सिस्टम के पूछने पर माइक्रोफ़ोन एक्सेस की अनुमति दें। एजेंट अपना पहला संदेश बोलता है और ट्रांसक्रिप्ट Console में दिखता है।

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

#### पब्लिक एजेंट

एजेंट ID सीधे पास करें। ID वाला कोई भी व्यक्ति एजेंट के साथ बातचीत शुरू कर सकता है।

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

#### प्राइवेट एजेंट

ऑथेंटिकेशन सक्षम वाले एजेंट को आपके अपने सर्वर से जारी किया गया कम समय के लिए वैध क्रेडेंशियल चाहिए। अपने बैकएंड से [signed URL](/docs/hi/eleven-agents/customization/authentication) मांगें और उसे `SignedUrl` के रूप में पास करें:

```csharp
using UnityEngine.Networking;

private static async Awaitable<string> FetchSignedUrlAsync()
{
    using var request = UnityWebRequest.Get("https://api.example-game.com/agent/signed-url");
    await request.SendWebRequest();
    if (request.result != UnityWebRequest.Result.Success)
        throw new InvalidOperationException(request.error);
    return request.downloadHandler.text;
}

var conversation = await Conversation.StartSessionAsync(
    new ConversationOptions { SignedUrl = await FetchSignedUrlAsync() }
);
```

WebGL पर WebRTC सेशन के लिए, बातचीत टोकन को `ConversationToken` के रूप में पास करें और `ConnectionType = ConnectionType.WebRTC` सेट करें।

> **Warning**
>
> गेम बिल्ड में कभी भी अपनी ElevenLabs API key शामिल न करें। अपने नियंत्रण वाले सर्वर पर signed URLs और बातचीत टोकन जनरेट करें।

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

## स्पेशल ऑडियो

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

```csharp
[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 के बीच वैल्यू रिटर्न करता है।

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

एजेंट के प्रॉम्प्ट और पहले संदेश में प्लेसहोल्डर भरने के लिए [डायनामिक वेरिएबल्स](/docs/hi/eleven-agents/customization/personalization/dynamic-variables) और एक सेशन के लिए एजेंट कॉन्फ़िगरेशन के हिस्से बदलने के लिए [ओवरराइड्स](/docs/hi/eleven-agents/customization/personalization/overrides) इस्तेमाल करें:

```csharp
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** सेटिंग्स में सक्षम करना होगा।

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

[क्लाइंट टूल्स](/docs/hi/eleven-agents/customization/tools/client-tools), एजेंट को आपके गेम में ऐक्शन ट्रिगर करने देते हैं। एजेंट की सेटिंग्स में टूल परिभाषित करें, फिर उसी नाम से हैंडलर रजिस्टर करें:

```csharp
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 पर ट्रिगर करता है।

| इवेंट                     | पेलोड                  | विवरण                                                                       |
| ------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `Disconnected`            | `DisconnectionDetails` | सेशन समाप्त हो गया। `Reason`, `User`, `Agent` या `Error` होता है।           |
| `ErrorOccurred`           | `string`               | सेशन शुरू होने के बाद एक error हुआ।                                         |
| `StatusChanged`           | `Status`               | कनेक्शन स्टेटस बदल गया।                                                     |
| `ModeChanged`             | `Mode`                 | एजेंट `Speaking` और `Listening` के बीच स्विच हुआ।                           |
| `UserTranscriptReceived`  | `UserTranscriptArgs`   | खिलाड़ी की स्पीच का अंतिम ट्रांसक्रिप्ट।                                    |
| `AgentResponded`          | `AgentResponseArgs`    | एजेंट के जवाब का टेक्स्ट।                                                   |
| `Interrupted`             | `InterruptionArgs`     | खिलाड़ी ने एजेंट को बाधित किया।                                             |
| `AgentToolRequested`      | `AgentToolRequestArgs` | एजेंट ने टूल कॉल शुरू की। पूरा होने पर `AgentToolResponded` ट्रिगर होता है। |
| `UnhandledClientToolCall` | `ClientToolCallArgs`   | एजेंट ने बिना रजिस्टर हैंडलर वाले क्लाइंट टूल को कॉल किया।                  |
| `CanSendFeedbackChanged`  | `bool`                 | सबसे नए एजेंट जवाब के लिए फ़ीडबैक उपलब्ध या अनुपलब्ध हुआ।                   |

`Connected` इवेंट, `StartSessionAsync` के रिटर्न होने से पहले ट्रिगर होता है, इसलिए कॉल पूरा होने पर सीधे `ConversationId` और `Status` पढ़ें। [पैकेज चेंजलॉग](https://github.com/elevenlabs/unity/blob/main/CHANGELOG.md) में इवेंट्स की पूरी सूची है।

## मेथड्स

| मेथड                                                          | विवरण                                                               |
| ------------------------------------------------------------- | ------------------------------------------------------------------- |
| `EndSession()`                                                | कनेक्शन बंद करें और ऑडियो डिवाइस रिलीज़ करें।                       |
| `SendUserMessage(string text)`                                | ऐसे टेक्स्ट संदेश भेजें जैसे खिलाड़ी ने उसे बोला हो।                |
| `SendContextualUpdate(string text)`                           | बातचीत बाधित किए बिना एजेंट के साथ गेम स्टेट साझा करें।             |
| `SendUserActivity()`                                          | संकेत दें कि खिलाड़ी सक्रिय है, ताकि एजेंट अपनी बारी बनाए रखे।      |
| `SendFeedback(bool like)`                                     | `CanSendFeedback` के `true` होने पर सबसे नए एजेंट जवाब को रेट करें। |
| `SetMicMuted(bool isMuted)`                                   | माइक्रोफ़ोन म्यूट या अनम्यूट करें।                                  |
| `SetVolume(float volume)`                                     | एजेंट का प्लेबैक वॉल्यूम 0 और 1 के बीच सेट करें।                    |
| `GetInputVolume()`, `GetOutputVolume()`                       | मौजूदा माइक्रोफ़ोन या एजेंट ऑडियो लेवल 0 और 1 के बीच पढ़ें।         |
| `GetInputByteFrequencyData()`, `GetOutputByteFrequencyData()` | ऑडियो विज़ुअलाइज़र के लिए फ़्रीक्वेंसी डेटा से बाइट बफ़र भरें।      |
| `UploadFileAsync()`, `SendMultimodalMessage()`                | फ़ाइल अपलोड करें और उसे यूज़र संदेश में अटैच करें।                  |
| `ChangeInputDevice()`, `ChangeOutputDevice()`                 | सेशन के दौरान माइक्रोफ़ोन या आउटपुट डिवाइस बदलें।                   |

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

```csharp
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()` इस्तेमाल करें।

> **Note**
>
> सक्रिय बिल्ड टारगेट WebGL होने पर Editor में Play Mode अभी समर्थित नहीं है। Editor में टेस्ट करने के लिए
> डेस्कटॉप बिल्ड टारगेट पर स्विच करें।

पूरी WebGL कंपैटिबिलिटी मैट्रिक्स के लिए [`COMPATIBILITY.md`](https://github.com/elevenlabs/unity/blob/main/COMPATIBILITY.md) देखें।

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

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

[GitHub](https://github.com/elevenlabs/unity/issues) पर बग रिपोर्ट करें और फ़ीचर का अनुरोध करें।