Telemetría del Player WebRTC¶
Descripción general¶
El player WebRTC de Netsocs incluye un panel de telemetría en tiempo real (OSD - On-Screen Display) que muestra métricas de calidad del stream en tres niveles: visor (browser), relay (DriversHub) y driver (dispositivo fuente). Permite diagnosticar problemas de conectividad, calidad de video y rendimiento de red sin necesidad de herramientas externas.
Requisitos: - Player en modo V2 (WebRTC/WHEP) - Versión 3.3.0 o superior
Activar y desactivar el panel de telemetría¶
1. Pase el cursor sobre el player para mostrar los controles de zoom (esquina inferior derecha).
2. Haga clic en el icono de informacion (circulo con i).
3. El panel OSD aparece en la esquina superior derecha del player.
4. Haga clic nuevamente en el mismo icono para ocultarlo.
El estado del panel no persiste entre sesiones; se desactiva al recargar la pagina.
Panel de telemetria: secciones¶
El OSD se actualiza cada 10 segundos. Muestra hasta tres secciones segun la disponibilidad de datos.
Seccion Viewer (Visor)¶
Metricas recogidas directamente desde la conexion WebRTC del navegador via RTCPeerConnection.getStats().
| Campo | Descripcion | Interpretacion |
|---|---|---|
| Estado (punto de color) | Indica si el stream esta fluyendo | Verde = LIVE (frames avanzando), Amarillo = STALLED (sin avance pero con datos previos), Rojo = NO DATA (sin estadisticas) |
| Resolucion | Dimensiones del frame de video en pixeles | Ej: 1920x1080. Resolucion baja puede indicar calidad sub o limitacion del encoder |
| FPS | Fotogramas por segundo decodificados en el visor | Valores tipicos: 15-30 fps. Caidas indican perdida de paquetes o CPU limitada |
| Bitrate (flecha hacia abajo) | Tasa de bits recibida calculada entre dos muestras | Muestra en Kbps o Mbps segun magnitud. Caidas sostenidas indican congestion de red |
| RTT | Round-Trip Time del candidato ICE nominado | Tiempo de ida y vuelta en milisegundos. Por debajo de 100 ms es optimo; por encima de 300 ms puede generar latencia visible |
| Loss | Porcentaje de paquetes perdidos | 0% es ideal. Valores por encima de 1% degradan la calidad de video |
| ICE | Tipo de candidato ICE usado | host = conexion directa LAN, srflx = NAT traversal sin relay, relay = TURN relay (mayor latencia) |
| Dec | Tiempo promedio de decodificacion por frame | En milisegundos. Valores altos (>20 ms en hardware moderno) indican sobrecarga de CPU o decodificacion por software |
Seccion Relay¶
Metricas publicadas por DriversHub desde el relay WHIP/WHEP del servidor. Se actualizan aproximadamente cada 10 segundos en el servidor y se obtienen via GET /whip/{streamId}/telemetry?source=relay&limit=1.
| Campo | Descripcion |
|---|---|
| Codec | Codec de video negociado por el relay (ej: H264, H265/HEVC) |
| Bitrate (flecha hacia abajo) | Bitrate observado en el relay en Kbps o Mbps |
| RTT | Latencia medida por el relay |
| Jit | Jitter del relay en milisegundos; variacion en los tiempos de llegada de paquetes |
Esta seccion solo aparece si el relay reporta al menos un punto de telemetria.
Seccion Driver¶
Metricas publicadas por el driver del dispositivo (ej: Hikvision) directamente al endpoint de telemetria. Se actualizan cada 5 segundos en el dispositivo y se obtienen via GET /whip/{streamId}/telemetry?source=publisher&limit=1.
| Campo | Descripcion | Interpretacion |
|---|---|---|
| RTP | Total de paquetes RTP enviados por el driver | Numero acumulado; sirve para verificar que el dispositivo esta transmitiendo activamente |
| IDR | Fotogramas IDR (keyframes) enviados | Fotogramas de referencia completa. El player los necesita para sincronizar el stream. Si es muy bajo puede causar demoras al conectar |
| Err | Errores RTP en el driver (mostrado en rojo cuando > 0) | Indica fallos en la capa de transporte del dispositivo; puede requerir reinicio del canal |
Esta seccion solo aparece si el driver reporta datos de telemetria.
Recoleccion y envio de datos¶
El hook useStreamTelemetry ejecuta un ciclo cada 10 segundos por visor activo:
- Lee estadisticas WebRTC del
RTCPeerConnectionlocal. - Calcula bitrate, perdida de paquetes y tiempo de decodificacion entre muestras consecutivas.
- Detecta si el stream esta fluyendo comparando
framesDecodedentre muestras. - Envia un punto de telemetria al servidor via
POST /whip/{streamId}/telemetry(fire-and-forget). - Consulta el ultimo punto de relay y publisher en paralelo para actualizar el OSD.
Cada sesion de visor genera un viewer_id UUID unico al montar el componente; permite al backend correlacionar multiples viewers del mismo stream.
Diagnostico de problemas comunes¶
| Sintoma en el OSD | Posible causa | Accion sugerida |
|---|---|---|
| Estado STALLED (amarillo) | Congestion de red o encoder detenido | Verificar conectividad; revisar estado del canal en el driver |
| Estado NO DATA (rojo) | PeerConnection sin estadisticas aun o stream no iniciado | Esperar el primer ciclo de 10 s; si persiste, revisar la conexion WHEP |
| Loss > 1% | Perdida de paquetes en la red | Revisar la red entre el browser y el relay; considerar pasar a calidad sub |
| ICE: relay | El browser no pudo conectar directamente | El servidor TURN esta siendo usado; puede incrementar la latencia |
| Err > 0 en Driver (rojo) | Errores RTP en el dispositivo fuente | Reiniciar el canal de video en la configuracion del dispositivo |
| Seccion Relay ausente | DriversHub no recibio datos del relay | Verificar que el servicio DriversHub este en linea y el stream WHIP activo |
| Seccion Driver ausente | El driver no envia telemetria | El modelo del dispositivo puede no soportar telemetria activa |
Consideraciones de privacidad y rendimiento¶
- Los datos de telemetria incluyen identificadores del stream y del visor pero no contienen video ni audio.
- El envio es
keepalive: truepara no bloquearse al cerrar la pestana. - El impacto en rendimiento es minimo: una llamada
getStats()y dos peticiones HTTP cada 10 segundos por visor. - Deshabilitar la feature flag
player_webrtc_telemetry_infoelimina completamente el boton OSD y detiene la recoleccion de datos del visor.