Videoconference Architecture

// huddle-room-state.ts: the room and participant state machines of the Huddle signalling server.
// Runs on Node.js 24 as it is (type stripping): node huddle-room-state.ts

export type RoomState = 'idle' | 'active' | 'draining' | 'closed';
export type ParticipantState = 'waiting' | 'admitted' | 'connecting' | 'connected' | 'reconnecting' | 'left';
export type Role = 'host' | 'guest';

export interface Participant {
  id: string;
  name: string;
  role: Role;
  state: ParticipantState;
  muted: boolean;
  cameraOff: boolean;
  sharing: boolean;
  reconnectDeadline: number | null;
}

export interface Room {
  name: string;
  state: RoomState;
  lobbyEnabled: boolean;
  maxParticipants: number;
  participants: Map<string, Participant>;
}

export type Event =
  | { type: 'join'; id: string; name: string; role: Role; now: number }
  | { type: 'admit'; by: string; id: string }
  | { type: 'deny'; by: string; id: string }
  | { type: 'transportConnected'; id: string }
  | { type: 'transportLost'; id: string; now: number }
  | { type: 'leave'; id: string }
  | { type: 'tick'; now: number }
  | { type: 'mute'; id: string; muted: boolean }
  | { type: 'endMeeting'; by: string };

// An effect is a side effect the server must perform; the reducer stays pure and testable.
export type Effect =
  | { type: 'notify'; to: string; message: string }
  | { type: 'broadcast'; message: string }
  | { type: 'issueToken'; to: string }
  | { type: 'closeMedia'; id: string }
  | { type: 'closeRoom' };

export const RECONNECT_GRACE_MS = 15_000;

export function createRoom(name: string, opts: { lobbyEnabled?: boolean; maxParticipants?: number } = {}): Room {
  return {
    name,
    state: 'idle',
    lobbyEnabled: opts.lobbyEnabled ?? false,
    maxParticipants: opts.maxParticipants ?? 50,
    participants: new Map(),
  };
}

function live(room: Room): Participant[] {
  return [...room.participants.values()].filter((p) => p.state !== 'left' && p.state !== 'waiting');
}

