Connecteur audio

Le connecteur audio vous permet d'envoyer des flux audio bruts (PCM 16 khz/16bit) d'une session vidéo Vonage en direct vers des services externes tels que AWS, GCP, Azure, etc., par le biais de vos propres serveurs pour un traitement et une analyse plus poussés. traitement et d'analyse.

Avec Audio Connector, vous pouvez envoyer des flux audio individuellement ou mélangés. Vous pouvez identifier le locuteur en envoyant les flux audio individuellement en ouvrant plusieurs connexions WS.

Le traitement ultérieur des flux audio en temps réel et hors ligne permet de construire des capacités telles que les sous-titres, les transcriptions, les traductions, la recherche et l'indexation, la modération de contenu, l'intelligence médiatique, les dossiers médicaux électroniques, l'analyse des sentiments, etc, l'intelligence médiatique, les dossiers médicaux électroniques, l'analyse des sentiments, etc.

Vous pouvez également utiliser Audio Connector pour utiliser une connexion WebSocket pour publier de l'audio dans une session.

L'Audio Connector est activé par défaut pour tous les projets et il s'agit d'un produit basé sur l'utilisation. L'utilisation de l'Audio Connector est facturée en fonction du nombre de flux audio des participants (ou ID de flux) envoyés au serveur WebSocket. La fonction Connecteur audio n'est prise en charge que dans les cas suivants les sessions routées (sessions qui utilisent le protocole Routeur média). Vous pouvez envoyer jusqu'à 50 flux audio d'une seule session à la fois.

Important Si une connexion à votre serveur WebSocket n'est pas établie dans les 6 secondes, l'appel à l'API Connect échouera.

Démarrer une connexion WebSocket

Pour démarrer une connexion WebSocket de l'Audio Connector, utilisez la commande L'API REST.

Vous pouvez également démarrer une connexion WebSocket Audio Connector à l'aide des SDK du serveur :

Java - Voir la page vonage.video.connectToWebsocket() méthode.
Nœud - Voir le vonage.video.connectToWebsocket() méthode.
PHP - Voir la page vonage->video->connectAudio() méthode.
Python - Voir la page vonage.video.start_audio_connector() méthode.
Ruby - Voir le site vonage.video.web_socket.connect() méthode
.NET - Voir la page vonage.video.Broadcast.StartBroadcast() méthode

Effectuez une requête HTTPS POST à l'URL suivante :

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

Remplacer application_id avec votre numéro d'identification de la demande.

Utilisez la méthode non interactive de génération OAuth 2.0 pour créer un jeton de support en utilisant la structure JWT et votre clé privée. Pour plus d'informations, voir l'authentification de l'appel à l'API REST.

Définir le corps de la demande en données JSON au format suivant :

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

L'objet JSON comprend les propriétés suivantes :

