Topologies: Mesh, SFU and MCU

// huddle-bandwidth.mjs - stream counts and bitrates per Huddle topology.
// Usage: node huddle-bandwidth.mjs [videoKbps] [audioKbps]
const videoKbps = Number(process.argv[2] ?? 1200); // one 720p camera layer
const audioKbps = Number(process.argv[3] ?? 40);   // one Opus stream
const simulcast = [150, 500, videoKbps];           // low, medium, high layers (kbit/s)
const media = videoKbps + audioKbps;

const mesh = (n) => ({ up: n - 1, down: n - 1, upKbps: (n - 1) * media, downKbps: (n - 1) * media, server: 0 });
const sfu = (n) => ({
  up: 1, down: n - 1,
  upKbps: simulcast.reduce((a, b) => a + b, 0) + audioKbps, // every layer is uploaded once
  downKbps: (n - 1) * media,                                  // one layer per remote peer
  server: n + n * (n - 1),                                    // n inbound, n*(n-1) outbound
});
const mcu = (n) => ({ up: 1, down: 1, upKbps: media, downKbps: media, server: 2 * n }); // n decoded, n mixed

const fmt = (k) => (k >= 1000 ? (k / 1000).toFixed(1) + ' Mbit/s' : Math.round(k) + ' kbit/s');
const rows = [];
for (const n of [2, 3, 4, 6, 8, 12, 25]) {
  for (const [name, f] of [['mesh', mesh], ['sfu', sfu], ['mcu', mcu]]) {
    const r = f(n);
    rows.push({ n, topology: name, 'up streams': r.up, 'down streams': r.down,
      uplink: fmt(r.upKbps), downlink: fmt(r.downKbps), 'server RTP streams': r.server });
  }
}
console.log(`video ${videoKbps} kbit/s, audio ${audioKbps} kbit/s, simulcast ${simulcast.join('/')}`);
console.table(rows);

video 1200 kbit/s, audio 40 kbit/s, simulcast 150/500/1200
 n  topology  up streams  down streams  uplink        downlink      server RTP streams
 4  mesh      3           3             3.7 Mbit/s    3.7 Mbit/s    0
 4  sfu       1           3             1.9 Mbit/s    3.7 Mbit/s    16
 4  mcu       1           1             1.2 Mbit/s    1.2 Mbit/s    8
 8  mesh      7           7             8.7 Mbit/s    8.7 Mbit/s    0
 8  sfu       1           7             1.9 Mbit/s    8.7 Mbit/s    64
 8  mcu       1           1             1.2 Mbit/s    1.2 Mbit/s    16
25  mesh      24          24            29.8 Mbit/s   29.8 Mbit/s   0
25  sfu       1           24            1.9 Mbit/s    29.8 Mbit/s   625
25  mcu       1           1             1.2 Mbit/s    1.2 Mbit/s    50

// huddle-mesh-server.mjs - static files plus a tiny room relay for Huddle mesh mode.
// Run: npm i ws && node huddle-mesh-server.mjs
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';
import { WebSocketServer } from 'ws';

const PORT = Number(process.env.PORT ?? 3000);
const MAX_MESH = 4;                       // Huddle refuses a fifth participant in mesh mode
const rooms = new Map();                  // room -> Map(peerId -> ws)

const http = createServer(async (req, res) => {
  if (req.url?.startsWith('/mesh')) {
    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
    res.end(await readFile(new URL('./huddle-mesh.html', import.meta.url)));
  } else { res.writeHead(404).end(); }
});

const wss = new WebSocketServer({ server: http, path: '/signal' });
wss.on('connection', (ws, req) => {
  const room = new URL(req.url, 'http://x').searchParams.get('room') ?? 'lobby';
  const peers = rooms.get(room) ?? new Map();
  rooms.set(room, peers);
  if (peers.size >= MAX_MESH) {
    ws.send(JSON.stringify({ type: 'full', max: MAX_MESH }));
    return ws.close(4403, 'mesh room full');
  }
  const id = randomUUID().slice(0, 8);
  ws.send(JSON.stringify({ type: 'welcome', id, peers: [...peers.keys()] }));
  for (const other of peers.values()) other.send(JSON.stringify({ type: 'peer-joined', id }));
  peers.set(id, ws);

  ws.on('message', (raw) => {
    const msg = JSON.parse(raw.toString());
    if (msg.type !== 'signal') return;
    peers.get(msg.to)?.send(JSON.stringify({ type: 'signal', from: id, data: msg.data }));
  });
  ws.on('close', () => {
    peers.delete(id);
    for (const other of peers.values()) other.send(JSON.stringify({ type: 'peer-left', id }));
    if (peers.size === 0) rooms.delete(room);
  });
});