export function reduce(room: Room, ev: Event): Effect[] {
  const fx: Effect[] = [];
  const get = (id: string) => room.participants.get(id);

  switch (ev.type) {
    case 'join': {
      if (room.state === 'draining' || room.state === 'closed') {
        return [{ type: 'notify', to: ev.id, message: 'room-closed' }];
      }
      if (live(room).length >= room.maxParticipants) {
        return [{ type: 'notify', to: ev.id, message: 'room-full' }];
      }
      const needsApproval = room.lobbyEnabled && ev.role !== 'host';
      room.participants.set(ev.id, {
        id: ev.id, name: ev.name, role: ev.role,
        state: needsApproval ? 'waiting' : 'admitted',
        muted: false, cameraOff: false, sharing: false, reconnectDeadline: null,
      });
      if (room.state === 'idle') room.state = 'active';
      if (needsApproval) {
        fx.push({ type: 'notify', to: ev.id, message: 'waiting-for-host' });
        for (const h of room.participants.values()) {
          if (h.role === 'host' && h.state !== 'left') fx.push({ type: 'notify', to: h.id, message: `knock:${ev.id}` });
        }
      } else {
        fx.push({ type: 'issueToken', to: ev.id });
      }
      break;
    }
    case 'admit': case 'deny': {
      const by = get(ev.by);
      const p = get(ev.id);
      if (!by || by.role !== 'host' || !p || p.state !== 'waiting') return [];
      if (ev.type === 'admit') {
        p.state = 'admitted';
        fx.push({ type: 'issueToken', to: p.id });
      } else {
        p.state = 'left';
        fx.push({ type: 'notify', to: p.id, message: 'denied' });
      }
      break;
    }
    case 'transportConnected': {
      const p = get(ev.id);
      if (!p) return [];
      const from = p.state;
      if (from === 'admitted' || from === 'connecting' || from === 'reconnecting') {
        p.state = 'connected';
        p.reconnectDeadline = null;
        fx.push({ type: 'broadcast', message: from === 'reconnecting' ? `back:${p.id}` : `joined:${p.id}` });
      }
      break;
    }
    case 'transportLost': {
      const p = get(ev.id);
      if (p && p.state === 'connected') {
        p.state = 'reconnecting';
        p.reconnectDeadline = ev.now + RECONNECT_GRACE_MS;
        fx.push({ type: 'broadcast', message: `reconnecting:${p.id}` });
      }
      break;
    }
    case 'tick': {
      for (const p of room.participants.values()) {
        if (p.state === 'reconnecting' && p.reconnectDeadline !== null && ev.now >= p.reconnectDeadline) {
          fx.push(...reduce(room, { type: 'leave', id: p.id }));
        }
      }
      break;
    }
    case 'leave': {
      const p = get(ev.id);
      if (!p || p.state === 'left') return [];
      const wasVisible = p.state !== 'waiting';
      p.state = 'left';
      fx.push({ type: 'closeMedia', id: p.id });
      if (wasVisible) fx.push({ type: 'broadcast', message: `left:${p.id}` });
      if (live(room).length === 0 && room.state === 'active') {
        room.state = 'idle';
        fx.push({ type: 'closeRoom' });
      }
      break;
    }
    case 'mute': {
      const p = get(ev.id);
      if (p && p.state === 'connected') {
        p.muted = ev.muted;
        fx.push({ type: 'broadcast', message: `${ev.muted ? 'muted' : 'unmuted'}:${p.id}` });
      }
      break;
    }
    case 'endMeeting': {
      const by = get(ev.by);
      if (!by || by.role !== 'host') return [];
      room.state = 'draining';
      for (const p of live(room)) {
        fx.push({ type: 'notify', to: p.id, message: 'meeting-ended' }, ...reduce(room, { type: 'leave', id: p.id }));
      }
      room.state = 'closed';
      fx.push({ type: 'closeRoom' });
      break;
    }
  }
  return fx;
}

// Demo: a lobby room, a guest that knocks, a network drop and a host ending the meeting.
if (process.argv[1]?.endsWith('huddle-room-state.ts')) {
  const room = createRoom('standup', { lobbyEnabled: true });
  const run = (label: string, ev: Event) => {
    const fx = reduce(room, ev);
    console.log(`${label.padEnd(28)} room=${room.state.padEnd(8)} fx=${fx.map((f) => ('message' in f ? `${f.type}(${f.message})` : f.type === 'issueToken' ? `issueToken(${f.to})` : f.type)).join(', ') || '-'}`);
  };
  run('host joins', { type: 'join', id: 'ana', name: 'Ana', role: 'host', now: 0 });
  run('guest joins (lobby)', { type: 'join', id: 'bob', name: 'Bob', role: 'guest', now: 1 });
  run('guest tries to admit self', { type: 'admit', by: 'bob', id: 'bob' });
  run('host admits guest', { type: 'admit', by: 'ana', id: 'bob' });
  run('host connected', { type: 'transportConnected', id: 'ana' });
  run('guest connected', { type: 'transportConnected', id: 'bob' });
  run('guest network lost', { type: 'transportLost', id: 'bob', now: 1000 });
  run('tick before grace ends', { type: 'tick', now: 10_000 });
  run('guest reconnected', { type: 'transportConnected', id: 'bob' });
  run('guest lost again', { type: 'transportLost', id: 'bob', now: 20_000 });
  run('tick after grace ends', { type: 'tick', now: 36_000 });
  run('host ends meeting', { type: 'endMeeting', by: 'ana' });
  run('late join', { type: 'join', id: 'cy', name: 'Cy', role: 'guest', now: 40_000 });
}

