Publicar: Diagnósticos

Este guia explica como coletar dados de diagnóstico para editores e resolver problemas comuns.

Como obter estatísticas sobre o stream de um editor

O SDK de vídeo da Vonage disponibiliza métricas detalhadas sobre a qualidade do fluxo por meio de uma API de estatísticas de alto nível — recomendada para a maioria dos casos de uso —, que fornece estatísticas de áudio, vídeo, rede e do lado do remetente de forma unificada e sensível à sessão, mantendo-se estável durante as transições entre conexões entre pares. Para depuração avançada, o SDK também oferece acesso ao relatório bruto de estatísticas do WebRTC, que reflete dados não processados das conexões entre pares.

Consulte Guia do desenvolvedor sobre observabilidade do cliente para obter informações detalhadas.

Transmissão de teste

Você pode publicar uma transmissão de teste e verificar suas estatísticas de áudio e vídeo para determinar o tipo de transmissão (como alta resolução ou somente áudio) compatível com a sua conexão.

Para obter estatísticas de um stream publicado pelo cliente local, é necessário usar uma sessão que utilize o Media Router (sessões com o modo de mídia definido como “routed”) e definir o testNetwork propriedade para true no options objeto que você passa para o Session.subscribe() método. Em seguida, você pode usar o getStats() método do objeto Subscriber para obter estatísticas de áudio e vídeo da transmissão que você publica.

Melhores práticas na publicação

Esta seção traz dicas para publicar transmissões com sucesso.

Permitir o acesso ao dispositivo

É recomendável informar aos usuários que será solicitado que eles autorizem o acesso à câmera e ao microfone.

Constatamos que, de longe, a maior parte das falhas na publicação se deve ao fato de os usuários clicarem no botão “recusar” ou simplesmente não clicarem no botão “permitir”. Disponibilizamos todos os eventos necessários para que você possa orientar seus usuários nesse processo:

publisher.on({
  accessDialogOpened: function (event) {
    // Show allow camera message
    pleaseAllowCamera.style.display = 'block';
  },
  accessDialogClosed: function (event) {
    // Hide allow camera message
    pleaseAllowCamera.style.display = 'none';
  }
});

Também é uma boa ideia hospedar seu site por SSL. Isso porque o Chrome exige que os usuários cliquem para permitir o acesso aos dispositivos apenas uma vez por domínio, desde que esse domínio seja hospedado por SSL. Isso significa que seus usuários (se estiverem no Chrome) não precisam lidar com aquela caixa de diálogo inconveniente de permissão/recusa toda vez que carregarem a página.

Separar OT.initPublisher() e Session.publish()

Outra coisa que recomendamos é dividir o OT.initPublisher() e Session.publish() etapas. Isso agiliza o tempo de conexão inicial, pois você se conecta à sessão enquanto aguarda que o usuário clique no botão “Permitir”. Portanto, em vez de:

session.connect(token, function (err) {
{... your error handling code ...}
if (!err) {
    var publisher = OT.initPublisher();
    session.publish(publisher);
  }
});

Mova o OT.initPublisher() siga este passo antes de se conectar, conforme mostrado a seguir:

var publisher = OT.initPublisher();
session.connect(token, function (err) {
{... your error handling code ...}
  if (!err) {
    session.publish(publisher);
  }
});

Resolução e taxa de quadros

É possível definir a resolução e a taxa de quadros do Publisher ao inicializá-lo:

OT.initPublisher(divId, {
  resolution: '320x240',
  frameRate: 15
});

Por padrão, a resolução de um Publisher é 640x480, mas você também pode defini-la como 1920x1080, 1280x720 ou 320x240. É recomendável tentar ajustar a resolução ao tamanho em que o vídeo será exibido. Se você estiver exibindo o vídeo apenas em 320x240 pixels, não faz sentido transmitir em 1280x720 ou 1920x1080. Reduzir a resolução pode economizar largura de banda e diminuir o congestionamento e as quedas de conexão.

Por padrão, a taxa de quadros do vídeo é de 30 quadros por segundo, mas você também pode defini-la para 15, 7 ou 1. Reduzir a taxa de quadros pode diminuir a largura de banda necessária. Vídeos com resolução menor podem ter uma taxa de quadros mais baixa sem que haja uma diferença perceptível para o usuário. Portanto, se você estiver usando uma resolução baixa, talvez seja interessante considerar o uso de uma taxa de quadros baixa também.

