Blog

WebRTC en Node.js: señalización, participantes y paquetes npm

· Andrij Tkachenko · 11 min de lectura

Una ventana de navegador con una persona en vídeo junto a un servidor marcado con un hexágono, con paquetes de la imagen que van por una línea discontinua hasta el servidor y vuelven

Node.js no tiene WebRTC propio: trae un cliente WebSocket integrado, pero no RTCPeerConnection. Así que Node.js participa en una llamada de una de dos formas: como el servidor de señalización que pasa las ofertas y las direcciones entre dos navegadores, para lo que basta una biblioteca de websockets, o como un participante más, con un paquete de npm que trae consigo la pila de WebRTC.

Este artículo muestra dónde encaja cada una, tres paquetes que convierten a Node.js en participante y lo que cada uno le entrega a tu código, dos programas cortos probados con Chromium y, después, cómo una app de Express añade llamadas entre sus usuarios sin ninguno de ellos.

Los dos papeles de Node.js en una llamada

Papel Quién lleva el medio Qué necesita Node.js
Señalización Los dos navegadores Una biblioteca de websockets, como ws
Participante El propio Node.js Un paquete WebRTC de npm

Ejecuta node -e "console.log(typeof RTCPeerConnection, typeof WebSocket)" en Node.js 22 e imprime undefined function. La API del navegador que lleva las llamadas no está, así que el código escrito para el navegador no puede ejecutarse tal cual en el servidor.

Para un videochat entre los usuarios de una app web, el servidor no necesita nada de eso. La llamada va de navegador a navegador, y Node.js solo les ayuda a encontrarse: cómo conecta WebRTC dos navegadores tiene ese relé entero en Node.js con el paquete ws, y la página que lo usa. El relé es la parte fácil. Hacer sonar el timbre en cada pestaña que la persona tenga abierta no lo es, porque necesita una conexión abierta para cada usuario, y en cuanto ejecutas más de un proceso esas conexiones quedan repartidas entre ellos (websockets en Node.js más allá de un servidor repasa lo que hace falta).

Un participante es para programas que necesitan el propio medio o el propio canal: una grabadora, un bot que entra en una llamada, una prueba que hace una llamada desde un script, un servidor de juego que habla con cada jugador por un canal de datos.

Los paquetes de npm que convierten a Node.js en participante

Todos son de código abierto y dan a Node.js el RTCPeerConnection del navegador, con la oferta, la respuesta y los candidatos intercambiados como en un navegador. Se diferencian en aquello sobre lo que están construidos, y por tanto en lo que recibe tu código:

Paquete Qué recibe tu código
werift 0.28 Medio en paquetes RTP, canales de datos
node-datachannel 0.33 Canales de datos, y su propio WebSocket
@roamhq/wrtc 0.10 Imagen y sonido decodificados, canales de datos

Lo que dice cada uno de sí mismo, y lo que vimos al ejecutarlos:

  • werift está escrito en TypeScript, necesita Node.js 22 o posterior y no instala nada nativo. Te entrega cada paquete del vídeo según llega, todavía codificado, y envía los paquetes que le das. Eso es lo que necesita el reenvío, y así funciona un servidor multimedia para llamadas en grupo: pasa el vídeo sin decodificarlo nunca (cómo funcionan las videollamadas en grupo).
  • node-datachannel enlaza libdatachannel, una pequeña biblioteca en C++, con binarios precompilados para Linux, macOS y Windows en Node.js 18.20 o posterior. Su export node-datachannel/polyfill da la API del navegador, y su README enumera un cliente y un servidor WebSocket propios, para la señalización.
  • @roamhq/wrtc es un fork del antiguo proyecto node-webrtc, con bindings a la versión 106 de la biblioteca WebRTC de Google, de 2022, y binarios precompilados para Linux y macOS en x64 y arm64, y para Windows en x64. Además de la API estándar tiene sinks y sources no estándar: le hicimos recibir la cámara de un navegador y nos dio cada imagen decodificada, de 640 por 480, como bytes en bruto.

