Insights técnicos de WebLiveHub

Checklist

• Fuerza relay una vez: configura temporalmente iceTransportPolicy: 'relay' para confirmar que es TURN.
• Confirma candidatos relay: registra strings de candidates y busca typ relay.
• No mezcles tipos de credenciales: user/pass estático vs credenciales con expiración (TURN REST) deben coincidir con tu configuración.
• Revisa desfase de reloj: con credenciales temporales, la deriva de tiempo puede romper la autenticación.
• A/B navegador vs WebView: si solo falla en WebView, prueba TURN sobre TCP/TLS como fallback de diagnóstico.

Pseudo-código: forzar relay + log de candidate type (API estándar WebRTC)

// PSEUDO-CODE (not WLSDK)
const pc = new RTCPeerConnection({
  iceServers: [
    {
      urls: 'turn:turn.example.com:3478',
      username: '<USERNAME>',
      credential: '<CREDENTIAL>',
    },
  ],
  iceTransportPolicy: 'relay',
});

pc.onicecandidate = (e) => {
  if (!e.candidate) return;
  const c = e.candidate.candidate;
  if (c.includes(' typ relay ')) console.log('relay', c);
};

¿Vas a incrustar live streaming en un producto? Empieza por la Guía de integración (PHP SDK). ¿Necesitas acceso? Solicita el SDK.

Checklist

• Registra todos los candidates: confirma si solo ves host o también srflx/relay.
• Valida UDP egress: reglas de egress / firewall pueden bloquear STUN sin un error evidente.
• Usa TURN como control: si relay aparece pero srflx no, el camino STUN es el sospechoso.
• Minimiza el repro: una página mínima que solo recolecte candidates en el mismo despliegue.

Pseudo-código: log de tipos de ICE candidates (API estándar WebRTC)

// PSEUDO-CODE (not WLSDK)
pc.onicecandidate = (e) => {
  if (!e.candidate) return;
  const c = e.candidate.candidate;
  if (c.includes(' typ host ')) console.log('host', c);
  if (c.includes(' typ srflx ')) console.log('srflx', c);
  if (c.includes(' typ relay ')) console.log('relay', c);
};

Si vas a incrustar streaming en un producto, mantén tu baseline reproducible. Empieza por la Guía de integración (PHP SDK). ¿Necesitas acceso? Solicita el SDK.

Checklist

• Guarda ambos SDP: conserva el offer y el answer completos del caso que falla.
• Verifica fingerprints: busca a=fingerprint y roles a=setup coherentes.
• Ojo con reescritura de SDP: proxies/SFUs/código de signaling que edita SDP puede eliminar líneas necesarias.
• Interoperabilidad: si integras WHIP/FFmpeg/SFU, confirma DTLS-SRTP (no SDES-SRTP).
• Reduce variables: reproduce con una sola m-line (audio o video) antes de complicar.

Pseudo-código: volcar offer/answer SDP (API estándar WebRTC)

// PSEUDO-CODE (not WLSDK)
function dump(label, desc) {
  console.log(label, desc.type);
  console.log(desc.sdp);
}

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
dump('local', pc.localDescription);

// después de recibir `answer` vía signaling
await pc.setRemoteDescription(answer);
dump('remote', pc.remoteDescription);

¿Vas a incrustar live streaming en un producto? Empieza por la Guía de integración (PHP SDK) para mantener un baseline limpio. ¿Necesitas acceso? Solicita el SDK.

Checklist

• Primero interacción: reproduce tras un click; revisa muted y volumen del sistema.
• Enumera dispositivos: confirma audiooutput en enumerateDevices().
• Comprueba setSinkId: no asumas que existe (varía por navegador / WebView).
• Escucha cambios: maneja devicechange (Bluetooth / auriculares).
• Repro mínimo: un track remoto + un <audio>.

Pseudo-código: enumerar salidas + setSinkId (si está disponible)

// PSEUDO-CODE (not WLSDK)
async function listAudioOutputs() {
  const devices = await navigator.mediaDevices.enumerateDevices();
  return devices.filter((d) => d.kind === 'audiooutput');
}

async function setOutput(audioEl, deviceId) {
  if (typeof audioEl.setSinkId !== 'function') {
    console.warn('setSinkId no soportado en este entorno');
    return;
  }
  await audioEl.setSinkId(deviceId);
}

Si vas a incrustar streaming en un producto, empieza por la Guía de integración (PHP SDK) y mantén un baseline simple. ¿Necesitas acceso? Solicita el SDK.

Checklist

