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.

Audio Connector

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

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.

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

Messages audio binaires

Les messages binaires représentent l'audio de l'appel. Le codec audio pris en charge par l'interface WebSocket est le PCM linéaire 16 bits, avec une fréquence d'échantillonnage de 16 kHz. Chaque message comprend une trame de 640 octets de données (20 ms d'audio) à raison de 50 trames (messages) par seconde.

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 de déconnexion

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 Messages audio binaires 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'application

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