La elección sale del trabajo. Para pasar el medio a otro, o grabarlo tal como llegó, bastan los paquetes. Para leer lo que hay en la imagen, o dibujar sobre ella, la necesitas decodificada, a costa del trabajo de CPU de cada imagen. Para datos solos, una biblioteca pequeña lo hace.

Node.js como participante: un vídeo que vuelve

El programa de abajo responde a un navegador con werift y le devuelve su vídeo directamente, con cada paquete pasando por Node.js sin decodificarse (npm install werift). Usa el módulo http de Node.js para la única petición que necesita el intercambio:

echo.mjs
import http from 'node:http';
import { readFile } from 'node:fs/promises';
import { RTCPeerConnection } from 'werift';

async function answer(offer) {
  const pc = new RTCPeerConnection();

  pc.ontrack = ({ track, transceiver }) => {
    // Cada paquete del vídeo del navegador vuelve directamente, sin decodificarse nunca.
    track.onReceiveRtp.subscribe((rtp) => transceiver.sender.sendRtp(rtp));
    // Pide al navegador una imagen completa de vez en cuando, para que el otro lado pueda empezar a dibujar.
    const timer = setInterval(() => transceiver.receiver.sendRtcpPLI(track.ssrc), 3000);
    pc.onconnectionstatechange = () => {
      if (['failed', 'closed'].includes(pc.connectionState)) clearInterval(timer);
    };
  };

  await pc.setRemoteDescription(offer);
  // Envía además de recibir en la línea de vídeo que ofreció el navegador.
  for (const transceiver of pc.getTransceivers()) transceiver.direction = 'sendrecv';
  await pc.setLocalDescription(await pc.createAnswer());

  // Espera a todos los candidatos, para que vayan todos en la única respuesta.
  await new Promise((resolve) => {
    if (pc.iceGatheringState === 'complete') return resolve();
    pc.onicegatheringstatechange = () => pc.iceGatheringState === 'complete' && resolve();
  });
  return pc.localDescription;
}

http.createServer(async (req, res) => {
  if (req.method === 'POST' && req.url === '/offer') {
    let body = '';
    for await (const chunk of req) body += chunk;
    res.setHeader('Content-Type', 'application/json');
    return res.end(JSON.stringify(await answer(JSON.parse(body))));
  }
  // La página y su script, desde la carpeta static.
  const file = req.url === '/' ? 'index.html' : req.url.slice(1);
  try {
    const body = await readFile(new URL(`./static/${file}`, import.meta.url));
    res.setHeader('Content-Type', file.endsWith('.js') ? 'text/javascript' : 'text/html');
    res.end(body);
  } catch {
    res.statusCode = 404;
    res.end();
  }
}).listen(8081);

La página va en static/index.html, con dos elementos de vídeo y el script:

HTML
<video id="me" autoplay playsinline muted></video>
<video id="back" autoplay playsinline></video>
<script type="module" src="/mirror.js"></script>
static/mirror.js
const local = await navigator.mediaDevices.getUserMedia({ video: true });
document.getElementById('me').srcObject = local;

const pc = new RTCPeerConnection();
pc.addTrack(local.getVideoTracks()[0], local);
pc.ontrack = ({ track }) => {
  document.getElementById('back').srcObject = new MediaStream([track]);
};

// El lado de Node.js acepta una sola oferta con todos los candidatos dentro, así que espera a tenerlos todos.
await pc.setLocalDescription(await pc.createOffer());
await new Promise((resolve) => {
  if (pc.iceGatheringState === 'complete') return resolve();
  pc.addEventListener('icegatheringstatechange', () => {
    if (pc.iceGatheringState === 'complete') resolve();
  });
});

const response = await fetch('/offer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(pc.localDescription),
});
await pc.setRemoteDescription(await response.json());

