Common Media Client Data (CMCD)

Common Media Client Data (CMCD) is a standard way for video players to send playback context with each media request. The player attaches buffer length, measured throughput, requested maximum throughput, selected bitrate, object type, session ID, and content ID to segment and manifest requests, so CDN delivery logs can be read next to the viewer’s playback state.

Enable CMCD in the video player used by the application. Gcore currently processes CTA-5004 (CMCD v1). Gcore can process CMCD data only when the player sends it with media requests.

CMCD support in Gcore CDN

Gcore currently processes CMCD v1. Later CTA revisions added keys and reporting modes, and they removed the v1 nrr key. Configure players that support later CMCD versions to send CMCD v1 for Gcore. Gcore processes CMCD values sent in the query string. Processing CMCD from request headers is available by special request. Gcore collects CMCD data at the CDN layer and can process it with internal tools to improve delivery and investigate playback behavior. To analyze a playback issue with CMCD data, contact Support and share the affected stream URL, approximate playback time, viewer geography, player name and version, and the session ID from the player.

CMCD data is not currently available through self-service Customer Portal reports. Gcore Support can help investigate CMCD data with internal tools.

Send CMCD over HTTPS. Do not put personally identifiable information in sid, cid, or custom CMCD values. Query parameters can appear in CDN logs and diagnostic records.

Query string CMCD

When CMCD is sent in the query string, the player adds one case-sensitive CMCD parameter to media requests. All key/value pairs are URL-encoded into that parameter.

https://demo-public.gvideo.io/mpegts/2675_19146/ed-sl-gc4/seg6000-qsid813-media0-200315959-101681.ts?CMCD=bl%3D26000%2Cbr%3D4596%2Ccid%3D%22mpegts%2F2675_19146%2Fmaster_mpegts.m3u8%22%2Cd%3D6000%2Cmtp%3D163400%2Cot%3Dav%2Cpr%3D1.1%2Csf%3Dh%2Csid%3D%229d40d87a-7539-46e0-ac2c-d1040ff04bef%22%2Ctb%3D4596

Decoded CMCD data from this request:

CMCD=bl=26000,br=4596,cid="mpegts/2675_19146/master_mpegts.m3u8",d=6000,mtp=163400,ot=av,pr=1.1,sf=h,sid="9d40d87a-7539-46e0-ac2c-d1040ff04bef",tb=4596

The keys in the table are CMCD v1 keys. nrr is a v1 key. Later CTA revisions moved range information into nor and removed nrr.

Code	Parameter	Value
`bl`	Buffer Length	26000 ms
`br`	Encoded Bitrate	4596 kbps
`bs`	Buffer Starvation	-
`cid`	Content ID	`mpegts/2675_19146/master_mpegts.m3u8`
`d`	Object Duration	6000 ms
`dl`	Deadline	-
`mtp`	Measured Throughput	163400 kbps
`nor`	Next Object Request	-
`nrr`	Next Range Request	-
`ot`	Object Type	`av`
`pr`	Playback Rate	1.1
`rtp`	Requested Max Throughput	-
`sf`	Streaming Format	`h`
`sid`	Session ID	`9d40d87a-7539-46e0-ac2c-d1040ff04bef`
`st`	Stream Type	-
`su`	Startup	-
`tb`	Top Bitrate	4596 kbps

Hyphens in the Value column mean that key was not present in this example request. CMCD values change between requests (buffer length, throughput, bitrate). If the CDN includes the CMCD query parameter in the cache key, each request can create a separate cached copy of the same segment and the cache hit ratio drops. After enabling query-string CMCD, open Ignore query string and confirm one of these modes:

Ignore all — every query parameter, including CMCD, is omitted from the cache key.
Ignore only — the parameter list includes CMCD, so CMCD is omitted from the cache key while other query parameters stay in the cache key.

HTTP request headers

Header mode is available in several players, but Gcore processes CMCD- headers only after the special request described in CMCD support. In header mode, CMCD data is sent in HTTP request headers. The specification defines four case-insensitive header fields with the CMCD- prefix.

CMCD-Request: bl=26000,mtp=163400
CMCD-Object: br=4596,d=6000,ot=av,tb=4596
CMCD-Status: bs
CMCD-Session: cid="content-id",pr=1.1,sf=h,sid="session-id"

Browsers treat those names as custom headers. The CDN CORS configuration must allow CMCD-Request, CMCD-Object, CMCD-Status, and CMCD-Session. Custom headers can trigger a CORS preflight (OPTIONS) for media URLs, which increases the request rate against the CDN. Query-string mode avoids that preflight.

Supported video players for CMCD

The CMCD specification allows players to send information in two ways:

Query string parameters: CMCD data is added to media request URLs as a CMCD query parameter.
HTTP request headers: CMCD data is sent in dedicated HTTP request headers.

Gcore processes query-string CMCD v1. Header processing still requires the special request above. Player CMCD version is what the player can send. Gcore-compatible version is the version Gcore processes.