• Registra cambios de estado: captura signalingState/connectionState/iceConnectionState alrededor de la renegociación.
• Compara el orden de m-lines: diffea el orden de secciones m= entre una ejecución que funciona y una que falla.
• Estabiliza transceivers: crea transceivers de audio/video una sola vez y en orden fijo; prioriza replaceTrack().
• Serializa offers: evita offers solapados disparados por múltiples eventos negotiationneeded.
• Perfect Negotiation: maneja la colisión de offer de forma consistente (polite/impolite + ignoreOffer).

Pseudo-código: Perfect Negotiation (API estándar WebRTC)

let makingOffer = false;
let ignoreOffer = false;
const polite = true;

pc.onnegotiationneeded = async () => {
  try {
    makingOffer = true;
    await pc.setLocalDescription();
    sendSignal({ description: pc.localDescription });
  } finally {
    makingOffer = false;
  }
};

onSignal(async ({ description, candidate }) => {
  if (description) {
    const offerCollision =
      description.type === 'offer' &&
      (makingOffer || pc.signalingState !== 'stable');

    ignoreOffer = !polite && offerCollision;
    if (ignoreOffer) return;

    await pc.setRemoteDescription(description);

    if (description.type === 'offer') {
      await pc.setLocalDescription();
      sendSignal({ description: pc.localDescription });
    }
  } else if (candidate) {
    try {
      await pc.addIceCandidate(candidate);
    } catch (e) {
      if (!ignoreOffer) throw e;
    }
  }
});

¿Vas a incrustar live streaming en un producto? Empieza por la Guía de integración (PHP SDK). ¿Necesitas acceso? Solicita el SDK.

Checklist

• Empieza pequeño: prueba 16–64KB por chunk.
• Controla el envío: haz throttle con dc.bufferedAmount y el evento bufferedamountlow.
• Estado: envía solo con dc.readyState === 'open'.
• Memoria en receptor: procesa incrementalmente; evita acumular el archivo completo en RAM.

Pseudo-código: backpressure con bufferedAmount (API estándar WebRTC)

const CHUNK = 64 * 1024;
async function sendFile(dc, buf) {
  dc.bufferedAmountLowThreshold = 1024 * 1024;

  for (let i = 0; i < buf.byteLength; i += CHUNK) {
    while (dc.bufferedAmount > dc.bufferedAmountLowThreshold) {
      await once(dc, 'bufferedamountlow');
    }
    dc.send(buf.slice(i, i + CHUNK));
  }
}

function once(dc, evt) {
  return new Promise((r) =>
    dc.addEventListener(evt, () => r(), { once: true })
  );
}

Si vas a incrustar streaming en un producto, mantén tu baseline reproducible. Empieza por la Guía de integración (PHP SDK). ¿Necesitas acceso? Solicita el SDK.

El síntoma: hay track, pero no se decodifica

Muchas veces se ve como “funciona en Chrome, falla en Safari/iOS” o “funciona en escritorio, falla en algunos Android”. La conexión puede estar establecida y aun así el decoder rechaza el perfil H.264 negociado.

Checklist

• Guarda ambos SDP: conserva offer y answer en el caso que funciona y en el que falla.
• Encuentra el payload de H.264: busca a=rtpmap:<pt> H264/90000 y anota <pt>.
• Compara las líneas fmtp: revisa a=fmtp:<pt> ... para profile-level-id, packetization-mode y level-asymmetry-allowed.
• Alinea perfiles: si controlas el encoder, usa perfiles compatibles entre plataformas (un A/B rápido es probar otro codec como VP8 para confirmar que es negociación de codec).
• No “rompas” el SDP: proxies/SFUs/capas de signaling que reescriben SDP a veces eliminan o cambian parámetros de H.264.

Si vas a incrustar live streaming en un producto, mantén pasos de reproducción mínimos y consistentes. Empieza por la Guía de integración (PHP SDK) y añade complejidad solo cuando puedas observar diferencias de negociación. ¿Necesitas acceso? Solicita el SDK.

El síntoma: hay pista, pero no hay frames

Puede dispararse ontrack, pero el elemento video sigue en negro. Esto puede pasar si el camino seleccionado no está transportando RTP (o si “conecta” pero la ruta real falla en tu red).

Checklist

• Confirma el estado ICE: registra iceConnectionState y captura el estado cuando llegue a connected/completed.
• Revisa el par de candidatos seleccionado: en Firefox usa about:webrtc para ver el candidato local/remoto elegido.
• Busca .local en candidatos: suele ser un candidato host vía mDNS. En algunas LAN/AP, los pares no pueden resolver mDNS y terminas con “conectado pero sin media”.
• Prueba A/B con hotspot: si con hotspot funciona pero con Wi‑Fi de oficina falla, casi siempre es red / resolución / firewall.
• Fuerza relay como prueba: si controlas la capa WebRTC, prueba temporalmente relay-only (iceTransportPolicy: 'relay') para verificar si el problema desaparece al usar rutas de TURN relay.

