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 de OpenTok.

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 OpenTok Media Router). Puedes enviar hasta 50 transmisiones de audio desde una misma sesión a la vez.

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

Esta página incluye las siguientes secciones:

Iniciar una conexión WebSocket

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

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

  • Java - Véase el OpenTok.connectAudioStream() método.
  • Nodo — Véase el opentok.websocketConnect() método.
  • PHP — Consulta el OpenTok->connectAudio()] método.
  • Python - Véase el opentok.connect_audio_to_websocket() método.
  • Rubí - Véase el opentok.websocket.connect() método
  • .NET - Véase el OpenTok.StartBroadcast() método

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.

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

Transmitir mensajes de eventos

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 tu servidor WebSocket cierra la conexión, la conexión de OpenTok para la llamada también finaliza. En cada cliente conectado a la sesión, el Client SDK de OpenTok del lado del cliente envía eventos que indican que la conexión ha finalizado (al igual que 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 utilizar la conexión WebSocket de Audio Connector para enviar datos de audio desde la conexión WebSocket a una transmisión publicada en una sesión de OpenTok (además de que la conexión WebSocket reciba audio de la sesión). Configura el 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 OpenTok incluyen métodos para examinar los datos de conexión de un flujo que se encuentra en sesión.)

Nota: En bidirectional Esta opción solo está disponible en la API REST. Actualmente no es compatible con los SDK de servidor de OpenTok.

Ejemplo de solicitud

Véase el vídeo-de-demostración-nodo-conector-de-audio proyecto de una aplicación de ejemplo en Node que utiliza Audio Connector.

Más información

Mira esto entrada de blog.