Audio-Anschluss

Mit dem Audio Connector können Sie rohe Audioströme (PCM 16 khz/16bit) aus einer Live-Videositzung von Vonage an externe Dienste wie AWS, GCP, Azure usw. über Ihre eigenen Server zur weiteren Verarbeitung und und Analyse.

Mit Audio Connector können Sie Audioströme einzeln oder gemischt senden. Sie können den Sprecher identifizieren, indem Sie die Audioströme einzeln senden, indem Sie mehrere WS-Verbindungen öffnen.

Die Weiterverarbeitung von Audioströmen in Echtzeit und offline ermöglicht die Entwicklung von Funktionen wie Untertitel, Transkriptionen, Übersetzungen, Suche und Index, Inhaltsmoderation, Media Intelligence, elektronische Gesundheitsakten, Stimmungsanalyse usw.

Sie können Audio Connector auch verwenden, um eine WebSocket-Verbindung zu verwenden Audio in einer Sitzung veröffentlichen.

Audio Connector ist standardmäßig für alle Projekte aktiviert und ist ein nutzungsbasiertes Produkt. Die Nutzung des Audio Connectors wird nach der Anzahl der Audio-Streams der Teilnehmer (oder Stream-IDs) abgerechnet die an den WebSocket-Server gesendet werden. Die Audio Connector Funktion wird nur unterstützt in gerouteten Sitzungen (Sitzungen, die die Medien-Router). Sie können bis zu 50 Audiostreams aus einer einzigen Sitzung auf einmal senden.

Wichtig Wenn eine Verbindung zu Ihrem WebSocket-Server nicht innerhalb von 6 Sekunden hergestellt wird, schlägt der Aufruf der Connect-API fehl.

Starten einer WebSocket-Verbindung

Um eine Audio Connector WebSocket-Verbindung zu starten, verwenden Sie die Die REST-API.

Sie können auch eine Audio Connector WebSocket-Verbindung mit den Server SDKs starten:

Java - Siehe die vonage.video.connectToWebsocket() Methode.
Knoten - Siehe die vonage.video.connectToWebsocket() Methode.
PHP - Siehe die vonage->video->connectAudio() Methode.
Python - Siehe die vonage.video.start_audio_connector() Methode.
Ruby - Siehe die vonage.video.web_socket.connect() Methode
.NET - Siehe die vonage.video.Broadcast.StartBroadcast() Methode

Stellen Sie eine HTTPS-POST-Anfrage an die folgende URL:

https://video.api.vonage.com/v2/project/:application_id/connect

Ersetzen Sie application_id mit Ihrer Application ID.

Verwenden Sie die nicht-interaktive Methode der OAuth 2.0-Generation zur Erstellung eines Bearer Token unter Verwendung der JWT-Struktur und Ihres privaten Schlüssels. Für weitere Informationen siehe die Authentifizierung des REST-API-Aufrufs.

Setzen Sie den Körper der Anfrage auf JSON-Daten des folgenden Formats:

{
  "sessionId": "session ID",
  "token": "A valid token",
  "websocket": {
    "uri": "wss://service.com/ws-endpoint",
    "streams": [
      "streamId-1",
      "streamId-2"
    ],
    "headers": {
      "headerKey": "headerValue"
    },
    "audioRate": 8000,
    "bidirectional": false,
    "audioTransport": {
      "transport": "binary"
    }
  }
}

Das JSON-Objekt enthält die folgenden Eigenschaften:

