🎥 CrowdStream

Broadcast. Watch. Connect — live.

Self-hosted, real-time live streaming infrastructure built for scale. CrowdStream enables low-latency broadcaster-to-audience sessions with live chat, reactions, co-broadcasting, and viewer presence — with no third-party streaming dependency, and no cloud vendor lock-in.

🎬 Demo

Live session, verified across devices and networks — desktop broadcaster (left) streaming to a mobile viewer over 4G (right), same session ID on both ends.

📖 Table of Contents

Demo
Overview
Key Features
Architecture
Multi-Pod Signaling
Deployment Topology — Local ↔ Cloud
NAT Traversal: HAProxy + Envoy in Front of Coturn
Key Flows
Tech Stack
Status
Contact

Overview

CrowdStream is a one-to-many live video streaming system. A broadcaster captures camera and mic and publishes media; many viewers subscribe and consume it. Media never flows peer-to-peer — it routes through a mediasoup SFU on the backend. Socket.IO carries all signaling; audio/video itself travels over WebRTC (UDP/DTLS/SRTP), traversing STUN/TURN when a direct path isn't available.

The full stack — signaling, SFU, NAT traversal, and multi-pod room routing — has been built and validated end to end on a local, self-hosted topology. The design is intentionally cloud-portable: every local component (ngrok, Nginx, HAProxy/Envoy, Coturn) maps one-to-one onto a standard cloud equivalent (public ingress, load balancer/API gateway, TURN relay), so moving to a cloud environment is a configuration swap, not a redesign.

✨ Key Features

Area	Capability
🎥 Broadcasting	Live video and audio over WebRTC, captured directly from browser camera/mic
📡 SFU Delivery	Multi-viewer fan-out via mediasoup SFU — no peer-to-peer mesh, no transcoding
💬 Live Chat	Real-time chat alongside the stream
❤️ Reactions	Real-time emoji reactions
🎙️ Co-broadcasting	Multiple active broadcasters in a single room
👀 Viewer Presence	Live viewer count
🧩 Multi-Pod Signaling	Viewers and broadcasters land on different backend pods but still join the same room transparently
🌐 NAT Traversal	Self-hosted Coturn (TURN/STUN), fronted by HAProxy and Envoy

🏗️ Architecture

CrowdStream splits cleanly into a React client (broadcaster + viewer), a Node.js signaling layer, and a mediasoup SFU that owns the actual media plane. A Redis-backed layer sits between backend pods so signaling isn't bound to a single process.

flowchart TB
    subgraph Clients["🖥️ Clients — React + Vite"]
        BC[Broadcaster<br/>broadcaster.ts · room.ts<br/>Device · sendTransport · producers]
        VW[Viewer<br/>viewer.ts · room.ts<br/>Device · recvTransport · consumers]
    end

    subgraph Backend["⚙️ Backend Pods — Node.js + TypeScript"]
        SOCK[Socket.IO Gateway<br/>registerBroadcaster · registerViewer · disconnect]
        SIG[Signaling / Domain Logic<br/>viewer.handler · broadcaster.util · canConsume]
        MEDIA[Media Handlers<br/>consumer.handler — pause/resume/close]
    end

    subgraph Coord["🔗 Cross-Pod Coordination"]
        REDIS[(Redis<br/>Socket.IO adapter + room registry)]
    end

    subgraph SFU["📡 MediaSoup SFU (^3.18)"]
        WORKER[Worker<br/>1 per room · rtcPorts 40000–49999]
        ROUTER[Router<br/>per room · Opus / VP8 / H264]
        TRANSPORT[WebRtcTransport<br/>send for broadcaster · recv per viewer]
    end

    subgraph State["🗄️ Runtime State"]
        MEM[(memoryRoom<br/>Map&lt;roomId, Room&gt;)]
        MONGO[(MongoDB<br/>defined, not yet wired in)]
    end

    BC -->|Socket.IO signaling| SOCK
    VW -->|Socket.IO signaling| SOCK
    BC -->|WebRTC UDP/DTLS/SRTP| TRANSPORT
    VW -->|WebRTC UDP/DTLS/SRTP| TRANSPORT
    SOCK <-->|pub/sub across pods| REDIS
    SOCK --> SIG --> MEDIA
    SIG --> ROUTER
    ROUTER --> WORKER
    ROUTER --> TRANSPORT
    SIG --> MEM
    SIG -->|roomId → owning pod| REDIS
    MONGO -.not invoked at runtime.-> MEM

Notes

SFU model: the broadcaster uploads one stream; the SFU fans it out to N viewers — no transcoding, no P2P mesh.
Runtime state is in-memory (memoryRoom), scoped per pod. The MongoDB layer is defined but not yet wired into the handler flow, so room/session state doesn't survive a restart.
One mediasoup Worker per room today — no worker pool yet; horizontal scaling across CPU cores within a pod is a known next step.
Redis does double duty: it backs the Socket.IO adapter (cross-pod event fan-out) and holds the roomId → pod ownership registry described below.

🧩 Multi-Pod Signaling

