<SYSTEM>This is the full developer documentation for MeshedFlow</SYSTEM>

# Quickstart

> Add MeshedFlow to a page and see peer-assisted offload in minutes.

Get MeshedFlow serving segments peer-to-peer on a test page in a few minutes. MeshedFlow ships as an [hls.js](https://github.com/video-dev/hls.js) loader, so you keep your player and your stream -- you just point hls.js at the MeshedFlow loader.

Three fields are all you need

The only required loader options are `signalingUrl`, `streamId`, and `authToken`. The public-key fetch and per-segment signature verification are **automatic** -- the SDK fetches the origin's verification key and checks every peer-delivered segment on its own.

1. **Get your credentials from the portal.**

   Sign in to the [MeshedFlow Dashboard](https://app.meshedflow.com) and open your stream. You need three values:

   * **`signalingUrl`** -- your tenant's signaling/WebSocket endpoint (the `wssEndpoint` shown when your tenant was provisioned, e.g. `wss://signal.meshedflow.com:8445/ws`).
   * **`streamId`** -- formatted as `<customerId>:<name>`, e.g. `cust_20260808_eb8790f7:live-demo`. The `<customerId>` prefix is what scopes the stream to your account.
   * **`authToken`** -- the SDK JWT you embed in your build.

   See [Authentication & provisioning](/concepts/auth/) for where each value comes from and how tokens rotate.

2. **Add your content origin in the portal.**

   Peer delivery only works for segments served from an origin you've allowlisted -- signing refuses any URL that isn't. In the portal, add your segment origin (e.g. `https://cdn.example.com`) to your tenant's content origins. See [Content signing & origins](/concepts/signing/).

   No origin, no offload

   If your content origin isn't in the allowlist, the control plane returns `403` for every sign request, no segment can be verified, and offload stays at **0%** -- all traffic falls back to your CDN. This is the single most common cause of "it's installed but offload reads zero." Add the origin first.

3. **Include the SDK and hls.js.**

   Load the SDK as an ES module from the CDN, alongside hls.js -- no build step needed. (Using a bundler instead? `npm install @meshedflow/sdk hls.js` and import from `@meshedflow/sdk` -- same build, see the SDK reference.)

   * ES module (import map)

     index.html

     ```html
     <script type="importmap">
       {
         "imports": {
           "hls.js": "https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.mjs",
           "@meshedflow/sdk": "https://meshedflow.com/sdk/dist/sdk.mjs"
         }
       }
     </script>
     <video id="video" controls playsinline></video>
     <script type="module" src="./player.js"></script>
     ```

   * Direct ESM imports

     player.js

     ```js
     import Hls from 'https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.mjs';
     import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';
     ```

   Note

   `@meshedflow/sdk` is available on request / coming soon on npm -- for now the `https://meshedflow.com/sdk/dist/sdk.mjs` module is the supported install. hls.js is a normal npm/CDN dependency.

4. **Wire the MeshedFlow loader into hls.js.**

   Pass `MeshedFlowLoader` as the hls.js `loader` and put the MeshedFlow options under `loaderConfig`. Then attach your `<video>` element and load the source exactly as you would with plain hls.js.

   player.js

   ```js
   import Hls from 'https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.mjs';
   import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';


   const video = document.getElementById('video');


   const hls = new Hls({
     loader: MeshedFlowLoader,
     loaderConfig: {
       signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
       streamId: 'cust_20260808_eb8790f7:live-demo',
       authToken: '<your-sdk-token>',
     },
   });


   hls.attachMedia(video);
   hls.loadSource('https://cdn.example.com/live-demo/master.m3u8');
   ```

   That's the whole integration. With the three required fields set and your origin allowlisted, the SDK fetches the verification key, joins the mesh, and starts pulling verified segments from peers with automatic CDN fallback.

5. **Wire the two player hooks.**

   The SDK delivers segment bytes but does not own the playback buffer, so two quality-of-experience signals must come from your player. Grab the loader instance from hls.js and call them:

   player.js

   ```js
   // hls.js constructs one loader per media playlist; reach the active
   // instance through the hls networking internals or keep your own reference.
   let loader;
   hls.on(Hls.Events.FRAG_LOADING, (_e, data) => {
     loader = data.frag?.loader ?? loader;
   });


   // Call once, when the player actually starts presenting frames.
   video.addEventListener('playing', () => loader?.markPlaybackStart(), { once: true });


   // Call on every stall/rebuffer, with the stall duration if you have it.
   video.addEventListener('waiting', () => {
     const start = performance.now();
     video.addEventListener('playing', () => {
       loader?.reportRebuffer(performance.now() - start);
     }, { once: true });
   });
   ```

   `markPlaybackStart()` enables the rebuffer counters so a stall-free session reports honest zeros; `reportRebuffer(ms)` records each stall. The SDK never estimates these -- if you don't report them, the pilot report shows them as "not captured."

6. **Verify offload with `getStats()`.**

   Poll the loader for its running offload figures:

   player.js

   ```js
   setInterval(() => {
     const s = loader?.getStats();
     if (s) {
       console.log(
         `offload ${(s.offloadRatio * 100).toFixed(1)}% | ` +
         `p2p ${s.offloadedBytes} B | cdn ${s.cdnBytes} B | shared ${s.sharedBytes} B`
       );
     }
   }, 5000);
   ```

   `getStats()` returns `{ offloadedBytes, totalBytes, cdnBytes, sharedBytes, offloadRatio }`. A rising `offloadRatio` with more than one viewer on the stream means the mesh is working. Your account-level figures are also visible in the [Dashboard](https://app.meshedflow.com) -- see [Analytics & pilot reports](/analytics/).

## Next steps

[Section titled "Next steps"](#next-steps)

* [SDK reference](/reference/sdk/) -- every loader option, the methods, and the full hls.js example.
* [Content signing & origins](/concepts/signing/) -- how verification works and why the origin allowlist gates offload.
* [Troubleshooting & FAQ](/troubleshooting/) -- if offload stays at 0% or peers fall back to CDN.

# Free developer tier

> A self-serve, no-card tenant on the production MeshedFlow network -- 50 concurrent watchers in total (at most 25 per stream) across up to 2 streams, with CDN fallback past the cap.

The free developer tier is a real tenant on the production MeshedFlow network, created self-serve from the sign-in page -- no card, no sales call. It exists so you can integrate the SDK against real infrastructure and watch genuine peer-delivered bytes before anyone talks about money.

## What you get

[Section titled "What you get"](#what-you-get)

* **A production tenant of your own.** Signup provisions a workspace with its own `customerId` and slug; everything in these docs -- the [Quickstart](/quickstart/), [content signing](/concepts/signing/), the [SDK reference](/reference/sdk/) -- works the same way it does for paying customers.
* **A portal account.** Sign in at [app.meshedflow.com](https://app.meshedflow.com) for your credentials, content-origin allowlist, per-stream telemetry, and offload figures.
* **The same SDK and delivery path.** Peer-delivered segments are verified against origin-signed manifests, and anything that can't be served peer-to-peer falls back to your CDN immediately -- the free tier does not run on a separate, smaller network.

## The hard limits

[Section titled "The hard limits"](#the-hard-limits)

The free tier has exactly three limits, and all of them are enforced by the platform, not by the honor system:

| Limit               | Value        | What it means                                                                                                      |
| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Concurrent watchers | **50 total** | Counted across **all** your streams -- 50 on the tenant is the whole allowance at any instant, however it is split. |
| Watchers per stream | **25 max**   | No single stream may hold more than 25 of those 50 at once -- two full streams (25 + 25) is the ceiling.            |
| Streams             | **2 max**    | At most two streams can exist on the tenant at once.                                                               |

50 is a total, 25 is per stream

The watcher pool is shared by every stream on the account, and no one stream may take more than half of it. Two streams do not mean 100 watchers, and one stream cannot use all 50.

## What counts as a stream

[Section titled "What counts as a stream"](#what-counts-as-a-stream)

A **stream is one distinct `streamId`** -- the identifier you pass to the SDK, formatted `<customerId>:<name>` (e.g. `cust_123:match-day`). It names a piece of content, not a rendition: every bitrate and resolution of the same content shares the one `streamId`, so a full ABR ladder -- 1080p, 720p, 480p -- is **one** stream, not three.

The platform counts streams where content signing happens: a stream is "active" while any of its segments was signed within a **rolling 6-hour window**. The cap is on *distinct active `streamId`s*, so:

* signing more segments of an already-active stream never costs anything -- it just keeps that stream active;
* a stream that signs nothing for 6 hours drops off the count by itself, and a new one can take its place -- no button to press;
* the third *distinct* `streamId` inside the window is declined at signing, and those viewers play from your CDN instead.

| You run                                                                 | Distinct active streamIds           | Counts as                                                                               |
| ----------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| One match in 1080p + 720p + 480p, all with `streamId: "cust_123:match"` | `cust_123:match`                    | **1 stream**                                                                            |
| That match plus a VOD replay (`cust_123:replay`)                        | `cust_123:match`, `cust_123:replay` | **2 streams** -- at the cap                                                              |
| A third id (`cust_123:extra`) while both are still active               | --                                   | **Declined** -- signing returns the stream-limit error; playback continues from your CDN |

One honest edge case: if a sign request carries no explicit `streamId`, the platform keys the stream by the **segment URL's directory** instead. Segments of one stream live under one path, so this normally lands on the same answer -- but a ladder that splits renditions across directories (`/720p/`, `/1080p/`) without a `streamId` would count each directory as its own stream. The SDK sends your configured `streamId` with every sign request, so this only affects hand-rolled integrations: always set `streamId`.

## What happens at the cap

[Section titled "What happens at the cap"](#what-happens-at-the-cap)

Nothing breaks, and no viewer sees an error.

* **Watcher #51 on the tenant** is simply not admitted to the mesh. The platform declines the peer session and the SDK does what it always does when peer delivery isn't available: **playback continues via your CDN**. The viewer watches normally; they just don't contribute to (or benefit from) offload.
* **Watcher #26 on a single stream** gets the same treatment even while the tenant total is under 50: the platform refuses to sign new segments for that stream, and its overflow viewers **fall back to your CDN** -- your other stream keeps meshing untouched.
* **Stream #3** is refused at provisioning time -- the request to add it fails with a clear error, and your two existing streams are unaffected.

In other words: the cap limits *offload*, never *playback*. Your telemetry in the portal will show the fallback bytes, which is also how you'll know you've outgrown the tier.

## Signup walkthrough

[Section titled "Signup walkthrough"](#signup-walkthrough)

1. **Open the signup page.**

   Go to [meshedflow.com/signup](https://meshedflow.com/signup.html). (The same form is also available from the portal sign-in page at [app.meshedflow.com](https://app.meshedflow.com/login?signup=1) under **Create free developer account**.)

2. **Fill in the form.**

   Work email, a password (minimum **12** characters, entered twice), and optionally your company name. Submitting creates the free-tier tenant and your owner account in one step.

   * If the email already has an account, you'll get a conflict message -- sign in instead.
   * Signups are rate-limited; if you're told to wait, wait a minute and retry.

3. **Check your email, then sign in.**

   Signup deliberately does not log you in. You'll see your new workspace slug on screen and a welcome note in your inbox -- sign in through the normal form with the address and password you just chose.

4. **Follow the Quickstart.**

   From here the [Quickstart](/quickstart/) applies unchanged: add your content origin to the allowlist, grab `signalingUrl` / `streamId` / `authToken` from the portal, and wire the loader into your player. With one page open in two tabs you can already watch `getStats()` report peer-delivered bytes.

## When you outgrow it

[Section titled "When you outgrow it"](#when-you-outgrow-it)

The upgrade path is a **measured pilot**, not a bigger self-serve plan. A pilot runs one of your real streams control-vs-treatment at production concurrency and hands back a report with offload, playback health, and the economics -- that report is what commercial terms are built from.

Request one from [meshedflow.com](https://meshedflow.com/) ("Book a measured pilot") or email <pilots@meshedflow.com>. Mention your free-tier workspace slug so your existing integration and telemetry carry over.

## Live network stats

[Section titled "Live network stats"](#live-network-stats)

The aggregate activity of the free developer tier is public: accounts, watchers now, active streams, and bytes served/offloaded, refreshed about once a minute. It's served from an unauthenticated endpoint on meshedflow\.com:

```plaintext
GET https://meshedflow.com/telemetry/public/network-stats
```

Response shape

```json
{
  "freeTier": {
    "accounts": 0,
    "activeViewers": 0,
    "activeStreams": 0,
    "bytesServed": 0,
    "bytesOffloaded": 0,
    "gbSaved": 0,
    "updatedAt": "2026-08-11T00:00:00Z"
  }
}
```

Only aggregates are ever exposed -- never account names or per-tenant figures. The same stats band shown on [meshedflow.com](https://meshedflow.com/#developers) is a reusable widget you can embed on your own page:

Embed the network stats widget

```html
<div data-mf-network-widget></div>
<script src="https://meshedflow.com/js/mf-network-widget.js" defer></script>
```

The widget renders into any element carrying `data-mf-network-widget`, fetches the endpoint above, refreshes roughly every 60 seconds, and shows zeros (never an error) when the network is quiet or unreachable.

# SDK reference

> The MeshedFlow browser SDK -- installation, initialization, and API surface.

The MeshedFlow browser SDK is an [hls.js](https://github.com/video-dev/hls.js) loader. You install it, pass it to hls.js as the `loader`, and put its options under `loaderConfig`. Beta [adapters](#player-adapters-beta) bring the same pipeline to Shaka Player and dash.js.

## Install

[Section titled "Install"](#install)

Install from **npm** for bundler workflows, or load the SDK as an ES module straight from the CDN -- both ship the same build.

* npm

  ```bash
  npm install @meshedflow/sdk hls.js
  ```

  ```js
  import { MeshedFlowLoader } from '@meshedflow/sdk';
  ```

* ES module import

  ```js
  import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';
  ```

* Script tag

  ```html
  <script type="module" src="https://meshedflow.com/sdk/dist/sdk.mjs"></script>
  ```

hls.js is a normal dependency -- install it from npm or a CDN as usual.

The npm package is licensed for use with the MeshedFlow service (see the `LICENSE` file in the package). The beta player adapters are available as subpath imports: `@meshedflow/sdk/adapters/shaka` and `@meshedflow/sdk/adapters/dashjs`.

## The loader

[Section titled "The loader"](#the-loader)

`MeshedFlowLoader` implements the hls.js loader interface. hls.js constructs one per request, drives its `load()` / `abort()` / `destroy()` lifecycle, and hands the delivered bytes to the player through the normal callback -- so from your player's point of view nothing changes except where the bytes come from.

player.js

```js
import Hls from 'hls.js';
import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';


const hls = new Hls({
  loader: MeshedFlowLoader,
  loaderConfig: {
    signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
    streamId: 'cust_20260808_eb8790f7:live-demo',
    authToken: '<your-sdk-token>',
  },
});
```

## Core options

[Section titled "Core options"](#core-options)

These are the options most integrations touch. `signalingUrl` and `streamId` are **required**; everything else has a default. Types and defaults below are taken verbatim from the SDK's `MeshedFlowLoaderConfig` interface.

| Option                       | Type                                                                     | Default                  | Purpose                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `signalingUrl`               | `string`                                                                 | -- (required)             | WebSocket signaling endpoint the SDK connects to for peer discovery.                                  |
| `streamId`                   | `string`                                                                 | -- (required)             | Stream identifier, formatted `<customerId>:<name>`. Scopes the session to your account.               |
| `authToken`                  | `string`                                                                 | `""`                     | JWT for peer authentication. Its `customerId` selects your signing allowlist and scopes your data.    |
| `originBaseUrl`              | `string`                                                                 | `""`                     | Origin/API base URL when signaling is served from a dedicated edge port (e.g. `https://example.com`). |
| `requireManifestSignature`   | `boolean`                                                                | `true`                   | Require a valid origin signature before accepting a peer-delivered segment.                           |
| `autoFetchManifestPublicKey` | `boolean`                                                                | `true`                   | Fetch `/manifest/public-key` from the signaling host when `manifestPublicKey` is unset.               |
| `httpFallback`               | `boolean`                                                                | `true`                   | Fall back to CDN/HTTP when peers can't deliver. Keep on for safe rollout.                             |
| `maxPeers`                   | `number`                                                                 | `10`                     | Maximum simultaneous peer connections (desktop default; mobile is capped lower internally).           |
| `receiveOnly`                | `boolean`                                                                | `false`                  | Download from peers but never upload to them.                                                         |
| `telemetry`                  | `boolean`                                                                | `true`                   | Send anonymous session telemetry. Only `false` disables it.                                           |
| `iceServers`                 | `{ urls: string \| string[]; username?: string; credential?: string }[]` | Google + Cloudflare STUN | ICE servers for WebRTC. TURN URLs are stripped unless `allowByoTurn` is `true`.                       |
| `allowByoTurn`               | `boolean`                                                                | `false`                  | Enterprise BYO-TURN: when `false`, TURN URLs are stripped from `iceServers` (STUN-only).              |
| `logLevel`                   | `number`                                                                 | `1`                      | SDK log verbosity.                                                                                    |

Tip

The default `iceServers` are STUN-only (Google + Cloudflare). See [Compatibility](/compatibility/#nat-and-ice) for when to bring your own TURN.

## Methods

[Section titled "Methods"](#methods)

Instance methods on the loader. hls.js calls `load()` / `abort()` / `destroy()` for you; `markPlaybackStart()`, `reportRebuffer()`, `getStats()`, and `refreshPeerMesh()` are the ones you call from your application.

| Method              | Signature                                                                          | Purpose                                                                                                                           |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `load`              | `load(context, config, callbacks) -> { abort }`                                     | hls.js loader entry point: loads one segment, peer-first with CDN fallback. Returns a per-request abort handle. Called by hls.js. |
| `getStats`          | `getStats() -> { offloadedBytes, totalBytes, cdnBytes, sharedBytes, offloadRatio }` | Current offload figures for this session. `offloadRatio = offloadedBytes / totalBytes`.                                           |
| `markPlaybackStart` | `markPlaybackStart() -> void`                                                       | Call when the player starts presenting frames. Enables the rebuffer counters so a stall-free session reports honest zeros.        |
| `reportRebuffer`    | `reportRebuffer(durationMs?) -> void`                                               | Call on every stall/rebuffer, with the stall duration in ms if known. The SDK never estimates stalls.                             |
| `refreshPeerMesh`   | `refreshPeerMesh() -> void`                                                         | Re-register with signaling and re-trigger peer matchmaking.                                                                       |
| `destroy`           | `destroy() -> void`                                                                 | Tear down signaling, peers, caches, and telemetry (final flush). Called by hls.js on teardown.                                    |

### `getStats()` return value

[Section titled "getStats() return value"](#getstats-return-value)

```ts
{
  offloadedBytes: number; // bytes delivered by peers
  totalBytes: number;     // total delivered bytes (denominator)
  cdnBytes: number;       // bytes fetched from the CDN
  sharedBytes: number;    // bytes this viewer uploaded to peers
  offloadRatio: number;   // offloadedBytes / totalBytes, 0..1
}
```

## Full hls.js integration

[Section titled "Full hls.js integration"](#full-hlsjs-integration)

player.js

```js
import Hls from 'hls.js';
import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';


const video = document.getElementById('video');


const hls = new Hls({
  loader: MeshedFlowLoader,
  loaderConfig: {
    signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
    streamId: 'cust_20260808_eb8790f7:live-demo',
    authToken: '<your-sdk-token>',
    // httpFallback, requireManifestSignature, autoFetchManifestPublicKey
    // all default on -- nothing else is required.
  },
});


hls.attachMedia(video);
hls.loadSource('https://cdn.example.com/live-demo/master.m3u8');


// Keep a reference to the active loader instance.
let loader;
hls.on(Hls.Events.FRAG_LOADING, (_e, data) => {
  loader = data.frag?.loader ?? loader;
});


// Report the two QoE signals the SDK can't observe on its own.
video.addEventListener('playing', () => loader?.markPlaybackStart(), { once: true });
video.addEventListener('waiting', () => {
  const start = performance.now();
  video.addEventListener('playing', () => {
    loader?.reportRebuffer(performance.now() - start);
  }, { once: true });
});


// Poll offload.
setInterval(() => {
  const s = loader?.getStats();
  if (s) console.log(`offload ${(s.offloadRatio * 100).toFixed(1)}%`);
}, 5000);
```

## Player adapters (beta)

[Section titled "Player adapters (beta)"](#player-adapters-beta)

Two beta adapters put the same delivery pipeline the hls.js loader uses -- peer-first fetch, automatic CDN fallback, signed-segment verification, and telemetry -- behind Shaka Player and dash.js. They take the **same config object** as `loaderConfig`, and both return a handle with `engine` (for `getStats()`) and `unregister()`.

Beta

Adapter interfaces may still change, and they have had far less production soak than the hls.js loader. Media segments route through the mesh; manifest and license requests always pass straight to the network.

### Shaka Player adapter (beta)

[Section titled "Shaka Player adapter (beta)"](#shaka-player-adapter-beta)

Registers a networking scheme plugin for `http`/`https` at application priority. Segment requests (including byte-ranged ones) go through the mesh; everything else uses a plain `fetch`. Shaka's abortable operations map onto the mesh fetch, so seeks and quality switches cancel cleanly.

shaka-player.js

```js
import { registerMeshedFlowShakaSupport } from 'https://meshedflow.com/sdk/dist/adapters/shaka.mjs';


shaka.polyfill.installAll();
const video = document.getElementById('video');
const player = new shaka.Player();
await player.attach(video);


const handle = registerMeshedFlowShakaSupport(shaka, player, {
  signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
  streamId: 'cust_20260808_eb8790f7:live-demo',
  authToken: '<your-sdk-token>',
});


await player.load('https://cdn.example.com/live-demo/stream.mpd');


// Offload figures, same shape as the hls.js loader's getStats().
console.log(handle.engine.getStats());


// On teardown: restores Shaka's stock network plugins.
handle.unregister();
```

The third argument also accepts an existing `MeshedFlowLoader` (or the engine from another adapter), so a page that runs hls.js and Shaka side by side can share one signaling connection and peer mesh.

### dash.js adapter (beta)

[Section titled "dash.js adapter (beta)"](#dashjs-adapter-beta)

Uses the dash.js **v5** request/response interceptor API (`player.addRequestInterceptor` / `player.addResponseInterceptor`). Media segment requests are served from the mesh -- the interceptor hands dash.js the verified bytes through a local object URL, so the player's own loader completes without touching the CDN. If the mesh can't deliver, the request is passed through unchanged and dash.js fetches it from the CDN as usual. MPD and license requests are never intercepted.

dashjs-player.js

```js
import { registerMeshedFlowDashSupport } from 'https://meshedflow.com/sdk/dist/adapters/dashjs.mjs';


const video = document.getElementById('video');
const player = dashjs.MediaPlayer().create();


const handle = registerMeshedFlowDashSupport(player, {
  signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
  streamId: 'cust_20260808_eb8790f7:live-demo',
  authToken: '<your-sdk-token>',
});


player.initialize(video, 'https://cdn.example.com/live-demo/stream.mpd', true);


console.log(handle.engine.getStats());


// On teardown: removes both interceptors.
handle.unregister();
```

Note

dash.js **v4 and older** do not expose `addRequestInterceptor`; the adapter throws a clear error there. Register the adapter on the freshly created player, before `initialize()`.

## More options

[Section titled "More options"](#more-options)

The loader accepts more options for routing policy, manifest validation, NAT/ICE, remote config, and caching. **Most integrators never set these** -- see [More options](/reference/advanced/) for the full reference.

## Related

[Section titled "Related"](#related)

* [Quickstart](/quickstart/) -- the step-by-step wiring.
* [HTTP API reference](/reference/api/) -- the endpoints behind the SDK.
* [Content signing & origins](/concepts/signing/) -- how verification works.

# Analytics & pilot reports

> Reading MeshedFlow offload metrics and pilot performance reports.

MeshedFlow measures real delivery. Everything you see is derived from the session reports the SDK posts during playback -- offloaded bytes, fallback bytes, peer counts, buffer health, and the stall counters your player reports.

## What you can see in the portal

[Section titled "What you can see in the portal"](#what-you-can-see-in-the-portal)

The [Dashboard](https://app.meshedflow.com) shows your streams and, per stream:

* **Offload %** -- the share of delivered bytes served by peers instead of your CDN (`avgOffloadRatio`).
* **Bytes offloaded vs. fallback** -- the peer-delivered and CDN-delivered byte totals.
* **Peers** -- average peer count per session over the window.
* **Sessions and buffer health** -- session totals and average buffer health.

The same figures are available over the [HTTP API](/reference/api/#telemetry) -- `GET /telemetry/streams?detail=1`, `GET /telemetry/metrics/:streamId`, `GET /telemetry/timeseries`, and `GET /telemetry/export`.

Note

A chart that honestly reads zero is a fact about your deployment, not a gap in the dashboard -- the platform never seeds or estimates a number. If offload reads zero, see [Troubleshooting](/troubleshooting/).

## The pilot report

[Section titled "The pilot report"](#the-pilot-report)

A pilot report is a report of your event's offload and savings -- a structured document composed from your stream's session reports, your billing rates, and the platform's live configuration. Retrieve it from:

```text
GET /control/reports/pilot/:streamId
```

The `:streamId` must be one of your own streams. See the [HTTP API reference](/reference/api/#pilot-reports) for auth and query params.

### The three formats

[Section titled "The three formats"](#the-three-formats)

Pass `?format=`:

* **`json`** (default) -- the full structured report object.
* **`md`** / **`markdown`** -- a downloadable Markdown document, structured to the MeshedFlow pilot report template, with operator-judgement fields left blank.
* **`html`** -- a self-contained, styled HTML document (the artifact typically emailed to a pilot company).

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/reports/pilot/cust_20260808_eb8790f7:live-demo?format=html" \
  -o pilot-report.html
```

### What the report contains

[Section titled "What the report contains"](#what-the-report-contains)

The rendered report includes:

* **Pilot metadata** -- date range, streams tested, viewer count and device mix, regions, and signaling deployment.
* **Configuration** -- SDK and signaling versions, remote-config policy, upload caps, auth mode, telemetry retention, and data region.
* **Results** -- total sessions and bytes, P2P-offloaded vs. CDN-fallback bytes, aggregate and steady-state offload ratio (with cold-start and final windows), rebuffer events, startup-time p95, average peer count, P2P connection success, and signaling errors -- compared against a CDN-only control cohort when one ran.
* **Routing breakdown** -- fallback reasons, delivery modes and paths, validation failures, and busy-peer events.
* **Cost impact** -- offloaded GB, avoided CDN cost, the MeshedFlow fee, and net savings (see below).
* **Event economics** -- a peak-concurrency-based forecast cross-check.
* **Conclusion** -- an auto-assessed pass/review against explicit criteria, with risks and required fixes. Operator-judgement lines (approved public claims, final pass/fail sign-off) are left for a human to fill in -- the system never writes the conclusion of its own evaluation.

## How savings are computed

[Section titled "How savings are computed"](#how-savings-are-computed)

The cost figures come from **your offloaded bytes** and **your CDN rate** -- not an assumed benchmark:

```text
offloaded GB       = bytesOffloaded / 1e9
avoided CDN cost   = offloaded GB x your CDN $/GB
MeshedFlow fee     = avoided CDN cost x savings-share %
net saving         = avoided CDN cost - MeshedFlow fee
```

MeshedFlow bills a **share of the CDN spend you avoided**, so the fee only exists where there were real savings. When no CDN rate is on file for your account, the report falls back to a platform-default rate and **says so** -- a savings figure argued from an assumed rate always admits the assumption. Set your real CDN rate so the numbers are yours.

## Related

[Section titled "Related"](#related)

* [Core concepts -> What "offload" means](/concepts/core/#what-offload-means).
* [HTTP API reference](/reference/api/) -- the telemetry and report endpoints.

# Compatibility

> Supported players, browsers, protocols, and platforms for MeshedFlow.

MeshedFlow runs in the browser, behind your player, over standard web platform APIs. This page covers what it works with and how device class shapes behavior.

## Players

[Section titled "Players"](#players)

* **hls.js** -- **generally available.** The primary, supported integration: MeshedFlow ships as an hls.js [loader](/reference/sdk/#the-loader). If you play HLS with hls.js, you keep your player and wire MeshedFlow in as the loader.
* **Shaka Player** -- **beta**, via the [Shaka adapter](/reference/sdk/#shaka-player-adapter-beta).
* **dash.js** -- **beta** (v5+), via the [dash.js adapter](/reference/sdk/#dashjs-adapter-beta).

### Players that embed hls.js

[Section titled "Players that embed hls.js"](#players-that-embed-hlsjs)

Many popular players are wrappers around hls.js -- **video.js in hls.js mode** (via an hls.js source-handler plugin), **Plyr**, **Clappr**, and **ArtPlayer** among them. Where the wrapper works, MeshedFlow works: the integration is the same `loader` / `loaderConfig` pair the [SDK reference](/reference/sdk/#the-loader) documents, passed through the wrapper's hls.js config.

```js
// Clappr example -- wrappers that accept an hls.js config forward it verbatim.
import { MeshedFlowLoader } from 'https://meshedflow.com/sdk/dist/sdk.mjs';


const player = new Clappr.Player({
  parentId: '#player',
  source: 'https://cdn.example.com/live-demo/master.m3u8',
  playback: {
    hlsjsConfig: {
      loader: MeshedFlowLoader,
      loaderConfig: {
        signalingUrl: 'wss://signal.meshedflow.com:8445/ws',
        streamId: 'cust_20260808_eb8790f7:live-demo',
        authToken: '<your-sdk-token>',
      },
    },
  },
});
```

For wrappers where you construct the `Hls` instance yourself (Plyr, ArtPlayer's `customType`), create `new Hls({ loader: MeshedFlowLoader, loaderConfig: { ... } })` and attach it to the wrapper's `<video>` element as usual.

### Shaka Player (beta)

[Section titled "Shaka Player (beta)"](#shaka-player-beta)

A beta adapter registers MeshedFlow as a Shaka networking scheme plugin for `http`/`https`: media **segment** requests go through the mesh (peer-first, CDN fallback, signed-segment verification); manifest, license, and every other request type passes straight to the network, untouched. Shaka's request cancellation maps onto the mesh fetch. See the [SDK reference](/reference/sdk/#shaka-player-adapter-beta) for the snippet.

### dash.js (beta)

[Section titled "dash.js (beta)"](#dashjs-beta)

A beta adapter uses the dash.js **v5** request/response interceptor API (`player.addRequestInterceptor`) to serve media segments from the mesh with automatic CDN fallback; MPD and license requests pass through untouched. dash.js v4 does not expose these interceptors -- for v4, use an hls.js-style low-level integration or ask us. See the [SDK reference](/reference/sdk/#dashjs-adapter-beta) for the snippet.

Beta status

The Shaka Player and dash.js adapters are beta: interfaces may still change, and they have seen far less production soak than the hls.js loader. Keep `httpFallback` on (the default) so playback never depends on the mesh.

## Formats

[Section titled "Formats"](#formats)

* **HLS** -- supported. MeshedFlow works with your existing HLS packaging.
* **DASH** -- beta, through the Shaka Player and dash.js adapters above.

Your packaging workflow is unchanged -- MeshedFlow is a delivery layer, not a packaging or rights-management layer.

## Browser requirements

[Section titled "Browser requirements"](#browser-requirements)

MeshedFlow needs these web platform APIs:

* **WebRTC** -- `RTCPeerConnection` and `RTCDataChannel` (the peer data path).
* **WebSocket** -- for signaling / peer discovery.
* **SubtleCrypto** (`crypto.subtle`) -- for verifying segment signatures.

Minimum supported environments:

* **Chrome desktop** -- current and previous major.
* **Edge desktop** -- current and previous major.
* **Chrome Android** -- current and previous major.
* **Safari** -- treat as experimental unless verified for your content.
* **iOS** -- treat as constrained: WebRTC/DataChannel support and background behavior vary.

Note

Where a browser lacks a required API or the mesh is otherwise unavailable, the SDK falls back to your CDN -- playback is never blocked by an unsupported environment, it just doesn't offload there.

## Device behavior

[Section titled "Device behavior"](#device-behavior)

The SDK adapts its participation to the device class:

* **Desktop** -- connects to up to \~10 peers (`maxPeers` default `10`).
* **Mobile** -- connects to fewer peers (mobile is capped lower internally) and applies upload caps to protect data and battery. A smaller in-memory cache applies on mobile automatically.
* **TV / constrained clients** -- can run **receive-only** (`receiveOnly: true`), downloading from peers without uploading to them.

## NAT and ICE

[Section titled "NAT and ICE"](#nat-and-ice)

By default the SDK is **STUN-only**: it uses public STUN servers (Google + Cloudflare) and does not relay through TURN. TURN URLs passed in `iceServers` are stripped unless you opt in.

* To **bring your own TURN**, set `allowByoTurn: true` and provide your TURN servers in `iceServers`.
* `iceDirectTimeoutMs` (default `45000`) bounds direct ICE setup before the SDK abandons a direct peer connection and lets the segment fall back to the CDN.

Clients behind **symmetric NAT** often can't establish a direct data channel STUN-only and will fall back to CDN for delivery. If a meaningful share of your audience is behind symmetric NAT and you want them meshing, add TURN -- see [Troubleshooting](/troubleshooting/#symmetric-nat-clients-fall-back-to-cdn).

## Related

[Section titled "Related"](#related)

* [SDK reference -> Core options](/reference/sdk/#core-options) -- `maxPeers`, `receiveOnly`, `iceServers`, `allowByoTurn`.
* [Troubleshooting & FAQ](/troubleshooting/).

# Authentication & provisioning

> Identity, tenant provisioning, and zero-touch onboarding in MeshedFlow.

Everything you do with MeshedFlow -- joining the mesh, signing manifests, reading your telemetry -- is scoped to your **tenant**. This page covers how a tenant is provisioned, where your credentials come from, and how they're scoped.

## How a company is provisioned

[Section titled "How a company is provisioned"](#how-a-company-is-provisioned)

A tenant is an attribution and policy unit on a shared delivery fleet. When MeshedFlow provisions your company, onboarding is zero-touch:

1. **You're invited.** The contact on the account becomes the tenant's first member -- an **owner** with a pending invite.

2. **A branded invite email goes out.** The email carries a one-time invite link back to the portal login (`https://app.meshedflow.com/login?invite=...`). If the mailer is unconfigured or the message bounces, an operator can hand you the invite token directly -- both paths land on the same acceptance screen.

3. **You set a password.** Accepting the invite lets you set a credential and sign in. From then on you use the [portal](https://app.meshedflow.com) for everything.

Additional teammates are invited the same way -- an owner or operator invites them by email, and they accept and set a password. One email address is one person: you can't be invited into two tenants under the same address.

## Where your credentials come from

[Section titled "Where your credentials come from"](#where-your-credentials-come-from)

When your tenant is provisioned you get an SDK integration set. Three values go into the loader:

* **`signalingUrl`** -- your tenant's signaling/WebSocket endpoint. This is the `wssEndpoint` returned at provisioning time (for example `wss://signal.meshedflow.com:8445/ws`). It's where the SDK connects for peer discovery.
* **`streamId`** -- the identifier for one stream, formatted as **`<customerId>:<name>`** (for example `cust_20260808_eb8790f7:live-demo`). The `<customerId>` prefix is what ties the stream to your account.
* **`authToken`** -- the SDK JWT you embed in your build. It carries your `customerId`, which is what the control plane uses to select your signing allowlist and to scope your data.

## The `<customerId>:<name>` boundary rule

[Section titled "The \<customerId>:\<name> boundary rule"](#the-customeridname-boundary-rule)

A stream belongs to your account when its id **is** your `customerId`, or starts with your `customerId` **followed by a separator** -- one of `:`, `/`, `-`, or `_`. The separator matters: it stops `acme` from claiming a stream called `acmecorp-live`. Concretely, for `customerId = cust_20260808_eb8790f7`:

```text
cust_20260808_eb8790f7:live-demo  OK belongs to you  (":" separator)
cust_20260808_eb8790f7/vod/movie  OK belongs to you  ("/" separator)
cust_20260808_eb8790f7            OK belongs to you  (exact match)
cust_20260808_eb8790f72:live      X different customer (no separator after your id)
```

The `<customerId>:<name>` form is the convention we recommend, and it's the same boundary the API uses to decide which streams, metrics, and reports you're allowed to read.

## Token lifetime and rotation

[Section titled "Token lifetime and rotation"](#token-lifetime-and-rotation)

SDK tokens are long-lived on purpose -- you embed one in a build and it has to outlive any single portal session. The SDK token issued at provisioning is valid for **90 days**. Rotate it by issuing a fresh token from the portal and shipping it in your next build; an already-issued token runs until it expires.

Note

The public verification key the SDK fetches for signature checks is a **separate** key from your `authToken` -- you never handle the signing key, and rotating your token doesn't affect verification. See [Content signing](/concepts/signing/).

## Tenant-role scoping

[Section titled "Tenant-role scoping"](#tenant-role-scoping)

Your session is scoped to your own tenant. A tenant-role token:

* sees **only its own streams** -- list, metrics, timeseries, export, and pilot reports are all narrowed to streams that match your `customerId` under the boundary rule above;
* manages **only its own** content-origin allowlist;
* is **refused** platform-wide reads that have no per-customer meaning (asking for those returns `403`).

For exactly which endpoints a tenant token may and may not call, see the [HTTP API reference](/reference/api/#what-a-tenant-token-can-call).

## Related

[Section titled "Related"](#related)

* [Content signing & origins](/concepts/signing/) -- how your `customerId` selects the signing allowlist.
* [HTTP API reference](/reference/api/) -- the endpoints your token can call.

# Core concepts

> How the MeshedFlow mesh, signaling, and segment exchange fit together.

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"](#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-is-an-hlsjs-loader)

The SDK integrates as a custom [hls.js](https://github.com/video-dev/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](/quickstart/) and [SDK reference](/reference/sdk/).

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"](#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.

Caution

If you set `httpFallback: false`, a segment that peers can't deliver has nowhere to go. Keep fallback on unless you have a specific reason not to.

## What "offload" means

[Section titled "What "offload" means"](#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()`](/reference/sdk/#methods):

```text
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](/analytics/) for how offloaded bytes translate into cost savings.

## What counts as a stream

[Section titled "What counts as a stream"](#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 `streamId`s 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](/free-tier/#what-counts-as-a-stream) for a worked example.

## Live and VOD

[Section titled "Live and VOD"](#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"](#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()`](/reference/sdk/#methods). 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.

Content signing

Why every peer segment is verified before it plays -- [Content signing & origins](/concepts/signing/).

Authentication

How credentials and provisioning work -- [Authentication & provisioning](/concepts/auth/).

# Content signing & origins

> How MeshedFlow signs manifests and enforces per-tenant content-origin allowlists.

Peer delivery introduces a trust problem: if a viewer accepts segment bytes from another viewer, how does it know those bytes are the real segment and not something a malicious peer swapped in? MeshedFlow answers this with **origin-signed segment manifests**. A peer can hand you bytes, but it can't make you accept bytes that don't match what your origin signed.

## Why signing exists

[Section titled "Why signing exists"](#why-signing-exists)

The mesh is only safe if a peer can never feed you tampered media. Every segment a peer delivers is checked, byte for byte, against a manifest that was signed by MeshedFlow's control plane using a key only the control plane holds. If the bytes don't match the signed manifest, the segment is rejected and the request falls back to your CDN. Only verified media is ever handed to the player.

## How it works

[Section titled "How it works"](#how-it-works)

1. **The control plane holds the signing key.** MeshedFlow's control plane holds an **ECDSA P-256** private key. It is the only signer -- the key never leaves the control plane.

2. **Signing re-fetches from your origin.** When a manifest is signed, the control plane fetches the segment **directly from your origin**, recomputes its SHA-256 checksums, and only signs a manifest that matches the real origin bytes. A client can't get a signature for content the origin never served.

3. **The SDK auto-fetches the public key.** On startup the SDK fetches the published verification key (a JWK, ECDSA P-256 / SHA-256) from the signaling host and uses it to verify every peer-delivered segment. This is controlled by two options, both on by default:

   * **`autoFetchManifestPublicKey`** (default `true`) -- fetch the public key automatically. You don't ship the key yourself.
   * **`requireManifestSignature`** (default `true`) -- require a valid signature before accepting a peer segment.

4. **Every peer segment is verified.** Before a peer-delivered segment reaches the player, the SDK checks its bytes against the signed manifest. A mismatch is rejected and the segment is fetched from the CDN instead.

Tip

You don't call any of this. With the [three required options](/quickstart/) set, the key fetch and per-segment verification happen automatically inside the SDK.

## The content-origin allowlist gate

[Section titled "The content-origin allowlist gate"](#the-content-origin-allowlist-gate)

Signing is scoped per tenant by a **content-origin allowlist**. When the control plane is asked to sign a segment manifest, it looks up the effective allowlist for the caller's `customerId` and refuses to sign any URL that isn't on it.

An origin matches when:

* the **scheme and host match** (compared case-insensitively -- `https` + `cdn.example.com`), and
* if the allowlist entry includes a **path prefix**, the segment URL's path starts with it. An entry with no path (or just `/`) matches any path on that host.

The effective list is **per tenant**: the control plane uses your tenant's own allowlist when you've set one, and falls back to the platform's global env allowlist otherwise. **If the effective allowlist is empty, every sign request returns `403`** -- nothing can be verified, so nothing offloads.

An empty or wrong allowlist means 0% offload

This is the number-one reason a correct-looking integration shows **0% offload**: the segment origin isn't in the allowlist, so signing returns `403`, no segment verifies, and everything falls back to the CDN. Add your origin in the portal first -- see the [API origins endpoints](/reference/api/#content-origins) and [Troubleshooting](/troubleshooting/).

## Managing your origins

[Section titled "Managing your origins"](#managing-your-origins)

You manage the allowlist from the portal, or via the HTTP API:

* **`GET /control/tenants/:id/origins`** -- read your current allowlist.
* **`PUT /control/tenants/:id/origins`** -- replace it.

Both accept your **tenant id or your `customerId`** in `:id`, and a tenant-role session may manage **only its own** list. Origins must be valid `http`/`https` URLs with a host. An empty list clears your tenant's allowlist and falls back to the platform default. See the [HTTP API reference](/reference/api/#content-origins).

## Related

[Section titled "Related"](#related)

* [Authentication & provisioning](/concepts/auth/) -- where your `customerId` and token come from (the token's `customerId` selects the allowlist).
* [Core concepts](/concepts/core/) -- how verification fits into the delivery decision and CDN fallback.

# MeshedFlow

> Peer-assisted video delivery. Offload CDN egress to a verified mesh of viewers -- same player, same stream, lower bill.

**MeshedFlow is a peer-assisted delivery layer for HLS video.** It runs behind your existing player: viewers help serve segments to one another over WebRTC, and anything that can't be delivered peer-to-peer falls back to your CDN immediately. Every peer-delivered segment is verified against an origin-signed manifest before it reaches the player, so a peer can never feed a viewer tampered bytes.

The result: you cut CDN egress on live and VOD by shifting delivery to a verified viewer mesh -- without changing your stream, your packaging, or the player your viewers already use.

Get started

Add MeshedFlow to a page and watch offload climb in minutes -- the [Quickstart](/quickstart/) walks the full wiring end to end.

SDK reference

The loader options, methods, and the hls.js integration -- see the [SDK reference](/reference/sdk/).

Understand the model

How the mesh, [content signing](/concepts/signing/), and [provisioning](/concepts/auth/) fit together in [Core concepts](/concepts/core/).

Run a pilot

Read your [analytics & pilot reports](/analytics/), check [compatibility](/compatibility/), and open the [Dashboard](https://app.meshedflow.com).

***

**For AI agents:** this site publishes [llms.txt](/llms.txt) (an index of every page) and [llms-full.txt](/llms-full.txt) (the complete docs as one markdown file) -- point your agent or coding assistant at either instead of scraping the HTML.

# More options

> Additional configuration flags and advanced integration options for MeshedFlow.

Tip

**Most integrators never set any of these.** The [three required options](/quickstart/) plus the [core options](/reference/sdk/#core-options) cover the overwhelming majority of integrations. Reach for this page only when you're tuning a specific behavior. Types and defaults are taken verbatim from the SDK's `MeshedFlowLoaderConfig` interface.

## Identity & stream shaping

[Section titled "Identity & stream shaping"](#identity--stream-shaping)

| Option         | Type                       | Default        | Purpose                                                                               |
| -------------- | -------------------------- | -------------- | ------------------------------------------------------------------------------------- |
| `peerId`       | `string`                   | auto-generated | Stable identifier for this peer. Generated per session if omitted.                    |
| `rendition`    | `string`                   | `""`           | Rendition label for the stream, used to scope peer matching by quality level.         |
| `regionTag`    | `string`                   | `""`           | Optional region label for the session, used to group peers.                           |
| `videoElement` | `HTMLVideoElement \| null` | `null`         | Video element to read buffer health from. Defaults to the first `<video>` in the DOM. |

## Routing policy

[Section titled "Routing policy"](#routing-policy)

| Option                     | Type     | Default | Purpose                                                                                |
| -------------------------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| `p2pTimeoutMs`             | `number` | `3000`  | Base peer-delivery timeout before reaching for the CDN. Adapts per segment internally. |
| `maxInFlightChunksPerPeer` | `number` | `2`     | Max concurrent chunk requests to a single peer.                                        |
| `chunkRetryPeerLimit`      | `number` | `2`     | How many peers a failed chunk is retried across before falling back to the CDN.        |

## Manifest signing & validation

[Section titled "Manifest signing & validation"](#manifest-signing--validation)

| Option                      | Type                                        | Default       | Purpose                                                                                           |
| --------------------------- | ------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `manifestPublicKey`         | `CryptoKey \| JsonWebKey \| string \| null` | `null`        | Pin the verification key instead of auto-fetching it.                                             |
| `manifestSignatureEncoding` | `ManifestSignatureEncoding`                 | `"base64url"` | Encoding of the manifest signature (matches the control plane's `r\|\|s` base64url).              |
| `requireMerkleValidation`   | `boolean`                                   | `false`       | Require Merkle-proof validation of chunks in addition to the segment signature.                   |
| `manifestSigningUrl`        | `string`                                    | `""`          | Override the origin manifest signing endpoint. Defaults to the signaling host's `/manifest/sign`. |

## NAT / ICE

[Section titled "NAT / ICE"](#nat--ice)

| Option               | Type      | Default | Purpose                                                   |
| -------------------- | --------- | ------- | --------------------------------------------------------- |
| `iceDirectTimeoutMs` | `number`  | `45000` | STUN-only ICE setup timeout before abandoning direct P2P. |
| `natDetection`       | `boolean` | `true`  | When `false`, skip client-side connectivity probing.      |

Note

For bringing your own TURN servers, use `iceServers` together with `allowByoTurn` from the [core options](/reference/sdk/#core-options) -- see [Compatibility -> NAT and ICE](/compatibility/#nat-and-ice).

## Remote config

[Section titled "Remote config"](#remote-config)

| Option                  | Type     | Default | Purpose                                                            |
| ----------------------- | -------- | ------- | ------------------------------------------------------------------ |
| `remoteConfigUrl`       | `string` | `""`    | URL to fetch remote routing config from.                           |
| `remoteConfigRefreshMs` | `number` | `0`     | Refresh interval for remote config; `0` disables periodic refresh. |

## Caching

[Section titled "Caching"](#caching)

| Option          | Type     | Default                                         | Purpose                                                         |
| --------------- | -------- | ----------------------------------------------- | --------------------------------------------------------------- |
| `maxCacheBytes` | `number` | `1073741824` (1 GB; capped to 200 MB on mobile) | Max bytes for the in-memory segment cache used for P2P sharing. |

## Telemetry endpoints

[Section titled "Telemetry endpoints"](#telemetry-endpoints)

| Option              | Type     | Default                            | Purpose                                                                        |
| ------------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------------ |
| `telemetryEndpoint` | `string` | `""` (derived from `signalingUrl`) | Explicit telemetry ingest endpoint. Derived from the signaling URL when unset. |
| `telemetryUrl`      | `string` | `""`                               | Deprecated alias for `telemetryEndpoint`.                                      |

## Segment URL handling

[Section titled "Segment URL handling"](#segment-url-handling)

| Option                  | Type                      | Default     | Purpose                                                                                    |
| ----------------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `segmentUrlNormalizer`  | `(url: string) => string` | `undefined` | Function to normalize segment URLs to a stable cache key (e.g. strip signed query params). |
| `segmentUrlQueryParams` | `string[]`                | `undefined` | Query params to preserve/consider when keying segments.                                    |

## Related

[Section titled "Related"](#related)

* [SDK reference](/reference/sdk/) -- install, core options, and methods.
* [Compatibility](/compatibility/) -- device behavior, NAT/ICE, and BYO TURN.

# HTTP API reference

> MeshedFlow control-plane and manifest HTTP endpoints available to a tenant token.

The MeshedFlow HTTP API lets you read your telemetry, manage your content origins, and pull pilot reports programmatically. This page documents the endpoints a **tenant-role** token (the SDK/API token issued to your account) is allowed to call.

## Base URL and auth

[Section titled "Base URL and auth"](#base-url-and-auth)

* **Base URL** -- the control plane on your tenant's host (the API served alongside your portal, e.g. `https://app.meshedflow.com`).
* **Auth** -- a Bearer token: your SDK/API token.

```http
Authorization: Bearer <your-sdk-token>
```

Your token carries your `customerId`. The API uses it to scope every read to your own streams, using the `<customerId>:<name>` boundary rule from [Authentication](/concepts/auth/#the-customerid-name-boundary-rule).

What a tenant token can call

A tenant token is deliberately scoped. It can read **its own** streams, metrics, timeseries, exports, and pilot reports, and manage **its own** content origins. Platform-wide reads are refused -- see [Not available to tenant tokens](#not-available-to-tenant-tokens).

## Telemetry

[Section titled "Telemetry"](#telemetry)

### GET /telemetry/streams

[Section titled "GET /telemetry/streams"](#get-telemetrystreams)

Lists your stream ids. A tenant token sees only streams attributed to your `customerId`. Add `?detail=1` to get a per-stream summary table instead of ids.

**Query params:** `window` (`24h` default, `7d`, `30d`, `1h`, `all`), `detail` (`1` / `true`).

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/streams?window=24h"
```

```json
{ "streams": ["cust_20260808_eb8790f7:live-demo", "cust_20260808_eb8790f7:vod-42"] }
```

With `?detail=1`, each entry is a summary object (`streamId`, `totalSessions`, `totalBytesOffloaded`, `totalBytesFallback`, `avgOffloadRatio`, `avgPeerCount`, `avgBufferHealth`, `activePeers`, `live`, `lastSeenAt`).

### GET /telemetry/metrics/:streamId

[Section titled "GET /telemetry/metrics/:streamId"](#get-telemetrymetricsstreamid)

Aggregated metrics for one of **your** streams. Requesting a stream that isn't attributed to your `customerId` returns `403`.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/metrics/cust_20260808_eb8790f7:live-demo?window=24h"
```

```json
{
  "streamId": "cust_20260808_eb8790f7:live-demo",
  "totalSessions": 1842,
  "totalBytesOffloaded": 734000000000,
  "totalBytesFallback": 266000000000,
  "avgOffloadRatio": 0.734,
  "avgPeerCount": 6.1,
  "avgBufferHealth": 12.4
}
```

Caution

`GET /telemetry/metrics` (no `:streamId`) is the **platform-wide** aggregate and is refused for tenant tokens -- see [below](#not-available-to-tenant-tokens). Use the per-stream form.

### GET /telemetry/timeseries

[Section titled "GET /telemetry/timeseries"](#get-telemetrytimeseries)

Bucketed series for one of your streams. A tenant token **must** name one of its own streams with `?streamId=` -- without it the request would return the platform-wide series, so it's refused (`403`). A `streamId` that isn't yours also returns `403`.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/timeseries?streamId=cust_20260808_eb8790f7:live-demo&bucketSeconds=600"
```

### GET /telemetry/export

[Section titled "GET /telemetry/export"](#get-telemetryexport)

Streams an export of one of your streams. Requires the `telemetry:read` capability (which a tenant token has) and, like timeseries, **requires `?streamId=`** naming one of your own streams -- otherwise the request is refused rather than exporting the platform-wide aggregate.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/telemetry/export?streamId=cust_20260808_eb8790f7:live-demo&window=7d" \
  -o export.json
```

## Content origins

[Section titled "Content origins"](#content-origins)

The per-tenant allowlist that [`/manifest/sign`](/concepts/signing/) enforces. Both routes accept your **tenant id or your `customerId`** in `:id`, and a tenant session may manage **only its own** list.

### GET /control/tenants/:id/origins

[Section titled "GET /control/tenants/:id/origins"](#get-controltenantsidorigins)

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/tenants/cust_20260808_eb8790f7/origins"
```

```json
{ "origins": ["https://cdn.example.com"] }
```

### PUT /control/tenants/:id/origins

[Section titled "PUT /control/tenants/:id/origins"](#put-controltenantsidorigins)

Replaces your allowlist. Origins must be valid `http`/`https` URLs with a host. An empty array clears your allowlist and falls back to the platform default.

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"origins":["https://cdn.example.com","https://vod.example.com/hls"]}' \
  "https://app.meshedflow.com/control/tenants/cust_20260808_eb8790f7/origins"
```

```json
{ "origins": ["https://cdn.example.com", "https://vod.example.com/hls"] }
```

Note

The allowlist is enforced upstream at the signer, so a `PUT` is pushed to the control plane synchronously -- if the control plane refuses or is unreachable, the request returns `502` and nothing is saved.

## Pilot reports

[Section titled "Pilot reports"](#pilot-reports)

### GET /control/reports/pilot/:streamId

[Section titled "GET /control/reports/pilot/:streamId"](#get-controlreportspilotstreamid)

A structured pilot report for one of your streams. Requires the `telemetry:read` capability; a tenant token may only request a stream attributed to it (`403` otherwise). By default returns JSON; add `?format=` for other renderings.

**Query params:** `format` (`json` default, `md` / `markdown`, `html`), `bucketSeconds` (`60`-`21600`, default `600`).

```bash
# JSON (default)
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/reports/pilot/cust_20260808_eb8790f7:live-demo"


# Downloadable Markdown or self-contained HTML
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meshedflow.com/control/reports/pilot/cust_20260808_eb8790f7:live-demo?format=html" \
  -o pilot-report.html
```

See [Analytics & pilot reports](/analytics/) for what the report contains and how its cost figures are computed.

## Manifest

[Section titled "Manifest"](#manifest)

### GET /manifest/public-key

[Section titled "GET /manifest/public-key"](#get-manifestpublic-key)

Public (no auth). Returns the ECDSA P-256 verification key (a JWK) SDK clients use to verify peer segments.

Tip

**You normally don't call this** -- the SDK fetches it automatically (`autoFetchManifestPublicKey`, on by default) to verify every peer segment. It's documented here for completeness. Signing (`POST /manifest/sign`) is performed by the control plane on the SDK's behalf; it is not a tenant-facing integration endpoint.

```bash
curl "https://app.meshedflow.com/manifest/public-key"
```

```json
{ "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "use": "sig", "alg": "ES256" }
```

## Not available to tenant tokens

[Section titled "Not available to tenant tokens"](#not-available-to-tenant-tokens)

The following return **`403`** for a tenant-role token because they read across every customer on the shared fleet and have no per-customer meaning:

* **`GET /telemetry/metrics`** -- platform-wide aggregate. Use `GET /telemetry/metrics/:streamId` instead.
* **Platform-wide billing reads** -- `GET /billing/summary`, `GET /billing/invoices`, and any `/billing/customers/...`, `/billing/usage/...`, or `/billing/invoices/...` route naming a customer other than yours.

Tenant-management routes such as the tenant list and tenant detail (`GET /control/tenants`, `GET /control/tenants/:id`) require the `tenants:read` capability, which a tenant-role token does not carry -- the origins routes above are the exception, gated by a customer-match check rather than that capability.

## Related

[Section titled "Related"](#related)

* [SDK reference](/reference/sdk/) -- the loader that calls this API for you.
* [Authentication & provisioning](/concepts/auth/) -- token scoping and the boundary rule.

# Troubleshooting & FAQ

> Common issues, diagnostics, and frequently asked questions for MeshedFlow.

If MeshedFlow is installed but not behaving as expected, this page walks the common causes. Start by polling [`getStats()`](/reference/sdk/#methods) -- the `offloadRatio`, `cdnBytes`, and `sharedBytes` numbers tell you which problem you have.

## Offload reads 0%

[Section titled "Offload reads 0%"](#offload-reads-0)

By far the most common issue, and almost always one of the following:

* **Your content origin isn't allowlisted.** Signing refuses any URL that isn't on your tenant's content-origin allowlist, so no segment verifies and everything falls back to the CDN. **Fix:** add your segment origin in the portal, or via `PUT /control/tenants/:id/origins`. The allowlist match is scheme + host (case-insensitive), plus an optional path prefix -- make sure the entry matches the host your segments are actually served from. See [Content signing & origins](/concepts/signing/#the-content-origin-allowlist-gate) and the [origins API](/reference/api/#content-origins).
* **The verification key isn't reachable.** With `autoFetchManifestPublicKey` on (the default), the SDK fetches the public key from the signaling host. If that fetch fails, peer segments can't be verified and are rejected. **Fix:** confirm `signalingUrl` is correct and `GET /manifest/public-key` on your host returns the JWK.
* **`requireManifestSignature` mismatch.** If you've turned signature requirements off on the client but expect verified offload -- or vice versa -- behavior won't match. **Fix:** leave `requireManifestSignature` at its default (`true`) unless you have a specific reason to change it.
* **Only one viewer.** The mesh needs peers watching near the same position. With a single session there's no one to share with. **Fix:** test with several concurrent viewers on the same stream.

Caution

The single most frequent root cause is the **origin allowlist**. If offload is zero on a multi-viewer stream, check that first.

## TLS / host errors

[Section titled "TLS / host errors"](#tls--host-errors)

* **Wrong scheme or host in the allowlist.** The signer compares the segment URL's scheme and host against the allowlist. An `http` entry won't match `https` segments (and vice versa), and a bare host mismatch fails. **Fix:** allowlist the exact scheme + host your CDN serves.
* **Signaling won't connect.** `signalingUrl` must be a reachable `wss://` endpoint with a valid certificate. **Fix:** verify the `wssEndpoint` from provisioning and that the port (e.g. `:8445`) is correct and open.

## Symmetric-NAT clients fall back to CDN

[Section titled "Symmetric-NAT clients fall back to CDN"](#symmetric-nat-clients-fall-back-to-cdn)

STUN-only, clients behind symmetric NAT often can't form a direct WebRTC data channel and will fall back to the CDN for delivery. This is expected and safe -- those viewers still play, they just don't mesh.

**Fix:** if a meaningful share of your audience is behind symmetric NAT and you want them participating, bring your own TURN: set `allowByoTurn: true` and add your TURN servers to `iceServers`. See [Compatibility -> NAT and ICE](/compatibility/#nat-and-ice).

## 401 on sign

[Section titled "401 on sign"](#401-on-sign)

A `401` from the signing path means the request had **no valid token**. Signing requires an authenticated caller because the token's `customerId` selects the allowlist -- an anonymous sign has no tenant to be scoped to.

**Fix:** ensure a valid `authToken` is set on the loader and that it hasn't expired. See [token lifetime and rotation](#token-expiry-and-rotation).

## Token expiry and rotation

[Section titled "Token expiry and rotation"](#token-expiry-and-rotation)

SDK tokens are long-lived (valid for **90 days**) because you embed one in a build. When a token expires, authenticated calls start failing.

**Fix:** issue a fresh token from the portal and ship it in your next build. An already-issued token runs until it expires -- rotating doesn't revoke the old one early, so plan a rollout window. See [Authentication -> Token lifetime and rotation](/concepts/auth/#token-lifetime-and-rotation).

## Frequently asked questions

[Section titled "Frequently asked questions"](#frequently-asked-questions)

**Will viewers notice anything?** No. MeshedFlow runs behind the player. If sharing is unavailable or unsafe, the CDN path is used immediately.

**How much can we save?** It depends on concurrency, geography, bitrate, and event shape. A [pilot](/analytics/#the-pilot-report) measures real offloaded bytes and playback quality on your own traffic rather than a generic benchmark.

**What happens if a peer is malicious?** Only verified media is accepted. Anything that doesn't match the origin-signed manifest is rejected and the request falls back to your CDN. See [Content signing](/concepts/signing/).

**Does this replace rights management or packaging?** No. MeshedFlow is a delivery layer, not a rights-management layer. It works alongside your existing content protection and never sees decrypted content -- your packaging and entitlement workflows stay on your normal path, unchanged.

**Can we limit the rollout?** Yes. You can constrain a pilot by stream, geography, device class, traffic percentage, or event window, with a rollback path back to normal CDN delivery.

**What do we get at the end of a pilot?** A measured report showing eligible traffic, offload percentage, playback quality, fallback volume, and the commercial case for expanding or stopping. See [Analytics & pilot reports](/analytics/).

## Related

[Section titled "Related"](#related)

* [SDK reference](/reference/sdk/) | [HTTP API reference](/reference/api/)
* [Content signing & origins](/concepts/signing/) | [Compatibility](/compatibility/)