Conector de audio

Audio Connector te permite enviar transmisiones de audio sin procesar (PCM 16 khz/16bit) desde una sesión en vivo de Vonage Video a servicios externos como AWS, GCP, Azure, etc., a través de tus propios servidores para su posterior procesamiento y análisis. y análisis.

Usando Audio Connector, puedes enviar flujos de audio individualmente o mezclados. Puedes identificar al orador enviando los flujos de audio individualmente abriendo varias conexiones WS.

El tratamiento posterior de los flujos de audio en tiempo real y fuera de línea permite crear funciones como subtítulos, transcripciones, traducciones, búsqueda e indexación, moderación de contenidos inteligencia mediática, historiales médicos electrónicos, análisis de opiniones, etc.

También puedes utilizar Audio Connector para usar una conexión WebSocket para publicar audio en una sesión.

Audio Connector está activado por defecto para todos los proyectos, y es un producto basado en el uso. El uso del Conector de audio se cobra en función del número de secuencias de audio de los participantes (o ID de secuencias) que se envían al servidor WebSocket. La función Conector de audio sólo es compatible con sesiones enrutadas (sesiones que utilizan el Router multimedia). Puedes enviar hasta 50 flujos de audio de una sola sesión a la vez.

Audio Connector

Importante Si no se establece una conexión con su servidor WebSocket en 6 segundos, la llamada a la API Connect fallará.

Iniciar una conexión WebSocket

Para iniciar una conexión WebSocket del Conector de audio, utilice la función La API REST.

También puedes iniciar una conexión WebSocket del Conector de Audio utilizando los SDK del servidor:

  • Java - Véase el vonage.video.connectToWebsocket() método.
  • Nodo - Véase el vonage.video.connectToWebsocket() método.
  • PHP - Véase el vonage->video->connectAudio() método.
  • Python - Véase el vonage.video.start_audio_connector() método.
  • Rubí - Véase el vonage.video.web_socket.connect() método
  • .NET - Véase el vonage.video.Broadcast.StartBroadcast() método

Realice una solicitud POST HTTPS a la siguiente URL:

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

Sustituir application_id con su ID de solicitud.

Utilice el método no interactivo de generación OAuth 2.0 para crear un token portador utilizando la estructura JWT y su clave privada. Para obtener más información, consulte la autenticación de la llamada a la API REST.

Establezca el cuerpo de la solicitud en datos JSON con el siguiente formato:

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

El objeto JSON incluye las siguientes propiedades:

  • sessionId​ (obligatorio) - El ID de sesión que incluye los flujos que desea incluir en el flujo WebSocket.

  • token​ (obligatorio) - El token de video de Vonage que se utilizará para la conexión del conector de audio a la sesión. Puedes agregar el token data para identificar que la conexión es el conector de audio o para otros datos de identificación. (Las librerías de cliente incluyen propiedades para inspeccionar los datos de conexión de un cliente conectado a una sesión). Ver la Creación de fichas guía del desarrollador.

  • websocket (obligatorio): Detalles incluidos para el WebSocket:

    • uri (obligatorio): Una URI de WebSocket públicamente accesible que se utilizará para el destino de el flujo de audio (como "wss://service.com/ws-endpoint").

    • streams (opcional) - Una matriz de IDs de flujo para los flujos que desea incluir en el flujo WebSocket. incluir en el flujo WebSocket. Si omite esta propiedad, se incluirán todos los flujos de la sesión. serán incluidos.

    • headers​ (opcional) - Un objeto de pares clave-valor de cabeceras que se enviarán al servidor WebSocket con cada mensaje, con una longitud máxima de 512 bytes. WebSocket con cada mensaje, con una longitud máxima de 512 bytes.

    • audioRate (opcional) - Un número que representa la frecuencia de muestreo de audio en Hz. Los valores aceptados son 8000, 16000 (por defecto) y 24000.

Si la llamada se realiza correctamente, se obtiene una respuesta HTTP 200, con los detalles incluidos en los datos de respuesta JSON:

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

Los datos de respuesta JSON incluyen las siguientes propiedades:

  • id - Un ID único que identifica la conexión WebSocket del Conector de Audio.

  • connectionId - El ID de conexión para la conexión WebSocket del conector de audio en la sesión.

Para más información, consulte la documentación de la API REST del conector de audio.