sessionId (obligatoire) - L'identifiant de session qui comprend les flux que vous souhaitez inclure dans le flux WebSocket. inclure dans le flux WebSocket.
token (obligatoire) - Le jeton vidéo Vonage à utiliser pour la connexion du connecteur audio à la session. session. Vous pouvez ajouter des jetons data pour indiquer que la connexion est le point d'arrivée de l'Audio Connector ou pour d'autres données d'identification. (Les bibliothèques client comprennent des propriétés pour inspecter les données de connexion d'un client connecté à une session). Voir la page Création de jetons guide du développeur.
websocket (obligatoire) : Détails inclus pour la WebSocket :
- uri (obligatoire) : URI WebSocket accessible au public à utiliser pour la destination du flux audio le flux audio (par exemple "wss://service.com/ws-endpoint").
- streams (facultatif) - Un tableau d'ID de flux pour les flux à inclure dans le flux WebSocket. inclure dans le flux WebSocket. Si vous omettez cette propriété, tous les flux de la session seront inclus. seront inclus.
- headers (facultatif) - Un objet de paires clé-valeur d'en-têtes à envoyer à votre serveur WebSocket avec chaque message. serveur WebSocket avec chaque message, d'une longueur maximale de 512 octets.
- audioRate (facultatif) - Un nombre représentant la fréquence d'échantillonnage audio en Hz. Les valeurs acceptées sont 8000, 16000 (par défaut) et 24000.
- audioTransport (facultatif) - Un objet JSON qui configure la façon dont l'audio est sérialisé sur le câble WebSocket. sur le câble WebSocket. Par défaut, l'audio est envoyé sous forme de trames binaires PCM 16 bits brutes. Définissez ceci pour utiliser de l'audio base64 enveloppé de JSON, ce qui est requis par certains fournisseurs d'IA (par exemple, OpenAI Realtime). L'objet possède les propriétés suivantes :
  - transport (obligatoire) - "binary" (PCM16 brut, par défaut) ou "json".
  - encoding (nécessaire lorsque le transport est "json") - "base64".
  - audio_field (facultatif) - Clé JSON pour les données audio sortantes. La valeur par défaut est "audio".
  - receive_audio_field (facultatif) - Clé JSON pour les données audio entrantes (lorsque la fonction bidirectionnelle est activée). La valeur par défaut est la même que celle de audio_field.
  - static_fields (facultatif) - Un objet de paires clé-valeur supplémentaires incluses dans chaque message audio JSON sortant.
  Voir le section sur le format de configuration du transport pour plus de détails et d'exemples.

Un appel réussi entraîne une réponse HTTP 200, dont les détails sont inclus dans les données de réponse JSON :

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

Les données de la réponse JSON comprennent les propriétés suivantes :

id - ID unique identifiant la connexion WebSocket du connecteur audio.
connectionId - L'identifiant de connexion pour la connexion WebSocket du connecteur audio dans la session.

Pour plus de détails, voir la documentation de l'API REST de l'Audio Connector.

En-têtes personnalisés (HTTP et WebSocket)

Lorsque vous démarrez la connexion WebSocket via REST ou les SDK de serveur, une demande de connexion HTTP à transformer en WebSocket, sera envoyée à votre serveur WebSocket. à votre serveur WebSocket.

Lors de la mise à niveau HTTP initiale, les en-têtes de la requête HTTP vers votre serveur WebSocket comprendront :

x-opentok-ws-conferenceid: Définit l'ID de la conférence ;
x-opentok-ws-connectionid: Indique l'ID de la connexion ;
x-opentok-ws-sessionid: Indique l'ID de la session.

En outre, vous pouvez inclure un headers JSON dans la section websocket du corps de l'API REST ou du corps de la requête SDK. Ces en-têtes se comportent différemment selon la phase de la connexion :

Pendant la mise à niveau HTTP initiale : Tous les en-têtes fournis sont envoyés en tant qu'en-têtes de requête HTTP à votre serveur WebSocket.
Une fois la liaison WebSocket établie : Vos en-têtes sont inclus dans chaque message de contrôle WebSocket sous la forme d'un bloc de texte. Il s'agit notamment de
- La première websocket:connected message ;
- Pour websocket:media:update (lorsque l'audio devient actif ou inactif) ;
- Les websocket:cleared message ;
- Les websocket:notify message ;
- La finale websocket:disconnected message.
- La première websocket:connected message
- websocket:media:update les messages (lorsque l'audio devient actif ou inactif)
- La finale websocket:disconnected message
Les clés d'en-tête sont canonisé à la casse conventionnelle des en-têtes HTTP (par exemple, X-CUSTOM-HEADER devient X-Custom-Header). Les clés d'en-tête ne sont pas sensibles à la casse.
Exception : La confirmation de l'effacement de la mémoire tampon ({"event":"websocket:cleared"}) n'inclut pas les en-têtes personnalisés. Nous corrigerons ce problème dans les prochaines versions d'AudioConnector.
Trames audio binaires : Ils contiennent uniquement des données audio et n'incluent pas les en-têtes.
Traitement spécial pour x-opentok-ws* les en-têtes : Toute clé d'en-tête préfixée par x-opentok-ws ne sont utilisés que dans la poignée de main HTTP et sont supprimés de la charge utile JSON répercutée dans les messages texte.

Les CUSTOM-HEADER-* présentées dans les exemples de messages ci-dessous proviennent de l'application headers fournie lors de l'établissement de la connexion.

Les en-têtes personnalisés sont limités à 512 octets, calculés sur la base de la longueur JSON sérialisée de l'en-tête headers objet websocket. Si la taille sérialisée dépasse 512 octets, la demande de connexion échouera.

Messages WebSocket

Premier message

Le message initial envoyé sur une connexion WebSocket établie sera de type texte et contiendra une charge utile JSON. event Le champ est fixé à websocket:connectedIl détaillera le format audio en content-type ainsi que toutes les autres métadonnées que vous avez placées dans le fichier headers du corps dans le point de terminaison POST. La propriété headers n'est pas présente dans la charge utile JSON du message, de sorte que les propriétés se trouvent au niveau supérieur du JSON. Par exemple, les propriétés sont au niveau supérieur du JSON :

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

Format des messages audio

Par défaut, l'Audio Connector envoie et reçoit de l'audio sous forme de trames PCM 16 bits binaires brutes sur la WebSocket. Certains fournisseurs d'IA (par exemple, l'API Realtime d'OpenAI) attendent de l'audio enveloppé dans des messages JSON avec un encodage base64. Au lieu d'exécuter un proxy pour recadrer l'audio, vous pouvez définir la propriété audioTransport propriété dans le websocket lorsque vous démarrer le connecteur audio.

Format de configuration du transport

Les audioTransport est un objet JSON contenant les champs suivants :

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.

Exemple : Transport JSON avec codage Base64

Le texte suivant audioTransport La configuration enveloppe l'audio sortant en base64 à l'intérieur d'un message JSON et ajoute un fichier statique type à chaque message - ce qui correspond au format attendu par l'API OpenAI Realtime :

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

Chaque message WebSocket sortant se présente comme suit :

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

Quand bidirectional est truele connecteur audio lit également les messages JSON entrants à l'aide de la fonction receive_audio_field (ou audio_field si receive_audio_field n'est pas défini) et décode l'audio base64 pour la lecture dans la session.

Exemple : Transport binaire par défaut

Si vous omettez audioTransport (ou définir transport à "binary"), l'audio est envoyé et reçu en tant que PCM linéaire 16 bits à la fréquence configurée. audioRate. Chaque message comprend une trame audio de 20 ms, de sorte que la taille de la trame varie en fonction de la taille du message. audioRate: 320 octets à 8 kHz, 640 octets à 16 kHz et 960 octets à 24 kHz, envoyés à 50 images (messages) par seconde. Si audioRate est omis, le transport binaire par défaut utilise un son de 16 kHz avec des trames de 640 octets.

Messages audio actifs/inactifs

Lorsque le son est coupé dans les flux inclus dans la WebSocket, un message texte est envoyé avec la charge utile JSON suivante JSON suivant (avec active fixé à 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"
}

(Le CUSTOM-HEADER dans cet exemple représentent des métadonnées que vous incluez dans le headers du corps de la requête POST pour démarrer la connexion WebSocket ).

L'audio peut être coupé parce que tous les clients cessent de publier de l'audio ou à la suite d'une erreur de l'utilisateur. force mute moderation événement.

Lorsque l'audio de l'un des flux reprend, un message texte est envoyé avec la charge utile JSON suivante JSON suivant (avec active fixé à 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"
}

Messages de flux d'événements

Lorsque les éditeurs se connectent à une session, un message texte est envoyé avec la charge utile JSON suivante suivant (avec method fixé à 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"
}

(Le CUSTOM-HEADER dans cet exemple représentent des métadonnées que vous incluez dans le headers du corps de la requête POST pour démarrer la connexion WebSocket ).

Lorsque les flux se déconnectent de la session, un message texte est envoyé avec la charge utile JSON suivante suivant (avec method fixé à 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"
}

Message de purge de la mémoire tampon (CLEAR)

Votre serveur WebSocket peut éventuellement envoyer un message de contrôle textuel pour demander à l'Audio Connector d'éliminer immédiatement toutes les trames audio qui sont actuellement en mémoire tampon mais qui n'ont pas encore été livrées. Ceci est utile pour les cas d'utilisation en temps réel tels que l'intrusion, l'interruption de la lecture TTS ou la réinitialisation d'un tour de conversation.

Pour vider la mémoire tampon, envoyez le message JSON suivant par l'intermédiaire de la WebSocket :

{
    "action": "CLEAR"
}

Lorsque le connecteur audio reçoit ce message, toutes les trames audio en attente dans la mémoire tampon sont supprimées, les nouvelles données audio entrantes continuent à être diffusées sans interruption et un message de confirmation est renvoyé :

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

Ce message de contrôle est facultatif. Si vous n'envoyez pas de "action": "CLEAR"le streaming audio se déroule normalement.

Message de notification (NOTIFY)

Votre serveur WebSocket peut éventuellement envoyer un message de contrôle textuel (NOTIFY). Le connecteur audio renverra la charge utile d'origine inchangée une fois que le message aura été traité en séquence avec le flux audio. Ceci peut être utilisé comme marqueur pour corréler les événements de l'application avec le flux audio.

Pour envoyer un NOTIFY envoyer le message JSON suivant par l'intermédiaire du WebSocket :

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

Lorsque le message est reçu, il est placé à la fin de la file d'attente audio. Lorsque l'audio est consommé et que le connecteur audio traite ce message, un message de confirmation est envoyé à votre serveur WebSocket :

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

Ce message de contrôle est facultatif. Si vous n'envoyez pas de "action": "NOTIFY"le streaming audio se déroule normalement.

Message déconnecté

Lorsque le connecteur audio WebSocket s'arrête à la suite d'un appel à la fonction méthode REST de déconnexion forcée ou parce que le délai de 6 heures est atteint (voir Arrêt d'une connexion WebSocket), un message texte est envoyé avec la charge utile JSON suivante :

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

Ce message marque la fin de la connexion WebSocket.

(Le CUSTOM-HEADER dans cet exemple représentent des métadonnées que vous incluez dans le headers du corps de la requête POST pour démarrer la connexion WebSocket ).

Arrêt d'une connexion WebSocket

Lorsque votre serveur WebSocket ferme la connexion, la connexion vidéo Vonage pour l'appel se termine également. Dans chaque client connecté à la session, le Client SDK envoie des événements indiquant la fin de la connexion (comme lorsque d'autres clients se déconnectent de la session). que la connexion est terminée (comme il le ferait lorsque d'autres clients se déconnectent de la session).

Vous pouvez déconnecter la connexion WebSocket du connecteur audio à l'aide de la fonction méthode REST de déconnexion forcée. Utilisez l'ID de connexion de la connexion WebSocket du connecteur audio.

Par mesure de sécurité, le WebSocket sera fermé automatiquement après 6 heures.

Reconnexions automatiques

L'Audio Connector tentera à plusieurs reprises de rétablir une connexion WebSocket qui se ferme de manière inattendue (par exemple, si la connexion WebSocket se ferme sans qu'il y ait de résultat). qui se ferme de manière inattendue (par exemple, si la WebSocket se ferme sans résulter d'un appel à la WebSocket). d'un appel à la fonction méthode REST de déconnexion forcée).

Publication d'audio dans une session via WebSocket

Vous pouvez utiliser la connexion WebSocket du connecteur audio pour envoyer des données audio de la connexion WebSocket à un flux publié dans une session Vonage (en plus de permettre à la connexion WebSocket de recevoir de l'audio de la session). Définissez l'option bidirectional à la propriété true dans les données que vous envoyez avec la méthode de l'API REST à démarrer le connecteur audio.

Voir Formatage des messages audio pour plus de détails sur le format des données audio à envoyer via la connexion WebSocket.

Lors de la création du jeton utilisé par le connecteur audio, vous pouvez ajouter le jeton data pour identifier le flux du connecteur audio. (Les bibliothèques du client Vonage comprennent des méthodes d'inspection des données de connexion pour la connexion d'un flux en session).

Exemple d'Applications

Voir le Connecteur audio bidirectionnel pour un exemple d'application Node qui utilise un connecteur audio bidirectionnel.

Navigation

Connecteur audio

Démarrer une connexion WebSocket

En-têtes personnalisés (HTTP et WebSocket)

Messages WebSocket

Premier message

Format des messages audio

Format de configuration du transport

Exemple : Transport JSON avec codage Base64

Exemple : Transport binaire par défaut

Messages audio actifs/inactifs

Messages de flux d'événements

Message de purge de la mémoire tampon (CLEAR)

Message de notification (NOTIFY)

Message déconnecté

Arrêt d'une connexion WebSocket

Reconnexions automatiques

Publication d'audio dans une session via WebSocket

Exemple d'Applications