Uma Video API mais inteligente e segura

Vídeos em tempo real podem ser um desafio. Os participantes se conectam a partir de diferentes dispositivos, em diferentes redes e em diferentes partes do mundo. As condições mudam no meio da chamada: um dispositivo móvel pode mudar do Wi-Fi para dados de celular (por exemplo, de 5G para 4G), um firewall corporativo pode bloquear certos caminhos UDP e um laptop de baixo desempenho pode ter dificuldade para lidar com a carga da CPU.

A Video API da Vonage foi desenvolvida com base em um conjunto de recursos inteligentes e complementares, que adaptam continuamente a sessão às mudanças nas condições; esses recursos estão organizados em três camadas, cada uma delas voltada para um nível diferente da pilha:

Nível de topologia: Infraestrutura da sessão, otimizações de roteamento e ciclo de vida do servidor. Esses fatores afetam todos os participantes de uma sessão e não exigem configuração específica por fluxo.
Nível de conexão entre pares: Como cada cliente se conecta e se comunica com o Media Router. Essas configurações se aplicam uma vez por cliente, mas pode haver vários clientes no mesmo dispositivo do usuário final.
Nível do fluxo: Opções de qualidade por stream: codec, resolução, taxa de bits e muito mais. Essas opções podem ser ajustadas de forma independente para cada emissor e receptor.

Os Elementos Básicos

Os recursos estão organizados em três camadas concêntricas. As camadas externas afetam todos os participantes; as camadas internas podem ser ajustadas individualmente por transmissão.

╔══════════════════════════════════════════════════════════════════════╗
║  TOPOLOGY LAYER                                                      ║
║  Routed vs. Relayed · Adaptive media routing · Media Mesh            ║
║  Session migration                                                   ║
║  ┌──────────────────────────────────────────────────────────────┐    ║
║  │  PEER-CONNECTION LAYER                                       │    ║
║  │  Single peer connection (SPC) · Codec negotiation            │    ║
║  │  ┌────────────────────────────────────────────────────┐      │    ║
║  │  │  STREAM LAYER                                      │      │    ║
║  │  │  Scalable video · Bitrate presets                  │      │    ║
║  │  │  Publisher resolution/frame rate                   │      │    ║
║  │  │  Subscriber preferred resolution/frame rate        │      │    ║
║  │  │  Audio fallback · FEC / NACK / DTX                 │      │    ║
║  │  └────────────────────────────────────────────────────┘      │    ║
║  └──────────────────────────────────────────────────────────────┘    ║
║  Monitoring: client observability · sender-side stats · MOS          ║
╚══════════════════════════════════════════════════════════════════════╝

A camada de monitoramento abrange todas as três, proporcionando visibilidade da qualidade em todos os níveis.

Por trás dos bastidores: a pilha do WebRTC

Muitas das garantias de confiabilidade provêm de recursos integrados à pilha do WebRTC que não exigem nenhuma chamada explícita à API. Compreendê-los ajuda você a analisar o comportamento de qualidade e a utilizar as APIs de nível superior de maneira mais eficaz.

Controle de congestionamento e adaptação de taxa

As implementações do WebRTC utilizam o Google Congestion Control (GCC) por padrão. O GCC verifica continuamente a largura de banda disponível, estima o gargalo atual e sinaliza ao codificador para aumentar ou diminuir sua taxa de bits alvo. Esse é o principal mecanismo que mantém uma sessão ativa durante congestionamentos transitórios. Qualquer configuração da Video API da Vonage que afete a taxa de bits atua como um teto acima do GCC, e o GCC continua a se adaptar dinamicamente abaixo desse limite.

Correção de Erros Prospectiva (FEC)

Por padrão, os fluxos de áudio tentam negociar o FEC do Opus. O codec Opus incorpora uma cópia de qualidade inferior de cada quadro de áudio dentro do próximo quadro. Se o primeiro quadro for perdido durante a transmissão, o receptor o reconstrói a partir da cópia contida no pacote seguinte, com um pequeno custo adicional de largura de banda. Isso é particularmente eficaz no caso de perda aleatória de pacotes, do tipo que ocorre em redes Wi-Fi ou celulares congestionadas.

