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 OpenTok-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 OpenTok Media Router). Sie können bis zu 50 Audiostreams aus einer einzigen Sitzung auf einmal senden.

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

Diese Seite enthält die folgenden Abschnitte:

Starten einer WebSocket-Verbindung

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

Sie können eine Audio Connector-WebSocket-Verbindung auch mithilfe der OpenTok-Server-SDKs herstellen:

  • Java - Siehe die OpenTok.connectAudioStream() Methode.
  • Knoten - Siehe die opentok.websocketConnect() Methode.
  • PHP - Siehe die OpenTok->connectAudio()] Methode.
  • Python - Siehe die opentok.connect_audio_to_websocket() Methode.
  • Ruby - Siehe die opentok.websocket.connect() Methode
  • .NET - Siehe die OpenTok.StartBroadcast() Methode

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.

    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"
}

Ereignismeldungen streamen

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 trennt, wird auch die OpenTok-Verbindung für den Anruf beendet. Auf jedem mit der Sitzung verbundenen Client löst das clientseitige OpenTok-SDK Ereignisse aus, die anzeigen, dass die Verbindung beendet wurde (genau wie bei der Trennung anderer Clients von der Sitzung).

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 nutzen, um Audiodaten über die WebSocket-Verbindung an einen in einer OpenTok-Sitzung veröffentlichten Stream zu senden (zusätzlich dazu, dass die WebSocket-Verbindung Audio aus der Sitzung empfängt). Legen 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 OpenTok-Client-Bibliotheken enthalten Methoden zur Überprüfung der Verbindungsdaten für die Verbindung eines Streams innerhalb einer Sitzung.)

Anmerkung: Die bidirectional Diese Option ist nur in der REST-API verfügbar. In den OpenTok-Server-SDKs wird sie derzeit nicht unterstützt.

Muster-Applikation

Siehe die Demo-Video-Knoten-Audioanschluss Projekt für eine Beispiel-Node-Anwendung, die den Audio Connector nutzt.

Weitere Informationen

Siehe hier Blog-Beitrag.