Skip to main content

Documentation Index

Fetch the complete documentation index at: https://gcore.com/docs/llms.txt

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

​
Overview

Common Media Client Data (CMCD) is a standard way for video players to send playback context with each media request. The player attaches values such as buffer length, measured throughput, requested maximum throughput, selected bitrate, object type, session ID, and content ID to segment and manifest requests.
CMCD must be enabled in the video player used by your application. Gcore can process CMCD data only when the player sends it with media requests.
CMCD helps connect CDN delivery logs with the real playback state of a viewer. This makes it much easier to investigate delivery and playback issues such as buffering, slow startup, bitrate drops, excessive rebuffering, or a specific player choosing a rendition that is too high for the current network. CMCD adds client-side playback events to the server-side delivery data already available in CDN logs. This helps CDN operators see what was happening in the player when each request was made and understand whether an issue is related to delivery, network conditions, player behavior, device limitations, or the viewer’s local environment.

​
CMCD support in Gcore CDN

Gcore supports processing CMCD values sent in the query string. CMCD processing 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. If you want to analyze a playback issue with CMCD data, contact Gcore Support and share the affected stream URL, approximate playback time, viewer geography, player name and version, and any session or content ID values configured in your player.
CMCD self-service monitoring in the Customer Portal is planned for a future release. Until then, Gcore Support can help investigate CMCD data with internal tools.

​
How CMCD looks

When CMCD is sent in the query string, the player adds a CMCD parameter to media requests. For example: 
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
CodeParameterValue
blBuffer Length26000 ms
brEncoded Bitrate4596 kbps
bsBuffer Starvation-
cidContent IDmpegts/2675_19146/master_mpegts.m3u8
dObject Duration6000 ms
dlDeadline-
mtpMeasured Throughput163400 kbps
norNext Object Request-
nrrNext Range Request-
otObject Typeav
prPlayback Rate1.1
rtpRequested Max Throughput-
sfStreaming Formath
sidSession ID9d40d87a-7539-46e0-ac2c-d1040ff04bef
stStream Type-
suStartup-
tbTop Bitrate4596 kbps

​
Player support

Most modern video players include a CMCD implementation. 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.
In the table, Query and Header show which transport methods each player supports. Supported means this is the player’s default transport mode for CMCD.
PlayerQueryHeaderCMCD versionDescription
AVPlayerNoSupportedv1 limitediOS 18+. See Apple documentation.
dash.jsSupportedSupportedv1See dash.js CMCD documentation.
ExoPlayerSupportedSupportedv1See ExoPlayer CMCD documentation.
hls.jsSupportedSupportedv1See hls.js CMCD documentation.
JW PlayerSupportedSupportedv1See JW Player CMCD documentation.
RokuNoSupportedv1See Roku CMCD data points.
Shaka PlayerSupportedSupportedv1See Google Media CDN: Enhancing streaming observability with CMCD metrics.

​
Query string parameters

This method is usually preferred because it is easier to enable, inspect in browser developer tools, and process in CDN logs.
In query string mode, all CMCD key/value pairs are encoded into one CMCD query parameter: 
https://cdn.example.com/video/segment.ts?CMCD=bl%3D26000%2Cbr%3D4596%2Cd%3D6000%2Cmtp%3D163400%2Cot%3Dav%2Csf%3Dh
Decoded, the value looks like this: 
CMCD=bl=26000,br=4596,d=6000,mtp=163400,ot=av,sf=h

​
HTTP request headers

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"

​
How to enable CMCD in players

The following examples show how to enable CMCD in different video players. The examples use the following default CMCD values:
  • Session ID: A unique identifier for the viewer’s playback session.
  • Content ID: A unique identifier for the content being played.
Enable CMCD in the HLS.js configuration:
const hls = new Hls({
  cmcd: {
    sessionId: 'session-' + Date.now(),
    contentId: 'content-id',
    useHeaders: false
  }
});
Documentation
Enable CMCD in the Shaka Player configuration:
const player = new shaka.Player(videoElement);

player.configure({
  cmcd: {
    enabled: true,
    sessionId: 'session-' + Date.now(),
    contentId: 'content-id',
    version: 1,
    useHeaders: false
  }
});
Documentation
Enable CMCD in the dash.js configuration:
const player = dashjs.MediaPlayer().create();

player.updateSettings({
  streaming: {
    cmcd: {
      enabled: true,
      sid: 'session-' + Date.now(),
      cid: 'content-id',
      mode: 'query',
      version: 1
    }
  }
});
player.initialize(videoElement, manifestUrl, true);
Documentation
Enable CMCD in the ExoPlayer configuration:
val cmcdConfigurationFactory = CmcdConfiguration.Factory { mediaItem ->
    val cmcdRequestConfig = object : CmcdConfiguration.RequestConfig {}
    val sessionId = UUID.randomUUID().toString()
    val contentId = UUID.randomUUID().toString()

    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.fromUri(manifestUrl)
player.setMediaItem(mediaItem)
player.prepare()
Documentation
Enable CMCD headers in the AVPlayer configuration:
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)
Documentation
CMCD is Supported in Gcore Video Player.Documentation