host joins                   room=active   fx=issueToken(ana)
guest joins (lobby)          room=active   fx=notify(waiting-for-host), notify(knock:bob)
guest tries to admit self    room=active   fx=-
host admits guest            room=active   fx=issueToken(bob)
host connected               room=active   fx=broadcast(joined:ana)
guest connected              room=active   fx=broadcast(joined:bob)
guest network lost           room=active   fx=broadcast(reconnecting:bob)
tick before grace ends       room=active   fx=-
guest reconnected            room=active   fx=broadcast(back:bob)
guest lost again             room=active   fx=broadcast(reconnecting:bob)
tick after grace ends        room=active   fx=closeMedia, broadcast(left:bob)
host ends meeting            room=closed   fx=notify(meeting-ended), closeMedia, broadcast(left:ana), closeRoom
late join                    room=closed   fx=notify(room-closed)

// huddle-join-token.ts: a signed, short-lived join token (HS256 JWT) for Huddle, with no dependencies.
// Run: node huddle-join-token.ts   (Node.js 24)
import { createHmac, timingSafeEqual } from 'node:crypto';

export interface Grants {
  room: string;
  canPublish: boolean;
  canSubscribe: boolean;
  canPublishData: boolean;
  canShareScreen: boolean;
  roomAdmin: boolean;
}
export interface JoinClaims extends Grants {
  iss: string;
  sub: string;      // participant identity, taken from the verified session
  name: string;
  iat: number;
  nbf: number;
  exp: number;
  jti: string;
}

const b64u = (buf: Buffer | string) => Buffer.from(buf).toString('base64url');
const SECRET = process.env.HUDDLE_TOKEN_SECRET ?? 'change-me-example-secret-at-least-32-bytes';

