Conector de áudio

O Audio Connector permite enviar fluxos de áudio bruto (PCM 16 kHz/16 bits) de uma sessão ao vivo do Vonage Video para serviços externos, como AWS, GCP, Azure etc., por meio de seus próprios servidores, para posterior processamento e análise.

Com o Audio Connector, você pode enviar fluxos de áudio individualmente ou misturados. É possível identificar quem está falando ao enviar os fluxos de áudio individualmente, abrindo várias conexões WS.

O processamento adicional de fluxos de áudio em tempo real e offline permite o desenvolvimento de recursos como legendas, transcrições, traduções, pesquisa e indexação, moderação de conteúdo, inteligência de mídia, Prontuários Médicos Eletrônicos, análise de sentimento, etc.

Você também pode usar o Audio Connector para estabelecer uma conexão WebSocket com publicar áudio em uma sessão.

O Audio Connector está habilitado por padrão para todos os projetos e é um produto cobrado com base no uso. A cobrança pelo uso do Audio Connector é feita com base no número de fluxos de áudio dos participantes (ou IDs de fluxo) enviados ao servidor WebSocket. O recurso Audio Connector é compatível apenas com sessões roteadas (sessões que utilizam o Roteador de mídia). É possível enviar até 50 transmissões de áudio de uma única sessão por vez.

Audio Connector

Importante Se a conexão com o servidor WebSocket não for estabelecida em até 6 segundos, a chamada da API Connect falhará.

Iniciando uma conexão WebSocket

Para iniciar uma conexão WebSocket do Audio Connector, use o A API REST.

Você também pode iniciar uma conexão WebSocket do Audio Connector usando os SDKs do servidor:

  • Java — Veja o vonage.video.connectToWebsocket() método.
  • Nó — Consulte o vonage.video.connectToWebsocket() método.
  • PHP — Consulte o vonage->video->connectAudio() método.
  • Python — Veja o vonage.video.start_audio_connector() método.
  • Ruby — Consulte o vonage.video.web_socket.connect() método
  • .NET — Veja o vonage.video.Broadcast.StartBroadcast() método

Faça uma solicitação POST via HTTPS para a seguinte URL:

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

Substituir application_id com o seu ID de inscrição.

Utilize o método não interativo de geração OAuth 2.0 para criar um token Bearer usando a estrutura JWT e sua chave privada. Para mais informações, consulte a autenticação da chamada à API REST.