Cabeceras personalizadas (HTTP y WebSocket)

Al iniciar la conexión WebSocket mediante REST o SDK de servidor, se enviará una solicitud de conexión HTTP que se actualizará a WebSocket, se enviará a su servidor WebSocket servidor.

Durante la actualización HTTP inicial, las cabeceras de la solicitud HTTP a su servidor WebSocket incluirán:

  • x-opentok-ws-conferenceid: Establezca el ID de la conferencia;
  • x-opentok-ws-connectionid: Establece el ID de conexión;
  • x-opentok-ws-sessionid: Establece el ID de sesión.

Además, puede incluir un headers JSON dentro de la sección websocket del cuerpo de la solicitud de la API REST o del SDK. Estas cabeceras se comportan de forma diferente en función de la fase de la conexión:

  • Durante la actualización HTTP inicial: Todas las cabeceras proporcionadas se envían como cabeceras de solicitud HTTP a su servidor WebSocket.

  • Una vez establecido el WebSocket: Sus cabeceras se incluyen en cada mensaje de control WebSocket basado en texto como un bloque de texto. Esto incluye:

    • Los primeros websocket:connected mensaje;
    • Para websocket:media:update mensajes (cuando el audio se activa o desactiva);
    • En websocket:cleared mensaje;
    • En websocket:notify mensaje;
    • El final websocket:disconnected mensaje.
    • Los primeros websocket:connected mensaje
    • websocket:media:update mensajes (cuando el audio se activa o desactiva)
    • El final websocket:disconnected mensaje

    Las teclas de cabecera son canonizado a los encabezados HTTP convencionales (por ejemplo, X-CUSTOM-HEADER se convierte en X-Custom-Header). No distinga entre mayúsculas y minúsculas en las claves de cabecera.

  • Excepción: La confirmación de borrado del búfer ({"event":"websocket:cleared"}) no incluye cabeceras personalizadas. Arreglaremos esto en las próximas versiones de AudioConnector.

  • Fotogramas binarios de audio: Sólo contienen datos de audio y no incluyen cabeceras.

  • Tratamiento especial para x-opentok-ws* cabeceras: Cualquier clave de cabecera prefijada con x-opentok-ws sólo se utilizan en el handshake HTTP y se eliminan de la carga útil JSON de la que se hacen eco los mensajes de texto.

En CUSTOM-HEADER-* que se muestran en los ejemplos de mensajes a continuación proceden de la función headers proporcionada al iniciar la conexión.

Las cabeceras personalizadas están limitadas a 512 bytes, calculados a partir de la longitud JSON serializada del archivo headers objeto websocket. Si el tamaño serializado supera los 512 bytes, la solicitud de conexión fallará.

Mensajes WebSocket

Primer mensaje

El mensaje inicial enviado en una conexión WebSocket establecida se basará en texto y contendrá una carga útil JSON, tendrá un carácter event con el valor websocket:connecteddetallará el formato de audio en content-type junto con cualquier otro metadato que haya puesto en el headers del cuerpo en el punto final POST. La dirección headers no está presente en la carga útil JSON del mensaje, por lo que las propiedades se encuentran en el nivel superior del JSON. Por ejemplo:

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

Mensajes de audio binarios

Los mensajes que son binarios representan el audio de la llamada. El códec de audio admitido en la interfaz WebSocket es PCM lineal de 16 bits, con una frecuencia de muestreo de 16 kHz. Cada mensaje incluye una trama de 640 bytes de datos (20 ms de audio) a 50 tramas (mensajes) por segundo.

Mensajes de audio activos/inactivos

Cuando se silencia el audio en los flujos incluidos en el WebSocket, se envía un mensaje de texto con el siguiente carga JSON (con active ajustado a 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"
}

(El CUSTOM-HEADER de este ejemplo representan metadatos que usted incluye en el headers del cuerpo de la solicitud POST para iniciar la conexión WebSocket ).

El audio puede silenciarse porque todos los clientes dejan de publicar audio o como resultado de una forzar moderación muda evento.

Cuando se reanuda el audio de uno de los flujos, se envía un mensaje de texto con el siguiente carga JSON (con active ajustado a 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"
}

Mensajes de Stream Events

Cuando los editores se conectan a una sesión, se envía un mensaje de texto con el siguiente JSON (con method ajustado a 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"
}

