Blog

WebRTC in Node.js: signaling, peer e i pacchetti npm

· Andrij Tkachenko · 11 min di lettura

Una finestra del browser con una persona in video accanto a un server segnato da un esagono, con pacchetti dell’immagine che passano lungo una linea tratteggiata fino al server e ritorno

Node.js non ha un WebRTC suo: ha un client WebSocket integrato, ma nessun RTCPeerConnection. Per questo Node.js partecipa a una chiamata in uno di due modi: o come server di signaling che passa offerte e indirizzi tra due browser, e per questo basta una libreria websocket, o come peer a sé con un pacchetto npm che porta con sé lo stack WebRTC.

Questo articolo mostra dove serve l’uno e dove l’altro, tre pacchetti che fanno di Node.js un peer e cosa ognuno consegna al tuo codice, due brevi programmi provati con Chromium, e poi come un’app Express aggiunge chiamate tra i suoi utenti senza nessuno dei due.

I due ruoli di Node.js in una chiamata

Ruolo Chi porta i media Cosa serve
Server di signaling I due browser Una libreria websocket, come ws
Peer nella chiamata Node.js stesso Un pacchetto WebRTC da npm

Esegui node -e "console.log(typeof RTCPeerConnection, typeof WebSocket)" su Node.js 22 e stampa undefined function. L’API del browser che porta le chiamate non c’è, quindi il codice scritto per il browser non può semplicemente girare sul server.

Per una videochat tra gli utenti di un’app web, al server non serve nulla di tutto ciò. La chiamata va da browser a browser, e Node.js li aiuta solo a trovarsi: come WebRTC collega due browser contiene tutto quel relay in Node.js con il pacchetto ws, e la pagina che lo usa. Il relay è la parte facile. Far squillare la persona in ogni scheda che ha aperto non lo è, perché serve una connessione tenuta aperta per ogni utente, e appena fai girare più di un processo quelle connessioni si dividono tra loro (i websocket in Node.js oltre un solo server spiega cosa richiede).

Un peer serve ai programmi che hanno bisogno dei media o del canale stessi: un registratore, un bot che entra in una chiamata, un test che ne avvia una da uno script, un server di gioco che parla con ogni giocatore su un data channel.

I pacchetti npm che fanno di Node.js un peer

Ognuno di questi è open source e dà a Node.js il RTCPeerConnection del browser, con l’offerta, la risposta e i candidati scambiati come in un browser. Si distinguono per ciò su cui sono costruiti, e quindi per ciò che riceve il tuo codice:

Pacchetto Cosa ricevi
werift 0.28 Media come pacchetti RTP, data channel
node-datachannel 0.33 Data channel, e un suo WebSocket
@roamhq/wrtc 0.10 Immagini e suono decodificati, data channel

Cosa dice ognuno di sé, e cosa abbiamo visto facendoli girare:

  • werift è scritto in TypeScript, richiede Node.js 22 o successivo e non installa nulla di nativo. Ti consegna ogni pacchetto del video appena arriva, ancora codificato, e invia i pacchetti che gli dai. È ciò che serve per inoltrare, ed è così che funziona un media server per le chiamate di gruppo: passa il video senza mai decodificarlo (come funzionano le videochiamate di gruppo).
  • node-datachannel collega libdatachannel, una piccola libreria C++, con binari precompilati per Linux, macOS e Windows su Node.js 18.20 o successivo. Il suo export node-datachannel/polyfill dà l’API del browser, e il suo README elenca un client e un server WebSocket propri, per il signaling.
  • @roamhq/wrtc è un fork del vecchio progetto node-webrtc, con binding alla release 106 della libreria WebRTC di Google, del 2022, e binari precompilati per Linux e macOS su x64 e arm64, e per Windows su x64. Accanto all’API standard ha sink e sorgenti non standard: gli abbiamo fatto ricevere la fotocamera di un browser e ci ha dato ogni immagine decodificata, 640 per 480, come byte grezzi.