Solução de problemas

Siga as dicas desta seção para evitar problemas de conectividade ao publicar. Para obter informações gerais sobre solução de problemas, consulte Depuração — Web.

Tratamento de erros

Existem métodos de retorno de chamada para ambos Session.publish() e OT.initPublisher(). Recomendamos tratar as respostas de erro desses dois métodos. Conforme mencionado anteriormente, é melhor dividir essas etapas e chamar OT.initPublisher() antes de iniciar a conexão com sua sessão. Além disso, o tratamento de erros fica mais fácil se você não chamar esses dois métodos ao mesmo tempo. Isso porque ambos os manipuladores de erros serão acionados caso ocorra algum erro na publicação. É melhor aguardar até que OT.initPublisher() para concluir e Session.connect() preencher e, em seguida, ligar Session.publish(). Dessa forma, você pode lidar com todos os problemas relacionados ao hardware no OT.initPublisher() callback e todos os problemas relacionados à rede no Session.publish() chamada de retorno.

var connected = false,
  publisherInitialized = false;

var publisher = OT.initPublisher(function(err) {
  if (err) {
    // handle error
  } else {
    publisherInitialized = true;
    publish();
  }
});

var publish = function() {
  if (connected && publisherInitialized) {
    session.publish(publisher);
  }
};

session.connect(token, function(err) {
  if (err) {
    // handle error
  } else {
    connected = true;
    publish();
  }
});

Acesso negado

O maior número de casos em que não se conseguiu OT.initPublisher() são resultado da recusa do usuário final em conceder acesso à câmera e ao microfone. Isso pode ser resolvido monitorando o accessDenied evento ou ao detectar uma resposta de erro no método OT.initPublisher() com um code propriedade definida como 1500 e um message propriedade definida como “Acesso do editor negado:”. Recomendamos que você trate dessa situação e exiba uma mensagem ao usuário indicando que ele deve tentar publicar novamente e permitir o acesso à câmera.

publisher.on({
  'accessDenied': function() {
    showMessage('Please allow access to the Camera and Microphone and try publishing again.');
  }
});

Acesso ao dispositivo

Outra razão para OT.initPublisher() A falha ocorre quando o OpenTok não consegue acessar uma câmera ou um microfone. Isso pode acontecer se não houver uma câmera ou um microfone conectado ao computador, se houver algum problema com o driver da câmera ou do microfone, ou se algum outro aplicativo estiver usando a câmera ou o microfone (isso só ocorre no Windows). Você pode tentar minimizar a ocorrência desses problemas usando nosso Componente de Configuração de Hardware ou ligando para o OT.getDevices() método diretamente. No entanto, você também deve tratar qualquer erro ao chamar OT.initPublisher() porque ainda pode dar algo errado. Por exemplo, o usuário pode ter negado o acesso à câmera ou ao microfone. Nesse caso, o error.name a propriedade está definida como "OT_USER_MEDIA_ACCESS_DENIED":

publisher = OT.initPublisher('publisher', {}, function (err) {
  if (err) {
    if (err.name === 'OT_USER_MEDIA_ACCESS_DENIED') {
      // Access denied can also be handled by the accessDenied event
      showMessage('Please allow access to the Camera and Microphone and try publishing again.');
    } else {
      showMessage('Failed to get access to your camera or microphone. Please check that your webcam'
        + ' is connected and not being used by another application and try again.');
    }
    publisher.destroy();
    publisher = null;
  }
});

Erros de rede

As outras causas de falhas na publicação geralmente se devem a algum tipo de falha na rede. Lidamos com elas na função de retorno de chamada para Session.publish(). Se o usuário não estiver conectado à rede, é passado à função de retorno de chamada um objeto de erro com o name propriedade definida como "OT_NOT_CONNECTED". Se o usuário estiver em uma conexão de rede muito restritiva que não permita conexões WebRTC, o Publisher não conseguirá se conectar, e o elemento Publisher exibirá uma roda giratória. Esse erro tem um name propriedade definida como "OT_CREATE_PEER_CONNECTION_FAILED". Nesse caso, recomendamos que você exiba uma mensagem ao usuário informando que a publicação não foi bem-sucedida e que ele deve verificar sua conexão de rede. O tratamento desses erros é feito da seguinte forma:

session.publish(publisher, function(err) {
  if (err) {
    switch (err.name) {
      case "OT_NOT_CONNECTED":
        showMessage("Publishing your video failed. You are not connected to the internet.");
        break;
      case "OT_CREATE_PEER_CONNECTION_FAILED":
        showMessage("Publishing your video failed. This could be due to a restrictive firewall.");
        break;
      default:
        showMessage("An unknown error occurred while trying to publish your video. Please try again later.");
    }
    publisher.destroy();
    publisher = null;
  }
});

Perda de conectividade

Seu Publisher também pode perder a conexão depois de já ter conseguido se conectar. Na maioria das vezes, isso também fará com que a sessão perca a conexão, mas nem sempre é assim. Você pode lidar com a desconexão do Publisher monitorando o streamDestroyed evento com um reason propriedade definida como “networkDisconnected” desta forma:

publisher.on({
  streamDestroyed: function (event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('Your publisher lost its connection. Please check your internet connection and try publishing again.');
    }
  }
});

Implementação de tentativas de reenvio de publicação de sessão

Falhas temporárias na publicação são um padrão conhecido e recorrente no SDK JS da Video API, especialmente em navegadores móveis. Quando session.publish() Se falhar, o SDK retorna um erro por meio do callback do manipulador de conclusão. A abordagem recomendada é implementar uma lógica de repetição de tentativa no nível do aplicativo, com um intervalo entre as tentativas.

Por que ocorrem falhas na publicação

As causas mais comuns para falhas transitórias na publicação são:

• Tempo limite do StreamCreateRequest (erro 1500): OT.Publisher não foi possível publicar dentro de um prazo razoável — geralmente devido a eventos de interrupção de mídia ou atrasos na rede durante a negociação do ICE/SDP.
• mediaStopped eventos durante o fluxo de publicação, onde o acesso ao dispositivo de mídia pode ser interrompido.
• Reutilização do objeto Publisher sem limpeza adequada — reutilizar uma instância de publisher inicializada com restrições diferentes sem chamar unpublish e reinicializando.
• OT_NOT_CONNECTED — tentativa de publicação antes que a sessão esteja totalmente conectada.
• OT_USER_MEDIA_ACCESS_DENIED — problemas de acesso ao dispositivo (que não permitem nova tentativa).

Erros recuperáveis x erros não recuperáveis

Nem todos session.publish() nem todos os erros são iguais. Antes de implementar uma lógica de repetição de tentativa, é essencial classificar os erros corretamente — repetir a tentativa em caso de um erro irrecuperável desperdiça tempo, prejudica a experiência do usuário e pode mascarar falhas reais que exigem uma resposta diferente.

Erros irrecuperáveis — Não tente novamente

Esses erros representam erros do programador, restrições rígidas de permissão ou contexto de chamada inválido. Repetir a tentativa não resolverá esses problemas. Em vez disso, exiba uma mensagem clara para o usuário ou corrija a lógica do aplicativo.

Erros recuperáveis — É seguro tentar novamente

Esses erros são normalmente causados por condições transitórias da rede, tempo limite de sinalização ou indisponibilidade temporária da plataforma. Eles são o principal alvo da lógica de nova tentativa.

Erros que exigem uma ação diferente (não uma simples repetição da tentativa)

Alguns erros não podem ser resolvidos nem com uma simples nova tentativa nem com uma interrupção definitiva — eles exigem uma ação corretiva específica antes de se tentar novamente.

Resumindo: Padrão recomendado de nova tentativa com classificação de erros

