Web SDK quick integration

MeshStream Web SDK adds P2P acceleration to HLS and DASH playback without replacing the existing player. MP4 and MP3 acceleration is enabled only when Service Worker is available. The player keeps manifest parsing, ABR, decoding, and rendering; the SDK owns playback sessions and acceleration handling.

This page covers the smallest production-ready integration. For Service Worker transport, existing-player adapters, dynamic authorization, diagnostics, and staged rollout, see Advanced usage.

Before running the code, complete Installation and setup, prepare your SDK Key and playable media URL, and configure the application network policy.

Minimal integration

attach is the standard entry point. It recognizes HLS, DASH, MP4, and MP3 from the media URL and creates the required session and transport path:

import { attach } from "@meshstream/p2p-web";

const session = attach({
  key: "your_sdk_key",
  url: "https://cdn.example.com/video/master.m3u8",
  video: document.querySelector("video")!,
});

const result = await session.start();
console.log(result.mode);

window.addEventListener("pagehide", () => session.dispose(), { once: true });

start() returns the active transport mode. When acceleration is temporarily unavailable, the session continues through the existing media delivery path; do not treat acceleration state as a playback failure or replace the player URL solely for that reason.

Basic configuration

Field	Required	Description
`key`	Yes	SDK Key issued in the console.
`url`	Yes	Original media URL. HLS/DASH use the standard path; MP4/MP3 acceleration requires Service Worker.
`video`	Yes	Target `<video>` or `<audio>` element.
`contentId`	No	Stable content identity. Recommended for signed or rotating URLs.
`mimeType`	No	Media hint: `m3u8`, `mpd`, `mp4`, or `mp3`. Usually inferred automatically.
`autoplay`	No	Attempts playback after initialization; browser autoplay policy still applies.
`p2pEnabled`	No	Set `false` to disable acceleration for this session.

Set mimeType for an extensionless authenticated URL. Set a stable contentId for a URL whose signature changes. See dynamic URLs and origin authorization for the full configuration.

Live and VOD

Do not pass a live/VOD flag. The SDK detects HLS live from #EXT-X-ENDLIST, DASH live from an MPD with type="dynamic", and treats MP4/MP3 as VOD. When the URL suffix is inconclusive, the SDK probes the origin Content-Type; set mimeType explicitly for an authenticated extensionless URL.

Use a stable channel identity for live streams and a stable asset identity for VOD:

const session = attach({
  key: "your_sdk_key",
  url: liveUrl,
  contentId: "live-channel-123",
  video: document.querySelector("video")!,
});

The result is used for both scheduling and usage reporting. Live buffering and low-latency parameters apply only to hls.js; see HLS and low-latency configuration. DASH is configured by Shaka, dash.js, or the application player, while MP4/MP3 use Service Worker range transport and are always VOD.

Lifecycle and playback continuity

Each playback has an independent session. Call dispose() when playback ends, content changes, or the page is unloaded. Create a new session for new content.

Situation	SDK behavior
Browser does not support acceleration	Keeps the player URL managed by the current session; normal playback continues.
Acceleration is temporarily unavailable	Normal playback continues automatically.
Key, application, or quota unavailable	A new session preserves normal playback and provides a diagnostic reason.
`setP2pEnabled(false)` called	Disables acceleration for this session without interrupting playback.

You can record fallbackReason for diagnostics, but never stop the player because it is set:

const result = await session.start();
if (result.fallbackReason) {
  console.info("MeshStream acceleration unavailable", result.fallbackReason);
}

Next steps

Web SDK Advanced Usage: Service Worker, dynamic URLs, authorization, player adapters, and observability.
Best practices: production checks and playback boundaries.
Troubleshooting: configuration, network, and peer diagnostics.

Workload and measurement guides

P2P CDN for live streaming: evaluate concurrency, reachability, latency, and CDN fallback before expanding a rollout.
Video CDN cost and offload guide: distinguish delivered bytes from net cost and compare representative workloads.

Related guides: Installation and setup · Advanced usage.

Minimal integration​

Basic configuration​

Live and VOD​

Lifecycle and playback continuity​

Next steps​

Workload and measurement guides​