A broadcaster and a viewer can land on different backend pods — normal behavior behind any load balancer with more than one replica — and still end up in the same room without either client being redirected or reconnected.

How it works:

🧩 Multi-Pod Signaling

Viewers can join a room whose mediasoup Router lives on a different pod than the one they're connected to, and the system transparently forwards the relevant calls to the owning pod and relays the response back — this path is implemented and working for joinRoom, createViewerTransport, connectConsumerTransport, consume, pauseConsumer, resumeConsumer, and viewer heartbeats.

How it works:

Room ownership (roomId → nodeId) is stored in Redis at room creation, keyed off each pod's config.instanceId.
When a viewer's request lands on a non-owning pod, that pod doesn't reject it — it packages the call into a PodCommandPayload (a typed request with a requestId, the original args, and a replyTo channel scoped to itself), publishes it to the owning pod over Redis, and registers a pending entry (with a 5-second timeout) in an in-memory podRequestHandleMap keyed by requestId.
The owning pod executes the actual mediasoup call locally and publishes the result back on the replyTo channel; the originating pod's pending entry resolves, and the viewer's ack() fires with the real result — the viewer's browser never needs to know a different pod handled it.
If the owning pod doesn't respond within 5 seconds, or the cross-pod publish reaches zero receivers, the request fails explicitly (CROSS_POD_TIMEOUT / CROSS_POD_UNREACHABLE) rather than hanging.

Host vs. co-broadcaster: the room's primary host always creates the room on their own pod via createRoom, so the host is the owning pod by construction — cross-pod forwarding for createBroadcasterTransport/connectBroadcasterTransport/produce is never needed on the host path. It is needed for a co-broadcaster joining a room already owned by a different pod — that path currently checks ownership and explicitly rejects with 409 Room belongs to another node rather than forwarding, marked as a TODO in the handler.

🗄️ Persistence (MongoDB)

MongoDB is wired into the live request path, write-through on every state change — not read from yet to gate behavior (Redis is still the source of truth for live routing decisions; nothing currently queries Mongo before letting a join or produce proceed).

LiveRoom — one document per room, created on createRoom with sfuNodeId set to the owning pod's config.instanceId (the same value used for the Redis ownership registry), totalViewersJoined incremented on every successful join.
Broadcaster — one document per broadcaster session, with hashed IP/user-agent (ipHash, userAgentHash — not raw values), and transportIds/producerIds appended as transports and producers are created.
Viewer — one document per viewer session, with the same hashed identifiers, transportIds and consumerIds appended as they're created.

All writes are fire-and-forget (void Model.create(...).catch(...)) off the critical path — persistence failures are logged but never block or fail the underlying signaling response.

sequenceDiagram
    participant V as Viewer (connected to Pod B)
    participant PB as Backend Pod B
    participant R as Redis (adapter + room registry)
    participant PA as Backend Pod A (owns the room)
    participant SFU as mediasoup SFU (on Pod A)

    V->>PB: joinRoom(roomId)
    PB->>R: lookup roomId → owning pod
    R-->>PB: roomId owned by Pod A
    PB->>R: publish joinRoom event (Socket.IO adapter)
    R-->>PA: deliver joinRoom event
    PA->>SFU: getRouterRtpCapabilities / createViewerTransport
    SFU-->>PA: transport + ICE/DTLS params
    PA->>R: publish response event
    R-->>PB: deliver response event
    PB-->>V: transport params (over its own Socket.IO connection)
    V->>SFU: WebRTC media (ICE/DTLS/SRTP) — direct to SFU, not via Pod B

Why this matters: clients never need to know or care which pod they're attached to, and a room isn't tied to "whichever pod the client happens to hit." This is the same pattern used to horizontally scale any Socket.IO deployment (@socket.io/redis-adapter), extended here with an explicit room-ownership registry so mediasoup-specific calls are routed to the one pod that actually holds the Router for that room.

🌍 Deployment Topology — Local ↔ Cloud

The current deployment is fully self-hosted and has been validated locally. Every layer maps directly onto a cloud equivalent — nothing in the design is local-only, so moving environments is a matter of pointing the same configuration at managed infrastructure rather than rebuilding it.

Local component	Cloud equivalent	Role
ngrok	Public ingress / DNS + managed TLS	Exposes the app publicly
Nginx	Nginx (unchanged) or a managed reverse proxy	Routes HTTP/Socket.IO traffic to backend pods
HAProxy (TCP)	Cloud NLB / TCP listener	TURN-over-TCP path for clients where UDP is blocked
Envoy (UDP)	Cloud NLB / UDP listener	STUN/TURN-over-UDP path — the primary ICE path
Coturn	Coturn (unchanged)	TURN/STUN relay for NAT traversal
Single-pod backend	Multiple backend pods behind a load balancer	Same Socket.IO + mediasoup code, now horizontally scaled via the Redis adapter above