async function publishWithRetry(session, publisher, attempt = 1) {
  const MAX_RETRIES = 3;
  const RETRY_DELAY_MS = 2000;

  const error = await new Promise((resolve) => {
    session.publish(publisher, resolve);
  });

  if (!error) {
    console.log('Publishing started successfully.');
    return;
  }

  // Non-recoverable: programmer error or hard permission constraint
  const nonRetryable = [
    'OT_NOT_CONNECTED',
    'OT_PERMISSION_DENIED',
    'OT_INVALID_PARAMETER',
    'OT_USER_MEDIA_ACCESS_DENIED',
    'OT_CHROME_MICROPHONE_ACQUISITION_ERROR',
    'OT_SCREEN_SHARING_NOT_SUPPORTED',
    'OT_CONSTRAINTS_NOT_SATISFIED',
  ];

  // Requires corrective action before retrying
  const requiresAction = [
    'OT_HARDWARE_UNAVAILABLE',
    'OT_NO_DEVICES_FOUND',
  ];

  if (nonRetryable.includes(error.name)) {
    console.error('Non-retryable error — user action or code fix required:', error.name);
    handleNonRecoverableError(error);
    return;
  }

  if (requiresAction.includes(error.name)) {
    console.warn('Device error — prompting user before retrying:', error.name);
    handleDeviceError(error);
    return;
  }

  // Recoverable: retry with backoff
  if (attempt < MAX_RETRIES) {
    console.warn(`Publish attempt ${attempt} failed (${error.name}), retrying...`);
    await delay(RETRY_DELAY_MS * attempt);
    await publishWithRetry(session, publisher, attempt + 1);
  } else {
    console.error('All publish attempts failed. Disconnecting user.');
    handlePublishFailure(session);
  }
}

function handleNonRecoverableError(error) {
  // Surface a meaningful message to the user based on error.name
  // e.g. for OT_USER_MEDIA_ACCESS_DENIED: "Please allow camera/mic access"
}

function handleDeviceError(error) {
  // Prompt the user to check their device, then allow them to retry manually
}

function handlePublishFailure(session) {
  session.disconnect();
}

Modo de uso:

const publisher = OT.initPublisher('publisher-container', publisherOptions);

// Wait for session to be connected before publishing
session.connect(token, (err) => {
  if (err) { /* handle connection error */ return; }
  publishWithRetry(session, publisher);
});

Importante: Limpeza do Publisher antes de tentar novamente

Se o editor tiver sido destruído entre as tentativas (por exemplo, você recebeu um streamDestroyed ou destroyed evento no editor), é necessário reinicializá-lo com OT.initPublisher() antes de ligar session.publish() novamente. Reutilizar um objeto publisher destruído não funcionará.

publisher.on('destroyed', () => {
  // Publisher was destroyed — reinitialize before retrying
  publisher = OT.initPublisher('publisher-container', publisherOptions);
});