Para vídeo, todos os codecs oferecem suporte ao RTP RED FEC quando este é negociado. O FEC é transparente para o seu aplicativo, adicionando redundância ao fluxo de mídia e permitindo que o receptor recupere pacotes perdidos ou corrompidos sem a necessidade de retransmissão. Para obter mais informações, você pode ler o RFC 8854.

NACK e RTX (Retransmissão)

Quando um pacote de vídeo é perdido, o receptor envia um ACK negativo (NACK) para solicitar a retransmissão. O NACK/RTX acrescenta uma latência proporcional ao tempo de ida e volta (normalmente entre 50 e 200 ms).

Transmissão descontínua (DTX)

O Opus DTX detecta o silêncio no microfone e interrompe o envio de pacotes de áudio durante os períodos de silêncio, reduzindo a largura de banda de áudio a quase zero. Você pode ativar o DTX por meio do enableDtx configuração do SDK de sua escolha ao inicializar o publisher.

DTLS-SRTP e Protocolo Seguro de Transporte em Tempo Real

Todas as transmissões de mídia são criptografadas por padrão usando DTLS-SRTP. A negociação das chaves de criptografia ocorre como parte do handshake do WebRTC, antes do início de qualquer transmissão de mídia. Para maior segurança, o AES-256 recurso adicional oferece criptografia de 256 bits. Esses métodos de criptografia na camada de transporte (DTLS-SRTP e AES-256) funcionam em conjunto com o recurso opcional de criptografia de ponta a ponta (E2EE), que adiciona uma camada adicional de criptografia no nível do aplicativo. Consulte o Guia sobre criptografia de ponta a ponta para mais detalhes.

ICE e TURN

O Estabelecimento Interativo de Conectividade (ICE) testa vários caminhos entre os pontos finais (UDP direto, STUN reflexivo, retransmissão TURN) e escolhe o melhor. Se o melhor caminho mudar no meio da chamada (algo comum quando um dispositivo móvel muda de rede), o ICE pode reiniciar e encontrar um novo caminho sem interromper a chamada. Para sessões que atravessam firewalls restritivos, consulte o Guia dos servidores TURN configuráveis e o Guia sobre redes restritas.

Otimizações no nível da topologia

As características no nível da topologia determinam o infraestrutura pelas quais os dados circulam. Elas são definidas ao criar uma sessão ou ao se conectar a ela, e afetam todos os participantes da mesma forma. Definir corretamente a topologia é a base sobre a qual tudo o mais se constrói.

Modo de mídia: roteado x retransmitido

A decisão mais fundamental em relação à topologia é modo de mídia.

Sessões retransmitidas: Os clientes tentam enviar fluxos de áudio e vídeo diretamente uns para os outros (ponto a ponto), recorrendo ao retransmissor TURN caso um firewall bloqueie o caminho direto. As sessões retransmitidas apresentam menor latência para grupos pequenos, mas não podem utilizar vídeo escalável, fallback de áudio do assinante, conexão com um único par ou estatísticas do lado do remetente.
Sessões encaminhadas: A mídia passa pelo Vonage Video Media Router. Isso permite o acesso a todo o conjunto de recursos inteligentes: vídeo escalável, fallback de áudio para assinantes, Conexão de Par Único (SPC), estatísticas do lado do remetente, transmissões ao vivo, arquivamento, interconexão SIP e muito mais.

Para sessões com três ou mais participantes, utilize sempre uma sessão roteada. Consulte o Criação de um guia de sessão.

Roteamento Adaptativo de Mídia

Em sessões roteadas (a partir da versão 2.24.7 do SDK para a Web e da versão 2.27.0 para aplicativos nativos), a plataforma utiliza automaticamente roteamento adaptativo de mídia para otimizar o tráfego entre os participantes. Quando os editores têm apenas um assinante e nenhum recurso exclusivo de roteamento (arquivamento, transmissão ao vivo, SIP etc.) está ativo, a mídia é roteada diretamente entre editores e assinantes, sem a necessidade de declarar uma sessão retransmitida antecipadamente. Assim que um emissor obtém mais de um assinante, ou um recurso exclusivo de roteamento é ativado, o Media Router assume o roteamento de forma contínua. Por exemplo, em casos de uso conversacionais (todos os participantes publicam e se inscrevem ao mesmo tempo) sem recursos exclusivos de roteamento, assim que o terceiro participante entrar, a sessão será transferida de forma transparente para o Media Router.