Ejecuta node echo.mjs y abre http://localhost:8081/. El navegador pide la cámara, y un momento después el segundo vídeo muestra el primero, de vuelta desde Node.js. Lo probamos en Chromium con una cámara simulada: la imagen volvió con 640 píxeles de ancho, y el número de imágenes dibujadas siguió subiendo, unas 20 por segundo.

Hay tres líneas en él que tienen su motivo:

  1. La dirección. Una respuesta creada sin pista propia solo recibe, así que el programa cambia la línea de vídeo a sendrecv antes de responder. Sin esa línea, el navegador no recibía nada de vuelta.
  2. La petición de una imagen completa. El vídeo se envía sobre todo como cambios respecto a la imagen anterior. Un programa que no decodifica nada no puede crear él mismo una imagen completa, así que se la pide al emisor de vez en cuando, y eso permite al otro lado empezar, o recuperarse tras un paquete perdido. Los servidores multimedia hacen lo mismo.
  3. Una sola petición es todo el intercambio. El navegador envía todos sus candidatos en la oferta y Node.js todos los suyos en la respuesta, así que basta con un POST normal, y este programa no necesita ningún websocket.

Node.js como participante: un canal de datos

Un canal de datos no necesita ningún medio. Con node-datachannel (npm install node-datachannel), el servidor de abajo responde a un navegador por un canal sin orden que nunca reenvía, el tipo que usa un juego para las posiciones, donde un mensaje que llega tarde vale menos que el siguiente:

JavaScript
// channel.mjs: el mismo servidor que echo.mjs, con esto en lugar de su import y de answer()
import { RTCPeerConnection } from 'node-datachannel/polyfill';

async function answer(offer) {
  const pc = new RTCPeerConnection();

  pc.ondatachannel = ({ channel }) => {
    channel.onmessage = ({ data }) => {
      // Responde a cada mensaje en el acto, con el reloj del servidor.
      const { sent } = JSON.parse(data);
      channel.send(JSON.stringify({ sent, server: Date.now() }));
    };
  };
  pc.onconnectionstatechange = () => {
    if (['failed', 'closed'].includes(pc.connectionState)) pc.close();
  };

  await pc.setRemoteDescription(offer);
  await pc.setLocalDescription(await pc.createAnswer());

  // Espera a todos los candidatos, para que vayan todos en la única respuesta.
  await new Promise((resolve) => {
    if (pc.iceGatheringState === 'complete') return resolve();
    pc.onicegatheringstatechange = () => pc.iceGatheringState === 'complete' && resolve();
  });
  return pc.localDescription;
}

La página abre el canal y mide cada ida y vuelta:

static/channel.js
const pc = new RTCPeerConnection();

// Sin orden y sin reenvíos: un mensaje que llega tarde vale menos que el siguiente.
const channel = pc.createDataChannel('state', { ordered: false, maxRetransmits: 0 });
channel.onopen = () => {
  setInterval(() => channel.send(JSON.stringify({ sent: performance.now() })), 1000);
};
channel.onmessage = ({ data }) => {
  const { sent } = JSON.parse(data);
  document.getElementById('log').textContent += `ida y vuelta ${Math.round(performance.now() - sent)} ms\n`;
};

// Envía una sola oferta con todos los candidatos dentro, ya que el servidor responde una vez.
await pc.setLocalDescription(await pc.createOffer());
await new Promise((resolve) => {
  if (pc.iceGatheringState === 'complete') return resolve();
  pc.addEventListener('icegatheringstatechange', () => {
    if (pc.iceGatheringState === 'complete') resolve();
  });
});

const response = await fetch('/offer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(pc.localDescription),
});
await pc.setRemoteDescription(await response.json());

