Conector de audio

Audio Connector te permite enviar flujos de audio sin procesar (PCM a 16 kHz/16 bits) desde una sesión de Vonage Video en directo a servicios externos como AWS, GCP, Azure, etc., a través de tus propios servidores para su posterior procesamiento 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 establecer una conexión WebSocket con 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 transmisiones de audio desde una misma 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 — Consulta 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

Realiza una solicitud POST HTTPS a la siguiente URL:

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

Sustituir application_id junto con tu 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,
    "audioTransport": {
      "transport": "binary"
    }
  }
}

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 determinar si la conexión corresponde al punto final «Audio Connector» o para obtener otros datos identificativos. (Las bibliotecas de cliente incluyen propiedades que permiten examinar los datos de conexión de un cliente conectado a una sesión.) Consulte el Creación de fichas guía del desarrollador.

  • websocket ​(obligatorio): Datos incluidos para el WebSocket:

    • uri ​(obligatorio): Una URI de WebSocket accesible públicamente que se utilizará como destino de la transmisión de audio (por ejemplo, «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 compuesto por pares clave-valor de encabezados que se enviarán a tu servidor 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.

    • audioTransport (opcional) — Un objeto JSON que configura cómo se serializa el audio en el canal WebSocket. Por defecto, el audio se envía como tramas PCM binarias sin procesar de 16 bits. Configúralo así para utilizar audio base64 envuelto en JSON, algo que exigen algunos proveedores de IA (por ejemplo, OpenAI Realtime). El objeto tiene las siguientes propiedades:

      • transport (obligatorio) — "binary" (PCM16 sin procesar, la opción predeterminada) o "json".
      • encoding (necesario cuando el transporte es "json") — "base64".
      • audio_field (opcional) — La clave JSON para los datos de audio de salida. El valor por defecto es "audio".
      • receive_audio_field (opcional) - La clave JSON para los datos de audio entrantes (cuando la bidireccionalidad está activada). Por defecto tiene el mismo valor que audio_field.
      • static_fields (opcional) - Un objeto de pares clave-valor adicionales incluidos en cada mensaje de audio JSON saliente.

      Véase el sección de formato de configuración de transporte para más detalles y ejemplos.

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 identificador de la conexión WebSocket de Audio Connector en la sesión.

Para más información, consulte La documentación de la API REST de Audio Connector.

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 inicial de HTTP, los encabezados de las solicitudes HTTP dirigidas a tu 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, puedes 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: Tus encabezados se incluyen en todos los mensajes de control de WebSocket basados 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);
    • El websocket:cleared mensaje;
    • El 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 encabezados personalizados. Solucionaremos este problema en las próximas versiones de AudioConnector.

  • Tramas de audio binarias: Sólo contienen datos de audio y no incluyen cabeceras.

  • Tratamiento especial para x-opentok-ws* encabezados: 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.

El CUSTOM-HEADER-* Las propiedades que aparecen en los ejemplos de mensajes que figuran a continuación proceden de la headers propiedad proporcionada al iniciar la conexión.

Los encabezados personalizados tienen un límite de 512 bytes, que se calcula en función de la longitud del JSON serializado del headers objeto WebSocket. Si el tamaño de los datos serializados 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:connected, indicará el formato de audio en content-type junto con cualquier otro metadato que hayas introducido 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"
}

Dar formato a los mensajes de audio

De forma predeterminada, Audio Connector envía y recibe audio en forma de tramas PCM binarias sin procesar de 16 bits a través de WebSocket. Algunos proveedores de IA (por ejemplo, la API en tiempo real de OpenAI) esperan que el audio esté envuelto en mensajes JSON con codificación base64. En lugar de utilizar un proxy para reformatear el audio, puedes configurar el audioTransport propiedad en el websocket objeto cuando Iniciar Audio Connector.

Formato de configuración de transporte

El audioTransport es un objeto JSON con los siguientes campos:

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.

Ejemplo: Transporte JSON con codificación Base64

Lo siguiente audioTransport envuelve el audio saliente como base64 dentro de un mensaje JSON y añade una estática type campo en cada mensaje, ajustándose al formato que espera la API en tiempo real de OpenAI:

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

Cada mensaje WebSocket saliente tendrá el siguiente formato:

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

En bidirectional es trueel conector de audio también lee los mensajes JSON entrantes mediante la función receive_audio_field (o audio_field si receive_audio_field no está configurado) y decodifica el audio base64 para su reproducción en la sesión.

Ejemplo: Transporte binario predeterminado

Si omites audioTransport (o establecer transport a "binary"), el audio se envía y se recibe en formato PCM lineal de 16 bits según la configuración audioRate. Cada mensaje incluye una trama de audio de 20 ms, por lo que el tamaño de la trama varía en función de audioRate: 320 bytes a 8 kHz, 640 bytes a 16 kHz y 960 bytes a 24 kHz, enviados a una velocidad de 50 tramas (mensajes) por segundo. Si audioRate se omite, el transporte binario por defecto utiliza audio de 16kHz con tramas de 640 bytes.

Mensajes de audio activos/inactivos

Cuando se silencia el audio de las transmisiones incluidas en el WebSocket, se envía un mensaje de texto con la 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 ).

Es posible que el audio esté silenciado porque todos los clientes han dejado de transmitir audio o como consecuencia de un modulación de silenciamiento forzado 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 la siguiente carga útil 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 las transmisiones se desconectan de la sesión, se envía un mensaje de texto con la siguiente carga útil 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, si lo deseas, enviar un mensaje de control de texto para indicar al Audio Connector que descarte inmediatamente cualquier trama de audio que se encuentre actualmente almacenada en el búfer pero que aún no se haya enviado. Esto resulta útil para casos de uso en tiempo real, como la intervención en una conversación, la interrupción de la reproducción de TTS o el reinicio 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.

Mensaje de notificación (NOTIFY)

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 Método REST de desconexión forzada 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 indica que la conexión WebSocket se ha cerrado.

(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 Método REST de desconexión forzada. Utilice el ID de conexión de la conexión WebSocket del conector de audio con este método.

Como medida de seguridad, la conexión 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 Método REST de desconexión forzada).

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ías mediante el método de la API REST a Iniciar Audio Connector.

Véase Dar formato a los mensajes de audio 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 Proyecto de una aplicación de ejemplo en Node que utiliza el conector de audio bidireccional.