Decentralized live streaming for the Qortal network.
QLive is a real-time, peer-to-peer live streaming protocol built on top of Qortal's decentralized infrastructure. It delivers low-latency video to an unlimited audience without a single centralized server, CDN, or ingest point — while leaving zero long-term disk footprint on participating nodes.
The problem: Q-Tube handles static video (VOD) beautifully by chunking and distributing files across the Qortal Data Network (QDN). But live streaming demands low latency, dynamic peer discovery, and transient data handling — constraints that traditional on-chain/QDN approaches cannot satisfy without bloating the blockchain or overloading node storage.
The solution: QLive decouples Signaling/Discovery (handled on-chain via QDN) from Data Transport (handled via an ephemeral P2P mesh overlay running entirely in RAM).
- Why QLive?
- Architecture Overview
- Core Components
- Technical Constraints & Challenges
- Comparison: Traditional vs. Qortal Mesh Live
- Network Incentives & Free-Rider Mitigation
- Getting Started
- Roadmap
- Contributing
- License
Traditional live streaming is built on centralized infrastructure:
- Ingest requires RTMP servers (Twitch, YouTube).
- Distribution requires paid CDNs (Cloudflare, AWS CloudFront).
- Storage requires infinite server capacity.
- Censorship is a single point of failure — one domain block or shutdown kills the stream.
QLive flips this model. The broadcaster's node is the ingest point. The audience is the CDN. Storage is a rolling RAM buffer that never touches disk. And because routing happens over Qortal's peer network with encrypted swarms, there is no single point of failure or censorship.
The network gets stronger as the viewer count grows.
┌─────────────────────────────────────────────────────────┐
│ QDN / Chain Layer (Signaling) │
│ - Stream Metadata & Publisher Identity │
│ - Active Swarm Peer List & Encryption Keys │
└───────────────────────────┬─────────────────────────────┘
│ (Discovery)
▼
┌─────────────────────────────────────────────────────────┐
│ Ephemeral P2P Mesh (RAM Transport) │
│ Publisher ───> Node A (Relay) ───> Node C (Viewer) │
│ │ ▲ │
│ └───────────> Node B (Relay) ──────────┘ │
└───────────────────────────┬─────────────────────────────┘
│ (Sliding-Window Archive)
▼
┌─────────────────────────────────────────────────────────┐
│ QDN Archival (VOD Engine) │
│ - Stitches live chunks into standard QDN Data Chunks │
│ - Converts completed Live Stream into a Q-Tube Video │
└─────────────────────────────────────────────────────────┘
Two layers, one protocol:
- QDN / Chain Layer (Signaling) — Slow, permanent, authoritative. Publishes stream metadata, publisher identity, active swarm peer lists, and encryption keys. This is the directory for the stream.
- Ephemeral P2P Mesh (Transport) — Fast, transient, in-RAM. Moves actual video fragments between peers in real time. This is the highway for the stream.
- QDN Archival (VOD Engine) — The bridge between live and on-demand. Stitches expired live fragments into permanent QDN data chunks and publishes them as a Q-Tube video when the stream ends.
- Sub-Second Fragments: The broadcaster's encoder produces ultra-short Chunked Media Application Format (CMAF) or fragmented MP4 (fMP4) slices (e.g., 500ms to 1s duration) for low-latency playback.
- Cryptographic In-Flight Signing: The broadcaster signs each chunk payload (
Sequence_ID,Timestamp,Data_Hash) using their registered Qortal Name/Key pair. Viewer nodes verify signatures in real time to prevent injection attacks or corrupted streams.
A pure BitTorrent-style mesh introduces latency; a rigid tree breaks when a node leaves. QLive uses a hybrid:
- Primary Delivery Tree (Low Latency): High-capacity, high-uptime nodes form a primary distribution tree for push-based delivery directly from the broadcaster.
- Secondary Local Swarm Mesh (Resilience): Viewer nodes nearby in the network topology exchange missing fragments over WebRTC/Reticulum data channels. If a parent node in the primary tree drops, the client falls back to pulling missing sub-chunks from its local mesh buffer.
- Nodes participating in a live stream store video fragments strictly in a rolling RAM cache (e.g., keeping only the last 30–60 seconds of video in memory).
- Once a fragment moves out of the active live window, it is flushed from RAM — avoiding disk wear and storage bloat.
As the live broadcast progresses, a background process on the streamer's node aggregates expired live chunks into standard QDN Data Chunks (e.g., 10MB–50MB blocks). When the live stream finishes:
- The static archive is committed to QDN.
- A Q-Tube manifest is published under the same Qortal Name.
- The stream instantly becomes a permanent replayable video on Q-Tube — without re-encoding.
| Challenge | QLive's Answer |
|---|---|
| Disk I/O & Storage Bloat — Live streams produce gigabytes of ephemeral video; committing every fragment to permanent QDN storage would bloat the network. | RAM-only sliding-window buffering. Fragments live in memory for 30–60s, then are flushed. Only the final archive is committed to QDN. |
| Blockchain State & Transaction Throughput — Block times and ledger consensus are far too slow for real-time video sync. | Live fragment manifests are never registered on the main Qortal ledger. Only lightweight signaling metadata (stream info, peer lists, keys) touches the chain. |
| Peer Churn & Network Instability — Viewers join/leave unpredictably; a dropped relay must not freeze downstream viewers. | Dual-layer swarm (tree + mesh). If a primary-tree parent drops, clients pull missing fragments from the local mesh buffer. |
| Feature | Traditional Live (HLS / CDN) | Decentralized P2P Mesh (QLive) |
|---|---|---|
| Ingest Infrastructure | Centralized Ingest (RTMP / Twitch / YouTube) | Direct Local Peer Broadcast |
| Bandwidth Distribution | Paid CDNs (Cloudflare, AWS CloudFront) | Distributed Peer-to-Peer Relay Swarm |
| Node Storage Impact | Infinite server storage required | Zero long-term disk impact (RAM-only rolling buffer) |
| Censorship Resistance | Single point of shutdown or domain block | Fully resistant via Qortal peer routing & encrypted swarms |
| Viewer Scalability | Costs increase linearly with viewer count | Network gets stronger as viewer count grows |
To ensure peers actually relay video traffic rather than just leeching bandwidth:
- Tit-for-Tat Data Swapping: Viewer nodes prioritize sending fragments to peers that contribute bandwidth back to the swarm.
- Proof-of-Relay (Minting / Reputation Integration): Nodes actively relaying live streams can collect signed bandwidth receipts from peer nodes. These micro-proofs could feed into Qortal's node reputation system or minting weight calculations to reward infrastructure contributors.
Status: Active development. A Python reference implementation of the core protocol (chunking, buffering, swarm, signaling, archival, incentives) and a React web UI are in place — both run fully offline against mock data. The Web UI now vendors Qortal's
qapp-corelibrary (see below) as the path to real QDN signaling / Qortal auth. Live QDN signaling and real P2P transport are not yet wired up. See TODO.md for the roadmap.
Cloning: QLive uses git submodules. Clone with
--recurse-submodules, or rungit submodule update --init --recursiveafter cloning, to fetchqapp-core/. Remote is assumed to begit@github.com:pikeaerospace-source/qlive.git; see CONTRIBUTING.md.
- Python 3.10+ (reference implementation)
- Node.js 20+ (web UI +
qapp-core) - React 19 + MUI v7 (via
qapp-corepeer deps) - FFmpeg (broadcaster encoder — optional for offline work)
- A Qortal Core / UI node (
qortalRequest— used once QDN signaling is wired)
cd src/python
pip install -e ".[dev]"
pytest # 311 tests
python -m qlive.benchmarks # offline benchmarks + simulationcd src/js
npm install
npm run dev # http://localhost:5173 (offline, mock data)The Web UI runs against one of two data sources behind a single Api
interface: an offline mock (default — canned data from src/data/mock.ts,
no Qortal node, no network) or the QDN-backed adapter (real QDN resources
via qortalRequest when running inside a Qortal UI host). To develop without a
node use the default mock; to point at a local Qortal node, load the app in a
Qortal UI (or inject a dev shim — see docs/WEB-UI-DATA-SOURCES.md).
The Web UI depends on qapp-core — Qortal's core React library — vendored as a
git submodule at qapp-core/. It provides Qortal authentication, QDN CRUD,
resource lists, a video/audio player, global state, and i18n, so QLive can talk
to the real Qortal API instead of mocking it. See TODO-QAPP-CORE.md
for the integration plan.
git submodule update --init --recursive
cd qapp-core
npm install
npm run build # builds dist/ (prepare runs automatically)
⚠️ Status: Thesrc/jstoolchain has been upgraded to React 19 + MUI v7 + Router 7 andqapp-coreis declared as afile:dependency (build =npm run build).tsc --noEmit,vitest(68/68), andvite buildare green. The remaining runtime step — mountingqapp-core'sGlobalProviderand wiring real Qortal auth/signaling — is deferred (see TODO-QAPP-CORE.md, Q3). Until then the Web UI still runs offline against mock data.
# Start a broadcaster (requires a Qortal node + FFmpeg)
qlive broadcast --name "my-qortal-name" --source "rtmp://localhost/live"
# Watch a stream
qlive watch --stream "qortal://my-qortal-name/live"
⚠️ The CLI and transport are wired to in-memory/mock components; live QDN signaling and real P2P transport are pending.
See TODO.md for the full, living roadmap. High-level milestones:
- Phase 0 — Research & Spec — Protocol design, chunk format, signaling schema.
- Phase 1 — Core Transport — Ephemeral chunking engine + RAM sliding-window buffer.
- Phase 2 — Swarm & Discovery — Dual-layer peer swarm + QDN signaling integration.
- Phase 3 — VOD Bridge — Live → Q-Tube archival pipeline.
- Phase 4 — Incentives — Tit-for-tat, proof-of-relay, reputation integration.
- Phase 5 — UX & Tooling — Broadcaster app, viewer app, Q-Tube integration.
Contributions are welcome across:
- Protocol design & specification
- Reference implementation (Python / React / WebRTC / Reticulum)
- Qortal Core integration
- Documentation & testing
Please see CONTRIBUTING.md for guidelines, SECURITY.md for security reporting, and TODO.md for open tasks.
Licensed under the MIT License. Copyright (c) 2026 Mike Sharkey mike@pikeaero.com.
QLive — live streaming that belongs to the network, not the platform.