Restrições de vídeo: como definir a resolução e a taxa de quadros preferidas

A Video API da Vonage permite que os editores otimizem as transmissões de vídeo definindo restrições preferenciais quanto à resolução e à taxa de quadros. Essas restrições ajudam a gerenciar o uso da largura de banda, se adaptar às capacidades dos dispositivos e oferecer uma experiência personalizada aos assinantes.

Este guia explica como usar o preferredResolution e preferredFrameRate APIs para editores.

Observação: Atualmente, essas APIs estão disponíveis apenas no SDK do JavaScript. Não há um cronograma anunciado para o suporte em outros SDKs.

Visão geral

Ao publicar um stream de vídeo, pode ser necessário ajustar dinamicamente a qualidade do vídeo por diversos motivos: economia de largura de banda, adequação aos requisitos da interface do usuário ou restrição do consumo de recursos para determinadas funções dos assinantes (como miniaturas ou telas com pouco movimento). A API de publicação da Vonage disponibiliza métodos que permitem ajustar a resolução e a taxa de quadros preferidas para suas faixas de vídeo. Essas restrições são aplicadas no dispositivo de entrada de vídeo por meio de APIs WebRTC padrão para obter resultados ideais, mas, em última instância, influenciam o que todos os assinantes receberão.

Controle da resolução e da taxa de quadros do vídeo

A editora pode especificar:

  • Resolução preferida: A largura e a altura desejadas (em pixels) para o fluxo de vídeo.
  • Taxa de quadros preferencial: O número desejado de quadros por segundo (fps) para a transmissão de vídeo.

Você pode controlá-los dinamicamente usando os seguintes métodos depois de O editor é inicializado:

// Set preferred resolution (width x height)
await publisher.setPreferredResolution({ width: 640, height: 360 });

// Set preferred frame rate
await publisher.setPreferredFrameRate(15);

Essas configurações controlam diretamente a trilha de vídeo transmitida pelo editor, o que, por sua vez, afeta a qualidade para todos os assinantes. No entanto, as condições reais da rede e os recursos dos dispositivos podem limitar ou substituir esses valores.

Como definir a resolução preferencial

Método: publisher.setPreferredResolution(preferredResolution)

  • preferredResolution é um objeto com width e height propriedades (ambas inteiros positivos, em pixels).
  • A resolução não pode ser maior do que a resolução inicial de publicação. Por exemplo, se você publicou em 640×480, não é possível definir uma resolução maior do que essa.

Uso típico:

publisher.setPreferredResolution({ width: 320, height: 240 });

Validações:

  • Deve ser chamado em um publisher que esteja capturando vídeo (publishVideo: true).
  • Ambos width e height devem ser números inteiros positivos.
  • A resolução não pode ser maior do que a resolução inicial de publicação.

Casos de erro:

  • Gera uma exceção se for chamado em um publisher apenas de áudio ou se os valores de entrada forem inválidos.

Definição da taxa de quadros preferencial

Método: publisher.setPreferredFrameRate(frameRate)

  • frameRate deve ser um número inteiro maior ou igual a 1.

Uso típico:

publisher.setPreferredFrameRate(15);

Validações:

  • Deve ser chamado em um editor com uma trilha de vídeo ativa.
  • A taxa de quadros deve ser um número inteiro válido ≥ 1.

Casos de erro:

  • Gera uma exceção se for chamado em um publisher somente de áudio ou se o parâmetro `frameRate` for inválido.

Melhores práticas

  • Se você já souber de antemão a resolução e a taxa de quadros ideais, defina-as ao criar o Publisher usando OT.initPublisher() (por exemplo, por meio de resolution e frameRate). Para assinantes, é possível omitir essas configurações ou usar preferredResolution: 'auto' ao ligar Session.subscribe().
  • Use as APIs de assinantes (subscriber.setPreferredResolution() / subscriber.setPreferredFrameRate()) para alterar a forma como um único assinante recebe/decodifica/exibe um fluxo. Isso afeta apenas esse assinante e não altera o que o Editor envia nem o que os outros assinantes recebem.
  • Use as APIs do Publisher (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) para alterar o que o Editor envia. Isso afeta todos os assinantes desse fluxo, que receberão automaticamente as configurações atualizadas. Talvez você queira reduzir a resolução do editor usando o preferredResolution método em vários casos, tais como:
    • Quando você perceber que o dispositivo editor está com dificuldades, seja devido a limitações da CPU ou a problemas de rede, e quiser aliviar a sobrecarga mais rapidamente do que a pilha WebRTC normalmente faria.
    • Se a bateria do aparelho estiver acabando e você quiser minimizar o consumo de energia para prolongar a duração da chamada.
    • Quando você inicia o compartilhamento de tela ou abre outros editores no mesmo dispositivo e precisa liberar recursos computacionais para essas atividades.
  • A resolução e a taxa de quadros preferidas pelo Publisher nunca podem exceder os valores especificados na inicialização do Publisher. Inicialize o Publisher com a resolução e a taxa de quadros máximas de que você possa precisar e, em seguida, reduza ou aumente esses valores dinamicamente dentro desses limites, de acordo com o seu caso de uso.
  • Escolha taxas de quadros adequadas ao conteúdo, por exemplo:
    • 5 fps para slides estáticos, painéis de controle, telas com muito pouco movimento ou uso mínimo de largura de banda.
    • 15 fps para telas com pouca movimentação ou em situações em que a largura de banda é um fator importante
    • 30 fps para vídeo em movimento ou para requisitos de alta qualidade
  • As condições da rede podem impedir que o SDK mantenha a resolução e a taxa de quadros de sua preferência. Considere os valores preferidos como metas: se a largura de banda ou a CPU ficarem limitadas, o SDK poderá reduzir automaticamente a qualidade do vídeo publicado/assinado (por exemplo, uma preferência de 1080p pode cair temporariamente para uma resolução inferior durante condições ruins de rede).
  • Atualmente, a resolução e a taxa de quadros preferidas estão disponíveis apenas no SDK do JavaScript. Não há um cronograma para a adição desse recurso a outros SDKs.

Notas adicionais

  • As restrições que você definir influenciam todos os assinantes na sua transmissão, e não apenas na interface do usuário local.
  • A rede e o backend determinarão, em última instância, a qualidade real do vídeo transmitido, com base no estado atual da conexão e na largura de banda disponível.
  • Essas APIs estão disponíveis apenas por meio do SDK do JavaScript; os demais SDKs não oferecem suporte a alterações dinâmicas nas restrições de vídeo no momento.

Recursos adicionais