Restrições de vídeo do editor — Web

Depois de inicializou um Publisher, é possível definir a resolução e a taxa de quadros preferidas da trilha de vídeo de saída. Isso permite otimizar a largura de banda e o uso da CPU para diferentes tamanhos de interface do usuário (miniaturas, blocos, tela cheia) e dispositivos dos assinantes.

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

Entendendo as restrições de vídeo dos editores

A editora pode anunciar um preferido resolução e taxa de quadros da trilha de vídeo: o SDK aplica restrições ao dispositivo de captura e à trilha de saída. Os assinantes se beneficiam de menor uso de largura de banda e CPU quando o editor define tamanhos menores ou taxas de quadros mais baixas para destinos de interface do usuário de pequeno porte. Observe que a qualidade entregue pode ser ajustada ainda mais de acordo com os recursos do dispositivo e as condições da rede.

Definindo a resolução preferida

Ligar publisher.setPreferredResolution(preferredResolution) para definir as dimensões em pixels preferidas:

await publisher.setPreferredResolution({ width: 640, height: 360 });
  • preferredResolution é um objeto: { width: number, height: number }.
  • A resolução preferencial não deve exceder a resolução inicial de publicação.
  • Aplica-se apenas quando o Editor está gravando vídeo (publishVideo: true).

Gera um erro se:

  • O Publisher é apenas em áudio.
  • width ou height não é um número inteiro positivo.
  • A resolução solicitada excede a resolução inicial de publicação.
try {
  // If the initial publish was 640x480, this will throw:
  await publisher.setPreferredResolution({ width: 1920, height: 1080 });
} catch (error) {
  console.error('Failed to set preferred resolution:', error.message);
}

Definição da taxa de quadros preferencial

Ligar publisher.setPreferredFrameRate(frameRate) para definir um valor preferencial de quadros por segundo:

await publisher.setPreferredFrameRate(15);
  • frameRate deve ser um número inteiro positivo (≥ 1).
  • Requer uma trilha de vídeo ativa.

Gera um erro se:

  • O Publisher é apenas em áudio.
  • frameRate não é um número inteiro válido ≥ 1.

Como as restrições afetam a entrega

As restrições preferenciais influenciam a trilha de vídeo de saída para todos os assinantes para a transmissão. No entanto, a resolução e a taxa de quadros finais transmitidas podem ser menores devido a:

  • Limitações do dispositivo de captura
  • Limitações do navegador ou do sistema operacional
  • Condições da rede e decisões adaptativas sobre mídia

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 assinante único 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 Editora envia. Isso afeta todos os assinantes desse stream, que receberão automaticamente as configurações atualizadas. Em alguns casos, pode ser interessante reduzir a resolução do editor usando o método `preferredResolution`, como, por exemplo:
    • 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.
  • Use taxas de quadros adequadas:
    • 5 fps — painéis estáticos, slides, interface de usuário sensível à largura de banda
    • 15 fps — conteúdo com pouca movimentação
    • 30 fps — vídeo em movimento contínuo/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, essas APIs são compatíveis apenas no SDK do JavaScript.

Exemplos

// Lower quality for mobile users
if (isMobileUser) {
  publisher.setPreferredResolution({ width: 320, height: 180 });
  publisher.setPreferredFrameRate(15);
}

// Higher quality for desktop
if (isDesktopUser) {
  publisher.setPreferredResolution({ width: 1280, height: 720 });
  publisher.setPreferredFrameRate(30);
}

// Error when using resolution above initial publish
try {
  await publisher.setPreferredResolution({ width: 1920, height: 1080 }); // If initial was 640x480, throws error
} catch (error) {
  console.error(error.message);
}

// Debugging: Current track settings
const videoTrack = publisher.getVideoSource().track;
const { width, height, frameRate } = videoTrack.getSettings();
console.log('Current resolution:', width, 'x', height);
console.log('Current frame rate:', frameRate);

Solução de problemas

Tratamento de erros

Encapsule as chamadas em try/catch e exibir mensagens de fácil compreensão quando as restrições forem inválidas ou quando o ambiente não puder atendê-las.

async function setPublisherQuality(publisher, preferredResolution, preferredFrameRate) {
  try {
    await publisher.setPreferredResolution(preferredResolution);
    await publisher.setPreferredFrameRate(preferredFrameRate);
  } catch (err) {
    showMessage('Unable to apply video constraints. Check your device and network.');
    console.error(err);
  }
}

Considerações sobre a rede

Se a rede estiver sobrecarregada, o pipeline de mídia poderá reduzir a resolução ou a taxa de quadros transmitidas, independentemente das configurações preferidas. Considere implementar indicadores na interface do usuário para os modos de qualidade reduzida.

Recursos adicionais