Quality

El SDK incluye un sistema de monitoreo de calidad que detecta y reporta problemas en tiempo real durante las videollamadas.

webrtc.addEventListener('quality:issues', event => {
    const { ... } = event.detail;
});

Quality Issues

El monitor de calidad detecta automáticamente los siguientes problemas:

Issue Type	Origin	Severity	Descripción	Umbral Warning	Umbral Critical
packetLoss	local	warning / critical	Pérdida de paquetes en la recepción (video/audio)	1%	10%
latency	local	warning / critical	Latencia de red (Round-Trip Time)	500ms	1500ms
jitter	video	warning / critical	Variación en llegada de paquetes de video	80ms	150ms
jitter	audio	warning / critical	Variación en llegada de paquetes de audio	35ms	60ms
bandwidth-limitation	local	warning / critical	Video limitado por ancho de banda	2s/5s	4s/5s
freezes	video	warning / critical	Congelamientos de video detectados	3 freezes/5s	10 freezes/5s

Interpretación de Severidades

• Warning: Degradación notable en la calidad, pero la comunicación sigue siendo funcional

• Critical: Problemas severos que dificultan o imposibilitan la comunicación efectiva

Origin Values

• local: Problema en la recepción local (tu downlink o el uplink del peer)

• video: Específico del stream de video

• audio: Específico del stream de audio

---

Cómo usar

Puedes configurar los umbrales de calidad al inicializar el SDK:

const latency = { warning: 500, critical: 1500 }; // ms
const thresholds = Object.assign(WebRTC.thresholds, { latency });
const webrtc = new WebRTC(component, parent, { thresholds });

Eventos

quality:issues

Se emite cuando se detecta un problema de calidad en tu conexión local.

Propiedad	Tipo	Valores Posibles	Descripción
type	string	packetLoss, latency, jitter, bandwidth-limitation, freezes	Tipo de problema detectado
severity	string	warning, critical	Nivel de severidad del problema
origin	string	local, video, audio	Origen o categoría del problema
value	number	-	Valor numérico de la métrica
timestamp	number	-	Timestamp Unix (ms) del evento

webrtc.addEventListener('quality:issues', (event) => {
    const { type, severity, origin, value, timestamp } = event.detail;
    // Do something...
});

quality:recovered

Se emite cuando un problema de calidad se ha recuperado en tu conexión local.

Propiedad	Tipo	Valores Posibles	Descripción
type	string	packetLoss, latency, jitter, bandwidth-limitation, freezes	Tipo de problema que se recuperó
origin	string	local, video, audio	Origen o categoría del problema
timestamp	number	-	Timestamp Unix (ms) del evento

webrtc.addEventListener('quality:recovered', (event) => {
    const { type, origin, timestamp } = event.detail;
    // Do something...
});

peer:quality

Se emite cuando se detecta un problema de calidad en la conexión del peer remoto. Este evento te permite saber si el otro participante está experimentando problemas.

Propiedad	Tipo	Valores Posibles	Descripción
status	string	issues o recovered	Estado del problema detectado
peerId	string	-	ID del peer con problemas
alias	string	-	Alias del peer (si fue asignado)
type	string	packetLoss, latency, jitter, bandwidth-limitation, freezes	Tipo de problema detectado
severity	string	warning, critical	Nivel de severidad del problema
origin	string	local, video, audio	Origen o categoría del problema
value	number	-	Valor numérico de la métrica
timestamp	number	-	Timestamp Unix (ms) del evento

webrtc.addEventListener('peer:quality', (event) => {
    const { status, peerId, alias, type, severity, origin, value, timestamp } = event.detail;
    // Do something...
});

---

Ejemplos de uso

webrtc.addEventListener('peer:quality', (event) => {
    const { alias, peerId, type, severity } = event.detail;
    const name = alias || peerId;
    
    showNotification({
        title: 'Problemas de Conexión',
        message: `${name} está experimentando problemas de ${type}`,
        type: severity
    });
});

---

Cálculos

Debounce

Para evitar alertas por problemas momentáneos, el sistema utiliza debounce:

• Issue Detection: Un problema debe persistir durante 2 intervalos consecutivos (10 segundos) antes de emitir el evento (por defecto).

• Recovery Detection: El problema debe estar ausente durante 2 intervalos consecutivos (10 segundos) antes de emitir recuperación (por defecto).

Severidad

Si un problema activo cambia de severidad, el evento se emite inmediatamente:

// t=0s: packet loss = 2% → warning emitido (después de debounce)
// t=10s: packet loss = 12% → critical emitido inmediatamente (escalamiento)
// t=15s: packet loss = 1.5% → warning emitido inmediatamente (degradación)
// t=25s: packet loss = 0.3% → recovered emitido (después de debounce)

Ventana deslizante (Packet Loss)

El packet loss utiliza una ventana deslizante de 2 intervalos (10 segundos) para calcular el promedio y evitar alertas por spikes momentáneos.

---

Notas Técnicas

• Los eventos se emiten cada 5 segundos (intervalo de stats)

• El sistema de debounce requiere 2 mediciones consecutivas para confirmar issues y recuperaciones

• Los umbrales están calibrados según datos reales de producción con >14,000 peers

• Packet loss se calcula como promedio de ventana deslizante para mayor estabilidad

• Bandwidth limitation y freezes son deltas del intervalo actual (últimos 5s)

• Los eventos peer:quality se propagan automáticamente vía signaling entre peers

---

Troubleshooting

Muchas alertas de warning

Considera ajustar los umbrales según tu caso de uso:

const webrtc = new WebRTC(component, parent, {
    thresholds: {
        packetLoss: {
            warning: 0.03,  // Más tolerante
            critical: 0.15
        }
    }
});

Issues oscilando entre warning y critical

Si un issue oscila constantemente, considera ampliar el rango de umbrales en la configuración de thresholds.