Si vas a incrustar live streaming en un producto, mantén un baseline mínimo y reproducible. Empieza por la Guía de integración (PHP SDK) y solo añade complejidad cuando puedas observar los estados. ¿Necesitas acceso? Solicita el SDK.

Lo que documenta la Guía de Integración

La Guía de Integración lista los códigos de idioma soportados por el player: en, ja, zh-Hant, zh-Hans, vi. Si no especificas lang, WLSDK lee el idioma del entorno; si no está disponible, hace fallback a en.

Ejemplo: forzar el idioma del player a inglés

<?php
echo WLSDK::iframe([
  'hostLabel' => 'connect',
  'streamer'  => '<STREAMER_USER_ID>',
  'lang'      => 'en',
]);
?>

Ver Guía de integración → “Multi-language integration (optional)”. Si necesitas acceso de desarrollador, solicita el SDK.

Los paneles suelen cargar demasiado, demasiado pronto

Si tu página renderiza muchas vistas en vivo a la vez, podrías terminar inicializando múltiples players al cargar. Si la mayoría están fuera de pantalla, normalmente no es necesario.

Usa el patrón “Multiple Iframes Lazy Loading” documentado

La Guía de Integración incluye un ejemplo multi-iframe con WLSDK::lazyIframe(). Mantén la llamada mínima y pasa solo parámetros documentados.

<!-- Dentro de tu bucle -->
<?php foreach ($activeStreamers as $streamerId): ?>
  <div class="stream-wrapper">
    <?php
      echo WLSDK::lazyIframe([
        'hostLabel' => 'connect',
        'streamer'  => $streamerId,
      ]);
    ?>
  </div>
<?php endforeach; ?>

Para más detalles, ver Guía de integración → “Multiple Iframes Lazy Loading”.

El “camino fácil” que luego se rompe

En el navegador parece simple: grabas chunks y guardas un Blob. Pero en producción te enfrentas a:

• Sin seek: WebM suele salir sin metadata (duración/tabla de seek).
• Riesgo de pérdida: si la pestaña se cae o el usuario recarga, se pierde todo lo que estaba en RAM.
• Variable Frame Rate (VFR): bajo carga se pierden frames y aparece desincronización A/V.

Solución fiable: grabación del lado servidor

Compón y graba en el servidor, donde controlas CPU y red. Si grabación/exportación (por ejemplo MP4) es un requisito, trátalo como un pipeline del lado servidor y confirma alcance/soporte cuando solicites el SDK.

El síntoma: “video congelado”

Cuando el usuario sale del WiFi, cambia la IP. El socket UDP actual deja de servir y el video se congela.

La solución: ICE Restart

Monitorea iceConnectionState. Si llega a disconnected o failed, dispara un ICE Restart (renegocia con iceRestart: true).

pc.createOffer({ iceRestart: true })

Así el navegador recoge candidatos nuevos en la red 4G sin destruir la pista de media.

Si vas a incrustar streaming en un producto, piensa la reconexión como parte de tu máquina de estados (ICE restart + UI). Empieza por el flujo mínimo de la Guía de integración y luego extiende según tus requisitos.

Síntomas y chequeos rápidos

Si ves ICE Connection Failed o se queda “candidate gathering”, casi siempre es ruta de red (firewall/NAT) o configuración de TURN.

Configuración base

• STUN/TURN: Provee un servidor TURN; no dependas solo de STUN.
• UDP 3478: Puerto estándar; muchas redes corporativas bloquean UDP.
• Fallback TCP 443: si UDP está bloqueado, asegúrate de soportar TCP 443 (TURNS).

Symmetric NAT es enemigo del P2P

Con Symmetric NAT, el P2P directo suele fallar: debes relé vía TURN.

Si no quieres operar un clúster TURN, considera un servicio TURN gestionado. Al evaluar opciones (o al solicitar el SDK), confirma qué componentes de red están incluidos y cuáles son sus límites.

La forma práctica: genera el embed en tu backend

Evita hardcodear URLs del player o credenciales en el frontend. En su lugar, genera el HTML del embed en tu backend y devuélvelo a usuarios autenticados; así mantienes secretos del lado servidor y tienes un punto único para aplicar tus propias reglas de acceso.

<?php
// Incluye la clase del SDK de WebLiveHub
require_once __DIR__ . '/vendor/autoload.php';
use WebLiveHub\SDK\WLSDK;