sessionId (erforderlich) - Die Sitzungs-ID, die die Streams enthält, die Sie die in den WebSocket-Stream aufgenommen werden sollen.
token (erforderlich) - Das Vonage-Videotoken, das für die Verbindung des Audio Connectors mit der Sitzung verwendet wird. Sie können Token hinzufügen data um festzustellen, dass es sich bei der Verbindung um den Audio Connector Endpunkt ist, oder für andere identifizierende Daten. (Die Client-Bibliotheken enthalten Eigenschaften um die Verbindungsdaten für einen mit einer Sitzung verbundenen Client zu untersuchen.) Siehe die Token-Erstellung Leitfaden für Entwickler.
websocket (erforderlich): Enthaltene Details für den WebSocket:
- uri (erforderlich): Ein öffentlich erreichbarer WebSocket-URI, der für das Ziel des des Audiostroms verwendet wird (z. B. "wss://service.com/ws-endpoint").
- streams (optional) - Ein Array von Stream-IDs für die Streams, die Sie in den WebSocket-Stream aufnehmen möchten. Wenn Sie diese Eigenschaft weglassen, werden alle Streams in der Sitzung eingeschlossen werden.
- headers (optional) - Ein Objekt mit Schlüssel-Wert-Paaren von Kopfzeilen, die mit jeder Nachricht an Ihren WebSocket-Server gesendet werden, mit einer maximalen Länge von 512 Bytes.
- audioRate (optional) - Eine Zahl, die die Audio-Abtastrate in Hz angibt. Akzeptierte Werte sind 8000, 16000 (Standard) und 24000.
- audioTransport (optional) - Ein JSON-Objekt, das konfiguriert, wie Audio auf der WebSocket-Leitung serialisiert der WebSocket-Leitung serialisiert wird. Standardmäßig wird Audio als rohe binäre PCM 16-Bit-Frames gesendet. Setzen Sie dies, um JSON-verpacktes base64-Audio zu verwenden, was von einigen KI-Anbietern (z. B. OpenAI Realtime) verlangt wird. Das Objekt hat die folgenden Eigenschaften:
  - transport (erforderlich) - "binary" (rohe PCM16, die Voreinstellung) oder "json".
  - encoding (erforderlich, wenn der Transport "json") - "base64".
  - audio_field (optional) - Der JSON-Schlüssel für die ausgehenden Audiodaten. Der Standardwert ist "audio".
  - receive_audio_field (optional) - Der JSON-Schlüssel für eingehende Audiodaten (wenn bidirektional aktiviert ist). Standardmäßig derselbe Wert wie audio_field.
  - static_fields (optional) - Ein Objekt mit zusätzlichen Schlüssel-Wert-Paaren, die in jeder ausgehenden JSON-Audionachricht enthalten sind.
  Siehe die Abschnitt über das Format der Transportkonfiguration für Einzelheiten und Beispiele.

Ein erfolgreicher Aufruf führt zu einer HTTP 200-Antwort, wobei die Details in den JSON-Antwortdaten enthalten sind:

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007"
}

Die JSON-Antwortdaten umfassen die folgenden Eigenschaften:

id - Eine eindeutige ID zur Identifizierung der Audio Connector WebSocket-Verbindung.
connectionId - Die Verbindungs-ID für die Audio Connector WebSocket-Verbindung in der Sitzung.

Für weitere Einzelheiten siehe die Audio Connector REST API Dokumentation.

Benutzerdefinierte Kopfzeilen (HTTP und WebSocket)

Wenn Sie die WebSocket-Verbindung über REST oder Server-SDKs starten, wird eine HTTP Verbindungsanfrage an Ihren WebSocket-Server gesendet, die auf WebSocket umgestellt werden soll. Server gesendet.

Während des anfänglichen HTTP-Upgrades enthalten die Header der HTTP-Anfrage an Ihren WebSocket-Server Folgendes:

x-opentok-ws-conferenceid: Auf die Konferenz-ID einstellen;
x-opentok-ws-connectionid: Wird auf die Verbindungs-ID gesetzt;
x-opentok-ws-sessionid: Wird auf die Sitzungs-ID gesetzt.

Zusätzlich können Sie eine headers JSON-Objekt im Websocket-Abschnitt des REST-API-Textes oder des SDK-Anfragetextes. Diese Header verhalten sich je nach Phase der Verbindung unterschiedlich:

Während des ersten HTTP-Upgrades: Alle bereitgestellten Header werden als HTTP-Anfrageheader an Ihren WebSocket-Server gesendet.
Nachdem der WebSocket eingerichtet ist: Ihre Kopfzeilen sind in jeder textbasierten WebSocket-Steuernachricht als Textblock enthalten. Dies beinhaltet:
- Die ursprüngliche websocket:connected Nachricht;
- Für websocket:media:update Nachrichten (wenn der Ton aktiv oder inaktiv wird);
- Die websocket:cleared Nachricht;
- Die websocket:notify Nachricht;
- Das Finale websocket:disconnected Nachricht.
- Die ursprüngliche websocket:connected Nachricht
- websocket:media:update Nachrichten (wenn Audio aktiv oder inaktiv wird)
- Das Finale websocket:disconnected Nachricht
Kopfzeilenschlüssel sind kanonisiert auf das herkömmliche HTTP-Header-Gehäuse (zum Beispiel, X-CUSTOM-HEADER wird X-Custom-Header). Bei den Kopfzeilenschlüsseln wird nicht zwischen Groß- und Kleinschreibung unterschieden.
Eine Ausnahme: Die Puffer-Löschbestätigung ({"event":"websocket:cleared"}) enthält keine benutzerdefinierten Header. Wir werden dies in den nächsten Versionen von AudioConnector beheben.
Binäre Audio-Frames: Diese enthalten nur Audiodaten und keine Header.
Sonderbehandlung für x-opentok-ws* Kopfzeilen: Alle Kopfzeilenschlüssel mit dem Präfix x-opentok-ws werden nur im HTTP-Handshake verwendet und aus der JSON-Nutzlast entfernt, die in Textnachrichten wiedergegeben wird.

