Skip to content
MeshedFlowMeshedFlow

Core concepts

MeshedFlow is a peer-assisted delivery layer that sits behind your player. It doesn’t change your stream, your packaging, or your player — it changes where segment bytes come from.

The viewer mesh

Section titled “The viewer mesh”

When several viewers watch the same stream, they usually download the same segments from your CDN at roughly the same time. MeshedFlow connects those viewers to each other over WebRTC data channels and lets them serve segments peer-to-peer. A viewer who already has a segment can hand it to a peer who needs it next, so that segment doesn’t have to be pulled from the CDN again.

Peers find each other through a WebSocket signaling connection to your tenant’s signaling endpoint (signalingUrl). Signaling only brokers the introductions and connection setup; the actual segment bytes flow directly between browsers over the WebRTC data channel, never through the signaling server.

The SDK is an hls.js loader

Section titled “The SDK is an hls.js loader”

The SDK integrates as a custom hls.js loader. hls.js already routes every segment request through a pluggable loader; MeshedFlow replaces that loader so it can decide, per request, whether to serve a segment from a peer or from the CDN. Your application stays a normal hls.js integration — you set loader: MeshedFlowLoader and pass the MeshedFlow options in loaderConfig. See the Quickstart and SDK reference.

Because the SDK operates at the loader boundary, the player always receives the exact, complete segment bytes it expects through the normal hls.js callback — whether those bytes arrived from a peer or the CDN.

CDN fallback is automatic

Section titled “CDN fallback is automatic”

MeshedFlow never bets playback on the mesh. For every segment the loader runs a delivery decision: it gives peers a bounded window to deliver, and if they don’t, it fetches the segment from your CDN instead.

  • httpFallback (default true) keeps the CDN path available. Leaving it on is what makes the mesh safe to enable — if sharing is unavailable, slow, or a segment can’t be verified, delivery falls straight back to your origin.
  • p2pTimeoutMs (default 3000) is the base peer-delivery timeout before the loader reaches for the CDN. The SDK also adapts this per segment based on buffer health and cold-start state.

What “offload” means

Section titled “What “offload” means”

Offload is the share of delivered bytes that came from peers instead of your CDN. The SDK tracks this continuously and exposes it through getStats():

offloadRatio = offloadedBytes / totalBytes
  • offloadedBytes — bytes delivered by peers (the bytes you didn’t pay your CDN for).
  • cdnBytes — bytes fetched from the CDN.
  • sharedBytes — bytes this viewer uploaded to other peers.
  • totalBytes — total delivered bytes (the denominator for the ratio).

Higher offload means lower CDN egress. See Analytics & pilot reports for how offloaded bytes translate into cost savings.

What counts as a stream

Section titled “What counts as a stream”

A stream is one distinct streamId — the identifier you configure on the loader, formatted <customerId>:<name> (e.g. cust_123:match-day). The streamId names a piece of content; it is what groups viewers into one mesh, keys session telemetry, and is the unit the free tier’s stream cap counts.

All bitrates and renditions of the same content belong under one streamId: a 1080p/720p/480p ABR ladder of one match is one stream. Give different content — a second channel, a separate VOD title — its own streamId.

For the free tier, the platform counts distinct streamIds that had segments signed within a rolling 6-hour window. A stream that signs nothing for 6 hours stops counting automatically. If a sign request carries no streamId at all, the segment URL’s directory stands in as the stream key (segments of one stream live under one path) — the SDK always sends your configured streamId, so this fallback only matters for hand-rolled integrations. See the free developer tier for a worked example.

Live and VOD

Section titled “Live and VOD”

MeshedFlow supports both live and VOD HLS. The mesh is most effective when many viewers are watching near the same playback position — a live event with high concurrency, or a popular VOD title with overlapping sessions — because that overlap is what lets one viewer’s download help another.

Telemetry and privacy posture

Section titled “Telemetry and privacy posture”

The SDK reports anonymous session telemetry so you can measure offload and playback quality. Telemetry is on by default (telemetry: true) and reports aggregate, per-session figures — offloaded/fallback bytes, peer counts, buffer health, delivery paths, and the stall counters you feed it via markPlaybackStart() and reportRebuffer(). Set telemetry: false to disable it entirely.

Session reports are keyed by streamId. MeshedFlow is a delivery layer and works alongside your existing content protection — it never sees decrypted content, and your entitlement and rights-management flows stay on your normal path, unchanged.