# 369peerjs — Manual de Integración WebRTC HD/4K, API Reference & Guía de Contexto para Inteligencia Artificial

Este documento es una **guía técnica exhaustiva, especificación de API y manual de patrones de diseño** para la librería WebRTC **369peerjs**. Está diseñado para ser leído e interpretado tanto por ingenieros de software como por modelos de Inteligencia Artificial (LLMs / AI Assistants) que necesiten integrar, extender o refactorizar proyectos de transmisión WebRTC de ultra alta definición (720p a 4K 60fps), transferencias binarias P2P e integración con sistemas de broadcasting (OBS Studio, vMix).

---

## 📋 Tabla de Contenidos
1. [Arquitectura y Conceptos Clave](#1-arquitectura-y-conceptos-clave)
2. [Instalación e Importación](#2-instalación-e-importación)
3. [Presets de Resolución y Ancho de Banda (720p - 4K)](#3-presets-de-resolución-y-ancho-de-banda-720p---4k)
4. [Objeto de Configuración Completo (Peer369 Options)](#4-objeto-de-configuración-completo-peer369-options)
5. [Infraestructura STUN / TURN / TURNS SSL](#5-infraestructura-stun--turn--turns-ssl)
6. [Referencia de Métodos de la Clase Principal (Peer369)](#6-referencia-de-métodos-de-la-clase-principal-peer369)
7. [Referencia de Métodos y Eventos de MediaConnection](#7-referencia-de-métodos-y-eventos-de-mediaconnection)
8. [Referencia de Métodos y Eventos de DataConnection](#8-referencia-de-métodos-y-eventos-de-dataconnection)
9. [Monitor de Calidad Real-Time en Pantalla (attachStatsHUD)](#9-monitor-de-calidad-real-time-en-pantalla-attachstatshud)
10. [Transmisión de Pantalla 4K Nativa (Screen Sharing)](#10-transmisión-de-pantalla-4k-nativa-screen-sharing)
11. [Integración Autónoma para Broadcast (OBS Studio & vMix)](#11-integración-autónoma-para-broadcast-obs-studio--vmix)
12. [Transferencia de Archivos Grandes mediante DataChannel Binario](#12-transferencia-de-archivos-grandes-mediante-datachannel-binario)
13. [Solución de Problemas Frecuentes y Patrones para IA](#13-solución-de-problemas-frecuentes-y-patrones-para-ia)

---

## 1. Arquitectura y Conceptos Clave

**369peerjs** es una abstracción cliente/servidor sobre la API nativa de WebRTC (`RTCPeerConnection`, `RTCDataChannel`, `RTCRtpTransceiver`) que resuelve los problemas comunes de señalización, throttling de ancho de banda y degradación de resolución.

### Principios Fundamentales:
- **Doble Munging SDP (`b=AS:` + `b=TIAS:`)**: Aplica simultáneamente `b=AS` en kilobits/seg (para Gecko/Firefox) y `b=TIAS` en bits/seg (para Chromium/WebKit/Safari) en el SDP para permitir bitrates sin estrangulamiento de hasta 35 Mbps.
- **Preferencia de No-Degradación (`maintain-resolution`)**: Configura por defecto los `RTCRtpSender` de video para conservar la nitidez píxel por píxel en 4K en lugar de borrar o pixelar la imagen ante variaciones de red.
- **Transceptores de Codec Preferente**: Utiliza `RTCRtpTransceiver.setCodecPreferences()` en navegadores modernos para forzar la selección de **VP9**, **H264** o **AV1**.
- **Canal Binario con Encabezado Compacto (14 Bytes)**: Los mensajes binarios y de archivos en `DataChannel` dividen la información en fragmentos de 16 KB con un encabezado de 14 bytes (`ArrayBuffer` nativo), eliminando errores de desbordamiento de pila (`RangeError`) y `TypeError`.
- **Servidor de Señalización Seguro (`wss://369peerjs.net.ar`)**: Utiliza WebSockets cifrados (WSS) con control de tasa de mensajes (Rate Limiting anti-DoS) y limpieza automática de sockets huérfanos.

---

## 2. Instalación e Importación

### Vía CDN en HTML (Producción)
```html
<script src="https://369peerjs.net.ar/369peer.min.js"></script>
```

### Vía Módulo ES6 (JS / React / Vue / Svelte / Angular)
```javascript
import Peer369 from 'https://369peerjs.net.ar/369peer.js';
```

---

## 3. Presets de Resolución y Ancho de Banda (720p - 4K)

La librería incluye `Peer369.RESOLUTION_PRESETS`, que preconfigura las restricciones de cámara, tasa de cuadros y ancho de banda objetivo:

| Nombre Preset | Resolución (px) | FPS Ideal / Máx | Bitrate Asignado (kbps) | Bitrate (Mbps) | Uso Recomendado |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `'720p'` | 1280 x 720 | 30 fps | 4,000 kbps | 4 Mbps | Dispositivos móviles, conexiones lentas |
| `'1080p'` | 1920 x 1080 | 60 fps | 10,000 kbps | 10 Mbps | Videollamadas HD de alta fidelidad |
| `'2k'` | 2560 x 1440 | 60 fps | 18,000 kbps | 18 Mbps | Gaming Quad HD y monitores anchos |
| `'4k'` | 3840 x 2160 | 60 fps | 35,000 kbps | 35 Mbps | Streaming profesional 4K Ultra HD |

---

## 4. Objeto de Configuración Completo (Peer369 Options)

Al instanciar `new Peer369(id, options)` o `new Peer369(options)`, se pueden pasar las siguientes opciones:

```javascript
const peer = new Peer369('mi-peer-id-opcional', {
  // 1. URL del Servidor de Señalización WebSocket (WSS cifrado)
  signalingServer: 'wss://369peerjs.net.ar',

  // 2. Preset de calidad multimedia: '720p', '1080p', '2k', '4k'
  preset: '1080p',

  // 3. Ancho de banda personalizado en kbps (sobreescribe el preset si se especifica)
  bandwidth: 10000,

  // 4. Codec de video preferido: 'VP9', 'H264', 'VP8', 'AV1'
  videoFormat: 'VP9',

  // 5. Estrategia de degradación WebRTC: 'maintain-resolution' | 'maintain-framerate' | 'balanced'
  degradationPreference: 'maintain-resolution',

  // 6. Restricciones de captura de cámara/micrófono personalizadas (MediaStreamConstraints)
  videoConstraints: {
    width: { ideal: 1920 },
    height: { ideal: 1080 },
    frameRate: { ideal: 60, max: 60 }
  },

  // 7. Configuración de Infraestructura STUN/TURN/TURNS
  turnServer: {
    realm: '369app.net.ar',
    ip: '13.140.43.187',
    port: 3478,
    turnsPort: 5349,
    user: '369user',
    password: '369turnpass2026',
    secret: 'LAhienas123'
  },

  // 8. Opciones avanzadas de RTCPeerConnection (opcional)
  config: {
    sdpSemantics: 'unified-plan',
    iceCandidatePoolSize: 10
  }
});
```

---

## 5. Infraestructura STUN / TURN / TURNS SSL

`Peer369` genera automáticamente servidores ICE nativos mediante `Peer369.generateIceServers()`:

- **STUN UDP/TCP**: `stun:369app.net.ar:3478` / `stun:13.140.43.187:3478`
- **TURN UDP/TCP**: `turn:369app.net.ar:3478` / `turn:13.140.43.187:3478` (con autenticación HMAC-SHA1 de tiempo limitado)
- **TURNS SSL (TLS Cifrado)**: `turns:369app.net.ar:5349?transport=tcp` / `turns:13.140.43.187:5349?transport=tcp`

---

## 6. Referencia de Métodos de la Clase Principal (Peer369)

### `async open(): Promise<void>`
Conecta al cliente con el servidor de señalización WebSocket y registra el `peer.id`.

### `call(peerId: string, stream: MediaStream, options?: object): MediaConnection`
Inicia una videollamada bidireccional en alta calidad hacia `peerId`.

### `callReceiveOnly(peerId: string, options?: object): MediaConnection`
Inicia una llamada en modo unidireccional (el iniciador solo recibe video del remoto sin enviar stream local).

### `connect(peerId: string, options?: object): DataConnection`
Abre un canal de datos P2P. Opciones de `serialization`: `'binary'`, `'json'`, `'raw'`, `'binary-utf8'`.

### `setQualityPreset(presetName: string): boolean`
Cambia dinámicamente la calidad y bitrate en todas las conexiones activas (`'720p'`, `'1080p'`, `'2k'`, `'4k'`).

### `setBitrate(bitrateKbps: number): void`
Ajusta el ancho de banda objetivo en kilobits por segundo (ej. `25000` para 25 Mbps) en caliente sin reconectar.

### `async getUserMedia(constraints?: object | string): Promise<MediaStream>`
Captura audio y video de la cámara/micrófono con manejo mejorado de errores en español. Acepta un objeto de restricciones o un string con el preset (ej. `peer.getUserMedia('4k')`).

### `async getDevices(): Promise<{ videoinput: Array, audioinput: Array, audiooutput: Array }>`
Enumeración segura de cámaras, micrófonos y altavoces disponibles.

### `async switchCamera(deviceId: string): Promise<MediaStream>`
Alterna en tiempo real la cámara en uso en todas las transmisiones activas sin cortar la llamada.

### `disconnect(): void`
Desconecta limpiamente el socket de señalización manteniendo activas las conexiones WebRTC P2P existentes.

### `destroy(): void`
Cierra todas las conexiones P2P, destruye los transceptores y libera los recursos de la instancia.

---

## 7. Referencia de Métodos y Eventos de MediaConnection

Representa una conexión de audio/video.

### Métodos Principales:
- `answer(stream?: MediaStream): void`: Responde a una llamada entrante.
- `setBitrate(bitrateKbps: number): Promise<void>`: Cambia el bitrate de esta conexión específica.
- `setQuality(presetName: string): Promise<void>`: Aplica un preset específico a esta llamada.
- `replaceStream(newStream: MediaStream): void`: Sustituye el stream local en vivo.
- `attachStatsHUD(videoElement: HTMLVideoElement): Function`: Adjunta un HUD flotante en pantalla que muestra resolución, FPS, bitrate, latencia y codec. Devuelve una función para removerlo.
- `close(): void`: Finaliza la videollamada.

### Eventos:
- `'stream' (remoteStream: MediaStream)`: Se emite al recibir el flujo de video/audio remoto.
- `'connected'`: Se emite cuando el handshake ICE completa con éxito.
- `'close'`: Se emite al cerrarse la llamada.
- `'error' (err: Error)`: Se emite en caso de error WebRTC.

---

## 8. Referencia de Métodos y Eventos de DataConnection

Representa un canal de datos P2P (`RTCDataChannel`).

### Métodos Principales:
- `send(data: any): void`: Envía datos. Para objetos se usa JSON; para archivos/blobs se aplica chunking binario automático de 16 KB.
- `close(): void`: Cierra el DataChannel.

### Eventos:
- `'open'`: Canal listo para transmisión de datos.
- `'data' (data: any)`: Recibe datos procesados (Strings, Objetos JSON o Blobs/ArrayBuffers).
- `'close'`: Canal cerrado.
- `'error' (err: Error)`: Error en la conexión de datos.

---

## 9. Monitor de Calidad Real-Time en Pantalla (attachStatsHUD)

Para verificar y mostrar en pantalla que la transmisión corre a la resolución y tasa real (ej. 4K 60fps 35Mbps):

```javascript
call.on('stream', (remoteStream) => {
  const videoElement = document.getElementById('remoteVideo');
  videoElement.srcObject = remoteStream;

  // Adjuntar HUD flotante con telemetría en vivo
  const detachHUD = call.attachStatsHUD(videoElement);

  // Para desadjuntar posteriormente:
  // detachHUD();
});
```

---

## 10. Transmisión de Pantalla 4K Nativa (Screen Sharing)

Ejemplo completo para compartir pantalla con máxima nitidez de texto y cero desenfoque:

```javascript
import Peer369 from 'https://369peerjs.net.ar/369peer.js';

const peer = new Peer369('emisor-pantalla', {
  preset: '4k',
  videoFormat: 'VP9',
  degradationPreference: 'maintain-resolution'
});

async function iniciarCompartirPantalla(receptorId) {
  try {
    const screenStream = await navigator.mediaDevices.getDisplayMedia({
      video: {
        width: { ideal: 3840, max: 3840 },
        height: { ideal: 2160, max: 2160 },
        frameRate: { ideal: 60, max: 60 },
        displaySurface: 'monitor'
      },
      audio: true
    });

    const call = peer.call(receptorId, screenStream);

    call.on('connected', () => {
      console.log('🚀 Transmisión de pantalla 4K iniciada hacia:', receptorId);
    });

    // Detectar cuando el usuario hace clic en "Detener presentación"
    screenStream.getVideoTracks()[0].onended = () => {
      call.close();
    };
  } catch (err) {
    console.error('❌ Error capturando pantalla:', err);
  }
}
```

---

## 11. Integración Autónoma para Broadcast (OBS Studio & vMix)

Plantilla HTML transparente para recibir transmisiones en **OBS Studio (Browser Source)** o **vMix (Web Input)** sin intervención del usuario:

```html
<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <title>Receptor OBS / vMix</title>
  <style>
    * { margin: 0; padding: 0; }
    html, body { width: 100%; height: 100%; background: transparent; overflow: hidden; }
    video { width: 100%; height: 100%; object-fit: contain; background: #000; }
  </style>
  <script src="https://369peerjs.net.ar/369peer.min.js"></script>
</head>
<body>
  <video id="broadcastVideo" autoplay playsinline muted></video>

  <script>
    // Leer ID de la URL: receptor-obs.html?peerId=CAM_01&preset=4k
    const params = new URLSearchParams(window.location.search);
    const peerId = params.get('peerId') || 'OBS_CAM';
    const preset = params.get('preset') || '4k';

    const peer = new Peer369(peerId, {
      preset: preset,
      videoFormat: 'VP9',
      degradationPreference: 'maintain-resolution'
    });

    peer.open();

    peer.on('call', (call) => {
      call.answer(); // Responde automáticamente
      call.on('stream', (stream) => {
        const v = document.getElementById('broadcastVideo');
        v.srcObject = stream;
        v.play().catch(e => console.log('Autoplay:', e));
      });
    });
  </script>
</body>
</html>
```

---

## 12. Transferencia de Archivos Grandes mediante DataChannel Binario

Ejemplo para enviar archivos de cualquier tamaño sin bloquear el hilo del navegador:

```javascript
// Emisor
const dataConn = peer.connect('receptor-id', {
  serialization: 'binary',
  reliable: true
});

dataConn.on('open', () => {
  const fileInput = document.getElementById('fileInput');
  const file = fileInput.files[0];
  dataConn.send(file);
});

// Receptor
peer.on('connection', (conn) => {
  conn.on('data', (data) => {
    if (data instanceof Blob) {
      const downloadUrl = URL.createObjectURL(data);
      const a = document.createElement('a');
      a.href = downloadUrl;
      a.download = 'archivo_recibido';
      a.click();
    }
  });
});
```

---

## 13. Solución de Problemas Frecuentes y Patrones para IA

### Reglas para Agentes de IA que escriban código con 369peerjs:
1. **Siempre instanciar Peer369 con `new Peer369(...)`**: Asegurarse de que el script incluya `https://369peerjs.net.ar/369peer.min.js`.
2. **Usar `preset: '4k'` o `setBitrate(...)` para streaming HD**: Nunca asumir que WebRTC ajustará el bitrate por sí solo; usar siempre los métodos de bitrate explícitos de 369peerjs.
3. **Escuchar el evento `open` antes de llamar**: Verificar que `peer.isOpen` sea `true` o esperar a `peer.on('open', ...)` antes de invocar `peer.call()` o `peer.connect()`.
4. **Manejar llamadas entrantes con `peer.on('call', ...)`**: En el receptor, siempre invocar `call.answer(localStream)` o `call.answer()` (si solo es recepción) para completar el ciclo SDP.
5. **No usar `b=AS:` manual**: La librería ya incluye munging SDP dual (`b=AS:` y `b=TIAS:`) en `Negotiator.js`. No manipules la cadena SDP manualmente.
6. **ICE Restart Automático y Resiliencia**: La librería detecta automáticamente cambios de interfaz de red (WiFi a 4G/5G, desconexión temporal de router, cambio de IP o reconexión de WebSocket) y ejecuta un **ICE Restart automático**, preservando el `RTCPeerConnection`, los `MediaStream` y tracks activos sin cerrar la llamada ni cortar el reproductor de video. Puedes escuchar los eventos `call.on('iceRestarting', ...)` y `call.on('iceRestartSuccess', ...)`.

---

## 13.1. Detección y Reconexión Automática con ICE Restart

Cuando un dispositivo cambia de red (ej. de WiFi a datos móviles) o experimenta una pérdida momentánea de conectividad:

1. **Detección Inmediata**: El motor monitorea `pc.oniceconnectionstatechange`, `pc.onconnectionstatechange`, los eventos de red `navigator.connection.onchange` y `window.ononline`.
2. **Preservación Total**: La instancia existente de `RTCPeerConnection` y todos los tracks (`MediaStreamTrack`) locales y remotos se mantienen activos. El elemento `<video>` en el DOM no parpadea ni se interrumpe.
3. **Renegociación SDP Segura**: Se envía una oferta con credenciales ICE frescas (`ufrag`/`pwd`). Los eventos de colisión (Glare) se resuelven de forma transparente sin lanzar excepciones.
4. **Métodos y Eventos Disponibles**:
   - `call.restartIce([options])` / `conn.restartIce([options])`: Dispara un reinicio manual de ICE si es necesario.
   - `peer.restartIce([peerId, options])`: Reinicia ICE en todas las conexiones activas o en un peer específico.
   - Eventos en conexión: `'iceRestarting'`, `'iceRestartSuccess'`, `'iceDisconnected'`, `'iceFailed'`, `'reconnected'`.

---

## 14. Créditos, Autoría y Contacto

La librería **369peerjs** ha sido ideada, diseñada y desarrollada por:

**Mgter. Mauro Germán Rodríguez**
- **Analista en Sistemas** y Desarrollador de Software de Medición
- **Diplomado en Master de Comunicación** (BBC Londres, CNN, UNINORTE)
- **Periodista & Cineasta**
- **Consultor Político & Ex Docente Académico**
- **Ex Director de Postgrado** Master en Periodismo UNINORTE
- **Especialista en Neurociencias y Comportamiento Humano**

> *Trayectoria*: En medios de comunicación desde 1990. Desde el año 2005 dedicado al estudio de las conductas humanas, incursionando en las neurociencias, programación neurolingüística (PNL) y comunicación no verbal, desarrollando técnicas y software propios para encuestas y mediciones.

### Canales Oficiales y Contacto:
- **Instagram**: [@maurogerman_ok](https://instagram.com/maurogerman_ok)
- **Facebook**: [facebook.com/maurogermanrodriguez](https://www.facebook.com/maurogermanrodriguez/)
- **Contacto Directo / WhatsApp**: `+54 9 3795 584082`