Die CUSTOM-HEADER-* Eigenschaften, die in den folgenden Nachrichtenbeispielen gezeigt werden, stammen aus dem headers Eigenschaft, die beim Starten der Verbindung angegeben wird.

Benutzerdefinierte Kopfzeilen sind auf 512 Byte begrenzt, berechnet auf der Grundlage der serialisierten JSON-Länge der headers Websocket-Objekt. Wenn die serialisierte Größe 512 Bytes überschreitet, schlägt die Verbindungsanfrage fehl.

WebSocket-Nachrichten

Erste Nachricht

Die erste Nachricht, die bei einer aufgebauten WebSocket-Verbindung gesendet wird, ist textbasiert und enthält eine JSON-Nutzlast, sie hat eine event Feld gesetzt auf websocket:connectedwird das Audioformat detailliert in content-type zusammen mit allen anderen Metadaten, die Sie in der headers Eigenschaft des Körpers im POST-Endpunkt. Die headers Eigenschaft ist in der JSON-Nutzlast der Nachricht nicht vorhanden, sodass sich die Eigenschaften auf der obersten Ebene des JSON befinden. Zum Beispiel:

{
    "content-type":"audio/l16;rate=16000",
    "event": "websocket:connected",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Audio-Nachrichten formatieren

Standardmäßig sendet und empfängt Audio Connector Audio als rohe binäre PCM 16-bit Frames über den WebSocket. Einige AI-Anbieter (z.B. die OpenAI Realtime API) erwarten Audio in JSON-Nachrichten mit base64-Kodierung. Anstatt einen Proxy laufen zu lassen, um das Audio umzuframpen, können Sie die audioTransport Eigentum in der websocket Objekt, wenn Sie Starten Sie den Audioanschluss.

Format der Transportkonfiguration

Die audioTransport value ist ein JSON-Objekt mit den folgenden Feldern:

Field	Required	Description
`transport`	Yes	`"binary"` (raw PCM16 — the default) or `"json"`.
`encoding`	When `transport` is `"json"`	`"base64"`. The encoding used for the audio payload inside the JSON message.
`audio_field`	No	The JSON key that holds the outbound audio data. Defaults to `"audio"`.
`receive_audio_field`	No	The JSON key for inbound audio data (when bidirectional is enabled). Defaults to the same value as `audio_field`.
`static_fields`	No	An object of extra key-value pairs included in every outbound JSON audio message.

Beispiel: JSON-Transport mit Base64-Kodierung

Die folgenden audioTransport Konfiguration verpackt ausgehendes Audio als base64 in einer JSON-Nachricht und fügt eine statische type Feld zu jeder Nachricht hinzuzufügen - entsprechend dem von der OpenAI Realtime API erwarteten Format:

{
  "transport": "json",
  "encoding": "base64",
  "audio_field": "audio",
  "static_fields": {
    "type": "input_audio_buffer.append"
  }
}

Jede ausgehende WebSocket-Nachricht wird wie folgt aussehen:

{
  "type": "input_audio_buffer.append",
  "audio": "<base64-encoded PCM16 audio>"
}

Wenn bidirectional ist trueliest der Audio Connector auch eingehende JSON-Nachrichten unter Verwendung der receive_audio_field Taste (oder audio_field wenn receive_audio_field nicht gesetzt ist) und dekodiert das base64-Audio für die Wiedergabe in der Sitzung.

Beispiel: Standard-Binär-Transport

Wenn Sie auslassen audioTransport (oder setzen transport zu "binary"), wird Audio als Linear PCM 16-Bit mit dem konfigurierten Wert gesendet und empfangen. audioRate. Jede Nachricht enthält einen 20 ms langen Audio-Frame, so dass die Frame-Größe mit der Zeit variiert. audioRate: 320 Byte bei 8kHz, 640 Byte bei 16kHz und 960 Byte bei 24kHz, gesendet mit 50 Bildern (Nachrichten) pro Sekunde. Wenn audioRate weggelassen wird, verwendet der Standard-Binär-Transport 16-kHz-Audio mit 640-Byte-Frames.

Audio-Aktiv/Inaktiv-Meldungen

Wenn das Audio in den Streams, die im WebSocket enthalten sind, stummgeschaltet wird, wird eine Textnachricht mit dem folgenden JSON-Nutzdaten (mit active eingestellt auf false):

{
    "content-type":"audio/l16;rate=16000",
    "method": "update",
    "event": "websocket:media:update",
    "active": false,
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

(Die CUSTOM-HEADER Eigenschaften in diesem Beispiel stellen Metadaten dar, die Sie in die headers Eigenschaft des Körpers in der POST-Anforderung, um die WebSocket Verbindung).

Audio kann stummgeschaltet werden, weil alle Clients die Veröffentlichung von Audio stoppen oder als Ergebnis einer Stummschaltung der Moderation erzwingen Veranstaltung.

Wenn der Ton eines der Streams wieder aufgenommen wird, wird eine Textnachricht mit dem folgenden JSON-Nutzdaten (mit active eingestellt auf true):

{
    "content-type":"audio/l16;rate=16000",
    "method": "update",
    "event": "websocket:media:update",
    "active": true,
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Stream-Ereignis-Meldungen

Wenn Verlage eine Verbindung zu einer Sitzung herstellen, wird eine Textnachricht mit der folgenden JSON Nutzdaten (mit method eingestellt auf created):

{
    "content-type": "audio/l16;rate=16000",
    "method": "created",
    "event": "websocket:stream:created",
    "info": {
        "projectId": "100",
        "sessionId": "1_MX4xMDB-fjE3NzA3NDAzMzIzMjh-ZXkvR1d6YjZoZHlkcHlySFRuNmtlTFZMfn5-",
        "stream": {
            "id": "c4ed69a1-b9a1-44a9-bbc5-edfcf099d772",
            "connection": {
                "id": "33f8c459-a18a-4a81-b1e4-b7d1bdbbc323"
            }
        }
    },
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

(Die CUSTOM-HEADER Eigenschaften in diesem Beispiel stellen Metadaten dar, die Sie in die headers Eigenschaft des Körpers in der POST-Anforderung, um die WebSocket Verbindung).

Wenn Streams die Verbindung zur Sitzung trennen, wird eine Textnachricht mit der folgenden JSON Nutzdaten (mit method eingestellt auf destroyed):

{
    "content-type": "audio/l16;rate=16000",
    "method": "destroyed",
    "event": "websocket:stream:destroyed",
    "info": {
        "projectId": "100",
        "sessionId": "1_MX4xMDB-fjE3NzA3NDAzMzIzMjh-ZXkvR1d6YjZoZHlkcHlySFRuNmtlTFZMfn5-",
        "stream": {
            "id": "c4ed69a1-b9a1-44a9-bbc5-edfcf099d772",
            "connection": {
                "id": "33f8c459-a18a-4a81-b1e4-b7d1bdbbc323"
            }
        }
    },
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Puffer leeren (CLEAR) Nachricht

Ihr WebSocket-Server kann optional eine textbasierte Kontrollnachricht senden, um den Audio Connector anzuweisen, alle Audio-Frames, die derzeit gepuffert, aber noch nicht geliefert wurden, sofort zu verwerfen. Dies ist nützlich für Echtzeit-Anwendungsfälle wie Barge-In, Unterbrechung der TTS-Wiedergabe oder Zurücksetzen einer Gesprächsrunde.

Um gepuffertes Audio zu flushen, senden Sie die folgende JSON-Nachricht über den WebSocket:

{
    "action": "CLEAR"
}

Wenn der Audio Connector diese Nachricht empfängt, werden alle ausstehenden gepufferten Audio-Frames verworfen, neu eingehende Audiodaten werden ohne Unterbrechung weiter gestreamt, und es wird eine Bestätigungsnachricht zurückgegeben:

{
    "event": "websocket:cleared",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Diese Kontrollmeldung ist optional. Wenn Sie nicht senden "action": "CLEAR"wird das Audio-Streaming normal fortgesetzt.

Benachrichtigung (NOTIFY) Nachricht

Ihr WebSocket-Server kann optional eine textbasierte Kontrollnachricht senden (NOTIFY). Der Audio Connector sendet die ursprüngliche Nutzlast unverändert zurück, sobald die Nachricht in der Reihenfolge des Audiostroms verarbeitet wurde. Dies kann als Marker verwendet werden, um Anwendungsereignisse mit dem Audiofluss zu korrelieren.

Zum Senden einer NOTIFY senden Sie die folgende JSON-Nachricht über den WebSocket:

{
    "action": "NOTIFY",
    "payload": "some info"
}

Wenn die Nachricht empfangen wird, wird sie an das Ende der Audio-Warteschlange gestellt. Nachdem das Audio konsumiert wurde und der Audio Connector diese Nachricht verarbeitet hat, wird eine Bestätigungsnachricht an Ihren WebSocket-Server gesendet:

{
    "event": "websocket:notify",
    "payload": "some info",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Diese Kontrollmeldung ist optional. Wenn Sie nicht senden "action": "NOTIFY"wird das Audio-Streaming normal fortgesetzt.

Unterbrochene Nachricht

Wenn der Audio Connector WebSocket aufgrund eines Aufrufs der REST-Methode zum erzwungenen Trennen der Verbindung oder weil die 6-Stunden Frist erreicht ist (siehe Beenden einer WebSocket-Verbindung), wird eine Textnachricht mit der folgenden JSON-Nutzlast gesendet:

{
    "content-type":"audio/l16;rate=16000",
    "method": "delete",
    "event": "websocket:disconnected",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

Diese Nachricht markiert die Beendigung der WebSocket-Verbindung.

(Die CUSTOM-HEADER Eigenschaften in diesem Beispiel stellen Metadaten dar, die Sie in die headers Eigenschaft des Körpers in der POST-Anforderung, um die WebSocket Verbindung).

Beenden einer WebSocket-Verbindung

Wenn Ihr WebSocket-Server die Verbindung schließt, wird auch die Vonage-Videoverbindung für den Anruf beendet. In jedem Client, der mit der Sitzung verbunden ist, sendet das Client-seitige SDK Ereignisse, die anzeigen dass die Verbindung beendet wurde (so wie es der Fall wäre, wenn andere Clients die Verbindung zur Sitzung trennen).

Sie können die Audio Connector WebSocket-Verbindung mit dem Befehl REST-Methode zum erzwungenen Trennen der Verbindung. Verwenden Sie die Verbindungs-ID der Audio Connector WebSocket-Verbindung mit dieser Methode.

Als Sicherheitsmaßnahme wird der WebSocket nach 6 Stunden automatisch geschlossen.

Automatische Wiederanschlüsse

Audio Connector unternimmt einige Versuche, eine WebSocket-Verbindung wiederherzustellen wiederherzustellen, die unerwartet geschlossen wird (z. B. wenn der WebSocket geschlossen wird, ohne dass von einem Aufruf an die REST-Methode zum erzwungenen Trennen der Verbindung).

Veröffentlichen von Audio in einer Sitzung über den WebSocket

Sie können die Audio Connector WebSocket-Verbindung verwenden, um Audiodaten von der WebSocket-Verbindung an einen Stream zu senden, der in einer Vonage-Sitzung veröffentlicht wird (zusätzlich dazu, dass die WebSocket-Verbindung Audio von der Sitzung empfängt). Setzen Sie die bidirectional Eigenschaft zu true in den Daten, die Sie mit der REST-API-Methode an Starten Sie den Audioanschluss.

Siehe Audio-Nachrichten formatieren für Details zum Format der Audiodaten, die über die WebSocket-Verbindung gesendet werden sollen.

Beim Erstellen des Tokens, das vom Audio Connector verwendet wird, können Sie das Token data um den Audio Connector Stream zu identifizieren. (Die Vonage Client-Bibliotheken enthalten Methoden zur Überprüfung der Verbindungsdaten für die Verbindung eines Streams in der Sitzung).

Muster-Applikation

Siehe die Bidirektionaler Audio-Anschluss Projekt für eine Node-Beispielanwendung, die den bidirektionalen Audio Connector verwendet.

Navigation

Audio-Anschluss

Starten einer WebSocket-Verbindung

Benutzerdefinierte Kopfzeilen (HTTP und WebSocket)

WebSocket-Nachrichten

Erste Nachricht

Audio-Nachrichten formatieren

Format der Transportkonfiguration

Beispiel: JSON-Transport mit Base64-Kodierung

Beispiel: Standard-Binär-Transport

Audio-Aktiv/Inaktiv-Meldungen

Stream-Ereignis-Meldungen

Puffer leeren (CLEAR) Nachricht

Benachrichtigung (NOTIFY) Nachricht

Unterbrochene Nachricht

Beenden einer WebSocket-Verbindung

Automatische Wiederanschlüsse

Veröffentlichen von Audio in einer Sitzung über den WebSocket

Muster-Applikation