How kixelated/moq works
Project’s Type and Purpose
• MoQ is a multi-language, layered media-delivery protocol implementation.
• It provides a generic pub/sub protocol over QUIC called moq-lite, media-specific extensions called hang, and ships both native Rust and web/TypeScript clients & servers.
• Components: core libraries (Rust/JS), relay servers (clusterable CDN-style), CLI tools, GStreamer plugin, WASM bridge, and front-end demos.
File Structure
• Top-level splits by language:
• rs/ contains all native Rust crates (moq-lite, moq-relay, hang, hang-gst, hang-cli, hang-wasm, etc.)
• js/ contains all TypeScript front-end libraries & demos (@kixelated/moq, @kixelated/hang, hang-demo, utilities)
• Deployment/dev config at root (.github/, justfile, Nix flakes).
• Each crate or package has its own Cargo.toml or package.json, build config, and source.
Main Components
a. Network & Transport Layer
• QUIC (Rust → Quinn)
• WebTransport (browser QUIC wrapper)
b. Protocol Layer
• moq-lite: pub/sub primitives (broadcast, track, frame, group)
c. Media Layer
• hang: encoding/decoding via WebCodecs (web) or GStreamer (native)
d. Application & Tools
• Front-end web app / demos (hang-demo, @kixelated/hang components)
• CLI (hang-cli)
• Native plugin (hang-gst)
• Relay servers (moq-relay clustered)
• WASM bridge (hang-wasm)
e. Clients & Peers
• Publishers (web or native)
• Subscribers/Viewers (web or native)
Relationships & Data Flows
• Publishers call into the hang layer → wrap frames into moq-lite messages → transport via QUIC/WebTransport → arrive at moq-relay cluster → forwarded to interested subscribers.
• Subscribers reverse the flow: receive QUIC streams → moq-lite demux → feed hang decode → render via WebCodecs or GStreamer.
• CLI and demo apps are simply clients of those libraries.
• Relay cluster peers talk to each other (peer-to-peer QUIC) to distribute load globally.
Architectural Patterns & Principles
• Layered architecture: clearly separate network, transport, protocol, media, and app layers.
• Pub/Sub pattern in moq-lite: topics = broadcasts/tracks/groups.
• Clusterable servers: moq-relay can be horizontally scaled.
• Cross-platform via multiple crates/packages—Rust native vs WASM/Web vs TypeScript.
Technologies & Frameworks to Call Out
• Rust ecosystem: quinn (QUIC), wasm-bindgen/web-sys, GStreamer bindings.
• JS ecosystem: Vite (bundling), React/TSX for controls, WebTransport API, WebCodecs API, Tailwind CSS (demo).
• Build/deploy: Just, Nix Flakes, Docker & GitHub Actions workflows.
Final Touches
• pub/sub topology: one publisher ↔ many subscribers through relays.
• Clearly separates each layer of MoQ
• Captures both native and browser stacks
• Shows how core libraries, servers, and apps interact
• Highlights protocol flows and clustering
• Omits nothing essential yet stays organized and readable.