WebRTC Events - Documentación

← Volver al Inicio

📊 Resumen del Sistema

✅ Completitud del Sistema: 100%

El sistema de notificaciones WebRTC está COMPLETO con todos los eventos implementados y documentados.

Estadísticas

Eventos Totales: 18 eventos
Eventos Críticos: 4 (producer-closed, transport-closed, peer-left, consume-error)
Eventos de Alta Prioridad: 7
Eventos de Media Prioridad: 7

Eventos Nuevos Agregados (2025-10-31)

✅ transport-closed - Notificación de transport cerrado
✅ transport-state-changed 🆕 - Cambios de estado del transport
✅ peer-left - Notificación de peer desconectado
✅ peer-joined - Notificación de peer conectado
✅ producer-created - Producer creado (interno)
✅ producer-paused - Producer pausado
✅ producer-resumed - Producer reanudado
✅ consume-error - Error al consumir producer

Vistas Actualizadas

✅ bidder-asm-stream.html - Manejo completo de eventos
✅ host-asm-stream.html - Monitoreo de eventos
✅ viewer-stream.html - Limpieza automática de recursos
✅ videoconference.html - Multi-party event handling

🏗️ Arquitectura del Sistema de Eventos

┌─────────────────────────────────────────────────────────────────┐
│ MEDIASOUP (Capa WebRTC Nativa)                                 │
│ - producer.on('close')                                          │
│ - producer.on('pause')                                          │
│ - transport.on('close')                                         │
│ - consumer.on('producerclose')                                  │
└────────────────────┬────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│ EVENT BUS (room.mjs)                                            │
│ - Centraliza todos los eventos                                 │
│ - room.emit('ProducerClosed', data)                            │
│ - room.emit('TransportClosed', data)                           │
└────────────────────┬────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│ WEBSOCKET BROADCAST (ws.mjs)                                   │
│ - room.eventBus.onProducerClosed = (data) => broadcast(...)   │
│ - Envía eventos a todos los peers conectados                   │
└────────────────────┬────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│ CLIENTES (bidder-asm-stream.html, host-asm-stream.html)       │
│ - ws.onmessage: if (m.type === 'producer-closed') {...}       │
│ - Actualiza UI según evento recibido                           │
└─────────────────────────────────────────────────────────────────┘

Event Bus

Sistema centralizado para emitir eventos WebRTC de manera consistente:

const room = {
  eventBus: {
    onProducerCreated: null,
    onProducerClosed: null,
    onProducerPaused: null,
    onProducerResumed: null,
    onTransportClosed: null,
    onDataProducerClosed: null,
  },

  emit(event, data) {
    const handler = this.eventBus[\`on\${event}\`];
    if (handler && typeof handler === 'function') {
      handler(data);
    }
  },
};

🎬 Eventos de Ciclo de Vida

welcome Alta Prioridad

📤 Dirección: Server → Client (unicast) ⏱️ Cuándo: Conexión inicial

Primer mensaje del servidor al cliente, informa su identidad asignada (peerId, role, roomId).

{
  "type": "welcome",
  "peerId": "uuid-del-peer",
  "roomId": "sala-100",
  "role": "bidder"
}

rtp-capabilities Alta Prioridad

📤 Dirección: Server → Client (unicast) ⏱️ Cuándo: Después de welcome

Envía las capacidades del router mediasoup para que el cliente pueda cargar el Device y negociar codecs.

{
  "type": "rtp-capabilities",
  "rtpCapabilities": {
    "codecs": [...],
    "headerExtensions": [...]
  }
}

📹 Eventos de Producers

producer-announced Alta Prioridad

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Nuevo producer creado

Notifica a todos los clientes que hay un nuevo producer disponible para consumir (video o audio).

{
  "type": "producer-announced",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "producerId": "producer-xyz789",
  "kind": "video"
}

producer-closed ⭐ CRÍTICO

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Producer se cierra

Notifica que un producer ya no está disponible (peer detuvo cámara/micrófono, se desconectó, etc.). Este es el evento más importante para limpieza de UI.

{
  "type": "producer-closed",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "producerId": "producer-xyz789",
  "kind": "video",
  "serverTs": 1234567890
}

Ejemplo de Manejo:

if (m.type === 'producer-closed') {
  const { producerId, kind, peerId } = m;

  if (kind === 'video' && mediaEls.has(peerId)) {
    updateVideoState(peerId, 'ended', 'disconnected',
      'El auctioneer detuvo la transmisión');
  }

  producers.delete(producerId);
}

producer-paused 🆕 Media Prioridad

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Producer se pausa

Indica que un producer se pausó temporalmente (ej: auctioneer mutea micrófono). Diferente de cerrar permanentemente.

{
  "type": "producer-paused",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "producerId": "producer-xyz789",
  "kind": "audio",
  "serverTs": 1234567890
}

producer-resumed 🆕 Media Prioridad

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Producer se reanuda

Indica que un producer previamente pausado vuelve a estar activo.

{
  "type": "producer-resumed",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "producerId": "producer-xyz789",
  "kind": "audio",
  "serverTs": 1234567890
}

🚚 Eventos de Transports

transport-closed ⭐ CRÍTICO

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Transport se cierra

Notifica que un transport WebRTC se cerró (falla de red, desconexión, timeout). Este evento es crítico para detectar pérdida de conexión.

{
  "type": "transport-closed",
  "roomId": "sala-100",
  "transportId": "transport-123",
  "peerId": "peer-abc123",
  "direction": "send",
  "serverTs": 1234567890
}

Ejemplo de Manejo:

if (m.type === 'transport-closed') {
  const { transportId, peerId, direction } = m;

  if (direction === 'send' && mediaEls.has(peerId)) {
    updateVideoState(peerId, 'ended', 'disconnected', 'Conexión perdida');
  }
}

transport-created Alta Prioridad

📤 Dirección: Server → Client (unicast) ⏱️ Cuándo: Respuesta a create-transport

Envía parámetros para que el cliente cree el transport WebRTC (ICE candidates, DTLS parameters, etc.).

{
  "type": "transport-created",
  "direction": "send",
  "params": {
    "id": "transport-123",
    "iceParameters": {...},
    "iceCandidates": [...],
    "dtlsParameters": {...}
  }
}

👥 Eventos de Peers

peer-joined 🆕 Media Prioridad

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Peer se conecta

Notifica que un nuevo peer se ha unido a la sala (antes de que produzca video/audio).

{
  "type": "peer-joined",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "role": "bidder",
  "serverTs": 1234567890
}

peer-left ⭐ CRÍTICO

📢 Dirección: Server → All Clients (broadcast) ⏱️ Cuándo: Peer se desconecta

Notifica que un peer se ha desconectado (cerró navegador, perdió conexión, timeout). Crítico para limpieza de recursos y UI.

{
  "type": "peer-left",
  "roomId": "sala-100",
  "peerId": "peer-abc123",
  "role": "auctioneer",
  "serverTs": 1234567890
}

Ejemplo de Manejo:

if (m.type === 'peer-left') {
  const { peerId, role } = m;

  // Limpiar producers del peer
  for (const [producerId, info] of producers.entries()) {
    if (info.peerId === peerId) {
      producers.delete(producerId);
    }
  }

  // Limpiar UI
  if (mediaEls.has(peerId)) {
    const { tile, healthCheckInterval } = mediaEls.get(peerId);
    if (healthCheckInterval) clearInterval(healthCheckInterval);
    tile.remove();
    mediaEls.delete(peerId);
  }
}

🚨 Eventos de Errores

consume-error 🆕 Alta Prioridad

📤 Dirección: Server → Client (unicast) ⏱️ Cuándo: Falla al consumir producer

Notifica que no se pudo crear un consumer para un producer (codec incompatible, producer no existe, etc.).

{
  "type": "consume-error",
  "producerId": "producer-xyz789",
  "error": "router cannot consume this producer",
  "code": "CONSUME_FAILED",
  "serverTs": 1234567890
}

Ejemplo de Manejo:

if (m.type === 'consume-error') {
  const { producerId, error, code } = m;
  console.error('❌ Error al consumir:', producerId, error);
  showErrorNotification(\`No se puede reproducir: \${error}\`);
}

💻 Ejemplos de Implementación

Cliente: Manejo Completo de Eventos

ws.onmessage = async (ev) => {
  const m = JSON.parse(ev.data);

  // ═══════════════════════════════════════════════════════════
  // CICLO DE VIDA
  // ═══════════════════════════════════════════════════════════

  if (m.type === 'welcome') {
    const { peerId, roomId, role } = m;
    myPeerId = peerId;
    log(\`Conectado como \${role} en \${roomId}\`);
    return;
  }

  if (m.type === 'rtp-capabilities') {
    device = new mediasoupClient.Device();
    await device.load({ routerRtpCapabilities: m.rtpCapabilities });
    return;
  }

  // ═══════════════════════════════════════════════════════════
  // PRODUCERS
  // ═══════════════════════════════════════════════════════════

  if (m.type === 'producer-announced') {
    const { producerId, kind, peerId } = m;
    producers.set(producerId, { kind, peerId });
    consume(producerId);
    return;
  }

  if (m.type === 'producer-closed') {
    const { producerId, kind, peerId } = m;
    if (kind === 'video' && mediaEls.has(peerId)) {
      updateVideoState(peerId, 'ended', 'disconnected',
        'El auctioneer detuvo la transmisión');
    }
    producers.delete(producerId);
    return;
  }

  if (m.type === 'producer-paused') {
    const { producerId, kind, peerId } = m;
    if (kind === 'video') {
      updateVideoState(peerId, 'paused', null, 'Video pausado');
    }
    return;
  }

  if (m.type === 'producer-resumed') {
    const { producerId, kind, peerId } = m;
    if (kind === 'video') {
      checkVideoPlaying(peerId);
    }
    return;
  }

  // ═══════════════════════════════════════════════════════════
  // TRANSPORTS
  // ═══════════════════════════════════════════════════════════

  if (m.type === 'transport-closed') {
    const { transportId, peerId, direction } = m;
    if (direction === 'send' && mediaEls.has(peerId)) {
      updateVideoState(peerId, 'ended', 'disconnected', 'Conexión perdida');
    }
    return;
  }

  // ═══════════════════════════════════════════════════════════
  // PEERS
  // ═══════════════════════════════════════════════════════════

  if (m.type === 'peer-joined') {
    const { peerId, role } = m;
    log('👋 Peer conectado:', peerId, role);
    return;
  }

  if (m.type === 'peer-left') {
    const { peerId, role } = m;
    log('👋 Peer desconectado:', peerId, role);

    // Limpiar producers
    for (const [producerId, info] of producers.entries()) {
      if (info.peerId === peerId) {
        producers.delete(producerId);
      }
    }

    // Limpiar UI
    if (mediaEls.has(peerId)) {
      const { tile, healthCheckInterval } = mediaEls.get(peerId);
      if (healthCheckInterval) clearInterval(healthCheckInterval);
      tile.remove();
      mediaEls.delete(peerId);
    }
    return;
  }

  // ═══════════════════════════════════════════════════════════
  // ERRORES
  // ═══════════════════════════════════════════════════════════

  if (m.type === 'consume-error') {
    const { producerId, error } = m;
    log('❌ Error al consumir:', producerId, error);
    return;
  }
};

Flujo Completo: Auctioneer Inicia Streaming

┌─────────────┐                 ┌─────────────┐                 ┌─────────────┐
│  AUCTIONEER │                 │   SERVER    │                 │   BIDDER    │
└──────┬──────┘                 └──────┬──────┘                 └──────┬──────┘
       │                               │                               │
       │ 1. WebSocket connect          │                               │
       ├──────────────────────────────>│                               │
       │                               │                               │
       │ 2. welcome, rtp-capabilities  │                               │
       │<──────────────────────────────┤                               │
       │                               │                               │
       │ 3. create-transport (send)    │                               │
       ├──────────────────────────────>│                               │
       │                               │                               │
       │ 4. transport-created          │                               │
       │<──────────────────────────────┤                               │
       │                               │                               │
       │ 5. connect-transport          │                               │
       ├──────────────────────────────>│                               │
       │                               │                               │
       │ 6. transport-connected        │                               │
       │<──────────────────────────────┤                               │
       │                               │                               │
       │ 7. produce (video)            │                               │
       ├──────────────────────────────>│                               │
       │                               │                               │
       │ 8. produced                   │ 9. producer-announced (broadcast)
       │<──────────────────────────────┤──────────────────────────────>│
       │                               │                               │
       │                               │ 10. (Bidder consume video...) │
       │                               │<──────────────────────────────┤
       │                               │                               │
       │ 11. Detener cámara            │                               │
       │ (producer.close())            │                               │
       ├──────────────────────────────>│                               │
       │                               │                               │
       │                               │ 12. producer-closed (broadcast)
       │                               ├──────────────────────────────>│
       │                               │                               │
       │                               │ 13. UI muestra "Transmisión   │
       │                               │     finalizada"               │
       │                               │                               │

📊 Tabla Resumen de Eventos

Evento	Dirección	Prioridad	Cuándo
`welcome`	Server → Client	Alta	Conexión inicial
`rtp-capabilities`	Server → Client	Alta	Después de welcome
`producer-announced`	Server → All	Alta	Nuevo producer
`producer-closed`	Server → All	CRÍTICA	Producer cierra
`producer-paused` 🆕	Server → All	Media	Producer pausa
`producer-resumed` 🆕	Server → All	Media	Producer reanuda
`transport-created`	Server → Client	Alta	Crear transport
`transport-closed` 🆕	Server → All	CRÍTICA	Transport cierra
`transport-state-changed` 🆕	Server → All	Media	Cambio estado transport
`peer-joined` 🆕	Server → All	Media	Peer conecta
`peer-left` 🆕	Server → All	CRÍTICA	Peer desconecta
`consume-error` 🆕	Server → Client	Alta	Error al consumir
`producers` (lista)	Server → Client	Alta	Late-joiner sync
`consumable`	Server → Client	Alta	Params de consumer

🎯 Eventos Críticos (4)

Estos eventos son esenciales para el correcto funcionamiento del sistema:

producer-closed - Limpieza de UI cuando se detiene video/audio
transport-closed - Detección de fallas de conexión
peer-left - Limpieza de recursos al desconectarse
consume-error - Manejo de errores de reproducción