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 diffuser un flux audio dans une session OpenTok.

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 multimédia OpenTok). Vous pouvez envoyer jusqu'à 50 flux audio d'une seule session à la fois.

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

Cette page comprend les sections suivantes :

Démarrer une connexion WebSocket

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

Vous pouvez également établir une connexion WebSocket Audio Connector à l'aide des SDK serveur OpenTok :

  • Java - Voir la page OpenTok.connectAudioStream() méthode.
  • Nœud - Voir le opentok.websocketConnect() méthode.
  • PHP - Voir la page OpenTok->connectAudio()] méthode.
  • Python - Voir la page opentok.connect_audio_to_websocket() méthode.
  • Ruby - Voir le site opentok.websocket.connect() méthode
  • .NET - Voir la page OpenTok.StartBroadcast() méthode

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.

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

Diffuser les messages relatifs aux é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 OpenTok associée à l'appel prend également fin. Sur chaque client connecté à la session, le SDK côté client OpenTok déclenche des événements indiquant que la connexion a pris fin (tout 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 d'Audio Connector pour envoyer des données audio depuis la connexion WebSocket vers un flux publié dans une session OpenTok (en plus de permettre à la connexion WebSocket de recevoir l'audio provenant de la session). Configurez le 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 Audio Connector. (Les bibliothèques client OpenTok comprennent des méthodes permettant d'analyser les données de connexion d'un flux en cours de session.)

Remarque : Les bidirectional Cette option n'est disponible que dans l'API REST. Elle n'est actuellement pas prise en charge dans les SDK serveur OpenTok.

Exemple d'Applications

Voir le vidéo-de-démonstration-nœud-connecteur-audio projet présentant un exemple d'application Node utilisant Audio Connector.

Plus d'informations

Regarde ça article de blog.