Conector de vídeo

O Vonage Video Connector permite que você participe programaticamente de sessões da Video API do Vonage como participante do lado do servidor. Ele permite que você se conecte a sessões de vídeo, publique e assine fluxos, e processe dados de áudio e vídeo em tempo real.

A biblioteca lida automaticamente com a conectividade WebRTC, o processamento de mídia e o gerenciamento de sessões, permitindo que você se concentre na criação da lógica do seu aplicativo. O áudio é transmitido como dados PCM linear de 16 bits, e o vídeo é transmitido como quadros de 8 bits nos formatos YUV420P, RGB24 ou ARGB32, todos com taxas de amostragem, resoluções e configurações de canais configuráveis.

Esta página descreve os conceitos e o comportamento comuns a todas as bibliotecas do Video Connector. Para obter instruções de instalação, assinaturas de API e exemplos de código, consulte o guia correspondente à sua linguagem de programação.

Escolha sua biblioteca

Ambas as bibliotecas oferecem os mesmos recursos e são baseadas na mesma implementação nativa. Elas diferem nas convenções de nomenclatura e na forma como as operações assíncronas são apresentadas: a biblioteca Python utiliza callbacks de conclusão, enquanto a biblioteca Node.js retorna promessas. Esta página descreve o comportamento que elas têm em comum.

Este tópico inclui as seguintes seções:

• Como funciona
• Requisitos
• Conceitos fundamentais
• Formatos de mídia
• Configuração da sessão
• Mídia editorial
• Inscrever-se em canais
• Gerenciamento do buffer de mídia
• Modelo de evento
• Limites

Como funciona

O Video Connector participa de uma sessão como um participante WebRTC comum. Do ponto de vista dos outros participantes, ele é indistinguível de um navegador ou cliente móvel: possui sua própria conexão, pode publicar um fluxo e pode se inscrever para receber os fluxos de outros participantes.

A diferença está no fato de que a mídia é trocada com o código do seu aplicativo, em vez de com uma câmera, um microfone ou uma tela. Você envia quadros de áudio e vídeo brutos para o conector a fim de publicá-los e recebe áudio e vídeo brutos dos fluxos nos quais você está inscrito. Isso torna o conector adequado para cargas de trabalho do lado do servidor, tais como:

• Agentes de IA de voz e vídeo em tempo real
• Transcrição, tradução e legendagem em tempo real
• Registro, arquivamento e captura para fins de conformidade
• Visão computacional e moderação de conteúdo
• Processamento de efeitos de áudio e vídeo

O ciclo de vida típico é:

1. Conecte-se a uma sessão usando seu ID de aplicativo, ID de sessão e um token.
2. Publique um stream e, em seguida, envie quadros de áudio e/ou vídeo para ele.
3. Inscreva-se nos streams de outros participantes assim que eles forem disponibilizados e processe o conteúdo de mídia que você receber.
4. Cancele a inscrição, remova a publicação e desconecte-se quando terminar.

Requisitos

O Video Connector é fornecido como uma biblioteca nativa com binários pré-compilados. Ele roda em Linux em x86_64 (AMD64) e ARM64 apenas.

Recomendamos o Debian Bookworm, pois é a distribuição na qual o conector foi testado de forma mais completa.

Conceitos fundamentais

O Video Connector utiliza um pequeno conjunto de objetos para representar sessões, participantes, transmissões e mídias. Compreender esses conceitos é essencial para trabalhar com qualquer uma das bibliotecas de maneira eficaz.

Sessão

Uma sessão da Video API da Vonage à qual os clientes se conectam. A sessão é identificada por seu ID e é repassada aos manipuladores de eventos no nível da sessão, para que você possa identificar qual sessão acionou um evento.

Conexão

A conexão de um participante a uma sessão. Cada participante, incluindo o próprio conector, possui exatamente uma conexão. Uma conexão transporta:

• Um identificador único
• Um carimbo de data e hora de criação
• Dados de conexão, que estão codificados no token utilizado para se conectar

Os dados de conexão são úteis para armazenar metadados personalizados sobre os participantes, como IDs de usuário ou funções.

Transmissão

Um fluxo de mídia (áudio, vídeo ou ambos) publicado por um participante. Um fluxo possui um identificador exclusivo e uma referência à conexão que o publicou. Os fluxos são anunciados a você à medida que os participantes começam a publicá-los, e são aqueles aos quais você se inscreve para receber mídia.

Editora

Seu próprio fluxo publicado na sessão. Há, no máximo, um editor por instância de conector. O editor mantém uma referência ao fluxo que criou, e é assim que os outros participantes o veem.