Defina o corpo da solicitação com dados JSON no seguinte 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"
    }
  }
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId​ (obrigatório) — O ID da sessão que contém os fluxos que você deseja incluir no fluxo do WebSocket.

  • token​ (obrigatório) — O token de vídeo da Vonage a ser usado para a conexão do Audio Connector à sessão. Você pode adicionar um token data para identificar se a conexão é o ponto final do Conector de Áudio ou para obter outros dados de identificação. (As bibliotecas de cliente incluem propriedades para analisar os dados de conexão de um cliente conectado a uma sessão.) Consulte o Criação de tokens guia do desenvolvedor.

  • websocket ​(obrigatório): Detalhes incluídos para o WebSocket:

    • uri ​(obrigatório): Um URI de WebSocket acessível ao público a ser usado como destino do fluxo de áudio (como “wss://service.com/ws-endpoint”).

    • streams (opcional) — Uma matriz de IDs dos fluxos que você deseja incluir no fluxo WebSocket. Se você omitir essa propriedade, todos os fluxos da sessão serão incluídos.

    • headers​ (opcional) — Um objeto contendo pares chave-valor de cabeçalhos a serem enviados ao seu servidor WebSocket a cada mensagem, com comprimento máximo de 512 bytes.

    • audioRate (opcional) — Um número que representa a taxa de amostragem de áudio em Hz. Os valores aceitos são 8.000, 16.000 (padrão) e 24.000.

    • audioTransport (opcional) — Um objeto JSON que configura como o áudio é serializado na conexão WebSocket. Por padrão, o áudio é enviado como quadros binários PCM de 16 bits sem processamento. Defina essa opção para usar áudio base64 encapsulado em JSON, o que é exigido por alguns fornecedores de IA (por exemplo, o OpenAI Realtime). O objeto possui as seguintes propriedades:

      • transport (obrigatório) — "binary" (PCM16 bruto, a configuração padrão) ou "json".
      • encoding (obrigatório quando o transporte for "json") — "base64".
      • audio_field (opcional) — A chave JSON para os dados de áudio de saída. O valor padrão é "audio".
      • receive_audio_field (opcional) — A chave JSON para dados de áudio de entrada (quando a opção bidirecional estiver ativada). O valor padrão é o mesmo que audio_field.
      • static_fields (opcional) — Um objeto com pares adicionais de chave-valor incluído em todas as mensagens de áudio JSON enviadas.

      Veja o seção de formato de configuração de transporte para obter mais detalhes e exemplos.

Uma chamada bem-sucedida resulta em uma resposta HTTP 200, com detalhes incluídos nos dados da resposta JSON:

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

Os dados da resposta JSON incluem as seguintes propriedades:

  • id — Um ID exclusivo que identifica a conexão WebSocket do Audio Connector.

  • connectionId — O ID da conexão WebSocket do Audio Connector na sessão.

Para mais detalhes, consulte a documentação da API REST do Audio Connector.

Cabeçalhos personalizados (HTTP e WebSocket)

Ao iniciar a conexão WebSocket por meio de REST ou SDKs de servidor, uma solicitação de conexão HTTP, que será convertida em WebSocket, será enviada ao seu servidor WebSocket. server.

Durante a atualização inicial do HTTP, os cabeçalhos da solicitação HTTP enviadas ao seu servidor WebSocket incluirão:

  • x-opentok-ws-conferenceid: Defina como o ID da conferência;
  • x-opentok-ws-connectionid: Definido como o ID da conexão;
  • x-opentok-ws-sessionid: Definido como o ID da sessão.

Além disso, você pode incluir um headers Objeto JSON na seção websocket do corpo da API REST ou do corpo da solicitação do SDK. Esses cabeçalhos se comportam de maneira diferente dependendo da fase da conexão:

  • Durante a atualização HTTP inicial: Todos os cabeçalhos fornecidos são enviados como cabeçalhos de solicitação HTTP para o seu servidor WebSocket.

  • Após o estabelecimento da conexão WebSocket: Seus cabeçalhos são incluídos em todas as mensagens de controle do WebSocket baseadas em texto como um bloco de texto. Isso inclui:

    • A inicial websocket:connected mensagem;
    • Para websocket:media:update mensagens (quando o áudio é ativado ou desativado);
    • O websocket:cleared mensagem;
    • O websocket:notify mensagem;
    • A final websocket:disconnected mensagem.
    • A inicial websocket:connected mensagem
    • websocket:media:update mensagens (quando o áudio é ativado ou desativado)
    • A final websocket:disconnected mensagem

    As chaves de cabeçalho são canonizado em relação às regras convencionais de maiúsculas e minúsculas dos cabeçalhos HTTP (por exemplo, X-CUSTOM-HEADER torna-se X-Custom-Header). Não considere as chaves dos cabeçalhos como sensíveis a maiúsculas e minúsculas.

  • Exceção: A confirmação de limpeza do buffer ({"event":"websocket:cleared"}) não inclui cabeçalhos personalizados. Corrigiremos isso nas próximas versões do AudioConnector.

  • Quadros de áudio binários: Esses arquivos contêm apenas dados de áudio e não incluem cabeçalhos.

  • Manuseio especial para x-opentok-ws* cabeçalhos: Quaisquer chaves de cabeçalho precedidas por x-opentok-ws são usados apenas no handshake HTTP e são removidos da carga JSON exibida nas mensagens de texto.

O CUSTOM-HEADER-* as propriedades apresentadas nos exemplos de mensagens abaixo provêm do headers propriedade fornecida ao iniciar a conexão.

Os cabeçalhos personalizados estão limitados a 512 bytes, calculados com base no comprimento do JSON serializado do headers objeto WebSocket. Se o tamanho da serialização exceder 512 bytes, a solicitação de conexão falhará.

Mensagens WebSocket

Primeira mensagem

A mensagem inicial enviada em uma conexão WebSocket estabelecida será baseada em texto e conterá uma carga JSON; ela terá um event campo definido como websocket:connected, ele informará o formato de áudio em content-type juntamente com quaisquer outros metadados que você tenha inserido no headers propriedade do corpo na endpoint POST. O headers A propriedade não está presente na carga JSON da mensagem; portanto, as propriedades estão no nível superior do JSON. Por exemplo:

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

Formatar mensagens de áudio

Por padrão, o Audio Connector envia e recebe áudio na forma de quadros binários PCM de 16 bits não processados pelo WebSocket. Alguns fornecedores de IA (por exemplo, a API em tempo real da OpenAI) esperam que o áudio esteja encapsulado em mensagens JSON com codificação base64. Em vez de executar um proxy para reestruturar o áudio, você pode definir o audioTransport propriedade no websocket objeto quando você iniciar o Audio Connector.

Formato de configuração de transporte

O audioTransport O valor é um objeto JSON com os seguintes 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.

Exemplo: Transporte JSON com codificação Base64

O seguinte audioTransport A configuração codifica o áudio de saída como base64 dentro de uma mensagem JSON e adiciona um valor estático type campo em todas as mensagens — seguindo o formato esperado pela API em tempo real da OpenAI:

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

Cada mensagem WebSocket de saída terá o seguinte formato:

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

Quando bidirectional é true, o Audio Connector também lê mensagens JSON recebidas usando o receive_audio_field chave (ou audio_field se receive_audio_field não está definido) e decodifica o áudio em base64 para reprodução na sessão.

Exemplo: Transporte binário padrão

Se você omitir audioTransport (ou definir transport para "binary"), o áudio é enviado e recebido no formato PCM linear de 16 bits na configuração audioRate. Cada mensagem inclui um quadro de áudio de 20 ms, portanto, o tamanho do quadro varia de acordo com audioRate: 320 bytes a 8 kHz, 640 bytes a 16 kHz e 960 bytes a 24 kHz, enviados a uma taxa de 50 quadros (mensagens) por segundo. Se audioRate Se for omitido, o transporte binário padrão utiliza áudio a 16 kHz com quadros de 640 bytes.

Mensagens de ativação/desativação de áudio

Quando o áudio nos fluxos incluídos no WebSocket é silenciado, é enviada uma mensagem de texto com a seguinte carga JSON (com active definir como 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"
}

(O CUSTOM-HEADER As propriedades neste exemplo representam metadados que você inclui no headers propriedade do corpo da solicitação POST para iniciar a conexão WebSocket .)

O áudio pode estar silenciado porque todos os clientes pararam de transmitir áudio ou como resultado de um moderação com silenciamento forçado evento.

Quando o áudio de uma das transmissões é retomado, é enviada uma mensagem de texto com a seguinte carga JSON (com active definir como 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 mensagens de eventos

Quando os editores se conectam a uma sessão, é enviada uma mensagem de texto com a seguinte carga JSON (com method definir como 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"
}

(O CUSTOM-HEADER As propriedades neste exemplo representam metadados que você inclui no headers propriedade do corpo da solicitação POST para iniciar a conexão WebSocket .)

Quando os streams se desconectam da sessão, é enviada uma mensagem de texto com a seguinte carga JSON (com method definir como 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"
}

Mensagem de limpeza do buffer (CLEAR)

Seu servidor WebSocket pode, opcionalmente, enviar uma mensagem de controle em formato de texto para instruir o Audio Connector a descartar imediatamente quaisquer quadros de áudio que estejam atualmente armazenados no buffer, mas ainda não tenham sido entregues. Isso é útil para casos de uso em tempo real, como a inserção de fala, a interrupção da reprodução de TTS ou a reinicialização de uma vez na conversa.

Para liberar o áudio armazenado em buffer, envie a seguinte mensagem JSON pelo WebSocket:

{
    "action": "CLEAR"
}

Quando o Conector de Áudio recebe essa mensagem, todos os quadros de áudio em buffer pendentes são descartados, o novo áudio recebido continua sendo transmitido sem interrupção e uma mensagem de confirmação é retornada:

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

Essa mensagem de controle é opcional. Se você não enviar "action": "CLEAR", a transmissão de áudio ocorre normalmente.

Mensagem de notificação (NOTIFY)

O seu servidor WebSocket pode, opcionalmente, enviar uma mensagem de controle em formato de texto (NOTIFY). O Conector de Áudio repetirá a carga útil original sem alterações assim que a mensagem for processada em sequência com o fluxo de áudio. Isso pode ser usado como um marcador para correlacionar eventos do aplicativo com o fluxo de áudio.

Para enviar um NOTIFY evento, envie a seguinte mensagem JSON pelo WebSocket:

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

Quando a mensagem é recebida, ela é colocada no final da fila de áudio. Depois que o áudio for reproduzido e quando o Audio Connector processar essa mensagem, uma mensagem de confirmação é enviada ao seu servidor WebSocket:

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

Essa mensagem de controle é opcional. Se você não enviar "action": "NOTIFY", a transmissão de áudio ocorre normalmente.

Mensagem desconectada

Quando o WebSocket do Audio Connector é interrompido devido a uma chamada para o método REST de desconexão forçada ou porque o prazo de 6 horas foi atingido (ver Interrompendo uma conexão WebSocket), é enviada uma mensagem de texto com a seguinte carga JSON:

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

Esta mensagem indica o encerramento da conexão WebSocket.

(O CUSTOM-HEADER As propriedades neste exemplo representam metadados que você inclui no headers propriedade do corpo da solicitação POST para iniciar a conexão WebSocket .)

Interrompendo uma conexão WebSocket

Quando o servidor WebSocket encerra a conexão, a conexão de vídeo da Vonage para a chamada também é encerrada. Em cada cliente conectado à sessão, o Client SDK do lado do cliente dispara eventos indicando que a conexão foi encerrada (da mesma forma que ocorreria quando outros clientes se desconectassem da sessão).

Você pode desconectar a conexão WebSocket do Audio Connector usando o método REST de desconexão forçada. Utilize o ID de conexão da conexão WebSocket do Audio Connector com este método.

Como medida de segurança, a conexão WebSocket será encerrada automaticamente após 6 horas.

Reconexões automáticas

O Audio Connector fará algumas tentativas para restabelecer uma conexão WebSocket que seja encerrada inesperadamente (por exemplo, se o WebSocket for encerrado sem que isso seja resultado de uma chamada ao método REST de desconexão forçada).

Publicação de áudio em uma sessão por meio do WebSocket

Você pode usar a conexão WebSocket do Audio Connector para enviar dados de áudio da conexão WebSocket para um stream publicado em uma sessão da Vonage (além de fazer com que a conexão WebSocket receba áudio da sessão). Defina o bidirectional propriedade para true nos dados que você envia com o método da API REST para iniciar o Audio Connector.

Veja Formatar mensagens de áudio para obter detalhes sobre o formato dos dados de áudio a serem enviados pela conexão WebSocket.

Ao criar o token usado pelo Audio Connector, você pode adicionar um token data para identificar o fluxo do Conector de Áudio. (As bibliotecas do cliente Vonage incluem métodos para analisar os dados de conexão de um fluxo em sessão.)

Exemplo de inscrição

Veja o Conector de áudio bidirecional projeto de um exemplo de aplicativo Node que utiliza o Audio Connector bidirecional.