http.listen(PORT, () => console.log(`huddle mesh signalling on http://localhost:${PORT}/mesh`));
export { http, wss };

<!doctype html>
<meta charset="utf-8">
<title>Huddle mesh</title>
<video id="local" autoplay muted playsinline></video>
<div id="remotes"></div>
<script type="module">
const room = new URLSearchParams(location.search).get('room') ?? 'lobby';
const ice = { iceServers: [{ urls: 'stun:stun.example.test:3478' }] };
const peers = new Map();                    // peerId -> RTCPeerConnection
let myId, ws, localStream;

localStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: { width: 640, height: 360 } });
document.getElementById('local').srcObject = localStream;

ws = new WebSocket(`ws://${location.host}/signal?room=${room}`);
const send = (to, data) => ws.send(JSON.stringify({ type: 'signal', to, data }));

function connect(remoteId, initiator) {
  const pc = new RTCPeerConnection(ice);
  peers.set(remoteId, pc);
  // one outgoing copy of the camera and microphone per remote peer: this is the N-1 uplink cost of mesh
  for (const track of localStream.getTracks()) pc.addTrack(track, localStream);
  pc.onicecandidate = ({ candidate }) => candidate && send(remoteId, { candidate });
  pc.ontrack = ({ streams: [stream] }) => {
    let el = document.getElementById('v-' + remoteId);
    if (!el) {
      el = Object.assign(document.createElement('video'), { id: 'v-' + remoteId, autoplay: true, playsInline: true });
      document.getElementById('remotes').append(el);
    }
    el.srcObject = stream;
  };
  if (initiator) {                          // the newcomer offers to everybody already present
    pc.onnegotiationneeded = async () => {
      await pc.setLocalDescription();
      send(remoteId, { description: pc.localDescription });
    };
  }
  return pc;
}

ws.onmessage = async ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.type === 'welcome') { myId = msg.id; msg.peers.forEach((id) => connect(id, true)); }
  else if (msg.type === 'peer-joined') connect(msg.id, false);
  else if (msg.type === 'peer-left') { peers.get(msg.id)?.close(); peers.delete(msg.id); document.getElementById('v-' + msg.id)?.remove(); }
  else if (msg.type === 'signal') {
    const pc = peers.get(msg.from) ?? connect(msg.from, false);
    const { description, candidate } = msg.data;
    if (description) {
      await pc.setRemoteDescription(description);
      if (description.type === 'offer') {
        await pc.setLocalDescription();
        send(msg.from, { description: pc.localDescription });
      }
    } else if (candidate) await pc.addIceCandidate(candidate);
  }
};

// Report what the mesh costs: outbound-rtp streams and bytes sent across all peer connections.
window.meshReport = async () => {
  let outVideo = 0, outAudio = 0, inVideo = 0, bytesSent = 0, connected = 0;
  for (const pc of peers.values()) {
    if (pc.connectionState === 'connected') connected++;
    for (const s of (await pc.getStats()).values()) {
      if (s.type === 'outbound-rtp') { s.kind === 'video' ? outVideo++ : outAudio++; bytesSent += s.bytesSent; }
      if (s.type === 'inbound-rtp' && s.kind === 'video') inVideo++;
    }
  }
  return { id: myId, peers: peers.size, connected, outVideo, outAudio, inVideo, bytesSent };
};
</script>

// run-mesh.mjs - starts the server, opens N headless Chrome pages and prints the mesh stream counts.
import puppeteer from 'puppeteer-core';
import { http } from './huddle-mesh-server.mjs';
const N = Number(process.argv[2] ?? 4);
const browser = await puppeteer.launch({
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  headless: true,
  args: ['--use-fake-device-for-media-stream', '--use-fake-ui-for-media-stream', '--no-first-run'],
});
const pages = [];
for (let i = 0; i < N; i++) {
  const page = await browser.newPage();
  await page.goto(`http://localhost:${process.env.PORT}/mesh?room=demo`);
  await page.waitForFunction(() => window.meshReport, { timeout: 15000 });
  pages.push(page);
  await new Promise((r) => setTimeout(r, 800));
}
await new Promise((r) => setTimeout(r, 4000));
for (const p of pages) console.log(JSON.stringify(await p.evaluate(() => window.meshReport())));
// a fifth participant is refused with close code 4403
const fifth = new WebSocket(`ws://localhost:${process.env.PORT}/signal?room=demo`);
await new Promise((r) => { fifth.onclose = (e) => { console.log('fifth peer closed:', e.code, e.reason); r(); }; });
await browser.close();
http.close();

