# Quality

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

```javascript
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:

```javascript
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  |

```javascript
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   |

```javascript
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   |

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

***

## Ejemplos de uso

```javascript
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:

```javascript
// 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:

```javascript
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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.videsk.io/es-developers/sdks/webrtc/quality.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.