Player	Query	Header	Player CMCD version	Gcore-compatible version	Documentation
AVPlayer	No	Supported	v1	v1	iOS 18+. Does not send `cid`, `rtp`, or `tb`. AVPlayer CMCD documentation. CMCD keys on AVPlayer.
dash.js	Supported	Supported	v1 and v2	v1	dash.js CMCD documentation.
ExoPlayer	Supported	Supported	v1	v1	ExoPlayer CMCD documentation.
hls.js	Supported	Supported	v1	v1	hls.js CMCD documentation.
JW Player	Supported	Supported	v1	v1	JW Player CMCD documentation.
Roku	No	Supported	v1	v1	Roku CMCD data points.
Shaka Player	Supported	Supported	v1	v1	Shaka Player CMCD configuration.
Gcore Video Player	Supported	No	v1	v1	Gcore Video Player CmcdConfig documentation.

CMCD configuration in video players

The examples below cover selected players from the table. JW Player and Roku are listed as supported; use each vendor’s CMCD documentation for those products. Set identifiers as defined in CTA-5004 (CMCD v1):

Session ID (sid): a UUID generated for each playback session on a single device.
Content ID (cid): a stable identifier for the same content across sessions and devices, derived from an asset ID or manifest URI. Do not generate a new random value per session.

HLS.js

Enable CMCD in the HLS.js configuration. The HLS.js API documents the cmcd option.

const hls = new Hls({
  cmcd: {
    sessionId: crypto.randomUUID(),
    contentId: 'asset-123',
    useHeaders: false
  }
});

Shaka Player

Enable CMCD in the Shaka Player configuration. The Shaka API documents the cmcd object.

const player = new shaka.Player(videoElement);

player.configure({
  cmcd: {
    enabled: true,
    sessionId: crypto.randomUUID(),
    contentId: 'asset-123',
    version: 1,
    useHeaders: false
  }
});

dash.js

Enable CMCD in the dash.js configuration. dash.js can send later CMCD versions; set version to 1 to send CMCD v1 for Gcore. The dash.js CMCD documentation documents the streaming.cmcd settings.

const player = dashjs.MediaPlayer().create();

player.updateSettings({
  streaming: {
    cmcd: {
      enabled: true,
      sid: crypto.randomUUID(),
      cid: 'asset-123',
      mode: 'query',
      version: 1
    }
  }
});
player.initialize(videoElement, manifestUrl, true);

ExoPlayer (Android)

Enable CMCD in the ExoPlayer configuration. The ExoPlayer CMCD guide documents CmcdConfiguration. Generate a UUID for the session. Derive contentId from a stable asset identifier (mediaId or the media URI), not from a second random UUID.

val cmcdConfigurationFactory = CmcdConfiguration.Factory { mediaItem ->
    val cmcdRequestConfig = object : CmcdConfiguration.RequestConfig {}
    val sessionId = UUID.randomUUID().toString()
    val contentId = mediaItem.mediaId

    CmcdConfiguration(
        sessionId,
        contentId,
        cmcdRequestConfig,
        CmcdConfiguration.MODE_QUERY_PARAMETER
    )
}

val mediaSourceFactory = DefaultMediaSourceFactory(context)
    .setCmcdConfigurationFactory(cmcdConfigurationFactory)

val player = ExoPlayer.Builder(context)
    .setMediaSourceFactory(mediaSourceFactory)
    .build()

val mediaItem = MediaItem.Builder()
    .setUri(manifestUrl)
    .setMediaId("asset-123")
    .build()
player.setMediaItem(mediaItem)
player.prepare()

AVPlayer (iOS)

Enable CMCD headers in the AVPlayer configuration. Apple documents sendsCommonMediaClientDataAsHTTPHeaders.

let asset = AVURLAsset(url: videoURL)

if #available(iOS 18.0, tvOS 18.0, *) {
    asset.resourceLoader.sendsCommonMediaClientDataAsHTTPHeaders = true
}

let playerItem = AVPlayerItem(asset: asset)
let player = AVPlayer(playerItem: playerItem)

Gcore Video Player

Enable CMCD with the CmcdConfig plugin. Register the plugin before creating the player, then pass a per-session UUID and a stable content ID in the cmcd object.

import { Player, CmcdConfig } from '@gcorevideo/player';

Player.registerPlugin(CmcdConfig);

const player = new Player({
  source: manifestUrl,
  cmcd: {
    sessionId: crypto.randomUUID(),
    contentId: 'asset-123'
  }
});

Playback verification

After the player is configured, confirm that media requests carry CMCD before contacting Support.

Stream playback

Play the stream in the player used by the application.

Request inspection

Open browser developer tools or the device network inspector. Select a manifest or segment request to the CDN.

CMCD confirmation

For query-string mode, confirm the case-sensitive CMCD query parameter is present. For header mode, confirm CMCD-Request, CMCD-Object, CMCD-Status, and CMCD-Session as sent by the player.

Session ID

Copy the session ID (sid) from the request. Keep that value when contacting Support.

Account settings

Developer Tools

CDN

FastEdge

Edge Cloud

AI

Gclaw

Managed DNS

Public DNS

Hosting

Colocation

Object Storage

Video Streaming

DDoS protection

Edge Proxy

WAAP

CMCD support in Gcore CDN

Query string CMCD

HTTP request headers

Supported video players for CMCD

CMCD configuration in video players

Playback verification

​CMCD support in Gcore CDN

​Query string CMCD

​HTTP request headers

​Supported video players for CMCD

​CMCD configuration in video players

​Playback verification

CMCD support in Gcore CDN

Query string CMCD

HTTP request headers

Supported video players for CMCD

CMCD configuration in video players

Playback verification