huddle mesh signalling on http://localhost:3000/mesh
{"id":"3ea58c0e","peers":3,"connected":3,"outVideo":3,"outAudio":3,"inVideo":3,"bytesSent":556973}
{"id":"d73f023c","peers":3,"connected":3,"outVideo":3,"outAudio":3,"inVideo":3,"bytesSent":540712}
{"id":"bd66d342","peers":3,"connected":3,"outVideo":3,"outAudio":3,"inVideo":3,"bytesSent":509756}
{"id":"d88eef95","peers":3,"connected":3,"outVideo":3,"outAudio":3,"inVideo":3,"bytesSent":442184}
fifth peer closed: 4403 mesh room full

// huddle-simulcast-sender.mjs - the browser half of SFU mode: one camera, three RTP encodings.
// Runs in headless Chrome here; in Huddle the same code runs inside the page before the offer is sent to the SFU.
import puppeteer from 'puppeteer-core';
import { createServer } from 'node:http';

const server = createServer((_, res) => res.writeHead(200, { 'content-type': 'text/html' }).end('<!doctype html><title>x</title>'))
  .listen(Number(process.env.PORT ?? 41101));
const browser = await puppeteer.launch({
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
  headless: true,
  args: ['--use-fake-device-for-media-stream', '--use-fake-ui-for-media-stream'],
});
const page = await browser.newPage();
await page.goto(`http://localhost:${server.address().port}/`);
const result = await page.evaluate(async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: { width: 1280, height: 720 } });
  const pc = new RTCPeerConnection();
  const sender = pc.addTransceiver(stream.getVideoTracks()[0], {
    direction: 'sendonly',
    streams: [stream],
    sendEncodings: [
      { rid: 'q', scaleResolutionDownBy: 4, maxBitrate: 150_000 },   // 320x180
      { rid: 'h', scaleResolutionDownBy: 2, maxBitrate: 500_000 },   // 640x360
      { rid: 'f', scaleResolutionDownBy: 1, maxBitrate: 1_200_000 }, // 1280x720
    ],
  }).sender;
  // Cap the whole sender when the SFU tells Huddle the uplink is constrained: switch the top layer off.
  const params = sender.getParameters();
  params.encodings[2].active = false;
  await sender.setParameters(params);
  const offer = await pc.createOffer();
  return {
    encodings: sender.getParameters().encodings.map(({ rid, active, maxBitrate, scaleResolutionDownBy }) => ({ rid, active, maxBitrate, scaleResolutionDownBy })),
    simulcastLine: offer.sdp.split('\r\n').find((l) => l.startsWith('a=simulcast')),
    ridLines: offer.sdp.split('\r\n').filter((l) => l.startsWith('a=rid')),
  };
});
console.log(JSON.stringify(result, null, 2));
await browser.close();
server.close();

// huddle-pick-topology.mjs - the rule Huddle's signalling server applies when a room is created or grows.
export function pickTopology({ participants, recording = false, dialIn = false, legacyDevices = false, uplinkKbps = 2000 }) {
  if (legacyDevices || dialIn) return { mode: 'mcu', reason: 'devices that decode one stream or a phone bridge need a single mixed stream' };
  if (participants <= 2) return { mode: 'mesh', reason: 'one connection per peer and no server media cost' };
  if (!recording && participants <= 4 && uplinkKbps >= (participants - 1) * 1240) {
    return { mode: 'mesh', reason: `${participants - 1} uploads fit in ${uplinkKbps} kbit/s` };
  }
  return { mode: 'sfu', reason: recording ? 'recording needs a server-side copy of every stream' : 'uplink or participant count rules mesh out' };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const cases = [
    { participants: 2 },
    { participants: 4, uplinkKbps: 5000 },
    { participants: 4, uplinkKbps: 2000 },
    { participants: 3, recording: true },
    { participants: 12 },
    { participants: 6, dialIn: true },
  ];
  for (const c of cases) console.log(JSON.stringify(c), '=>', JSON.stringify(pickTopology(c)));
}

{"participants":2} => {"mode":"mesh","reason":"one connection per peer and no server media cost"}
{"participants":4,"uplinkKbps":5000} => {"mode":"mesh","reason":"3 uploads fit in 5000 kbit/s"}
{"participants":4,"uplinkKbps":2000} => {"mode":"sfu","reason":"uplink or participant count rules mesh out"}
{"participants":3,"recording":true} => {"mode":"sfu","reason":"recording needs a server-side copy of every stream"}
{"participants":12} => {"mode":"sfu","reason":"uplink or participant count rules mesh out"}
{"participants":6,"dialIn":true} => {"mode":"mcu","reason":"devices that decode one stream or a phone bridge need a single mixed stream"}