La scelta segue dal compito. Per passare i media oltre, o registrarli così come arrivano, bastano i pacchetti. Per leggere cosa c’è nell’immagine, o disegnarci sopra, ti serve decodificata, al costo del lavoro della CPU per ogni fotogramma. Per i soli dati basta una piccola libreria.

Node.js come peer: un video che torna indietro

Il programma qui sotto risponde a un browser con werift e gli rimanda subito il suo video, con ogni pacchetto che passa per Node.js senza essere decodificato (npm install werift). Usa il modulo http di Node.js per l’unica richiesta di cui lo scambio ha bisogno:

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 }) => {
    // Ogni pacchetto del video del browser torna subito indietro, mai decodificato.
    track.onReceiveRtp.subscribe((rtp) => transceiver.sender.sendRtp(rtp));
    // Chiede di tanto in tanto al browser un’immagine completa, così l’altro lato può iniziare a disegnare.
    const timer = setInterval(() => transceiver.receiver.sendRtcpPLI(track.ssrc), 3000);
    pc.onconnectionstatechange = () => {
      if (['failed', 'closed'].includes(pc.connectionState)) clearInterval(timer);
    };
  };

  await pc.setRemoteDescription(offer);
  // Invia oltre a ricevere sulla linea video offerta dal browser.
  for (const transceiver of pc.getTransceivers()) transceiver.direction = 'sendrecv';
  await pc.setLocalDescription(await pc.createAnswer());

  // Aspetta tutti i candidati, così entrano tutti nell’unica risposta.
  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 pagina e il suo script, dalla cartella 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 pagina va in static/index.html, con due elementi video e lo 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]);
};

// Il lato Node.js accetta un’offerta sola con tutti i candidati dentro, quindi aspettali tutti.
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());

Esegui node echo.mjs e apri http://localhost:8081/. Il browser chiede la fotocamera, e un attimo dopo il secondo video mostra il primo, di ritorno da Node.js. L’abbiamo provato in Chromium con una fotocamera finta: l’immagine tornava larga 640 pixel, e il numero di immagini disegnate continuava a salire, circa 20 al secondo.

Tre righe ci sono per un motivo:

  1. La direzione. Una risposta fatta senza una traccia propria riceve soltanto, quindi il programma imposta la linea video su sendrecv prima di rispondere. Senza quella riga il browser non riceveva nulla indietro.
  2. La richiesta di un’immagine completa. Il video viene inviato per lo più come differenze rispetto all’immagine precedente. Un programma che non decodifica nulla non può creare da sé un’immagine completa, quindi di tanto in tanto ne chiede una a chi invia, e così l’altro lato può iniziare, o riprendersi dopo un pacchetto perso. I media server fanno lo stesso.
  3. Una sola richiesta è tutto lo scambio. Il browser invia tutti i candidati nella sua offerta e Node.js tutti i candidati nella sua risposta, quindi basta una semplice POST, e per questo programma non serve nessun websocket.

Node.js come peer: un data channel

Un data channel non ha bisogno di nessun media. Con node-datachannel (npm install node-datachannel), il server qui sotto risponde a un browser su un canale non ordinato che non ripete mai l’invio, il tipo che un gioco usa per le posizioni, dove un messaggio in ritardo vale meno del successivo:

JavaScript
// channel.mjs: lo stesso server di echo.mjs, con questo al posto del suo import e di answer()
import { RTCPeerConnection } from 'node-datachannel/polyfill';

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

  pc.ondatachannel = ({ channel }) => {
    channel.onmessage = ({ data }) => {
      // Risponde subito a ogni messaggio, con l’orologio del server.
      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());

  // Aspetta tutti i candidati, così entrano tutti nell’unica risposta.
  await new Promise((resolve) => {
    if (pc.iceGatheringState === 'complete') return resolve();
    pc.onicegatheringstatechange = () => pc.iceGatheringState === 'complete' && resolve();
  });
  return pc.localDescription;
}

La pagina apre il canale e misura ogni andata e ritorno:

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

// Non ordinato, mai reinviato: un messaggio in ritardo vale meno del successivo.
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 += `andata e ritorno ${Math.round(performance.now() - sent)} ms\n`;
};

