Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CeeblueTV/wrts-client/llms.txt

Use this file to discover all available pages before exploring further.

Common Media Client Data (CMCD) is a CTA-Wave standard for attaching real-time client-side telemetry to media requests. When enabled, the WebRTS client appends playback quality information — buffer state, current bitrate, latency, track ID, and session ID — to each media fetch request. Your CDN or origin server can read these values to make smarter decisions about caching, throttling, and quality-of-service monitoring. CMCD is disabled by default and must be explicitly enabled after onStart fires.

​
CMCD Levels

The CMCD enum controls how much data is sent per request:
ValueStringDescription
CMCD.NONE'none'CMCD disabled (default)
CMCD.SHORT'short'Sends only the most important keys, minimizing header overhead
CMCD.FULL'full'Sends all available CMCD keys

​
Delivery Modes

The CMCDMode enum controls how CMCD data is delivered to the server:
ValueStringDescription
CMCDMode.HEADER'header'Appended as HTTP request headers (default)
CMCDMode.QUERY'query'Appended as a cmcd query string parameter

​
Enabling CMCD

CMCD properties must be set after onStart fires. The underlying source — which owns the CMCD state — is not created until onsourceopen resolves internally, which happens asynchronously after player.start() returns. Setting these properties before onStart fires throws: Cannot change cmcd on stopped player.
import { Player, CMCD, CMCDMode } from '@ceeblue/wrts-client';

const player = new Player(videoElement);

player.onStart = () => {
  // Enable CMCD after the source is initialized
  player.cmcd    = CMCD.FULL;           // send all keys
  player.cmcdMode = CMCDMode.HEADER;    // deliver via HTTP headers
  player.cmcdSid  = 'my-session-id';    // optional: tag this viewing session
};

player.start({
  endPoint: 'https://<hostname>/wrts/out+<stream-id>/index.json'
});
In production, prefer CMCD.SHORT over CMCD.FULL to keep per-request overhead small. SHORT omits lower-priority keys — content ID (cid), download deadline (dl), object type (ot), and stream type (st) — while keeping the critical buffer and bitrate fields intact.

​
Resetting to Defaults

Setting any CMCD property to undefined resets it to its default value. This makes it safe to pass URL query parameters directly without checking whether they exist: 
// Translate URL params to CMCD config safely
const options = Object.fromEntries(new URLSearchParams(location.search));

player.onStart = () => {
  // Each property falls back to its default if the param is absent
  player.cmcd    = options.cmcd;     // defaults to CMCD.NONE  ('none')
  player.cmcdMode = options.cmcdMode; // defaults to CMCDMode.HEADER ('header')
  player.cmcdSid  = options.cmcdSid;  // defaults to '' (empty string)
};

​
What Data Is Reported

On each media fetch, the following information is included in the CMCD payload:
  • Buffer state and depth — current bufferAmount and bufferState
  • Bitrate — current audio and video byte rates
  • Latency — estimated distance to the live edge
  • Track ID — the ID of the track being requested
  • Session ID — the value of cmcdSid (if set)
This data is computed via player.computeStats() at the time of each request and encoded into the HTTP headers or query string using the CTA-5004 CMCD format.

​
CMCD and Source Compatibility

CMCD is only available when using HTTPAdaptiveSource (the default source). Other source implementations — such as WSSource — do not support CMCD. Attempting to enable CMCD on an incompatible source throws: <SourceName> doesn't support CMCD. 
player.onStart = () => {
  // Safe to set on HTTPAdaptiveSource (the default)
  player.cmcd = CMCD.SHORT;
};

// If you are using a WebSocket-based source, skip CMCD
// const player = new Player(videoElement, WSSource);

Build docs developers (and LLMs) love

Get started for freeTalk to us