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.

Audio Connector

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

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 und 16000 (Standard).

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.

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

Binäre Audiomeldungen

Binäre Nachrichten stellen den Ton des Anrufs dar. Der von der WebSocket-Schnittstelle unterstützte Audiocodec ist Linear PCM 16-Bit mit einer Abtastrate von 16 kHz. Jede Nachricht enthält einen 640-Byte-Datenrahmen (20 ms Audio) bei 50 Rahmen (Nachrichten) pro Sekunde.

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

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

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

Meldung über die Unterbrechung der Verbindung

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 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 Binäre Audiomeldungen 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).

Anwendungsbeispiele

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