// Invia un’offerta sola con tutti i candidati dentro, perché il server risponde una volta.
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());

Il suo static/index.html è un <pre id="log"></pre> e un tag script per /channel.js. Su una sola macchina in Chromium, ogni andata e ritorno richiedeva da 1 a 4 millisecondi. Su una rete vera è il tempo del percorso stesso, senza nessun messaggio trattenuto dietro uno andato perso, cosa che un websocket su TCP non può promettere.

Su un tuo server, entrambi i programmi hanno bisogno di ciò che serve a qualsiasi peer: un server STUN per conoscere il proprio indirizzo pubblico, e un server TURN per chi sta dietro reti rigide, indicati in new RTCPeerConnection({ iceServers: [...] }) (i server STUN e TURN, spiegati). Perché la fotocamera si apra, la pagina deve essere su localhost o in HTTPS. Se una chiamata non si collega, perché una connessione WebRTC non riesce passa in rassegna cosa controllare.

Quale ti serve

  • I tuoi utenti si chiamano tra loro. Node.js è il server di signaling, oppure lo lascia a un servizio. I browser portano la chiamata, e il tuo server decide chi può chiamare chi.
  • Un programma entra nella chiamata. Un registratore, un bot, un test, una fotocamera su un piccolo dispositivo: Node.js è un peer, con il pacchetto che ti consegna i media nella forma che ti serve, e lo fai girare su server tuoi.
  • Il tuo server parla con ogni browser con il ritardo più basso. Un data channel verso un peer Node.js, per giochi e controlli dal vivo, accanto a un websocket o al suo posto.

La stessa divisione vale in altri linguaggi: WebRTC in Python è questo articolo per Python, con aiortc come peer. La maggior parte delle app web ha bisogno del primo, e il lavoro sta meno nel relay che in ciò che gli sta intorno: lo squillo in ogni scheda, i relay, la riconnessione quando un telefono cambia rete, e le chiamate di gruppo oltre le quattro persone.

Chiamate in Express e Node.js con WordPlus Cloud

Con il pacchetto @wordplus/realtime, un’app Node.js avvia chiamate tra i suoi utenti senza un server di signaling, un relay o una schermata di chiamata da scrivere, e senza un peer proprio da far girare. La tua app decide chi può chiamare in una sua route, che risponde con un token per la chiamata. In Express:

JavaScript
// server.mjs: GET /call-token?to=34&type=video, che il pulsante chiede quando viene premuto.
app.get('/call-token', async (req, res) => {
  // Qui va il tuo controllo: chi può chiamare chi.
  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 pagina avvia la schermata di chiamata e mette un pulsante dove le persone chiamano, che chiede il token alla tua route:

JavaScript
await rt.callScreen(); // lo squillo e la finestra di chiamata, su ogni pagina dove una chiamata può squillare
HTML
<call-button to="34" token-url="/call-token" type="video" name="Ann">Call Ann</call-button>

La chiamata squilla in ogni scheda e su ogni dispositivo che Ann ha aperto. Va direttamente tra i due browser quando le loro reti lo consentono, attraverso i nostri relay sulle porte 443 e 80 quando non lo consentono, e attraverso i nostri media server quando nemmeno i relay arrivano, passando dall’uno all’altro senza riagganciare. Le chiamate tra due persone sono cifrate end-to-end su ogni percorso, e le chiamate di gruppo girano sugli stessi server. Senza un token dalla tua route non parte nulla, quindi nessuno può aggirarla.

La pagina sulle chiamate della guida Express mostra il resto: chi può chiamare, le chiamate di gruppo con un host e un’interfaccia di chiamata tutta tua. Lo stesso pacchetto funziona in un semplice server Node.js, in Fastify o in Hono.

Videochiamate per la tua app Node.js

WordPlus Cloud for Apps ha un prezzo in base alle connessioni simultanee, a partire da 1.000, con fatturazione mensile o annuale, e le chiamate tra due persone non consumano crediti su nessun percorso. Scopri videochiamate e chiamate di gruppo per le app, oppure i prezzi per le app. Domande sulla tua integrazione? Scrivici.