// Inicializa la configuración del SDK
WLSDK::setup([
    'hb_endpoint' => getenv('WL_HOSTED_BACKEND_URL') ?: '<HOSTED_BACKEND_ENDPOINT>',
    'user_id' => '<AUTH_USER_ID>',
    'password' => '<AUTH_PASSWORD>'
]);
?>

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <?php echo WLSDK::script(); ?>
</head>
<body>
  <?php
    echo WLSDK::iframe([
      'hostLabel' => 'connect',
      'streamer'  => '<STREAMER_USER_ID>',
      'attrs' => [ 'id' => 'stream-container', 'class' => 'wlh-stream', 'style' => 'border-radius:6px;' ]
    ]);
  ?>
</body>
</html>

El SDK devuelve un embed <iframe>. Usa attrs para pasar atributos HTML estándar y valida el comportamiento de autoplay/permisos en tus navegadores objetivo (especialmente iOS/Safari).

¿Por qué usar el SDK?

• Integración backend-first: mantén credenciales de larga duración en tu servidor; decide cuándo renderizar un embed para un usuario logueado.
• Baseline sólido: sigue el flujo de la Guía de integración (setup → script → iframe) y luego extiende según tu app.

👉 Obtén tus credenciales del SDK

Primero define un baseline (aburrido). Luego depura.

Muchos problemas de “no reproduce / sin audio / pantalla negra” son condiciones del entorno. Si igualas el baseline, el diagnóstico se vuelve mucho más rápido.

Navegador y dispositivo

• Valida primero en Chrome/Edge (luego Safari/iOS).
• Confirma permisos de cámara/micrófono y dispositivos disponibles.
• Prueba en ventana incógnita para descartar extensiones.

Despliegue y red

• El sitio debe ir por HTTPS (en local sirve localhost).
• Red corporativa puede bloquear UDP; compara con hotspot móvil.

Reproducción

• Autoplay suele estar bloqueado: inicia tras un clic.
• Verifica salida de audio y mute (SO + navegador).

Siguiente paso: sigue la Guía de integración (PHP SDK). Si necesitas acceso, solicita el SDK.

Divide el problema en 3 capas: media → conexión → reproducción

La clave es convertir “no funciona” en estados observables.

1) Media

• ¿Permisos OK? ¿Cámara/micrófono realmente disponibles?
• Prueba otro dispositivo para descartar hardware/driver.

2) Conexión

• Red corporativa a menudo bloquea UDP; si funciona en hotspot, ya tienes la causa.

3) Reproducción

• Activa la reproducción tras un clic (autoplay/mute).
• Confirma salida de audio correcta (BT/pantalla/altavoces).

Datos que vale la pena capturar (una vez)

• Chrome: chrome://webrtc-internals (exportar o capturas).
• Hora, navegador, SO, tipo de red.

Siguiente paso: contrasta tu flujo con la Guía de integración (PHP SDK).

Por qué “en Chrome funciona, en iPhone no” es tan común

En iOS, permisos y cambios de foreground/background son más estrictos. Tu plan de pruebas debe ser explícito.

Checklist de prueba

• Inicia siempre tras clic del usuario.
• Prueba ir a segundo plano y volver (y valida recuperación).
• Repite 3 veces: los bugs intermitentes aparecen así.

Para reportar

• Modelo de iPhone, versión iOS y Safari
• Si usas auriculares Bluetooth
• Modo ahorro de energía

Siguiente paso: establece un baseline con la Guía de integración (PHP SDK) y luego agrega features.

No digas “se traba”: conviértelo en números

Los cortes suelen ser mezcla de pérdida, jitter, bitrate insuficiente o decodificación lenta.

5 métricas clave

• Packet loss
• Jitter
• Bitrate
• Frames dropped / decode time
• End-to-end latency

Cómo capturarlas

• Chrome: chrome://webrtc-internals para tendencias rápidas.
• Repite el mismo escenario 3 veces antes de comparar.

Siguiente paso: completa la Guía de integración (PHP SDK) y crea tu baseline de calidad.

El bug típico en SPA: el usuario se fue, pero los listeners no

Si no limpias eventos/timers, terminas con conexiones duplicadas, audio ocupado o memoria en aumento.

Regla simple

• Registra en mount.
• Desregistra en unmount (removeEventListener, clearInterval, liberar recursos).
• Reconexión con estado (evita disparar múltiples reconexiones).

Eventos útiles

• visibilitychange (background/foreground)
• pagehide (común en mobile)

Siguiente paso: alinea tu implementación con la Guía de integración (PHP SDK).