Isso significa que, na prática, você pode declarar uma sessão roteada para todos os casos e ainda assim obter uma latência próxima à de uma transmissão direta para chamadas 1:1. O roteamento adaptativo de mídia está habilitado por padrão e não requer configuração. Consulte o Criação de um guia de sessão.

Media Mesh

A plataforma utiliza Media Mesh para conectar automaticamente cada participante ao datacenter do Media Router mais próximo dele (você pode verificar aqui (a lista de todos os datacenters disponíveis). Para uma sessão geograficamente distribuída (por exemplo, participantes em Nova York, Frankfurt e Sydney), o Media Mesh garante que cada cliente encaminhe a mídia por meio do servidor regional mais próximo, em vez de passar por um único datacenter, que pode estar distante. O resultado é menor latência e melhor qualidade para todos os participantes, especialmente em grandes sessões internacionais.

O Media Mesh está ativado por padrão e não requer configuração. Se você precisar de mais controle sobre para onde a mídia é encaminhada, há duas opções de personalização:

Sugestão de localização (esforço máximo): você pode indicar um datacenter de sinalização preferencial como sugestão. A plataforma tentará usar a localização solicitada sempre que possível, mas isso não é garantido e ela poderá recorrer a outro datacenter com base na disponibilidade, capacidade ou outras considerações operacionais. Consulte o Criação de um guia de sessão para mais informações.
Zona de Mídia Regional (obrigatória): se for necessário manter o roteamento de mídia dentro de uma região específica (por requisitos de residência de dados ou conformidade), configure uma Zona de Mídia Regional. Essa configuração é obrigatória: a sinalização e a mídia serão roteadas pela zona selecionada, em vez de escolher automaticamente o datacenter mais próximo. Documentação adicional pode ser consultada no Guia das Zonas de Mídia Regionais.

Migração de sessão

O que ele faz: Transfere de forma transparente todos os participantes de uma sessão para um novo servidor Media Router quando ocorre uma rotação planejada de servidores, sem desconectar ninguém. Não é necessário nenhum tratamento do lado do aplicativo (ou seja, as aplicações não precisam implementar sua própria lógica de transferência/reconectividade; a plataforma faz isso por elas).

Por que isso é importante: A infraestrutura em nuvem nunca é estática. Os servidores recebem atualizações, são dimensionados para aumentar ou reduzir a capacidade e são substituídos. Sem a migração de sessão, uma rotação de servidores obriga todos os participantes a se desconectarem e se reconectarem, o que pode ser uma experiência perturbadora quando a sessão ultrapassa 8 horas. Com a migração de sessão ativada (SDK v2.30.0+), a transição é imperceptível: as transmissões continuam, nenhum evento de reconexão é acionado e o áudio/vídeo em exibição não é interrompido.

O que ainda precisa ser reiniciado: Gravações (arquivos), transmissões ao vivo e instâncias do Experience Composer são encerradas quando uma sessão é migrada e devem ser reiniciadas por meio do callback de notificação da sessão. Arquivos automáticos reiniciar automaticamente.

Como ativar: Passe sessionMigration: true nas opções de inicialização da sessão para cada cliente. Por padrão, isso é false. Consulte o Guia de rotação de servidores e migração de sessões para uma visão geral, e o Migração de sessões: Guia de instalação e configuração para obter a sintaxe completa específica do SDK, exemplos de API e detalhes sobre como lidar com o callback de notificação de sessão.

Retornos de chamada em caso de interrupção do serviço

O que ele faz: Quando ocorre uma interrupção não planejada do serviço, a plataforma envia uma resposta ao servidor do seu aplicativo com as informações relevantes. Isso permite que seu aplicativo reinicie quaisquer recursos que não possam continuar funcionando durante uma interrupção (arquivos, transmissões ao vivo, instâncias do Experience Composer).

Por que isso é importante: Sem uma função de retorno de chamada, seu aplicativo não teria como saber que um arquivo ou uma transmissão chegou ao fim e precisa ser reiniciado.

Como funciona: Quando ocorre uma interrupção no serviço, a plataforma envia uma solicitação HTTP POST para a URL de retorno de chamada configurada por você, com uma carga JSON que descreve o evento. Seu aplicativo pode, então, tomar as medidas adequadas, como reiniciar um arquivo ou uma transmissão. Consulte o Guia de retornos de chamada em caso de interrupção do serviço para obter instruções detalhadas sobre a recuperação de cada serviço.

Reconexão automática

O que ele faz: Quando um cliente perde inesperadamente a conexão com uma sessão, o SDK tenta automaticamente se reconectar sem a necessidade de qualquer código do aplicativo.

Por que isso é importante: Sem a reconexão automática, uma breve interrupção na rede obrigaria o usuário a se reconectar manualmente à sessão. Com a reconexão automática, o SDK lida com a recuperação de forma transparente. Os fluxos aos quais o usuário estava inscrito serão pausados e retomados automaticamente quando a conexão for restaurada.

Como funciona: Não é necessária nenhuma configuração. Quando a conexão é interrompida e o cliente tenta se reconectar:

O objeto Session despacha um sessionReconnecting evento.
Se a conexão for restabelecida, o objeto Session dispara um sessionReconnected evento.
Se não for possível restabelecer a conexão, o cliente se desconecta da sessão e o sessionDisconnected o evento é disparado.

Sua aplicação pode, opcionalmente, monitorar esses eventos para exibir indicadores de status ao usuário:

session.on({
  sessionReconnecting: function() {
    // Display a "reconnecting..." indicator
  },
  sessionReconnected: function() {
    // Hide the indicator
  },
  sessionDisconnected: function() {
    // Handle permanent disconnection
  }
});

Os sinais enviados durante um período de desconexão temporária são colocados em fila e entregues assim que a conexão for restabelecida. Consulte o Guia para participar de uma sessão para ver exemplos completos e os nomes de eventos específicos do SDK.

Estratégias no nível da conexão entre pares

Os recursos no nível da conexão entre pares determinam como as conexões WebRTC de um cliente com o Media Router são estruturadas e quais codecs são negociados. Essas configurações se aplicam uma vez por cliente (e não por fluxo) e têm um impacto significativo no consumo de recursos e na compatibilidade.

Conexão com um único par (SPC)

O que ele faz: Agrupa todos os fluxos de assinantes de um cliente em uma única conexão WebRTC entre pares com o Media Router, em vez de uma conexão por fluxo.

Por que isso é importante: Cada conexão adicional entre pares acarreta sobrecarga: candidatos a ICE distintos, handshakes DTLS e estado do soquete no nível do sistema operacional. Em um dispositivo móvel inscrito em dez fluxos, dez conexões entre pares podem sobrecarregar o dispositivo e consumir uma quantidade significativa de energia. O SPC reduz isso a uma única conexão, diminuindo o consumo de recursos e permitindo sessões maiores em clientes móveis nativos.

Benefício adicional — controle de taxa: Com uma única conexão, o controlador de congestionamento do WebRTC detecta todos agrupa os fluxos de entrada em um único pacote e pode tomar decisões mais bem fundamentadas sobre a adaptação da taxa de transmissão. No modelo de múltiplas conexões, cada conexão realiza testes e adaptações de forma independente, o que pode causar oscilações e um compartilhamento de largura de banda abaixo do ideal.

Como ativar: O SPC está desativado por padrão. Configure singlePeerConnection: true ao inicializar a sessão. Para o SDK da web, passe-o como uma propriedade no OT.initSession() objeto de opções. Para outros SDKs:

Android: Session.Builder.setSinglePeerConnection(true)
iOS: OTSessionSettings.singlePeerConnection = YES
Windows: SinglePeerConnection propriedade em Session.Builder
Linux/macOS: otc_session_settings_set_single_peer_connection()
React Native: enableSinglePeerConnection na OTSession options adereço

Veja o Criação de um guia de sessão para ver exemplos completos.

Quando usar: Ative o SPC sempre que houver mais do que um punhado de assinantes em uma sessão roteada — especialmente em plataformas móveis. Os benefícios aumentam com o número de transmissões.

Seleção de codec

O que ele faz: Seleciona o codec de vídeo utilizado entre cada par emissor-destinatário.

Por que isso é importante: A escolha do codec afeta a qualidade em uma determinada taxa de bits, o uso da CPU, a disponibilidade de aceleração por hardware e a compatibilidade com vídeo escalável. O VP8 é a opção padrão mais segura: é universalmente compatível, conta com aceleração por hardware na maioria das plataformas e é compatível com vídeo escalável. O VP9 oferece melhor qualidade na mesma taxa de bits, mas com maior consumo de CPU. O H.264 se beneficia de codificadores de hardware no iOS e em alguns dispositivos Android, reduzindo o consumo da bateria, mas não suporta vídeo escalável.

Como funciona automaticamente: A plataforma da Vonage negocia o codec para cada par emissor-receptor, respeitando a preferência definida no nível do projeto, mas recorrendo ao VP8 caso o codec preferido não seja compatível com ambos os terminais.

Quando intervir: Veja o Guia de codecs de vídeo Para conhecer todos os critérios de decisão, consulte o Guia sobre vídeo escalável VP9 para o comportamento específico do VP9, e o Guia da API de codecs de vídeo recomendados pelo editor para substituir a configuração por editora.

Criptografia de ponta a ponta (E2EE)

O que ele faz: Criptografa os dados de mídia no cliente, de modo que permaneçam criptografados ao longo de todo o Media Router e só possam ser descriptografados por outros participantes da mesma sessão. Isso proporciona uma camada adicional de criptografia além da criptografia de transporte padrão DTLS-SRTP.

Por que isso é importante: Em sessões roteadas padrão, o Media Router pode acessar mídia não criptografada (o que é necessário para recursos como arquivamento, transcodificação e seleção de camada de vídeo escalável). A criptografia de ponta a ponta (E2EE) impede que o Media Router acesse o conteúdo de mídia, o que é necessário para casos de uso em que é preciso manter a privacidade rigorosa dos dados de ponta a ponta.

Restrições importantes: Quando o E2EE está ativado, os recursos que exigem decodificação de mídia no Media Router ficam indisponíveis: arquivamento, transmissões ao vivo, Experience Composer, Audio Connector e interconexão SIP. Certifique-se de levar em conta essas limitações antes de ativar o E2EE.

Como ativar: O E2EE é um recurso opcional que precisa ser ativado primeiro na sua conta do Vonage Video. Depois de ativado, crie a sessão com e2ee: true utilizando a Video API do lado do servidor e definindo o segredo de criptografia ao inicializar a sessão no cliente:

vonage.video.createSession({ mediaMode: "routed", e2ee: true });

Todos os participantes da sessão devem usar o mesmo segredo de criptografia para receber mídia compreensível. O segredo pode ser alterado dinamicamente assim que a sessão for estabelecida. Consulte o Guia sobre criptografia de ponta a ponta para obter instruções completas de configuração e exemplos específicos do SDK.

Controles de qualidade no nível do fluxo

Os recursos no nível do fluxo são os controles mais detalhados disponíveis. Eles podem ser configurados de forma independente para cada emissor e receptor, e muitos podem ser alterados dinamicamente durante a chamada. Essa é a camada em que seu aplicativo participa ativamente do gerenciamento de qualidade.

Vídeo escalável

O que ele faz: O emissor codifica várias camadas espaciais e temporais do mesmo fluxo. Cada assinante recebe a camada que corresponde à sua largura de banda disponível e aos seus requisitos de exibição, sem que o emissor envie fluxos duplicados em resolução total.

Por que isso é importante: Em uma sessão com dez assinantes, enviar dez transmissões independentes em Full HD a partir do editor é um desperdício, enquanto adaptar uma única transmissão ao assinante com a conexão mais limitada está longe de ser a solução ideal. O vídeo escalável envia um único stream com várias camadas de qualidade; o Media Router seleciona e encaminha a camada apropriada para cada assinante. À medida que a rede de um assinante se deteriora, o Media Router reduz a qualidade da camada em tempo real, enquanto o editor permanece inalterado, continuando a transmitir todas as suas camadas para que o Media Router tome a decisão.

Como funciona automaticamente: Em sessões roteadas com mais de dois participantes, o Media Router habilita o vídeo escalável automaticamente (o Auto (configuração do projeto). O SDK de cada emissora define a estrutura de escalabilidade (a transmissão simultânea em VP8 utiliza camadas L1T1/L2T1/L3T1; o SVC em VP9 também pode utilizar camadas espaciais).

Quando intervir: Para transmissões com compartilhamento de tela, habilite explicitamente o vídeo escalável quando desejar que o Media Router reduza a resolução dessas transmissões para assinantes com menor largura de banda. Consulte o Guia de vídeo escalável.

Predefinições de taxa de bits e taxa de bits máxima do editor

O que ele faz: Permite limitar a taxa de bits máxima que um editor utiliza para vídeos de câmera, por meio de predefinições nomeadas (DEFAULT, BW_SAVER, EXTRA_BW_SAVER) ou valores brutos.

Por que isso é importante: Em uma conexão com limite de tráfego ou congestionada, um emissor sem restrições competirá pela largura de banda com todos os outros aplicativos no dispositivo. Definir uma predefinição mais baixa reduz o consumo de largura de banda do vídeo, deixando mais margem para outros aplicativos no mesmo dispositivo. É importante ressaltar que, ao usar o VP8 com o vídeo escalável ativado, a predefinição também controla quais camadas de codificação estão ativas, de modo que BW_SAVER limita efetivamente o fluxo a duas camadas espaciais (baixa e média), e EXTRA_BW_SAVER limita a um (baixo).

Interação com o controle de velocidade: O Controle de Congestionamento do Google (GCC) continua se adaptando dinamicamente abaixo do limite máximo predefinido. Configuração BW_SAVER é um limite máximo, não um mínimo.

Não utilize predefinições de taxa de bits para o compartilhamento de tela. Os codificadores de compartilhamento de tela funcionam de maneira diferente; aplicar um limite de taxa de bits a um compartilhamento de tela pode resultar em uma saída desfocada e com baixa taxa de quadros, sem a economia de largura de banda esperada. Consulte o Guia de taxa de bits máxima do Publisher.

Controles de resolução e taxa de quadros do editor

Além das predefinições de taxa de bits, é possível controlar diretamente a resolução e a taxa de quadros com que um editor codifica o vídeo. Existem duas abordagens: defini-las no momento da publicação ou ajustá-las dinamicamente após o início da publicação.

Definição da resolução e da taxa de quadros no momento da publicação (Web SDK):

const publisher = OT.initPublisher(targetElement, {
  resolution: '1280x720', // '1920x1080', '1280x720', '640x480', '320x240'
  frameRate: 15,          // 30, 15, 7, or 1
});

Sempre inicialize o editor no máximo resolução e taxa de quadros de que você possa precisar (o SDK só pode reduzir o valor inicial, não aumentá-lo além disso).

Resolução dinâmica e ajuste da taxa de quadros (Web SDK):

Após o início da transmissão, é possível alterar a resolução e a taxa de quadros preferidas do transmissor sem precisar reiniciar a transmissão:

// Reduce resolution
await publisher.setPreferredResolution({ width: 320, height: 180 });

// Reduce frame rate
await publisher.setPreferredFrameRate(7);

Situações comuns em que o ajuste dinâmico é útil:

Em resposta a qualityLimitationReason: "cpu" De acordo com as estatísticas do editor: reduza a taxa de quadros para aliviar a carga sobre a CPU.
Resposta a uma queda repentina na largura de banda antes que o mecanismo de fallback de áudio seja acionado.

Dicas sobre conteúdo de vídeo (Web SDK): Para transmissões com compartilhamento de tela, defina a dica de conteúdo para orientar a estratégia de codificação do navegador:

publisher.setVideoContentHint("text");    // Prioritises sharp text/static content
publisher.setVideoContentHint("motion");  // Prioritises smooth motion (default camera behaviour)
publisher.setVideoContentHint("detail");  // Prioritises fine detail at lower frame rates

Veja o Guia de restrições de vídeo para editores e o Como publicar um stream — Guia da Web.

Preferência de redução de qualidade de vídeo do editor

O que ele faz: Determina como o mecanismo de vídeo define a prioridade entre reduzir a resolução e reduzir a taxa de quadros quando a largura de banda ou os recursos da CPU estão limitados.

Por que isso é importante: Quando a rede ou o dispositivo não conseguem manter a qualidade atual do vídeo, o codificador precisa fazer alguma redução. Por padrão, o mecanismo de vídeo decide de forma autônoma. A preferência de redução permite que você defina a prioridade do seu aplicativo: por exemplo, uma sessão de compartilhamento de tela se beneficia da manutenção da resolução (texto nítido é mais importante do que movimento suave), enquanto uma transmissão de câmera se beneficia da manutenção da taxa de quadros (movimento suave é mais natural do que imagens estáticas pixeladas).

Dica sobre a relação com o conteúdo: Dicas sobre conteúdo em vídeo e a preferência de degradação têm finalidades diferentes, mas relacionadas. A dica de conteúdo descreve o tipo de conteúdo que está sendo transmitido (por exemplo, "text" (para compartilhamento de tela), enquanto a preferência de degradação controla explicitamente a estratégia de codificação. Ao definir uma dica de conteúdo, o mecanismo de vídeo seleciona automaticamente uma preferência de degradação adequada — por exemplo, "text" seleciona automaticamente para manter a resolução. Uma preferência de redução de qualidade definida explicitamente substitui a seleção automática do Content Hint.

Relação com o vídeo escalável: Quando o vídeo escalável está ativo, o mecanismo de vídeo pode decidir remover uma camada temporal ou espacial, em vez de reduzir a resolução do fluxo restante. A preferência de redução de qualidade continua valendo como orientação dentro das camadas ativas.

APIs específicas do SDK:

Consulte os guias de publicação específicos para cada plataforma para ver exemplos completos: Android, iOS, iOS (Swift), Linux, Windows.

Resolução e taxa de quadros preferidas pelo assinante

Ao assinar um fluxo de vídeo escalável, é possível indicar ao Media Router qual camada de qualidade deve ser transmitida a cada assinante. Essa é a principal ferramenta para a criação de layouts adaptativos. Por exemplo, em uma grande grade de conferência, em que as miniaturas devem receber uma camada de baixa resolução e o palestrante ativo deve receber a resolução total.

Definição da resolução preferencial no momento da inscrição (Web SDK):

session.subscribe(stream, targetElement, {
  preferredResolution: 'auto', // Recommended: SDK picks the layer based on element size
  // Or specify explicitly:
  // preferredResolution: { width: 320, height: 240 },
  // preferredFrameRate: 7,
});

O "auto" Essa configuração é recomendada na maioria dos casos: o Web SDK determina automaticamente a resolução preferencial a partir do tamanho renderizado do elemento de vídeo do assinante e solicita a camada de vídeo escalável mais adequada. É importante observar que "auto" é sensível ao layout. Se o seu aplicativo alterar com frequência o tamanho dos blocos dos assinantes (por exemplo, alternância do alto-falante ativo, fluxos de fixação/desfixação, reajustes responsivos da grade ou transições animadas), o SDK poderá atualizar repetidamente a resolução preferencial. Isso pode provocar trocas mais frequentes de camadas e ciclos de “aumento/redução” da largura de banda no Media Router, o que pode aumentar a instabilidade da rede e reduzir a estabilidade visual. Para layouts altamente dinâmicos, considere definir uma preferredResolution (e atualizá-la somente quando a interface do usuário se estabilizar), ou limitar a frequência das alterações na resolução para evitar oscilações rápidas.

Ajuste dinâmico após a assinatura:

// Downgrade a tile when moving it to a thumbnail position
subscriber.setPreferredResolution({ width: 320, height: 240 });
subscriber.setPreferredFrameRate(7);

// Upgrade when the subscriber becomes the active speaker
subscriber.setPreferredResolution({ width: 1280, height: 720 });
subscriber.setPreferredFrameRate(30);

Restrição da taxa de quadros (Web SDK): subscriber.restrictFrameRate(true) limita o assinante a um quadro por segundo ou menos. Isso pode ser útil para participantes inativos em sessões grandes, a fim de economizar CPU e largura de banda, mantendo, ainda assim, a exibição de um bloco de “presença”. Chamada restrictFrameRate(false) para restaurar a taxa de quadros normal.

Para APIs entre SDKs, consulte o Guia de vídeo escalável e o Inscreva-se no guia de qualidade.

Alternativa de áudio

O que ele faz: Quando a rede de um editor ou assinante não consegue mais suportar a transmissão de vídeo, o SDK desativa automaticamente o vídeo para essa transmissão, mantendo o áudio ativo, e o reativa quando as condições melhoram.

Por que isso é importante: Um quadro de vídeo congelado é incômodo; uma interrupção no fluxo de áudio interrompe completamente a conversa. O recurso de fallback de áudio garante que, quando a largura de banda se esgota, os participantes ainda possam ouvir uns aos outros. Combinado com o Opus FEC e o DTX, o áudio permanece inteligível mesmo em taxas de bits muito baixas.

Dois modos complementares:

Opção alternativa de áudio do editor: Acionado pela avaliação de rede realizada pelo próprio cliente de publicação. Quando as métricas de congestionamento do editor indicam que a transmissão de vídeo não é sustentável, o editor desativa sua trilha de vídeo. Disponível tanto em sessões retransmitidas quanto em sessões roteadas.
Solução alternativa de áudio para assinantes: Acionado pelo Media Router em nome de um assinante específico. Apenas o assinante afetado perde o sinal de vídeo; os demais assinantes continuam a recebê-lo. Disponível apenas em sessões roteadas.

Ambos os recursos são ativados automaticamente. Para obter mais informações, consulte o Guia de alternativas de áudio.

Monitoramento e Observabilidade

A camada de monitoramento abrange todas as três camadas da pilha, proporcionando visibilidade da qualidade em todos os níveis, desde a topologia da infraestrutura até as métricas de fluxos individuais.

Monitoramento de qualidade e observabilidade do cliente

O que ele faz: A API de observabilidade do cliente fornece um fluxo contínuo de estatísticas por stream — perda de pacotes, taxa de bits, taxa de quadros, resolução decodificada, contagem de travamentos e muito mais — tanto para editores quanto para assinantes. Além disso, o SDK para web fornece um Índice de Opinião Média (MOS) para vídeo, que é um índice de qualidade que simula a escala do MOS de áudio, e monitoramento do desempenho da CPU.

Por que isso é importante: Sem visibilidade do que está acontecendo em cada terminal, não é possível distinguir entre “a rede do usuário está com problemas” e “o dispositivo do usuário está sobrecarregado”. As estatísticas permitem que seu aplicativo tome decisões inteligentes: alertar o usuário antes que a qualidade se deteriore ainda mais, ajustar layouts ou acionar ações baseadas em políticas.

Principais recursos:

API de estatística de alto nível: Métricas agregadas por editor ou por assinante, normalizadas em relação às transições de conexão entre pares. Utilize isso para monitoramento de produção e experiência do usuário adaptativa.
Eventos relacionados à alteração da qualidade do vídeo: É disparado quando a qualidade muda com um código de motivo (largura de banda, CPU, mudança de codec, mudança de resolução). Use-os para controlar o estado da interface do usuário sem precisar fazer polling.
Pontuação Média de Opinião (MOS): Uma pontuação de qualidade de 1 a 5, padrão do setor (somente na web). Integre-a à sua pilha de observabilidade para acompanhar as tendências de qualidade das chamadas ao longo do tempo.
Monitoramento do desempenho da CPU: Detecta sobrecarga da CPU no dispositivo antes que ela cause perda de quadros (apenas na web). Reaja desativando recursos que exigem muito da CPU, como o desfoque de fundo.
Testes prévios à chamada: Use o Biblioteca de testes da Rede de Vídeo da Vonage para estimar o MOS e verificar se o áudio e o vídeo estão aptos para publicação antes que o usuário entre em uma sessão.

Veja o Guia de observabilidade do cliente para consultar a documentação completa sobre estatísticas e exemplos de código específicos do SDK.