Su static/index.html es un <pre id="log"></pre> y una etiqueta script para /channel.js. En una sola máquina con Chromium, cada ida y vuelta tardó de 1 a 4 milisegundos. En una red real es el tiempo del propio camino, sin ningún mensaje retenido detrás de uno que se perdió, algo que un websocket sobre TCP no puede prometer.

En un servidor tuyo, los dos programas necesitan lo que necesita cualquier participante: un servidor STUN para conocer su dirección pública, y un servidor TURN para la gente detrás de redes estrictas, indicados en new RTCPeerConnection({ iceServers: [...] }) (los servidores STUN y TURN, explicados). La página tiene que estar en localhost o en HTTPS para que se abra la cámara. Si una llamada no conecta, por qué falla una conexión WebRTC repasa qué comprobar.

Cuál necesitas

  • Tus usuarios se llaman entre sí. Node.js es el servidor de señalización, o deja eso a un servicio. Los navegadores llevan la llamada, y tu servidor decide quién puede llamar a quién.
  • Un programa entra en la llamada. Una grabadora, un bot, una prueba, una cámara en un dispositivo pequeño: Node.js es participante, con el paquete que te entrega el medio en la forma que necesitas, y lo ejecutas en servidores tuyos.
  • Tu servidor habla con cada navegador con el menor retardo. Un canal de datos con un participante de Node.js, para juegos y controles en directo, junto a un websocket o en su lugar.

La misma división vale en otros lenguajes: WebRTC en Python es este artículo para Python, con aiortc como participante. La mayoría de las apps web necesitan lo primero, y el trabajo no está tanto en el relé como en lo que lo rodea: el timbre en cada pestaña, los relés, reconectar cuando un teléfono cambia de red y las llamadas en grupo de más de cuatro personas.

Llamadas en Express y Node.js con WordPlus Cloud

Con el paquete @wordplus/realtime, una app de Node.js hace llamadas entre sus usuarios sin servidor de señalización, relé ni pantalla de llamada que escribir, y sin ningún participante propio que ejecutar. Tu app decide quién puede llamar en una ruta propia, que responde con un token para la llamada. En Express:

JavaScript
// server.mjs: GET /call-token?to=34&type=video, que el botón pide al pulsarlo.
app.get('/call-token', async (req, res) => {
  // Aquí va tu propia comprobación: quién puede llamar a quién.
  const me = req.session.userId;
  if (!me) return res.sendStatus(401);
  res.json({ token: await realtime.callToken(me, req.query.to, { type: req.query.type }) });
});

La página inicia la pantalla de llamada y pone un botón allí desde donde la gente llama, que le pide el token a tu ruta:

JavaScript
await rt.callScreen(); // el timbre y la ventana de la llamada, en cada página en la que pueda sonar una llamada
HTML
<call-button to="34" token-url="/call-token" type="video" name="Ann">Call Ann</call-button>

La llamada suena en cada pestaña y en cada dispositivo que Ann tenga abierto. Va directamente entre los dos navegadores cuando sus redes lo permiten, a través de nuestros relés en los puertos 443 y 80 cuando no, y a través de nuestros servidores multimedia cuando ni siquiera los relés llegan, pasando de uno a otro sin colgar. Las llamadas entre dos personas están cifradas de extremo a extremo sea cual sea el camino, y las llamadas en grupo funcionan en los mismos servidores. Sin un token de tu ruta no empieza nada, así que nadie puede saltárselo.

La página de llamadas de la guía de Express muestra el resto: quién puede llamar, las llamadas en grupo con anfitrión y una interfaz de llamada propia. El mismo paquete funciona en un servidor Node.js puro, en Fastify o en Hono.

Videollamadas para tu app de Node.js

WordPlus Cloud for Apps tiene un precio según las conexiones simultáneas, a partir de 1.000, con facturación mensual o anual, y las llamadas entre dos personas no gastan créditos por ningún camino. Consulta las videollamadas y las llamadas en grupo para apps, o los precios para apps. ¿Preguntas sobre tu integración? Escríbenos.