export function sign(claims: JoinClaims, secret = SECRET): string {
  const head = b64u(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
  const body = b64u(JSON.stringify(claims));
  const mac = createHmac('sha256', secret).update(`${head}.${body}`).digest();
  return `${head}.${body}.${b64u(mac)}`;
}

export function mintJoinToken(opts: { identity: string; name: string; room: string; host: boolean; webinarViewer?: boolean; ttlSeconds?: number; now?: number }): string {
  const now = Math.floor((opts.now ?? Date.now()) / 1000);
  const viewer = opts.webinarViewer === true;
  return sign({
    iss: 'huddle-api',
    sub: opts.identity,
    name: opts.name,
    iat: now,
    nbf: now,
    exp: now + (opts.ttlSeconds ?? 600),
    jti: crypto.randomUUID(),
    room: opts.room,
    canPublish: !viewer,
    canSubscribe: true,
    canPublishData: !viewer,
    canShareScreen: !viewer,
    roomAdmin: opts.host,
  });
}

export type Verdict = { ok: true; claims: JoinClaims } | { ok: false; reason: string };

export function verifyJoinToken(token: string, expectedRoom: string, opts: { now?: number; secret?: string; seen?: Set<string> } = {}): Verdict {
  const parts = token.split('.');
  if (parts.length !== 3) return { ok: false, reason: 'malformed' };
  const [head, body, sig] = parts as [string, string, string];
  let header: { alg?: string };
  try { header = JSON.parse(Buffer.from(head, 'base64url').toString()); } catch { return { ok: false, reason: 'malformed' }; }
  if (header.alg !== 'HS256') return { ok: false, reason: 'unexpected algorithm' };   // never trust the header to choose
  const expected = createHmac('sha256', opts.secret ?? SECRET).update(`${head}.${body}`).digest();
  const given = Buffer.from(sig, 'base64url');
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return { ok: false, reason: 'bad signature' };
  const claims = JSON.parse(Buffer.from(body, 'base64url').toString()) as JoinClaims;
  const now = Math.floor((opts.now ?? Date.now()) / 1000);
  if (now < claims.nbf) return { ok: false, reason: 'not yet valid' };
  if (now >= claims.exp) return { ok: false, reason: 'expired' };
  if (claims.room !== expectedRoom) return { ok: false, reason: 'wrong room' };
  if (opts.seen) {                                    // optional one-time use: the join endpoint keeps a short-lived set of jti
    if (opts.seen.has(claims.jti)) return { ok: false, reason: 'already used' };
    opts.seen.add(claims.jti);
  }
  return { ok: true, claims };
}

if (process.argv[1]?.endsWith('huddle-join-token.ts')) {
  const t0 = Date.parse('2026-10-24T10:00:00Z');
  const guest = mintJoinToken({ identity: 'u-42', name: 'Bob', room: 'standup', host: false, now: t0 });
  const seen = new Set<string>();
  const show = (label: string, v: Verdict) => console.log(label.padEnd(26), v.ok ? `ok publish=${v.claims.canPublish} admin=${v.claims.roomAdmin}` : `rejected: ${v.reason}`);
  show('fresh guest token', verifyJoinToken(guest, 'standup', { now: t0 + 1000, seen }));
  show('same token again', verifyJoinToken(guest, 'standup', { now: t0 + 2000, seen }));
  show('after ten minutes', verifyJoinToken(guest, 'standup', { now: t0 + 601_000 }));
  show('other room', verifyJoinToken(guest, 'retro', { now: t0 + 1000 }));
  const [h, b, s] = guest.split('.') as [string, string, string];
  const claims = JSON.parse(Buffer.from(b, 'base64url').toString());
  claims.roomAdmin = true;
  show('forged admin claim', verifyJoinToken(`${h}.${b64u(JSON.stringify(claims))}.${s}`, 'standup', { now: t0 + 1000 }));
  const none = `${b64u('{"alg":"none"}')}.${b}.`;
  show('alg none', verifyJoinToken(none, 'standup', { now: t0 + 1000 }));
  const viewer = mintJoinToken({ identity: 'v-1', name: 'Viewer', room: 'standup', host: false, webinarViewer: true, now: t0 });
  show('webinar viewer', verifyJoinToken(viewer, 'standup', { now: t0 + 1000 }));
}

fresh guest token          ok publish=true admin=false
same token again           rejected: already used
after ten minutes          rejected: expired
other room                 rejected: wrong room
forged admin claim         rejected: bad signature
alg none                   rejected: unexpected algorithm
webinar viewer             ok publish=false admin=false

// huddle-layout.ts: speaker selection, layout choice and the per-tile subscription plan of a Huddle client.
// Run: node huddle-layout.ts   (Node.js 24)

export type Rid = 'q' | 'h' | 'f';
export const LAYERS: Record<Rid, { width: number; height: number; kbps: number }> = {
  q: { width: 320, height: 180, kbps: 150 },
  h: { width: 640, height: 360, kbps: 500 },
  f: { width: 1280, height: 720, kbps: 1500 },
};

export interface Peer {
  id: string;
  cameraOn: boolean;
  screenShare: boolean;
  pinned: boolean;
  audioLevel: number;   // 0 (silence) to 1 (loud), as in the RTP audio level header extension converted to a linear scale
  joinedAt: number;
}

// The RFC 6464 header extension carries the level as 0..127, meaning 0 to -127 dBov (127 is digital silence).
export function linearFromDbov(value: number): number {
  return value >= 127 ? 0 : 10 ** (-value / 20);
}

// Active speaker: the loudest peer above a threshold, held for a minimum time so tiles do not flicker.
export class SpeakerTracker {
  private current: string | null = null;
  private since = 0;
  private threshold: number;
  private holdMs: number;
  constructor(threshold = 0.1, holdMs = 1500) { this.threshold = threshold; this.holdMs = holdMs; }
  update(peers: Peer[], now: number): string | null {
    const loud = peers.filter((p) => p.audioLevel >= this.threshold).sort((a, b) => b.audioLevel - a.audioLevel)[0];
    if (!loud) return this.current;                                   // silence keeps the last speaker on screen
    if (this.current === null) { this.current = loud.id; this.since = now; return this.current; }
    if (loud.id !== this.current && now - this.since >= this.holdMs) { this.current = loud.id; this.since = now; }
    return this.current;
  }
}

export type LayoutMode = 'spotlight' | 'speaker' | 'grid';
export interface Viewport { width: number; height: number; mobile: boolean }
export interface Tile { peerId: string; width: number; height: number; video: Rid | 'off'; reason: string }
export interface Plan { mode: LayoutMode; tiles: Tile[]; audioOnly: string[]; estimatedKbps: number }

function bestLayer(width: number, height: number): Rid {
  // the smallest layer that is at least as large as the tile, so the picture is never upscaled
  for (const rid of ['q', 'h', 'f'] as const) {
    if (LAYERS[rid].width >= width && LAYERS[rid].height >= height) return rid;
  }
  return 'f';
}

function downgrade(rid: Rid): Rid | 'off' { return rid === 'f' ? 'h' : rid === 'h' ? 'q' : 'off'; }

export function planLayout(peers: Peer[], speakerId: string | null, vp: Viewport, downlinkKbps: number): Plan {
  const maxTiles = vp.mobile ? 4 : 16;                               // last-N: everyone else is audio only
  const sharer = peers.find((p) => p.screenShare);
  const pinned = peers.find((p) => p.pinned);
  const mode: LayoutMode = sharer || pinned ? 'spotlight' : peers.length <= 2 ? 'speaker' : 'grid';
  const focusId = sharer?.id ?? pinned?.id ?? (mode === 'speaker' ? speakerId ?? peers[0]?.id : null);

  // order: focus, then the current speaker, then newest first
  const ordered = [...peers].sort((a, b) => {
    const rank = (p: Peer) => (p.id === focusId ? 0 : p.id === speakerId ? 1 : 2);
    return rank(a) - rank(b) || b.joinedAt - a.joinedAt;
  });
  const shown = ordered.filter((p) => p.cameraOn || p.screenShare || p.id === focusId).slice(0, maxTiles);
  const audioOnly = ordered.filter((p) => !shown.includes(p)).map((p) => p.id);

  const tiles: Tile[] = [];
  if (mode === 'grid') {
    const cols = Math.ceil(Math.sqrt(shown.length));
    const rows = Math.ceil(shown.length / cols);
    const w = Math.floor(vp.width / cols), h = Math.floor(vp.height / rows);
    for (const p of shown) tiles.push({ peerId: p.id, width: w, height: h, video: bestLayer(w, h), reason: 'grid cell' });
  } else {
    const stripH = Math.floor(vp.height * 0.18);
    const rest = shown.filter((p) => p.id !== focusId);
    const mainH = rest.length ? vp.height - stripH : vp.height;
    for (const p of shown) {
      if (p.id === focusId) tiles.push({ peerId: p.id, width: vp.width, height: mainH, video: p.screenShare ? 'f' : bestLayer(vp.width, mainH), reason: p.screenShare ? 'screen share' : 'focus' });
      else {
        const w = Math.floor(vp.width / Math.max(rest.length, 1));
        tiles.push({ peerId: p.id, width: Math.min(w, 320), height: stripH, video: 'q', reason: 'thumbnail strip' });
      }
    }
  }

  // fit the plan into the downlink: lower the largest layer first, the lowest-priority tile first on ties,
  // and never switch off the focus tile or the current speaker (they keep at least the smallest layer)
  const cost = (ts: Tile[]) => ts.reduce((n, t) => n + (t.video === 'off' ? 0 : LAYERS[t.video].kbps), 0);
  const budget = downlinkKbps * 0.8;                                  // keep 20 percent headroom for audio, data and retransmissions
  const protectedIds = new Set([focusId, speakerId]);
  while (cost(tiles) > budget) {
    const candidates = tiles
      .map((t, i) => ({ t, i }))
      .filter(({ t }) => t.video !== 'off' && !(t.video === 'q' && protectedIds.has(t.peerId)));
    if (candidates.length === 0) break;
    candidates.sort((a, b) => LAYERS[b.t.video as Rid].kbps - LAYERS[a.t.video as Rid].kbps || b.i - a.i);
    const victim = candidates[0]!.t;
    victim.video = downgrade(victim.video as Rid);
    if (!victim.reason.endsWith('reduced for bandwidth')) victim.reason += ', reduced for bandwidth';
  }
  return { mode, tiles, audioOnly: [...audioOnly, ...tiles.filter((t) => t.video === 'off').map((t) => t.peerId)], estimatedKbps: cost(tiles) };
}

if (process.argv[1]?.endsWith('huddle-layout.ts')) {
  const mk = (n: number, extra: Partial<Peer> = {}): Peer[] =>
    Array.from({ length: n }, (_, i) => ({ id: `p${i + 1}`, cameraOn: true, screenShare: false, pinned: false, audioLevel: 0, joinedAt: i, ...extra }));
  const desktop: Viewport = { width: 1280, height: 720, mobile: false };
  const phone: Viewport = { width: 390, height: 700, mobile: true };
  const print = (label: string, plan: Plan) => {
    console.log(`${label}: mode=${plan.mode} ~${plan.estimatedKbps} kbit/s audioOnly=[${plan.audioOnly.join(',')}]`);
    for (const t of plan.tiles) console.log(`   ${t.peerId} ${t.width}x${t.height} ${t.video} (${t.reason})`);
  };

  console.log('level 30 =', linearFromDbov(30).toFixed(3), ' level 10 =', linearFromDbov(10).toFixed(3), ' level 127 =', linearFromDbov(127));
  const tracker = new SpeakerTracker();
  const four = mk(4);
  four[2]!.audioLevel = 0.6;
  console.log('speaker at t=0     :', tracker.update(four, 0));
  four[2]!.audioLevel = 0; four[0]!.audioLevel = 0.9;
  console.log('p1 louder at 500ms :', tracker.update(four, 500), '(held)');
  console.log('p1 louder at 2000ms:', tracker.update(four, 2000));
  console.log('silence at 4000ms  :', (four[0]!.audioLevel = 0, tracker.update(four, 4000)));

  print('1. two people          ', planLayout(mk(2), 'p2', desktop, 5000));
  print('2. six people on desktop', planLayout(mk(6), 'p3', desktop, 8000));
  const share = mk(6); share[1]!.screenShare = true;
  print('3. screen share        ', planLayout(share, 'p3', desktop, 8000));
  print('4. twelve on a phone   ', planLayout(mk(12), 'p5', phone, 3000));
  print('5. six, 900 kbit/s down', planLayout(mk(6), 'p3', desktop, 900));
}

level 30 = 0.032  level 10 = 0.316  level 127 = 0
speaker at t=0     : p3
p1 louder at 500ms : p3 (held)
p1 louder at 2000ms: p1
silence at 4000ms  : p1
1. two people          : mode=speaker ~1650 kbit/s audioOnly=[]
   p2 1280x591 f (focus)
   p1 320x129 q (thumbnail strip)
2. six people on desktop: mode=grid ~3000 kbit/s audioOnly=[]
   p3 426x360 h (grid cell)
   p6 426x360 h (grid cell)
   p5 426x360 h (grid cell)
   p4 426x360 h (grid cell)
   p2 426x360 h (grid cell)
   p1 426x360 h (grid cell)
3. screen share        : mode=spotlight ~2250 kbit/s audioOnly=[]
   p2 1280x591 f (screen share)
   p3 256x129 q (thumbnail strip)
   p6 256x129 q (thumbnail strip)
   p5 256x129 q (thumbnail strip)
   p4 256x129 q (thumbnail strip)
   p1 256x129 q (thumbnail strip)
4. twelve on a phone   : mode=grid ~2000 kbit/s audioOnly=[p9,p8,p7,p6,p4,p3,p2,p1]
   p5 195x350 h (grid cell)
   p12 195x350 h (grid cell)
   p11 195x350 h (grid cell)
   p10 195x350 h (grid cell)
5. six, 900 kbit/s down: mode=grid ~600 kbit/s audioOnly=[p2,p1]
   p3 426x360 q (grid cell, reduced for bandwidth)
   p6 426x360 q (grid cell, reduced for bandwidth)
   p5 426x360 q (grid cell, reduced for bandwidth)
   p4 426x360 q (grid cell, reduced for bandwidth)
   p2 426x360 off (grid cell, reduced for bandwidth)
   p1 426x360 off (grid cell, reduced for bandwidth)