Assinante

Uma assinatura do stream de outro participante. Você cria um assinante para cada stream do qual deseja receber mídia, e cada assinante mantém uma referência ao stream do qual é assinante. Os eventos de mídia e legenda são entregues junto com o assinante que os produziu, para que você possa identificar de qual participante os dados vieram.

Como eles se relacionam

Session
├── Connection (multiple participants)
│   └── Stream (participant's published media)
│       ├── Publisher (your published stream)
│       └── Subscriber (your subscription to their stream)
├── Audio data (flowing through streams)
└── Video frames (flowing through streams)

Formatos de mídia

Áudio

O áudio é sempre transmitido como PCM linear, inteiros com sinal de 16 bits. Um quadro de áudio corresponde a uma amostra por canal; portanto, um buffer deve conter pelo menos (número de quadros × número de canais) amostras.

• Taxas de amostragem: 8.000, 12.000, 16.000, 24.000, 32.000, 44.100 ou 48.000 Hz
• Canais: 1 (mono) ou 2 (estéreo)
• Tamanho do quadro: blocos de 20 ms, em geral, variando de acordo com a taxa de amostragem

A taxa de amostragem e o número de canais podem ser configurados independentemente para o áudio que você publica e para o áudio mixado que você recebe. Consulte Configuração da sessão.

Vídeo

O vídeo é compartilhado como Valores de 8 bits sem sinal em um dos três formatos de pixel:

• Resoluções: até 1920x1080 (2.073.600 pixels no total)
• Taxas de quadros: 1 a 30 FPS

Configuração da sessão

Áudio para publicação versus áudio para assinatura

O conector permite configurar dois formatos de áudio independentes:

• Áudio da editora define o formato dos dados de áudio que você fornece ao publicar. O áudio enviado deve estar de acordo com essa taxa de amostragem e esse número de canais.
• Áudio da composição do público assinante define o formato do áudio mixado que você recebe de todos os streams assinados. A biblioteca lida com a mixagem de vários participantes e com a reamostragem ou conversão de canais para se adequar ao formato solicitado por você.

Essa separação permite que você otimize de acordo com o seu caso de uso. Por exemplo:

• Publique em estéreo para obter um resultado de alta qualidade e, ao mesmo tempo, receba uma mixagem mono para simplificar o processamento
• Transmita a 16 kHz para voz e receba a 48 kHz para reprodução em alta fidelidade
• Utilize taxas diferentes em cada lado para atender aos requisitos de um pipeline de processamento de áudio

Resolução e taxa de quadros preferenciais do assinante

Ao assinar transmissões roteadas que utilizam transmissão simultânea, a SFU (Unidade de Encaminhamento Seletivo) da Video API da Vonage pode enviar diferentes camadas de qualidade do vídeo. As configurações do assinante permitem que você solicite uma camada específica:

• Resolução preferida solicita uma camada espacial. O SFU envia a camada que mais se aproxima.
• Taxa de quadros preferencial solicita uma camada temporal. A SFU envia a camada que mais se aproxima.

Essas preferências ajudam a otimizar a largura de banda e o processamento do lado do assinante, solicitando apenas o nível de qualidade de que você precisa, em vez de receber sempre a melhor qualidade disponível.

Migração de sessão

A migração de sessão pode ser ativada para que o conector migre automaticamente em caso de rotação do SFU. Por padrão, ela está desativada.

Exploração madeireira

O nível de detalhamento dos registros do console pode ser configurado em cinco níveis: ERROR, WARN, INFO, DEBUG, e TRACE.

Mídia editorial

Um publisher deve publicar áudio, vídeo ou ambos. Configurar um publisher sem nenhum dos dois constitui um erro.

Aguardando a disponibilidade do áudio

Continuidade de áudio

Quando você publica um arquivo de áudio, a biblioteca mantém uma transmissão contínua em seu nome:

Publicação inicial. A biblioteca envia silêncio (quadros preenchidos com zeros) até que você forneça seus primeiros dados de áudio. Isso torna o fluxo imediatamente disponível para os assinantes, sem que seja necessário aguardar que seu aplicativo produza áudio.

Tolerância ao silêncio. Se você interromper temporariamente o envio de áudio, a biblioteca tolera breves intervalos, deixando de enviar qualquer pacote de áudio. Essa histerese evita o envio de pacotes de silêncio desnecessários durante atrasos momentâneos no processamento.

Silêncio explícito. Após o período de tolerância, se não houver nenhum novo áudio disponível, a biblioteca passa a enviar quadros de silêncio explícitos. Isso mantém o fluxo, ao mesmo tempo em que indica que nenhum áudio ativo está sendo fornecido.

Limpeza do buffer. Se você fornecer menos do que o equivalente a um período completo de áudio, a biblioteca descarta os dados restantes e preenche com silêncio para manter a sincronização correta e evitar desvios de áudio.

Continuidade do vídeo

Quando você publica um vídeo, a biblioteca mantém a continuidade dos quadros para você:

Publicação inicial. A biblioteca envia quadros pretos até que você forneça seu primeiro quadro, de modo que o fluxo fica imediatamente disponível para os assinantes.

Repetição do último quadro. Se você parar de enviar quadros, a biblioteca repetirá o último quadro enviado por até 2 segundos, mantendo a reprodução fluida para os assinantes.

Opção alternativa com moldura preta. Após 2 segundos de repetição, a biblioteca passa a exibir quadros em preto. Isso sinaliza aos assinantes que o vídeo não está mais sendo transmitido ativamente, mantendo, porém, a transmissão ativa.

Melhores práticas

• Envie os dados de mídia em intervalos regulares, de acordo com a taxa de amostragem e a taxa de quadros configuradas
• Monitore as estatísticas do buffer para confirmar se você está fornecendo dados suficientes
• Trate o evento de esvaziamento do buffer para detectar quando os buffers de mídia estiverem esgotados
• Adapte sua estratégia de geração de mídia às diferentes cargas de processamento

Inscrever-se em canais

Quando um participante começa a publicar, um evento de recepção de stream é acionado e você decide se deseja se inscrever. A mídia das suas inscrições é entregue por meio de três canais distintos.

Vídeo é transmitido por fluxo. Cada quadro chega ao assinante acompanhado da informação que identifica sua origem, de modo que você pode processar o vídeo de cada participante de forma independente — para gerenciamento de layout, gravação por fluxo ou aplicação de efeitos por fluxo.

Áudio misto é transmitido como um único fluxo no nível da sessão. A biblioteca combina automaticamente o áudio de todos os fluxos assinados em um único fluxo, no formato que você configurou para a combinação do assinante. Os participantes individuais não podem ser distinguidos nesse áudio combinado.

Áudio individual é fornecido por fluxo, no nível do assinante. Atualmente, esse recurso está disponível na versão beta. O áudio chega no formato recebido da transmissão — PCM linear de 16 bits — e nem a taxa de amostragem nem o número de canais podem ser configurados antes da recepção.

Legendas são entregues por fluxo. Atualmente, esse recurso está disponível na versão beta. Cada evento de legenda inclui a identificação do assinante do fluxo de origem, o texto da legenda e se o resultado é definitivo ou provisório:

• Provisório Os resultados são parciais e podem ser atualizados à medida que mais falas forem processadas. Útil para exibição em tempo real.
• Final Os resultados estão completos e não sofrerão alterações. Utilize-os para armazenamento ou processamento posterior.

Gerenciamento do buffer de mídia

O conector mantém buffers internos para o áudio e o vídeo que você publica. Você pode verificar a quantidade de conteúdo em fila a qualquer momento e limpar ambos os buffers quando precisar descartar o conteúdo pendente — por exemplo, ao interromper um bot no meio de uma fala.

Eventos de esvaziamento do buffer

Um evento de esgotamento do buffer é disparado quando um buffer interno de áudio ou vídeo fica vazio. Isso ocorre quando a mídia é transmitida para a sessão mais rapidamente do que sua aplicação consegue fornecê-la. Trate o evento como um sinal para aumentar sua taxa de produção de mídia ou ajustar sua estratégia de publicação.

O evento implementa histerese para evitar acionamentos excessivos: após um consumo inicial, ele não será acionado novamente até que o buffer seja reabastecido com novos conteúdos e, posteriormente, se esgote novamente. Isso evita uma enxurrada de notificações repetidas enquanto o buffer permanecer vazio.

Modelo de evento

Ambas as bibliotecas disponibilizam o mesmo conjunto de eventos, agrupados de acordo com o objeto ao qual pertencem.

A forma como esses eventos são apresentados varia de acordo com a linguagem. Em Python, todo evento é um callback que você registra. No Node.js, os eventos de ciclo de vida únicos — conexão da sessão, criação do stream do publisher e conexão do assinante — são consumidos pela promessa retornada pelo método correspondente, e os demais eventos são callbacks. Consulte o guia da linguagem para obter mais detalhes.

Limites