webrtcperf

WebRtcPerf é uma ferramenta de código aberto projetada para testar serviços WebRTC com múltiplas conexões de clientes simultâneas, medindo as estatísticas RTC mais importantes e coletando-as de forma fácil.

GitHub

223

Experimente este MCPPatrocinado

Documentação

WebRtcPerf

Página no GitHub | Documentação

WebRtcPerf é uma ferramenta de código aberto projetada para testar serviços WebRTC com múltiplas conexões de clientes simultâneas, medindo as estatísticas de RTC mais importantes e coletando-as de forma fácil. Esta documentação abordará seus diversos recursos e opções de configuração, mostrando como aproveitar esta ferramenta para obter insights valiosos sobre suas soluções de comunicação em tempo real.

Pré-requisitos e instalação

A ferramenta webrtcperf é um aplicativo NodeJS que inicia múltiplos navegadores headless Puppeteer que realmente iniciarão as conexões WebRTC, portanto, idealmente, pode ser executada em qualquer plataforma onde NodeJS e o navegador Chromium possam ser executados. De qualquer forma, para aproveitar alguns recursos específicos, o uso de um sistema operacional Linux é a forma sugerida de usar a ferramenta. Se você planeja executar múltiplas conexões simultâneas para um host externo que executa o serviço WebRTC, você precisa garantir que sua máquina tenha largura de banda de rede suficiente para enviar e receber os fluxos de áudio/vídeo sem afetar a qualidade, além de uma quantidade de CPU e memória proporcional ao número de clientes que deseja iniciar. De qualquer forma, você também pode usar uma máquina limitada para esse fim, a fim de avaliar como o servidor WebRTC e o cliente reagem ao ambiente restrito. Considere também que a ferramenta usa o framework Traffic Controller (TC) no Linux para aplicar restrições de rede e alterá-las durante a execução dos testes.

O comando para instalar a ferramenta:

npm install -g @vpalmisano/webrtcperf
webrtcperf --help

Certifique-se de ter o FFMpeg instalado na mesma máquina.

Alternativamente, use a imagem Docker pré-construída:

docker pull ghcr.io/vpalmisano/webrtcperf:devel
docker run -it ghcr.io/vpalmisano/webrtcperf:devel --help

A ferramenta também pode ser usada a partir do código-fonte:

git clone https://github.com/vpalmisano/webrtcperf.git
cd webrtcperf
yarn build
yarn start --help

Uso da linha de comando

Os argumentos da linha de comando podem ser fornecidos explicitamente usando o formato snake case minúsculo (ex.: --run-duration=) ou definindo a variável de ambiente correspondente no formato snake case maiúsculo (RUN_DURATION=). Os parâmetros da linha de comando têm precedência sobre as variáveis de ambiente correspondentes. Alternativamente, é possível carregar as variáveis de configuração salvas em lower camel case em um arquivo local JSON/JSON5, YAML ou TOML; o arquivo também pode ser armazenado remotamente e carregado usando sua URL HTTP pública.
Exemplo executando um cenário simples com demo do Mediasoup:

webrtcperf https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/scenarios/mediasoup.json

Pare a ferramenta pressionando q (fechamento normal do navegador) ou x (encerrará o processo imediatamente).

Usando a ferramenta para executar testes simples

Vamos começar executando alguns cenários de teste simples com apenas 2 participantes. Os argumentos da linha de comando necessários para entrar em uma sala pública do Google Meet são:

webrtcperf \
  --sessions=1 \
  --run-duration=600 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js

Em particular, os argumentos obrigatórios são:

--sessions: o número total de sessões do navegador chromium que desejamos iniciar.
--run-duration: a duração da execução do teste em segundos.
--url: a URL remota que desejamos visitar.

Outros argumentos necessários para entrar em uma sala do Google Meet:

--debugging-port: definido com um valor diferente de zero para desabilitar o recurso webdriver (https://issues.chromium.org/issues/40746300).
--script-path: injeta um código javascript na página em execução. Aceita uma lista separada por vírgulas de caminhos de arquivos locais ou URLs http. Neste caso, o código preenche automaticamente o nome de usuário e entra na sala.

Por padrão, a ferramenta emitirá periodicamente algumas métricas obtidas dos objetos RTC PeerConnection em execução. As métricas são agregadas em todas as sessões em execução, mostrando a soma (quando faz sentido), média, desvio padrão, percentis 5º e 95º, valores mínimos e máximos.

-- Wed, 04 Jun 2025 11:04:30 GMT -------------------------------------------------------------------
                          name    count      sum     mean   stddev       5p      95p      min      max
                    System CPU        1             10.20     0.00    10.20    10.20    10.20    10.20 %
                    System GPU        1             22.00     0.00    22.00    22.00    22.00    22.00 %
                 System Memory        1             33.64     0.00    33.64    33.64    33.64    33.64 %
                      CPU/page        1    92.29    92.29     0.00    92.29    92.29    92.29    92.29 %
                   Memory/page        1  2021.88  2021.88     0.00  2021.88  2021.88  2021.88  2021.88 MB
                         Pages        1        1        1        0        1        1        1        1
                        Errors        1        0        0        0        0        0        0        0
                      Warnings        1        0        0        0        0        0        0        0
              Peer Connections        1        1        1        0        1        1        1        1
-- Inbound audio -----------------------------------------------------------------------------------
-- Inbound video -----------------------------------------------------------------------------------
-- Outbound audio ----------------------------------------------------------------------------------
                          rate        1    73.81    73.81     0.00    73.81    73.81    73.81    73.81 Kbps
                          lost        1              0.00     0.00     0.00     0.00     0.00     0.00 %
                 roundTripTime        1             0.033    0.000    0.033    0.033    0.033    0.033 s
-- Outbound video ----------------------------------------------------------------------------------
                          sent        1     2.62     2.62     0.00     2.62     2.62     2.62     2.62 MB
                          rate        1  1209.16  1209.16     0.00  1209.16  1209.16  1209.16  1209.16 Kbps
                          lost        1              0.00     0.00     0.00     0.00     0.00     0.00 %
                 roundTripTime        1             0.000    0.000    0.000    0.000    0.000    0.000 s
 qualityLimitResolutionChanges        1        0        0        0        0        0        0        0
          qualityLimitationCpu        1        0        0        0        0        0        0        0 %
    qualityLimitationBandwidth        1        0        0        0        0        0        0        0 %
                         width        1              1280        0     1280     1280     1280     1280 px
                        height        1               720        0      720      720      720      720 px
                           fps        1                25        0       25       25       25       25 fps
              firCountReceived        1                 0        0        0        0        0        0
              pliCountReceived        1                 0        0        0        0        0        0

As métricas acima representam:

CPU/GPU/Memória do sistema: a % de CPU, GPU e memória RSS do sistema usada (variando de 0 a 100%).
CPU/página: a quantidade de % de CPU usada por cada processo chromium, incluindo todos os processos filhos (variando de 0 a N00% dependendo do número de núcleos de CPU disponíveis).
Memória/página: a memória RSS usada por cada processo chromium, incluindo todos os processos filhos.
Páginas: o número de páginas abertas (deve corresponder ao valor --sessions fornecido).
Erros, Avisos: o número cumulativo de erros e logs de aviso coletados por cada página.
Conexões de Pares: o número de objetos RTC Peer Connection conectados em execução em cada página.
taxa: a taxa de bits de entrada/saída.
perdidos: a % de pacotes perdidos.
roundTripTime: o valor do Tempo de Ida e Volta.
qualityLimitResolutionChanges: a contagem de eventos de limitação de qualidade.
qualityLimitationCpu, qualityLimitationBandwidth: a % de tempo em que o remetente executou com limitação de qualidade.
largura, altura, fps: a resolução e taxa de quadros atuais enviadas.
firCountReceived, pliCountReceived: contam o número de FIR/PLI (keyframe) solicitados àquele remetente.

Vamos ver o que acontece quando começamos a aumentar o número de sessões, introduzindo mais participantes na mesma sala (--sessions=2):

-- Wed, 04 Jun 2025 11:34:00 GMT -------------------------------------------------------------------
                          name    count      sum     mean   stddev       5p      95p      min      max
                    System CPU        2             18.92     0.00    18.92    18.92    18.92    18.92 %
                    System GPU        2              0.00     0.00     0.00     0.00     0.00     0.00 %
                 System Memory        2             33.98     0.00    33.98    33.98    33.98    33.98 %
                      CPU/page        2   370.03   185.01     1.91   183.10   186.93   183.10   186.93 %
                   Memory/page        2  3914.67  1957.34    10.50  1946.84  1967.83  1946.84  1967.83 MB
                         Pages        2        2        1        0        1        1        1        1
                        Errors        2        0        0        0        0        0        0        0
                      Warnings        2        0        0        0        0        0        0        0
              Peer Connections        2        2        1        0        1        1        1        1
-- Inbound audio -----------------------------------------------------------------------------------
                          rate        2    89.64    44.82     0.02    44.80    44.83    44.80    44.83 Kbps
                          lost        2              0.00     0.00     0.00     0.00     0.00     0.00 %
                        jitter        2              0.00     0.00     0.00     0.00     0.00     0.00 s
          avgJitterBufferDelay        2             65.87    13.25    52.62    79.12    52.62    79.12 ms
-- Inbound video -----------------------------------------------------------------------------------
                      received        2    12.93     6.47     0.01     6.46     6.48     6.46     6.48 MB
                          rate        2  2985.18  1492.59    15.29  1477.30  1507.88  1477.30  1507.88 Kbps
                          lost        2              0.00     0.00     0.00     0.00     0.00     0.00 %
                        jitter        2              0.01     0.00     0.01     0.01     0.01     0.01 s
          avgJitterBufferDelay        2             52.64     4.28    48.36    56.92    48.36    56.92 ms
                         width        2              1280        0     1280     1280     1280     1280 px
                        height        2               720        0      720      720      720      720 px
                           fps        2                25        0       24       25       24       25 fps
-- Outbound audio ----------------------------------------------------------------------------------
                          rate        2   154.32    77.16     0.01    77.15    77.17    77.15    77.17 Kbps
                          lost        2              0.00     0.00     0.00     0.00     0.00     0.00 %
                 roundTripTime        2             0.032    0.001    0.031    0.033    0.031    0.033 s
-- Outbound video ----------------------------------------------------------------------------------
                          sent        2    13.72     6.86     0.03     6.83     6.90     6.83     6.90 MB
                          rate        2  2986.60  1493.30    15.40  1477.91  1508.70  1477.91  1508.70 Kbps
                          lost        2              0.00     0.00     0.00     0.00     0.00     0.00 %
                 roundTripTime        2             0.032    0.001    0.031    0.033    0.031    0.033 s
 qualityLimitResolutionChanges        2        0        0        0        0        0        0        0
          qualityLimitationCpu        2        0        0        0        0        0        0        0 %
    qualityLimitationBandwidth        2        0        0        0        0        0        0        0 %
                         width        2              1280        0     1280     1280     1280     1280 px
                        height        2               720        0      720      720      720      720 px
                           fps        2                25        0       25       25       25       25 fps
              firCountReceived        2                 0        0        0        0        0        0
              pliCountReceived        2                 0        0        0        0        0        0

Como podemos ver na saída do comando, agora temos count=2 para todas as métricas e começamos a notar algumas diferenças entre os valores de soma, média, mínimo, máximo e percentis.

Enviando estatísticas para o Prometheus

Coletar e analisar as métricas usando a saída do console de comando pode ser uma tarefa difícil, especialmente quando aumentamos o número de sessões. Para esse fim, o webrtcperf permite enviar os valores das métricas para um serviço externo Prometheus/Grafana, através de um serviço Pushgateway. Um exemplo de configuração docker compose para executar todos os serviços necessários está disponível em https://github.com/vpalmisano/webrtcperf/tree/devel/prometheus-stack.
Supondo que o serviço Pushgateway esteja em execução em localhost:9091, o parâmetro adicional a incluir na linha de comando é: --prometheus-pushgateway=http://localhost:9091
Se o servidor Pushgateway estiver protegido por credenciais de nome de usuário e senha, basta adicionar o parâmetro --prometheus-pushgateway-auth=username:password.
Além disso, podemos alterar a tag job=default do Prometheus usando o parâmetro --prometheus-pushgateway-job-name=custom-tag; dessa forma, podemos diferenciar facilmente as métricas provenientes de diferentes ou concorrentes execuções de teste.

Visitando o serviço Grafana iniciado com o docker compose anterior, é possível acessar o dashboard de exemplo, mostrando uma série de métricas coletadas pelo webrtcperf:

Uso avançado

Opções de URL

Nos exemplos anteriores, usamos a opção --url para definir uma URL de destino da página que é usada por todas as sessões em execução. A ferramenta tem outras duas opções para personalizar a URL de destino:

--url-query: Permite especificar uma string de consulta de URL adicional que será anexada ao --url fornecido. A string pode incluir algumas variáveis de modelo que serão substituídas em tempo de execução:
- $p o pid do processo
- $s o índice da sessão
- $S o total de sessões
- $t o índice da aba
- $T o total de abas por sessão
- $i o índice absoluto da aba
Exemplo: --url-query=”participantName=Test-$i” anexará ?participantName=Test-0, ?participantName=Test-1 à URL da sessão correspondente.
--custom-url-handler: Esta opção aceita um caminho de módulo javascript contendo uma única função exportada que será invocada para cada sessão iniciada. Use esta opção sem definir a opção --url.
A função será invocada com um único objeto com as seguintes propriedades:
- sessions: o número total de sessões;
- tabsPerSession: o número total de abas por sessão;
- id: o índice global da sessão (baseado em 0);
- index: o índice global da aba (baseado em 0);
- tabIndex: o índice da aba na sessão atual (baseado em 0);
- pid: o pid do processo;
- env: o objeto de variáveis de ambiente;
- params: o objeto de parâmetros do script.
  
  Exemplo de script:
```
export default function ({ id, sessions, tabIndex, tabsPerSession, index, env, pid }) {
  return `https://example.com/${id}/${sessions}/${tabIndex}/${tabsPerSession}/${index}/${pid}`
}
```

As opções de entrada do getUserMedia

A ferramenta aproveita várias opções oferecidas pelo chromium para especificar um arquivo de entrada de áudio/vídeo que será usado como fonte do getUserMedia. Usar áudio e vídeo falsos nos permite executar testes consistentes e repetíveis, sem introduzir a aleatoriedade implícita que seria causada pela execução de testes com entradas locais de webcam/microfone.
A ferramenta permite configurar as seguintes opções:

--video-path: Um caminho de arquivo usado como fonte para os fluxos de áudio e vídeo. O FFMpeg será usado para converter este arquivo em um formato aceito pelas opções do chromium, portanto, qualquer formato de entrada aceito pelo ffmpeg é um valor válido (ex.: https://…). Além disso, usar generate:null gerará um vídeo preto e uma faixa de áudio silenciosa; com generate:test gerará um padrão de vídeo testsrc do ffmpeg e um áudio de frequência única com padrão de bipe. A opção é definida por padrão para este vídeo de teste https://github.com/vpalmisano/webrtcperf/releases/download/videos-1.0/kt.mp4. Mais vídeos de teste estão disponíveis sob esta tag de versão: https://github.com/vpalmisano/webrtcperf/releases/tag/videos-1.0.
--video-width, --video-height, --video-framerate: a resolução e a taxa de quadros de vídeo que serão usadas para aumentar ou reduzir a escala do vídeo de entrada.
--video-seek: o tempo de busca em segundos a partir do início no vídeo fornecido.
--video-duration: a duração total usada para cortar o vídeo de entrada.
--video-cache-raw: quando verdadeiro (valor padrão), os arquivos gerados serão armazenados em cache no diretório ~/.webrtcperf/cache.
--video-format: o formato de vídeo usado para a conversão da faixa de vídeo; pode ser "y4m" (vídeo yuv bruto, o valor padrão) ou "mjpeg".
--use-fake-media:
- quando verdadeiro (padrão), o arquivo fornecido especificado com videoPath será convertido em arquivos de áudio e vídeo brutos que serão passados ao executável do chromium usando os parâmetros use-fake-ui-for-media-stream, use-file-for-fake-video-capture e use-file-for-fake-audio-capture. As chamadas getUserMedia emitirão faixas geradas a partir dos arquivos brutos fornecidos.
- Quando falso, o navegador será executado sem qualquer opção de mídia falsa, mas o script de página padrão do webrtcperf substituirá a chamada getUserMedia carregando um elemento de vídeo oculto dentro da página e usando-o como fonte para as faixas geradas. A vantagem de usar esta abordagem é que as faixas de áudio e vídeo serão executadas em sincronia, portanto, pode ser usada para detectar dessincronização de áudio/vídeo; a desvantagem é o maior uso de memória e CPU da página causado pela decodificação da mídia falsa.

As opções de entrada do getDisplayMedia

O comportamento padrão do chromium para falsificar a faixa de mídia de exibição permite obter uma animação de vídeo gerada que geralmente é muito diferente do que temos em uma videoconferência regular quando os usuários compartilham uma apresentação estática com transições de slides. Na verdade, a animação gerada pelo chromium produz um fluxo de taxa de bits constante, enquanto uma apresentação real gera uma taxa de bits baixa em média com grandes picos causados pelas transições de slides. Emular esse comportamento é essencial para avaliar a qualidade de vídeo do compartilhamento de tela em um serviço de videoconferência.
No webrtcperf, as chamadas getDisplayMedia emitirão uma faixa de vídeo obtida do compartilhamento da janela atual do navegador (quando --use-fake-media=true) ou de uma nova aba do navegador (--use-fake-media=false). Em ambos os casos, a ferramenta usará uma automação de script de página que gera uma sequência falsa de compartilhamento de tela que pode ser personalizada adicionando uma opção fakeScreenshare na opção de linha de comando --script-params. A opção fakeScreenshare aceita os seguintes parâmetros:

animationDuration: a duração da animação do slide expressa em milissegundos (padrão: 1000).
delay: o atraso de troca de slide em milissegundos (padrão: 5000).
embed: uma URL opcional especificando um documento ou uma apresentação externa do Google Drive que será carregada dentro de um elemento iframe.
width, height: a resolução do compartilhamento de tela (padrão: 1920x1080)
pointerAnimation: se diferente de zero, desenhará uma animação aleatória simulando o movimento do mouse.
slides: o total de slides a gerar (padrão: 4).
urls: um array opcional de strings que pode incluir (mesmo em ordem mista):
- uma URL de imagem ou vídeo que será usada como conteúdo do slide;
- um documento que será incorporado em um elemento iframe e será usado como conteúdo do slide.
  
  Quando tanto slides quanto embed não forem fornecidos, a ferramenta carregará as imagens de https://picsum.photos.

Limitação de rede (Network throttling)

A largura de banda disponível na Internet, a latência da rede e a perda de pacotes são fatores que geralmente podem impactar a qualidade percebida de um serviço de videoconferência. Replicar as condições de rede que afetam usuários reais é geralmente uma boa maneira de avaliar se o serviço WebRTC é capaz de se adaptar à largura de banda disponível (aumentando ou diminuindo a resolução do vídeo e a taxa de quadros) e lidar com a perda de pacotes e o atraso.
A ferramenta webrtcperf inclui uma funcionalidade de limitação de rede oferecida pelo projeto https://github.com/vpalmisano/throttler, que é essencialmente um wrapper NodeJS do framework Linux Traffic Controller (https://tldp.org/HOWTO/Traffic-Control-HOWTO/intro.html) e NetEm. O parâmetro --throttle-config aceita uma string codificada em JSON/JSON5 contendo um array de configuração de throttler; cada item de configuração é um objeto contendo as seguintes propriedades:

sessions (string): Os IDs das sessões webrtcperf que usarão esta configuração de throttling. Pode ser um único índice ("0"), um intervalo ("0-2") ou uma lista separada por vírgulas ("0,3,4").
up, down (string, JSON): Uma única regra ou um array de regras de throttling que serão aplicadas ao uplink e ao downlink.
protocol ("udp" | "tcp"): Se especificado, apenas pacotes TCP ou UDP serão limitados.
device (string): A interface de rede a ser limitada. Se não especificada, a interface padrão será usada.
filter (string): Uma regra adicional de filtro de pacotes IPTables.
match (string): Uma expressão de correspondência TC adicional usada para filtrar pacotes.
skipSourcePorts, skipDestinationPorts (string): Uma lista separada por vírgulas de portas de origem e destino que não serão limitadas. Exemplo de uso: em alguns casos, é melhor evitar limitar as portas 80,443, caso contrário, o aplicativo web falhará ao carregar.
capture (string): Se definido, os pacotes que correspondem à sessão e protocolo fornecidos serão capturados nesse local de arquivo no formato PCAP.

Cada regra de throttling pode incluir as seguintes propriedades que controlam o valor correspondente na ferramenta NetEm:

rate: A largura de banda disponível (Kbps).
delay: O atraso de ida (ms).
delayJitter: O jitter de atraso de ida (ms).
delayJitterCorrelation: A correlação do jitter de atraso de ida.
delayDistribution: A distribuição do atraso ('uniform' | 'normal' | 'pareto' | 'paretonormal').
reorder: A porcentagem de reordenação de pacotes.
reorderCorrelation: A correlação de reordenação de pacotes.
reorderGap: O intervalo de reordenação de pacotes.
loss: A porcentagem de perda de pacotes.
lossBurst: A rajada de perda de pacotes.
queue: O tamanho da fila de pacotes.
at: Se definido, a regra será aplicada após o número especificado de segundos.

Exemplos
Execute uma videoconferência com dois participantes no Google Meet, limitando o uplink do primeiro participante a 500Kbps, com atraso de 100ms e 2% de perda de pacotes:

webrtcperf \
  --sessions=2 \
  --run-duration=300 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js \
  --prometheus-pushgateway=http://localhost:9091 \
  --throttle-config='[{sessions:"0",protocol:"udp",up:[{rate:500,delay:100,loss:2,queue:50}]}]'

O stream de vídeo “Participant-000000” tem uma qualidade visivelmente inferior em comparação com “Participant-000001”:

Comparando a mesma execução de teste sem e com a opção de throttling de rede, podemos ver como a taxa de bits enviada diminuiu de uma média de ~600Kbps para ~300Kbps; a perda de pacotes aumentou para 1-2% e o tempo de ida e volta aumentou de ~40ms para ~150ms:

Vamos executar outro teste com uma configuração de throttling diferente. Neste caso, especificamos múltiplas regras para a limitação do uplink, usando um valor diferente de at para cada uma; em particular, o que queremos testar é:

começar aplicando uma limitação de taxa de bits de 1Mbps;
após 60 segundos, alterar a limitação de taxa de bits para 500Kbps;
após 60 segundos, definir a taxa de bits novamente para 1Mbps.

webrtcperf \
  --sessions=2 \
  --run-duration=300 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js \
  --prometheus-pushgateway=http://localhost:9091 \
  --throttle-config='[{   
      sessions:"0",   
      protocol:"udp",   
      up: [     
        { rate:1000, delay:100, queue:50 },
        { rate:500, delay:100, queue:50, at:60 },     
        { rate:1000, delay:100, queue:50, at:120 },
      ] 
    }]'

Observando as métricas medidas, vemos o efeito da mudança de limitação de largura de banda:

a taxa de bits do vídeo diminuiu de 600Kbps para 300Kbps de t=60 a t=120;
tivemos alguma perda de pacotes após a diminuição da largura de banda;
o indicador de limitação de qualidade de largura de banda aumentou para ~80% no mesmo intervalo de tempo.

Simulação de orador aleatório

Usar um arquivo de mídia falso com fala contínua quando executamos testes com múltiplos participantes não se aproxima do que acontece em uma sala de videoconferência real, onde os participantes geralmente falam em turnos sem sobreposição. A automação de página do webrtcperf permite ativar/desativar automaticamente as faixas de áudio capturadas com getUserMedia alterando a propriedade track.enabled; o mecanismo pode ser controlado com as seguintes opções de linha de comando:

--random-audio-period: Especifica o período máximo em segundos após o qual uma nova sessão ativa aleatória é selecionada, habilitando as faixas de áudio getUserMedia nessa sessão e desabilitando todas as outras.
--random-audio-probability: define a probabilidade % de que o áudio selecionado seja ativado (padrão: 100%). Definir esse valor para um valor menor que 100 terá o efeito de desativar o áudio para todas as sessões.
--random-audio-range: Define os índices de sessão que devem ser incluídos no mecanismo de seleção aleatória (padrão: incluir todas as sessões).

Além da propriedade track.enabled, a ferramenta invocará a função publisherSetMuted(true | false), se essa função tiver sido implementada em um script de página personalizado (carregado com --script-path); dessa forma, é possível acionar o estado mudo clicando no botão correspondente de mudo/desmutar dentro da página, dependendo do serviço específico que estamos testando.

Usando a compilação personalizada do Chromium para economizar CPU

Executar testes com muitos participantes aumenta a quantidade de CPU necessária para renderizar a página, codificar os streams de áudio/vídeo e decodificá-los no lado do receptor. A imagem docker do webrtcperf inclui uma versão modificada do Chromium que permite à ferramenta especificar um número máximo de streams de vídeo RTC para decodificar em paralelo para cada sessão do navegador. O valor pode ser controlado usando as seguintes opções de linha de comando:

--max-video-decoders: O número máximo de streams de vídeo RTC que serão decodificados por cada sessão do navegador (padrão: 0, decodificar todos os vídeos).
--max-video-decoders-range: Aplica a opção de máximo de decodificadores de vídeo às sessões incluídas nesta lista (padrão: “true” que incluirá todas as sessões).

Vale notar que desabilitar a decodificação do stream de vídeo fará com que algumas métricas RTC (por exemplo, largura, altura, taxa de quadros recebidas) sempre reportem um valor zero. A maneira sugerida de usar esse recurso é manter o decodificador de vídeo habilitado para uma porcentagem de sessões, dependendo da quantidade de CPU que se deseja economizar.
A versão modificada do Chromium pode ser compilada a partir do código-fonte usando os seguintes comandos:

git clone https://github.com/vpalmisano/webrtcperf.git
cd webrtcperf/chromium
./build.sh setup
 # Use a valid tag version
./build.sh update "tags/139.0.7230.1"
./build.sh build 
# install the package (on Ubuntu/Debian)
sudo dpkg -i ./chromium-browser-unstable_139.0.7230.1-1_amd64.deb

Depois que o pacote personalizado do Chromium for instalado, especifique o caminho do executável com a opção --chromium-path (ou definindo a variável de ambiente CHROMIUM_PATH):

export CHROMIUM_PATH=/usr/bin/chromium-browser-unstable
webrtcperf https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/scenarios/mediasoup.json

Opções adicionais de registro (logging)

A ferramenta oferece várias opções de registro para salvar os logs das páginas abertas e, opcionalmente, a saída completa do processo do Chromium.

--show-page-log: Se verdadeiro (padrão), os logs do console das páginas serão exibidos no console.
--page-log-filter: Se definido, apenas os logs com o texto ou expressão regular correspondente serão impressos no console.
--page-log-path: Se definido, os logs do console da página serão salvos no caminho de arquivo selecionado.
--enable-browser-logging: Habilita o registro do navegador Chromium para os índices de sessão especificados. Requer que a opção --page-log-path esteja definida. Quando habilitado, a ferramenta ativará o registro verboso do Chromium (com --vmodule=*/webrtc/*=5) que será gravado no diretório do caminho de log da página. Também ativa a opção --webrtc-event-logging do Chromium, que salvará o arquivo de registro de eventos no mesmo diretório (você pode usar https://github.com/fippo/dump-webrtc-event-log para analisar este arquivo).

A automação de script

Nos exemplos anteriores, usamos a opção --script-path fornecendo uma página javascript que executa alguma automação de página (como preencher automaticamente o nome do participante e clicar no botão de entrar). Por padrão, a ferramenta webrtcperf carregará o pacote de script webrtcperf-js, que fornece várias utilidades para automatizar as tarefas de teste e executar medições avançadas no contexto da página. O script personalizado fornecido com a opção --script-path pode acessar as utilidades webrtcperf-js sob o objeto global webrtcperf. Alguns dos recursos oferecidos pelo webrtcperf-js precisam ser configurados no momento do carregamento da página; para esse fim, o webrtcperf oferece a opção --script-params que pode ser usada para fornecer um objeto JSON/JSON5 com os valores que serão definidos no objeto webrtcperf.params.

Medindo o atraso de ponta a ponta (boca-a-ouvido)

Definir os parâmetros de script timestampWatermarkAudio e timestampWatermarkVideo habilitará um recurso do webrtcperf-js que aplica automaticamente uma sobreposição de marca d'água de vídeo e um sinal de áudio modulado contendo o timestamp UNIX do remetente. No lado do receptor, a sobreposição de vídeo será reconhecida usando a biblioteca Tesseract.js, enquanto o sinal de áudio será decodificado com a biblioteca ggwave. Subtraindo o valor decodificado do timestamp UNIX no lado do receptor, obteremos o atraso total de ponta a ponta que ocorre desde o momento da captura do quadro de áudio/vídeo até o momento da exibição (observe que os relógios das máquinas do remetente e do receptor precisam estar sincronizados, caso contrário, introduziremos um erro na estimativa do atraso).
Exemplo de uso:

webrtcperf \
  --sessions=2 \
  --run-duration=300 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --prometheus-pushgateway=http://localhost:9091 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js \
  --script-params='{timestampWatermarkAudio:true,timestampWatermarkVideo:true}'

Medindo o atraso de ponta a ponta da rede usando a extensão abs-capture-time

A biblioteca webrtcperf-js vem com outro mecanismo que pode ser usado para estimar o atraso de ponta a ponta da rede. Definindo o parâmetro de script absCaptureTime, a biblioteca modificará a oferta SDP inserindo a extensão de cabeçalho abs-capture-time (https://datatracker.ietf.org/doc/draft-ietf-avtcore-abs-capture-time/) para as seções de mídia de áudio e vídeo. Se o SFU suportar esse cabeçalho de extensão, o lado do receptor receberá o valor captureTimestamp na fonte contribuinte correspondente. Considere também que alguns aplicativos de videoconferência (por exemplo, Google Meet) já usam esse cabeçalho, então você não precisa adicionar nenhum parâmetro de script para obter a medição.
O código usado para calcular o atraso é o seguinte:

const contributingSource = receiver.getSynchronizationSources()[0]
const captureTimestamp = contributingSource?.captureTimestamp
const senderCaptureTimeOffset = contributingSource?.senderCaptureTimeOffset

if (contributingSource && captureTimestamp && senderCaptureTimeOffset !== undefined) {
  endToEndDelay = (contributingSource.timestamp - (captureTimestamp + senderCaptureTimeOffset - 2208988800000)) / 1000
}

Como podemos ver, o atraso é calculado como a diferença de tempo entre o timestamp atual e o timestamp de captura, usando o deslocamento de tempo para compensar a diferença de relógio entre as máquinas do remetente e do receptor; tanto a captura quanto o deslocamento são baseados no tempo NTP (meia-noite UTC de 1º de janeiro de 1900), então precisamos rebaseá-los para o tempo inicial UNIX (meia-noite UTC de 1º de janeiro de 1970).
O atraso de ponta a ponta calculado com a extensão abs-capture-time em um teste do Google Meet (métricas audioEndToEndDelay e videoEndToEndDelay):
A vantagem de usar esta opção é que ela não requer nenhuma marca d'água de áudio ou vídeo, e economizará alguma CPU no lado do receptor necessária para executar o reconhecimento de imagem. De qualquer forma, este método leva em consideração apenas o atraso unidirecional do RTP no caminho da rede; se você quiser obter um atraso mais preciso, deve adicionar os valores das métricas de codificação (videoEncodeLatency) e decodificação (videoDecodeLatency) ao valor de videoEndToEndDelay.

Executar automações de página

Definir o valor dos parâmetros de script actions nos permite executar várias tarefas de página em momentos diferentes, a partir do horário de lançamento do webrtcperf. Cada objeto de ação pode incluir as seguintes propriedades:

name (string): o método javascript a ser chamado (deve ser um método exportado globalmente).
params (array): os argumentos do método.
index (string): os índices de sessão do webrtcperf onde a ação deve ser executada.
at (number): o número de segundos desde o início do teste em que a ação deve ser executada. Se o carregamento da página levar mais tempo do que “at” segundos, a execução da ação é ignorada.
relaxedAt (number): use este em vez da propriedade “at” se quiser executar a ação mesmo que o tempo agendado seja maior que o tempo decorrido.
every (number): se definido, a ação será executada em intervalos regulares.
times (number): o número de vezes que a ação deve ser executada.

Exemplo: supondo que você tenha definido uma função personalizada muteParticipant para silenciar/reativar o microfone, use estas ações de script para silenciar “Participant-000000” após 60 segundos e reativá-lo após 180 segundos a partir do horário de início do teste:

webrtcperf \
  --sessions=2 \
  --run-duration=300 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --prometheus-pushgateway=http://localhost:9091 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js \
  --script-params='{
      actions: [
        { name: "muteParticipant", params: [true], index: "0", at: 60 },
        { name: "muteParticipant", params: [false], index: "0", at: 180 },
      ]
    }'

A taxa de bits de áudio enviada por Participant-000000 relata um período vazio no período de mudo:

As taxas de bits de áudio recebidas por Participant-000001 refletem o período de pausa do áudio:

Modificadores de resposta de página

Usando a opção --response-modifiers, é possível executar uma substituição de string em uma ou mais solicitações HTTP feitas pela página (incluindo XHR, assets, etc.). Ela aceita um objeto JSON com o padrão de URL da solicitação e uma lista de uma ou mais substituições desejadas.
Exemplos:

Execute uma substituição de string em cada solicitação *.js feita à URL selecionada:
{ "https://url.com/*.js": [{ search: "searchString": replace: "anotherString" }] }
Substitua completamente a saída da solicitação por um arquivo local:
{ "https://url.com/file.js": [{ file: "path/to/newFile.js" }] }

Outra opção útil para depurar as solicitações de página é --download-reponses. Ela aceita uma matriz de padrões de URL que queremos salvar como arquivos locais. Por exemplo, salvar o download dos fragmentos mpegts do HLS enquanto assiste a uma transmissão ao vivo exigirá algo assim:
[{ urlPattern: "https://url.com/*.ts", output: "save/directory" }]

Cabeçalhos personalizados, CSS, cookies

--extra-headers: Especifique esta opção para adicionar cabeçalhos HTTP personalizados a cada solicitação. Exemplo:
{ "https://url.com/*": { "Authorization": "Bearer secret" } }
Ele anexará um cabeçalho “Authorization” para cada solicitação feita ao padrão de URL especificado.
--extra-css: Uma string contendo as regras CSS que serão injetadas dentro do conteúdo da página.
--cookies: Uma matriz de objetos JSON CookieParam ( https://pptr.dev/api/puppeteer.cookieparam) que serão definidos na página da web em execução.

Opções de depuração

A ferramenta aceita as seguintes opções que nos permitem acessar as páginas abertas do Chromium com o inspetor de devtools (chrome://inspect/#devices). Dessa forma, podemos acessar o contexto da página durante a execução do teste para depurar o aplicativo da web.
As opções que permitem configurar o depurador são:

--debugging-port: Se não for zero, habilitará o depurador do Chromium escutando na porta selecionada.
--debugging-address: O navegador Chromium permite escutar apenas no endereço 127.0.0.1, portanto, não é possível alcançar uma sessão em execução dentro de um contêiner docker ou em uma máquina remota. Quando esta opção é definida, o webrtcperf iniciará um encaminhador de porta permitindo que você se conecte ao protocolo devtool mesmo se a página estiver em execução remotamente.

Outras opções diversas que simplificam a depuração da página são:

--emulate-cpu-throttling: Quando diferente de zero, usará o recurso de limitação de CPU do devtools para limitar a execução do javascript da página, emulando um dispositivo lento.
--hardware-concurrency: Ele substitui a propriedade navigator.hardwareConcurrency. Alguns provedores de conferência web usam esta opção para inferir as capacidades da máquina e reduzir a resolução do vídeo e a taxa de quadros de acordo com o número de núcleos de CPU detectados.
--device-scale-factor: O fator de escala do dispositivo do navegador a ser usado (padrão: 1).
--user-agent: Uma string de user agent personalizada para usar.
--chromium-field-trials: Uma string de substituição de field trials do Chromium válida.
--local-storage e --session-storage: Um objeto JSON que será definido na página localStorage e sessionStorage no carregamento da página.
--override-permissions: Uma lista separada por vírgulas de permissões para conceder à página. Os valores possíveis estão listados aqui: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#directives.
--debug: Permite aumentar a verbosidade das mensagens de log da ferramenta. Veja https://github.com/commenthol/debug-level#readme para a sintaxe.

Regras de alerta

Após executar os testes, geralmente precisamos olhar as métricas coletadas na interface do Grafana ou diretamente dos logs de saída e inspecioná-las observando valores de perda de pacotes, baixa largura de banda ou resoluções, etc.
Webrtcperf vem com uma funcionalidade que tenta automatizar a inspeção de métricas e a detecção de falhas executando uma etapa de verificação de valores toda vez que as métricas são coletadas. As verificações de valores podem ser especificadas fornecendo uma string JSON válida para a opção --alert-rules contendo um único objeto com as métricas que queremos verificar com a definição da regra de alerta correspondente.

Exemplo 1: queremos verificar se a soma das conexões de pares ativas é igual a 100 após 1 minuto do início do teste.

--alert-rules='{
  pages: {
    tags: ["connectivity"],
    sum: { "$eq": 100, "$after": 60 },
  },
}'

Exemplo 2: queremos verificar se, após 2 minutos, o número de vídeos recebidos é igual a 25 e se o 5º percentil das taxas de bits recebidas está incluído na faixa de 2-3 Mbps.

--alert-rules='{
  videoRecvBitrates: {
    tags: ["quality"],
    length: { "$eq": 25, "$after": 120 },
    p5: { "$gt": 2000000, "$lt": 3000000, "$after": 120 },
  },
}'

A lista completa das métricas coletadas pelo webrtcperf está disponível aqui. As regras de métricas podem incluir estes especificadores:

length: o número de métricas realmente coletadas (por exemplo, o número de fluxos de vídeo);
sum: a soma dos valores das métricas;
min, max, mean, p5, p95: valores mínimo, máximo, 5º e 95º percentil.

As verificações de valores podem incluir:

$eq: o valor da métrica deve ser igual ao valor especificado;
$gt, $gte: o valor da métrica deve ser maior / maior ou igual ao valor;
$lt, $lte: menor / menor ou igual;
$after: a ferramenta começará a avaliar a regra após o valor fornecido em segundos;
$before: a ferramenta parará de avaliar a regra após o valor fornecido em segundos.

A regra opcional “tag” pode ser usada para agrupar a regra de teste em uma categoria personalizada. Se o --alert-rules-output for especificado, ao final do teste a ferramenta escreverá um arquivo JSON com os resultados do teste agrupados por tag de categoria, relatando a porcentagem de tempo em que as métricas verificadas em cada categoria falharam em corresponder às regras correspondentes. Você pode usar essa saída para acionar um alerta automatizado em um sistema de monitoramento sempre que os resultados do teste forem diferentes dos valores esperados. Além disso, para cada verificação de regra de alerta, a ferramenta adicionará uma métrica Prometheus _alert que pode ser usada para visualizar o limite de alerta no Grafana e relatar se a verificação da métrica está falhando ou não.

Exemplo 3: executando um teste com 2 participantes visitando uma página de demonstração do Mediasoup; o primeiro participante será executado com rede de downlink limitada (1Mbps, atraso de 100ms) e queremos verificar se a taxa de bits de vídeo recebida cai no intervalo de 400Kbps - 1Mbps:

mediasoup_r1000-d100.yaml configuração do cenário:

sessions: 2
runDuration: 300
url: 'https://v3demo.mediasoup.org/?roomId=webrtcperf-test-12345&displayName=Participant-$i'
debuggingPort: 9000
prometheusPushgateway: 'http://localhost:9091'
showPageLog: false
showStats: false
statsInterval: 5
throttleConfig: |
    [{
        sessions: "0",
        protocol: "udp",
        down: [
            { rate: 1000, delay: 100, queue: 50 },
        ]
    }]
alertRules: |
    {
        peerConnections: {
            tags: ["connectivity"],
            sum: { "$eq": 4, "$after": 30 },
        },
        videoRecvBitrates: {
            tags: ["quality"],
            length: { "$eq": 2, "$after": 30 },
            p5: { "$gt": 400000, "$lt": 1000000, "$after": 30 },
        },
    }
alertRulesOutput: 'results.json'

Comando de teste:

webrtcperf mediasoup_r1000-d100.yaml

Podemos ver a métrica do Grafana e o estado correspondente da regra de alerta; neste caso, o 5º percentil não corresponde aos valores esperados, então temos algumas falhas na verificação de alerta.

O conteúdo do results.json e o final do teste relatam uma porcentagem de falha de teste de 48%, com os detalhes sobre quantas vezes e a duração total em que a verificação falhou:

{
  "tags": {
    "connectivity": 0,
    "quality": 48
  },
  "reports": {
    "videoRecvBitrates p5 > 400000 and < 1000000 after 30s": {
      "totalFails": 18,
      "totalFailsTime": 50,
      "valueAverage": 419731.18521030556,
      "totalFailsTimePerc": 19,
      "failAmount": 48,
      "count": 54
    }
  }
}

Se alterarmos a regra de alerta videoRecvBitrates usando "$gt": 100000, as verificações do teste são bem-sucedidas em vez disso:

Avaliação de qualidade VMAF

Avaliar a qualidade do vídeo na maioria dos casos requer uma inspeção visual dos fluxos de saída procurando por artefatos, efeitos de desbloqueio, etc. Executar essa comparação de forma automatizada é preferível e permite que a infraestrutura de teste relate imediatamente um alerta quando a qualidade detectada não corresponder ao valor esperado ao executar o mesmo cenário de teste nas mesmas condições.
VMAF (Video Multimethod Assessment Fusion) é um algoritmo de avaliação perceptual de qualidade de vídeo desenvolvido pela Netflix (https://github.com/Netflix/vmaf). É uma métrica de referência completa, o que significa que requer tanto um vídeo de referência (original) quanto um vídeo distorcido (codificado) para avaliação. O VMAF visa prever a qualidade do vídeo combinando várias métricas em um único valor de pontuação (variando de 0 a 100). O VMAF foi projetado para avaliar a qualidade da codificação de vídeo assumindo que a versão distorcida do vídeo contém exatamente os mesmos quadros de vídeo do vídeo de entrada. Isso não é verdade no contexto WebRTC, onde o vídeo recebido pode ser afetado por atraso (atraso de rede implícito, buffer de jitter, operações de codificação/decodificação) e perda de pacotes. A falta de relação perfeita entre os quadros de vídeo enviados e recebidos torna impossível usar a ferramenta VMAF como está, após simplesmente gravar os fluxos de vídeo no lado do remetente (referência) e no lado do receptor (distorcido). A ferramenta webrtcperf integra um mecanismo de marca d'água de vídeo que usamos anteriormente para medir o atraso de vídeo de ponta a ponta (timestampWatermarkVideo). Tendo tanto os arquivos de vídeo de referência quanto os distorcidos com um carimbo de data/hora sobreposto em cada quadro, a ferramenta é capaz de processar os arquivos de vídeo, alinhá-los e filtrar os quadros que têm o mesmo carimbo de data/hora sobreposto. Após a etapa de alinhamento, a ferramenta avalia a pontuação do vídeo usando o filtro ffmpeg libvmaf. O que obtemos aqui é uma indicação perceptual da degradação do vídeo causada pelo codificador que pode reduzir a taxa de bits para corresponder à largura de banda disponível. Vale a pena notar que a ferramenta não avaliará a qualidade do vídeo para quadros descartados (perdidos), então a pontuação VMAF obtida deve ser combinada com as outras métricas WebRTC (como perda de pacotes e taxa de quadros de vídeo recebida) para ter uma avaliação completa da qualidade.
A maneira sugerida de usar este recurso é executar a imagem docker do webrtcperf que já inclui uma versão corrigida do ffmpeg com o filtro libvmaf.

Exemplo de teste executando a avaliação de qualidade VMAF (inicie a pilha prometheus antes de executar o teste):

docker run -it --rm \
  -v /dev/shm:/dev/shm \
  -v $PWD/data:/data \
  -p 9000 \
  --net=prometheus-stack_default \
  ghcr.io/vpalmisano/webrtcperf:devel \
  --sessions=2 \
  --run-duration=180 \
  --url=https://meet.google.com/<ID> \
  --debugging-port=9000 \
  --script-path=https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js \
  --prometheus-pushgateway=http://pushgateway:9091 \
  --script-params="{timestampWatermarkVideo:true,saveSendVideoTrack:'0',saveRecvVideoTrack:'1'}" \
  --server-port=5000 \
  --server-use-https \
  --server-data=/data \
  --vmaf-path=/data \
  --vmaf-preview

A ferramenta executará uma conferência do Google Meet com 2 participantes, salvando o vídeo enviado por “Participant-000000” (saveSendVideoTrack:’0’) e o vídeo recebido por “Participant-000001” (saveRecvVideoTrack:'1'). Precisamos ativar a ferramenta no modo servidor (--server-port) para salvar os quadros de vídeo capturados dentro da automação da página da web. Adicionar a opção --vmaf-path fará com que a ferramenta execute a avaliação VMAF no final do teste e --vmaf-preview gerará uma comparação lado a lado entre o vídeo de referência e o vídeo degradado.
As saídas do VMAF são:

Um nome de pasta para cada comparação feita pela ferramenta para o teste atual no formato <Sender Participant>_recv-by_<Receiver Participant>; para este teste simples será Participant-000000_recv-by_Participant-000001. Em cada pasta encontraremos os seguintes arquivos:
- psnr.log (o log PSNR);
- vmaf-log.json (a saída completa do VMAF);
- vmaf-log.png (um gráfico feito com as pontuações quadro a quadro);
- comparison.mp4 com a comparação lado a lado.
Um arquivo vmaf.json contendo algumas pontuações VMAF agregadas para cada comparação.

vmaf-log.png:

vmaf.json:

[
  {
    "sender": "Participant-000000",
    "receiver": "Participant-000001",
    "min": 61.083063,
    "max": 87.46276,
    "mean": 76.260023,
    "harmonic_mean": 76.118533
  }
]

Outras opções para controlar a avaliação VMAF são:

--vmaf-keep-source-files: Verdadeiro por padrão, mantém os arquivos de vídeo brutos gravados na pasta de destino após a avaliação.
--vmaf-keep-intermediate-files: Falso por padrão, quando verdadeiro, todos os arquivos de vídeo intermediários usados pela ferramenta VMAF serão mantidos na pasta de destino, permitindo depurá-los.
--vmaf-skip-duplicated: Falso por padrão, quando verdadeiro, a ferramenta pulará os quadros com o mesmo timestamp reconhecido. Use esta opção se o codificador usado pelo serviço que você está testando aplicar uma duplicação de quadros para corresponder à taxa de quadros configurada (por exemplo, isso pode acontecer ao testar vídeos HLS).
--vmaf-crop: uma string JSON com uma configuração de corte a ser aplicada aos vídeos de referência e/ou degradados. A configuração de corte deve ser expressa usando a sintaxe do filtro de corte do ffmpeg (https://ffmpeg.org/ffmpeg-filters.html#crop).
Exemplo:
```
{
  "Participant-000001_recv-by_Participant-000000": {
    ref: { w: "iw-10", h: "ih-5" },
    deg: { w: "200", h: "200" }
  }
}
```

Executar testes distribuídos

Executar testes com vários participantes geralmente requer uma quantidade de CPU e memória que pode não corresponder às capacidades da máquina host. Além disso, executar testes com vídeo de alta resolução e/ou receber streams de muitos participantes remotos na mesma sala de conferência exigirá uma quantidade de largura de banda que pode não estar disponível em um único host. Por essas razões, ao executar testes com muitos participantes simultâneos, a maneira preferida de usar o webrtcperf é ativando a opção de modo servidor em uma instância (chamaremos de "coletor") e executar todas as outras instâncias de teste do webrtcperf necessárias em hosts diferentes ("trabalhadores"); as instâncias trabalhadoras coletarão as métricas extraídas das sessões locais em execução e as enviarão ao coletor, que as agregará e enviará ao serviço Prometheus Pushgateway.

Exemplo de comando para iniciar o webrtcperf no modo "coletor" no host 192.168.0.1:

webrtcperf \
  --run-duration=200 \
  --prometheus-pushgateway=http://127.0.0.1:9091 \
  --server-port=5000 \
  --server-use-https \
  --server-secret=<SECRET>

Exemplo de comando para iniciar duas instâncias "trabalhadoras" em hosts diferentes, executando 50 participantes cada uma:

# Worker 1 
webrtcperf \
  --sessions=50 \
  --run-duration=180 \
  --url=<URL> \
  --push-stats-url=https://192.168.0.1:5000 \
  --server-secret=<SECRET> \
  --push-stats-id=1 \
  --start-session-id=0 \
  --start-timestamp=1749212181000

# Worker 2
webrtcperf \
  --sessions=50 \
  --run-duration=180 \
  --url=<URL> \
  --push-stats-url=https://192.168.0.1:5000 \
  --server-secret=<SECRET> \
  --push-stats-id=2 \
  --start-session-id=50 \
  --start-timestamp=1749212181000

Observe que você precisa adicionar as seguintes opções para cada trabalhador:

O endereço/porta do coletor com --push-stats-url.
Um identificador único com --push-stats-id que será usado pelo coletor para agregar as métricas provenientes desse trabalhador.
Você precisa definir --start-session-id como 50 no segundo host, para que os participantes sejam indexados começando de Participant-000050 até Participant-000099.
Use o mesmo --start-timestamp para ambos os hosts e defina-o para o mesmo timestamp UNIX expresso em milissegundos. Dessa forma, toda a automação de ações em execução em cada host será sincronizada no tempo (exemplo: desmutar Participant-000001 e Participant-000051 no tempo 60 será executado ao mesmo tempo de relógio em ambas as instâncias). Os relógios das máquinas trabalhadoras devem estar sincronizados.
Use o mesmo valor de --server-secret para o coletor e os trabalhadores.

Para a configuração do coletor, use uma opção --run-duration mais longa apenas para evitar perder as últimas atualizações de métricas dos hosts trabalhadores.

Recursos experimentais

Executar testes com o prompt de IA

A opção --prompt permite executar um teste com um prompt de IA que será usado para gerar a configuração do cenário de teste. O prompt deve ser uma descrição precisa do cenário de teste que queremos executar, incluindo o número de participantes, a URL do serviço, a configuração de limitação de rede, etc. O prompt será enviado ao serviço Google Gemini AI e a resposta será analisada para gerar uma configuração de teste válida.

Exemplo de uso:

export GEMINI_API_KEY=<key>
webrtcperf --prompt "run a 2min test with 2 sessions on 'https://v3demo.mediasoup.org/?roomId=webrtcperf-test-12345' limiting the 2nd session upstream at 1Mbps with 1% packet loss for 30s, 2Mbps for 30s and 1Mbps for all the remaining time"

Adicione a opção --dry-run para imprimir a configuração de teste gerada sem executá-la:

webrtcperf --prompt --dry-run "run a 2min test with 2 sessions on 'https://v3demo.mediasoup.org/?roomId=webrtcperf-test-12345' limiting the 2nd session upstream at 1Mbps with 1% packet loss for 30s, 2Mbps for 30s and 1Mbps for all the remaining time"

{
  throttleConfig: '[{ sessions: "1", up: [{ rate: 1000, loss: 1, at: 0 }, { rate: 2000, at: 30 }, { rate: 1000, at: 60 }] }]',
  runDuration: 120,
  sessions: 2,
  url: 'https://v3demo.mediasoup.org/?roomId=webrtcperf-test-12345',
}

Instalação do MCP

Para usar o webrtcperf como um servidor MCP, adicione a seguinte configuração:

{
  "mcpServers": {
    "webrtcperf": {
      "command": "npx",
      "args": ["-y", "@vpalmisano/webrtcperf@latest", "--mcp"]
    }
  }
}

Autores

Vittorio Palmisano [github]

Licença

AGPL