WebRTC: guia de migração legado do getStats()

Henrik Boström

A API WebRTC getStats() legada será removida no Chrome 117. Os apps que a usam precisarão migrar para a API padrão. Neste artigo, explicamos como migrar seu código e o que fazer se você precisar de mais tempo para fazer essa alteração.

Historicamente, há duas versões concorrentes da API getStats() do WebRTC. A API getStats() legada, que é anterior ao processo de padronização e aceita um argumento de callback, e a API padronizada e amplamente compatível que retorna uma promessa.

A API padrão é mais repleta de recursos e tem métricas bem definidas e documentadas publicamente na especificação do W3C Identificadores para a API Statistics do WebRTC (em inglês). A especificação inclui descrições de cada métrica listada neste guia e muito mais.

No Chrome 117, a API getStats() legada gera uma exceção no canal de lançamento Stable. A geração da exceção será lançada gradualmente. Siga este guia e facilite a transição para a API padrão.

Tipos de estatísticas legados versus padrão

A lista completa dos tipos de estatísticas padrão pode ser encontrada no enum RTCStatsType na especificação. Isso inclui a definição do dicionário de estatísticas que descreve as métricas coletadas para cada tipo.

Todos os objetos de estatísticas têm um atributo de ID que identifica exclusivamente o objeto subjacente em várias chamadas de getStats(). O mesmo objeto terá o mesmo ID sempre que o método for chamado. Isso é útil para calcular a taxa de mudança de métricas (há um exemplo na próxima seção). Os IDs também formam relações de referências. Por exemplo, o objeto de estatísticas outbound-rtp faz referência ao objeto de estatísticas media-source associado usando o atributo outbound-rtp.mediaSourceId. Ao desenhar todas as relações ...Id, você recebe um gráfico.

A API legada tem os seguintes tipos de estatísticas, que correspondem aos tipos padrão da seguinte forma:

Mapeamento de métricas legadas para padrão

O objetivo desse mapeamento é ajudar os desenvolvedores a descobrir qual métrica legada corresponde a qual métrica padrão. No entanto, a métrica correspondente pode usar unidades diferentes ou ser expressa como um contador total em vez de um valor instantâneo. Consulte a especificação para definições de métrica.
A API padrão prefere expor o total de contadores em vez de taxas. Isso significa que, para conseguir a taxa correspondente (por exemplo, taxa de bits), como na API legada, o app precisa calcular a taxa média usando o delta entre duas chamadas getStats(). Exemplo:

// Periodically (e.g. every second or every 10 seconds)...
const currReport = await pc.getStats();
// Calculate bitrate since the last getStats() call.
// Handling of undefined is omitted for clarity.
const currOutboundRtp = currReport.values().find(s => s.type == 'outbound-rtp');
const prevOutboundRtp = prevReport.get(currOutboundRtp.id);
const deltaBits = (currOutboundRtp.bytesSent - prevOutboundRtp.bytesSent) * 8;
const deltaSeconds = (currOutboundRtp.timestamp - prevOutboundRtp.timestamp) / 1000;
logBitrateMeasurement(deltaBits / deltaSeconds);
// Remember the report for next time.
prevReport = currReport;

Calcular as taxas e médias dessa forma pode parecer uma etapa adicional complicada, mas permite que você obtenha médias em qualquer intervalo de tempo desejado. Chamar a API padrão com menos frequência do que com a API legada gera alguns benefícios de desempenho.

A API padrão reconhece transmissões simultâneas

Se você usa a transmissão simultânea, pode ter notado que a API legada só informa um único SSRC, mesmo quando você a usa para enviar (por exemplo) três streams de RTP em três SSRCs separados.

A API padrão não compartilha essa limitação e retorna três objetos de estatísticas outbound-rtp, um para cada um dos SSRCs. Isso significa que é possível analisar cada stream de RTP individualmente, mas também é necessário agregar todos eles para conseguir a taxa de bits total de todos os streams de RTP.

Por outro lado, os streams SVC ou RTP com várias camadas espaciais configuradas pela API scalabilityMode ainda aparecem como um único outbound-rtp porque são enviados por um único SSRC.

Se você precisar de mais tempo para a migração

Quando a API legada for removida no Chrome 117, o uso dela vai gerar uma exceção. Se você não conseguir migrar seu código a tempo, o teste de origem da API getStats() baseada em callback do RTCPeerConnection oferecerá mais tempo para a migração dos sites registrados. Com um token de teste de origem, a API getStats() legada pode continuar sendo usada até o Chrome 121.