Se a editora não tiver sido destruída (a session.publish() (a função de retorno de chamada retornou um erro, mas o objeto publisher ainda está ativo), você pode tentar novamente com a mesma instância do publisher.

O que NÃO fazer

• Faça não chamada OT.initPublisher() duas vezes no mesmo objeto “publisher” com restrições diferentes, sem limpar primeiro (session.unpublish() → esperar por streamDestroyed → em seguida, reinicialize).
• Faça não tentar novamente em OT_PERMISSION_DENIED (o usuário negou acesso à câmera/microfone) — isso requer uma ação do usuário, não uma nova tentativa.
• Faça não tentar novamente em OT_NOT_CONNECTED — verifique se a sessão está conectada antes de publicar.
• Faça não tentar novamente indefinidamente — limitar a 3 tentativas e lidar com a falha de maneira adequada.

Lidando com o mediaStopped Evento

A reprodução da mídia pode ser interrompida no meio da publicação. Fique atento a esse evento e trate-o como um gatilho para tentar novamente:

publisher.on('mediaStopped', async () => {
  console.warn('Media stopped during publish — retrying...');
  // Unpublish if already publishing, then retry
  try { session.unpublish(publisher); } catch (e) { /* ignore */ }
  await delay(2000);
  publishWithRetry(session, publisher);
});

Resumo dos parâmetros recomendados

Como lidar com problemas de captura de áudio: audioAcquisitionProblem e audioAcquisitionProblemResolved

Além das tentativas de repetição no nível da publicação, há uma categoria distinta de problemas de áudio que podem afetar um publicador ativo: o dispositivo de áudio do cliente pode não conseguir transmitir dados de áudio mesmo após uma publicação bem-sucedida. O SDK JS da Video API disponibiliza dois eventos específicos para esse cenário.

Causas comuns

O audioAcquisitionProblem O evento é acionado quando o SDK detecta — por meio das estatísticas do publisher — que a trilha de áudio parou de enviar bytes para a conexão entre pares, mesmo que getUserMedia foi bem-sucedida e a editora parece estar ativa. As causas principais mais comuns são:

• Dispositivo de áudio Bluetooth conectado ou desconectado no meio da sessão: Quando um usuário conecta ou desconecta fones de ouvido, ou conecta fones de ouvido Bluetooth (por exemplo, AirPods) durante uma sessão ativa, o sistema operacional pode alterar o dispositivo de áudio padrão. O pipeline de áudio do navegador pode não conseguir reaquisiar o microfone no novo dispositivo, resultando no envio de zero bytes de áudio.
• Alteração do dispositivo de áudio no início da sessão: Mudar a entrada de áudio logo no início da sessão — nos primeiros 1 a 2 segundos após a publicação — tende a causar esse problema com maior frequência.
• Faixa de áudio encerrada pelo navegador ou pelo sistema operacional (trackEndedEvent): O navegador pode encerrar a faixa de áudio subjacente independentemente de qualquer ação do usuário. O SDK detecta isso por meio de um track.ended evento e aumentos audioAcquisitionProblem com method: trackEndedEvent.
• Detecção baseada em estatísticas (ausência de fluxo de bytes de áudio): O SDK monitora continuamente as estatísticas do editor após o estabelecimento da conexão entre pares. Se nenhum byte de áudio for detectado dentro de 30 segundos após a conexão atingir o estado “conectada”, audioAcquisitionProblem é levantada com method: getStats.

Os eventos

Esses eventos são emitidos na instância do publisher:

• audioAcquisitionProblem — disparado quando o SDK detecta que o editor parou de enviar áudio (com base nas estatísticas do editor). Isso não significa necessariamente que a transmissão irá falhar, mas é um indicador de que a captura de áudio foi interrompida.
• audioAcquisitionProblemResolved — disparado quando a transmissão de áudio é restabelecida após uma audioAcquisitionProblem. Se esse evento ocorrer, não é necessária nenhuma ação corretiva.

Padrão de recuperação recomendado

Inicie um temporizador curto ao receber audioAcquisitionProblem. Se audioAcquisitionProblemResolved Se o problema for resolvido antes que o temporizador expire, o áudio terá se recuperado sozinho e não será necessária nenhuma ação. Se o temporizador expirar sem que o problema tenha sido resolvido, troque a fonte de áudio como medida de recuperação.

publisher.on('audioAcquisitionProblem', () => {
  // Start a 3-second timer
  const timeout = setTimeout(() => {
    // Problem not resolved — attempt recovery by switching audio source
    publisher.setAudioSource(newDeviceId);
  }, 3000);

  publisher.on('audioAcquisitionProblemResolved', () => {
    // Audio recovered — clear the timer, no action needed
    clearTimeout(timeout);
  });
});

Principais considerações

• Não é um indicador de falha garantida: audioAcquisitionProblem nem sempre resulta em uma falha na assinatura. Utilize-o como um sinal precoce para monitorar e, eventualmente, tomar medidas, e não como um evento definitivo de falha.
• Acompanhar as estatísticas de áudio do editor: Após receber audioAcquisitionProblem, você também pode acompanhar as estatísticas de áudio do editor (por exemplo, por meio de publisher.getStats()) para confirmar se a transmissão de áudio realmente foi interrompida antes de tomar qualquer medida.
• Medida de recuperação: Chamando publisher.setAudioSource(newDeviceId) é o principal mecanismo de recuperação. Isso alterna o dispositivo de entrada de áudio sem exigir um ciclo completo de retirada da publicação e nova publicação.
• Relação com os prazos de validade das assinaturas: Se o áudio não for recuperado e o emissor continuar sem enviar pacotes de áudio, os assinantes poderão eventualmente se deparar com OT_TIMEOUT (1501). Tratamento proativo de audioAcquisitionProblem pode ajudar a evitar essa falha em etapas posteriores.