(El CUSTOM-HEADER de este ejemplo representan metadatos que usted incluye en el headers del cuerpo de la solicitud POST para iniciar la conexión WebSocket ).

Cuando los flujos se desconectan de la sesión, se envía un mensaje de texto con el siguiente JSON (con method ajustado a 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"
}

Mensaje de vaciado del búfer (CLEAR)

Tu servidor WebSocket puede enviar opcionalmente un mensaje de control basado en texto para ordenar al Conector de Audio que descarte inmediatamente cualquier fotograma de audio que esté actualmente en el buffer pero que aún no haya sido entregado. Esto es útil para casos de uso en tiempo real, como la irrupción, la interrupción de la reproducción TTS o el restablecimiento de un turno de conversación.

Para vaciar el búfer de audio, envíe el siguiente mensaje JSON a través del WebSocket:

{
    "action": "CLEAR"
}

Cuando el Conector de Audio recibe este mensaje, todas las tramas de audio pendientes almacenadas en buffer son descartadas, el nuevo audio entrante continúa fluyendo sin interrupción y se devuelve un mensaje de confirmación:

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

Este mensaje de control es opcional. Si no envía "action": "CLEAR"la transmisión de audio se realiza con normalidad.

Notificar (NOTIFY) Mensaje

Su servidor WebSocket puede enviar opcionalmente un mensaje de control basado en texto (NOTIFY). El Conector de Audio se hará eco de la carga original sin cambios una vez que el mensaje haya sido procesado en secuencia con el flujo de audio. Esto puede usarse como marcador para correlacionar eventos de aplicación con el flujo de audio.

Para enviar un NOTIFY envíe el siguiente mensaje JSON a través del WebSocket:

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

Cuando se recibe el mensaje, se coloca al final de la cola de audio. Una vez consumido el audio, y cuando el Conector de Audio procesa este mensaje, se envía un mensaje de confirmación a tu servidor WebSocket:

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

Este mensaje de control es opcional. Si no envía "action": "NOTIFY"la transmisión de audio se realiza con normalidad.

Mensaje de desconexión

Cuando el WebSocket del conector de audio se detiene debido a una llamada a la función forzar desconexión método REST o porque se ha alcanzado el (véase Detener una conexión WebSocket), se envía un mensaje de texto con la siguiente carga JSON:

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

Este mensaje marca la finalización de la conexión WebSocket.

(El CUSTOM-HEADER de este ejemplo representan metadatos que usted incluye en el headers del cuerpo de la solicitud POST para iniciar la conexión WebSocket ).

Detener una conexión WebSocket

Cuando el servidor WebSocket cierra la conexión, también finaliza la conexión de video de Vonage para la llamada. En cada cliente conectado a la sesión, el SDK del lado del cliente envía eventos que indican que que la conexión finalizó (como lo haría cuando otros clientes se desconectan de la sesión).

Puedes desconectar la conexión WebSocket del Conector de Audio utilizando el botón forzar desconexión método REST. Utilice el ID de conexión de la conexión WebSocket del conector de audio con este método.

Como medida de seguridad, el WebSocket se cerrará automáticamente al cabo de 6 horas.

Reconexiones automáticas

Audio Connector hará algunos intentos para restablecer una conexión WebSocket que se cierra inesperadamente (por ejemplo, si el WebSocket se cierra sin resultar de una llamada al forzar desconexión método REST).

Publicación de audio en una sesión a través de WebSocket

Puedes usar la conexión WebSocket del conector de audio para enviar datos de audio desde la conexión WebSocket a una transmisión publicada en una sesión de Vonage (además de hacer que la conexión WebSocket reciba audio de la sesión). Configura la bidirectional propiedad a true en los datos que envíe con el método de la API REST a iniciar el conector de audio.

Véase Mensajes de audio binarios para más detalles sobre el formato de los datos de audio a enviar a través de la conexión WebSocket.

Al crear el token utilizado por el conector de audio, puedes añadir token data para identificar el flujo del Conector de audio. (Las bibliotecas de cliente de Vonage incluyen métodos para inspeccionar los datos de conexión para la conexión de un flujo en sesión).

Ejemplo de solicitud

Véase el Conector de audio bidireccional para ver un ejemplo de aplicación Node que utiliza el conector de audio bidireccional.