sequenceDiagram
    participant U as Broadcaster / Viewer
    participant Ingress as Ingress<br/>(ngrok locally / DNS+LB in cloud)
    participant NG as Nginx
    participant BE as Node.js Backend Pod
    participant SFU as mediasoup SFU
    participant TURN as Coturn

    U->>Ingress: HTTPS / Socket.IO
    Ingress->>NG: forward request
    NG->>BE: route to backend pod
    BE->>BE: createRoom / exchange RTP capabilities
    BE->>SFU: create WebRTC transport
    SFU-->>BE: ICE + DTLS parameters
    SFU->>SFU: generate ICE candidates
    SFU->>TURN: STUN binding / TURN allocation
    TURN-->>SFU: relay candidate
    SFU-->>U: candidates returned via signaling
    U->>U: ICE connectivity checks
    U->>TURN: selected candidate pair
    TURN->>SFU: DTLS handshake → SRTP media flow

🔀 NAT Traversal: HAProxy + Envoy in Front of Coturn

With no managed load balancer in the self-hosted path, TURN/STUN traffic is split across two proxies before it reaches Coturn — HAProxy handles the TCP path, Envoy handles the UDP path. This pair stands in for a cloud ALB/NLB and works identically against a cloud-hosted deployment.

⚠️ Local setup requirement: Coturn needs to advertise the machine's actual public-facing IPv4 (its external-ip config) for ICE candidates to resolve correctly. If the machine running the server is on a mobile hotspot, the visible public IP can be behind carrier-grade NAT or change between sessions — in that case, TURN relay candidates get advertised with the wrong address, and clients on a different network than the host will fail to connect even though everything looks configured correctly. Bind Coturn's external-ip to a stable, reachable public IPv4 (a static IP where available, or the actual current public IP if not) before testing across networks. This is a local/self-hosted-topology concern only — a cloud deployment behind a proper NLB/TURN relay (see Deployment Topology) doesn't have this problem, since the relay's public address is stable by design.

flowchart TB
    CLIENT[WebRTC Client] -->|ICE: STUN / TURN| SPLIT{Transport type}
    SPLIT -->|TURN over TCP| HAP[HAProxy<br/>TCP Proxy]
    SPLIT -->|STUN/TURN over UDP| ENVOY[Envoy<br/>UDP Proxy]
    HAP --> TURN[(Coturn)]
    ENVOY --> TURN
    TURN --> RELAY[Relay Media]
    RELAY --> SFU[mediasoup SFU]

HAProxy proxies TURN-over-TCP connections — useful for clients on networks that block or throttle UDP.
Envoy proxies the UDP path for STUN and TURN — the primary route for ICE connectivity checks and media relay.
Both sit in front of a single Coturn instance, giving it one consistent entry point regardless of which transport a client's ICE agent picks.
This layer is a like-for-like substitute for a cloud ALB/NLB; the same HAProxy/Envoy configuration runs unchanged in front of a cloud-hosted Coturn instance.

🔁 Key Flows

Broadcast (publish): createRoom → owning pod spins up Worker + Router, registers roomId → podId in Redis → getRouterRtpCapabilities → client loads Device → createBroadcasterTransport → connectBroadcasterTransport (DTLS) → produce (video + audio) → Producers stored in memoryRoom on the owning pod.

View (subscribe), same pod or different pod: joinRoom → signaling layer resolves the room's owning pod via Redis (transparent if it's the same pod) → load Device → createViewerTransport → connectConsumerTransport (DTLS) → consume (creates paused Consumers per producer, gated by canConsume) → resumeConsumer → client builds a MediaStream and renders. Signaling events are relayed pod-to-pod over the Socket.IO Redis adapter; the media path (WebRTC) always goes directly from the client to the SFU that owns the room.

Teardown: disconnect → handleDisconnect closes transports/producers/consumers, removes the entry from memoryRoom, and clears the room's ownership entry from Redis.

🧰 Tech Stack

Layer	Technology
Backend	Node.js, TypeScript, Socket.IO
Cross-Pod Coordination	Redis — Socket.IO adapter (pub/sub) + room-ownership registry
Media	MediaSoup (WebRTC SFU) — one worker process per room, media plane in C++ off the event loop
Frontend	React, Vite, mediasoup-client
Database	MongoDB (Mongoose) — write-through persistence for rooms, broadcasters, and viewers; not yet read from on the live request path
NAT Traversal	Coturn (TURN/STUN)
Proxy / Ingress	ngrok (local) / DNS + managed ingress (cloud), Nginx, HAProxy (TCP), Envoy (UDP)
Media Processing	FFmpeg (thumbnails now, recording planned)

📞 Contact

Built by Harshit Singh Parihar.

_{Low-latency, self-hosted live streaming — no third-party dependency.}

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🎥 CrowdStream

🎬 Demo

📖 Table of Contents

Overview

✨ Key Features

🏗️ Architecture

🧩 Multi-Pod Signaling

🧩 Multi-Pod Signaling

🗄️ Persistence (MongoDB)

🌍 Deployment Topology — Local ↔ Cloud

🔀 NAT Traversal: HAProxy + Envoy in Front of Coturn

🔁 Key Flows

🧰 Tech Stack

📞 Contact