backend-web-real-timeUse when the user asks about WebRTC, real-time video/audio, media streaming, SFU/MCU, signaling server, TURN/STUN, live streaming, WebSocket for media, or real-time communication infrastructure. Do NOT use for: basic WebSocket patterns (websocket-patterns), or general real-time updates (data-streaming).
Independent GitHub snapshot · Automated classification · Original documentation governs
Build real-time communication systems: WebRTC signaling, media server architecture (SFU/MCU), TURN/STUN infrastructure, live streaming, and real-time data channels.
User mentions WebRTC, real-time video/audio, media streaming, SFU, MCU, signaling server, TURN/STUN, live streaming, media server, coturn, or real-time communication infrastructure.
Architecture design with signaling protocol, media server topology, TURN/STUN config, client integration code, and deployment infrastructure.
No preamble. No postamble. No explanations. No filler/hedging/transitions. Strip articles a/an/the where unambiguous. Compress output.
4096 tokens
| Criterion | Mesh (P2P) | SFU (Selective Forwarding) | MCU (Multipoint Control) |
|---|---|---|---|
| Participants | 2-4 | 4-100+ | 4-50 |
| Server bandwidth | None | O(n) — one uplink per peer | O(1) — single mixed stream |
| Client bandwidth | O(n^2) — send to all peers | O(1) — send once, receive n-1 | O(1) — single stream |
| Latency | Lowest | Low (no mixing) | Higher (mixing delay) |
| CPU cost | Client-side | Server relays | Server transcodes |
| Complexity | Simplest | Moderate | High |
| Fallback | STUN only | STUN + TURN | STUN + TURN |
Decision: Always prefer SFU for multi-party. Mesh for 1-1 calls. MCU only when legacy client compatibility required.
| Criterion | WebSocket | HTTP Long Polling | SSE |
|---|---|---|---|
| Latency | <50ms | 200-500ms | 100-300ms |
| Bidirectional | Yes | Yes | Server→Client only |
| NAT Traversal | Native ws:// wss:// | HTTP (always works) | HTTP (always works) |
| Browser Support | All modern | All | All (except IE) |
| Connection overhead | Upgrade handshake | New request per poll | Persistent connection |
| Reconnection | Built-in (some libs) | Stateless | Built-in (EventSource) |
Decision: WebSocket for production signaling. SSE for one-way broadcast. HTTP polling as last resort for restrictive networks.
| Codec | Bitrate | Quality | Licensing | Browser Support |
|---|---|---|---|---|
| VP8 | 200-1500 kbps | Good | Royalty-free | Chrome, Firefox, Safari 14.1+ |
| VP9 | 150-800 kbps | Better | Royalty-free | Chrome, Firefox |
| H.264 | 200-1500 kbps | Excellent | Patent-encumbered | Chrome, Firefox, Safari, Edge |
| AV1 | 100-500 kbps | Best | Royalty-free | Chrome (limited) |
Decision: H.264 for widest compatibility. VP9/AV1 for bandwidth-constrained environments.
Peer A → Signaling Server ← Peer B
| |
↓ ↓
STUN/TURN Server ← → ICE Negotiation ← → STUN/TURN Server
| |
↓ ↓
└─────── Media via SRTP/SCTP ────────┘
| Protocol | When to Use | Example |
|---|---|---|
| WebSocket | Low latency, bidirectional | Socket.io, ws |
| HTTP Long Polling | Simple, no WebSocket support | REST endpoints |
| Server-Sent Events | One-way server→client | Event notifications |
| Architecture | Description | Pros | Cons |
|---|---|---|---|
| Mesh (P2P) | Every peer connects to every other | No server cost | Bandwidth scales O(n^2) |
| MCU | Server mixes all streams into one | Low client bandwidth | Single point of failure |
| SFU | Server relays streams, selective forwarding | Scalable, flexible | Higher server bandwidth |
| Component | Purpose | Service |
|---|---|---|
| STUN | Discover public IP/port for NAT traversal | coturn (self-hosted), Google STUN |
| TURN | Relay media when P2P fails (NAT/firewall) | coturn (self-hosted), Twilio Network Traversal |
// server/signaling.ts
import { WebSocketServer, WebSocket } from 'ws';
interface SignalingMessage {
type: 'offer' | 'answer' | 'ice-candidate' | 'join' | 'leave' | 'room-info';
roomId: string;
senderId: string;
payload: unknown;
}
const wss = new WebSocketServer({ port: 8080 });
const rooms = new Map<string, Map<string, WebSocket>>();
wss.on('connection', (ws) => {
let userId: string;
let currentRoom: string;
ws.on('message', (data) => {
const msg: SignalingMessage = JSON.parse(data.toString());
switch (msg.type) {
case 'join': {
userId = msg.senderId;
currentRoom = msg.roomId;
if (!rooms.has(msg.roomId)) rooms.set(msg.roomId, new Map());
rooms.get(msg.roomId)!.set(userId, ws);
broadcastToRoom(msg.roomId, { type: 'room-info', roomId: msg.roomId, senderId: 'system', payload: { peers: Array.from(rooms.get(msg.roomId)!.keys()) } }, userId);
break;
}
case 'offer':
case 'answer':
case 'ice-candidate': {
const targetPeer = rooms.get(msg.roomId)?.get(msg.payload.targetId);
if (targetPeer?.readyState === WebSocket.OPEN) targetPeer.send(JSON.stringify(msg));
break;
}
case 'leave': {
rooms.get(msg.roomId)?.delete(userId);
broadcastToRoom(msg.roomId, { type: 'leave', roomId: msg.roomId, senderId: userId, payload: {} }, userId);
}
}
});
ws.on('close', () => {
rooms.get(currentRoom)?.delete(userId);
if (rooms.get(currentRoom)?.size === 0) rooms.delete(currentRoom);
broadcastToRoom(currentRoom, { type: 'leave', roomId: currentRoom, senderId: userId, payload: {} }, userId);
});
});
function broadcastToRoom(roomId: string, msg: SignalingMessage, excludeId?: string) {
const room = rooms.get(roomId);
if (!room) return;
for (const [id, ws] of room) {
if (id !== excludeId && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
}
}
// client/webrtc.ts
export class WebRTCClient {
private pc: RTCPeerConnection | null = null;
private signaling: WebSocket;
private localStream: MediaStream | null = null;
private remoteStream = new MediaStream();
constructor(serverUrl: string, private userId: string, private roomId: string) {
this.signaling = new WebSocket(serverUrl);
this.setupSignaling();
}
private setupSignaling() {
this.signaling.onopen = () => {
this.signaling.send(JSON.stringify({ type: 'join', roomId: this.roomId, senderId: this.userId, payload: {} }));
};
this.signaling.onmessage = async (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case 'offer': await this.handleOffer(msg); break;
case 'answer': await this.pc!.setRemoteDescription(new RTCSessionDescription(msg.payload)); break;
case 'ice-candidate': await this.pc!.addIceCandidate(new RTCIceCandidate(msg.payload)); break;
}
};
}
async startCall(constraints: MediaStreamConstraints = { audio: true, video: true }) {
this.localStream = await navigator.mediaDevices.getUserMedia(constraints);
this.pc = new RTCPeerConnection({
iceServers: [
{ urls: 'stun:stun.l.google.com:19302' },
{ urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' },
],
});
this.localStream.getTracks().forEach(t => this.pc!.addTrack(t, this.localStream!));
this.pc.ontrack = (event) => { event.streams[0].getTracks().forEach(t => this.remoteStream.addTrack(t)); };
this.pc.onicecandidate = (event) => {
if (event.candidate) this.signaling.send(JSON.stringify({ type: 'ice-candidate', roomId: this.roomId, senderId: this.userId, payload: { targetId: 'peer-id', candidate: event.candidate } }));
};
const offer = await this.pc.createOffer();
await this.pc.setLocalDescription(offer);
this.signaling.send(JSON.stringify({ type: 'offer', roomId: this.roomId, senderId: this.userId, payload: { targetId: 'peer-id', sdp: offer } }));
}
private async handleOffer(msg: any) {
this.pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
this.pc.ontrack = (event) => { event.streams[0].getTracks().forEach(t => this.remoteStream.addTrack(t)); };
this.pc.onicecandidate = (event) => {
if (event.candidate) this.signaling.send(JSON.stringify({ type: 'ice-candidate', roomId: this.roomId, senderId: this.userId, payload: { targetId: msg.senderId, candidate: event.candidate } }));
};
await this.pc.setRemoteDescription(new RTCSessionDescription(msg.payload.sdp));
const answer = await this.pc.createAnswer();
await this.pc.setLocalDescription(answer);
this.signaling.send(JSON.stringify({ type: 'answer', roomId: this.roomId, senderId: this.userId, payload: { targetId: msg.senderId, sdp: answer } }));
}
}
// sfu-server.ts
import * as mediasoup from 'mediasoup';
import { WebSocketServer } from 'ws';
async function createSfu() {
const worker = await mediasoup.createWorker();
const router = await worker.createRouter({
mediaCodecs: [
{ kind: 'audio', mimeType: 'audio/opus', clockRate: 48000, channels: 2 },
{ kind: 'video', mimeType: 'video/VP8', clockRate: 90000 },
{ kind: 'video', mimeType: 'video/H264', clockRate: 90000, parameters: { 'level-asymmetry-allowed': 1, 'packetization-mode': 1, 'profile-level-id': '42e01f' } },
],
});
const wss = new WebSocketServer({ port: 8081 });
const peers = new Map<string, { transport: mediasoup.types.WebRtcTransport; producer: mediasoup.types.Producer | null }>();
wss.on('connection', (ws) => {
ws.on('message', async (data) => {
const msg = JSON.parse(data.toString());
if (msg.type === 'create-transport') {
const transport = await router.createWebRtcTransport({
listenIps: [{ ip: '0.0.0.0', announcedIp: process.env.PUBLIC_IP }],
enableUdp: true, enableTcp: true, preferUdp: true,
initialAvailableOutgoingBitrate: 1000000,
});
peers.set(msg.peerId, { transport, producer: null });
ws.send(JSON.stringify({ type: 'transport-created', id: transport.id, iceParameters: transport.iceParameters, iceCandidates: transport.iceCandidates, dtlsParameters: transport.dtlsParameters }));
}
if (msg.type === 'connect-transport') {
await peers.get(msg.peerId)!.transport.connect({ dtlsParameters: msg.dtlsParameters });
ws.send(JSON.stringify({ type: 'transport-connected' }));
}
if (msg.type === 'produce') {
const peer = peers.get(msg.peerId)!;
const producer = await peer.transport.produce({ kind: msg.kind, rtpParameters: msg.rtpParameters });
peer.producer = producer;
// Forward to all other peers
for (const [id, p] of peers) {
if (id !== msg.peerId && p.transport) {
const consumer = await p.transport.consume({ producerId: producer.id, rtpCapabilities: router.rtpCapabilities });
ws.send(JSON.stringify({ type: 'new-consumer', peerId: id, producerId: producer.id, id: consumer.id, kind: consumer.kind, rtpParameters: consumer.rtpParameters }));
}
}
ws.send(JSON.stringify({ type: 'produced', id: producer.id }));
}
});
});
}
# docker-compose.yml
version: '3.8'
services:
coturn:
image: coturn/coturn:latest
network_mode: host
command: >
-n --log-file=stdout
--min-port=49152 --max-port=65535
--fingerprint --lt-cred-mech
--realm=example.com
--user=appuser:securepassword
--external-ip=YOUR_PUBLIC_IP
ports:
- "3478:3478/udp"
- "3478:3478/tcp"
- "5349:5349/tcp"
- "49152-65535:49152-65535/udp"
// TURN credential generation (time-limited)
import crypto from 'crypto';
function generateTurnCredentials(sharedSecret: string, username: string, ttl = 86400): { username: string; credential: string } {
const timestamp = Math.floor(Date.now() / 1000) + ttl;
const turnUser = `${timestamp}:${username}`;
const hmac = crypto.createHmac('sha1', sharedSecret).update(turnUser).digest('base64');
return { username: turnUser, credential: hmac };
}
| Anti-Pattern | Why | Fix |
|---|---|---|
| Relying on P2P mesh for >4 participants | Bandwidth O(n^2) kills clients | Use SFU for any multi-party |
| Hardcoded STUN/TURN URLs | Rotate credentials; no auth on STUN | Use credential-generating TURN with time-limited tokens |
| No reconnection logic | WebRTC fails on network change; no recovery | Implement ICE restart + signaling reconnection |
| Sending raw RTP without congestion control | Network collapse under load | Use WebRTC built-in GCC or SCream congestion control |
| Single signaling server | SPOF for entire system | Load balance signaling; use Redis for room state |
| No simulcast/SVC encoding | All receive same quality regardless of bandwidth | VP9 SVC or VP8 simulcast with 3 spatial layers |
| Blocking TURN ports | Users behind symmetric NAT can't connect | Document required ports: 3478 (TURN), 49152-65535 (media) |
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { WebSocket } from 'ws';
describe('WebRTC Signaling Server', () => {
let ws: WebSocket;
beforeAll(() => { ws = new WebSocket('ws://localhost:8080'); });
afterAll(() => ws.close());
it('handles room join and broadcasts peer list', (done) => {
ws.on('message', (data) => {
const msg = JSON.parse(data.toString());
if (msg.type === 'room-info') {
expect(msg.payload.peers).toContain('peer-a');
done();
}
});
ws.send(JSON.stringify({ type: 'join', roomId: 'test-room', senderId: 'peer-a', payload: {} }));
});
it('relays offers between peers', (done) => {
const ws2 = new WebSocket('ws://localhost:8080');
ws2.on('message', (data) => {
const msg = JSON.parse(data.toString());
if (msg.type === 'offer') {
expect(msg.payload.sdp.type).toBe('offer');
ws2.close();
done();
}
});
ws2.on('open', () => {
ws2.send(JSON.stringify({ type: 'join', roomId: 'test-room', senderId: 'peer-b', payload: {} }));
ws.send(JSON.stringify({ type: 'offer', roomId: 'test-room', senderId: 'peer-a', payload: { targetId: 'peer-b', sdp: { type: 'offer', sdp: 'v=0...' } } }));
});
});
});
| Metric | Target | Critical |
|---|---|---|
| ICE connection time | <3s | >10s |
| Call success rate | >98% | <95% |
| End-to-end latency (audio) | <150ms | >400ms |
| End-to-end latency (video) | <300ms | >500ms |
| Packet loss | <1% | >5% |
| Jitter | <30ms | >80ms |
| TURN relay bandwidth | <70% capacity | >90% capacity |
| Signaling latency | <100ms | >500ms |
backend/universal/websocket-patterns — WebSocket fundamentals and optimizationsbackend/universal/data-streaming — Real-time data streaming patternsbackend/universal/load-testing — Load testing signaling and media infrastructuresecurity/network — TURN/STUN firewall and network securityconnectionstatechange listenerAudioContext timer for audio synciceTransportPolicy: 'relay' for critical sessionsRTCRtpSender.setParameters dynamicallyRTCRemoteInboundRtpStreamStats round-trip time + packet loss. Reduce bitrate when RTT > 300ms or loss > 5%.Buffer pools.net.core.rmem_default = 26214400, net.core.wmem_default = 26214400. Prevents packet drop under load.coturn instance handles ~1Gbps per 4 vCPU / 8GB RAM. Horizontal scale with DNS round-robin.navigator.mediaDevices.getUserMedia with video: { width: 640, height: 480, frameRate: 30 } — don't encode 4K for video calls.excellent / good / poor / degraded. UI adapts (disable HD, hide tiles).connect() callback. Token includes roomId, userId, exp. Reject expired tokens.getStats() shows dtlsState: 'connected'.username = timestamp:userid, credential = HMAC(shared_secret, username). Rotate shared secret weekly.getDisplayMedia() prompt (browser-enforced). Never auto-accept. Server can request track.stop() on disconnect.rtp-parameters → FFmpeg pipe). Recorded files encrypted at rest. Access logged.Access-Control-Allow-Origin set per environment, never wildcard.alerts:
ice_failure_rate:
window: 5m
threshold: "> 5%"
action: page
turn_bandwidth:
window: 10m
threshold: "> 80%"
action: page
signaling_latency_p99:
window: 5m
threshold: "> 200ms"
action: alert
call_success_rate:
window: 30m
threshold: "< 95%"
action: page
packet_loss_avg:
window: 5m
threshold: "> 3%"
action: alert