Feature: CMCD v2 by cotid-qualabs · Pull Request #4816 · Dash-Industry-Forum/dash.js

cotid-qualabs · 2025-08-01T19:52:43Z

CMCD v2 Support - Comprehensive Implementation

This Pull Request introduces comprehensive support for CMCD (Common Media Client Data) Version 2, significantly expanding the player's capabilities for media analytics and client-side data reporting. The implementation leverages the @svta/cml-cmcd library's CmcdReporter to centralize reporting mechanisms, reducing complexity and improving maintainability while aligning with the latest CMCD specifications.

Key Features & Enhancements:

1. CMCD Reporter Integration

Strategic Architecture Shift: Migrated from manual CMCD reporting to using CmcdReporter from @svta/cml-cmcd library
Centralized Reporting Logic: All CMCD data transmission, event handling, and sequence number tracking now managed by the external reporter
Simplified Controller: CmcdController focuses on orchestration and configuration, delegating report transmission to CmcdReporter
Streamlined Model: CmcdModel specializes in calculating CMCD data for requests, with cleaner separation of concerns

2. CMCD v2 Specification Adherence

Supported CMCD v2 keys: ltc, rc, bg, sta, ttfb, ttlb, ts, url, ec, msd, e, cmsdd, cmsds, df, sn, pb, tpb, bsd, ab, tab, lab
Ensures correct mapping to HTTP headers or query parameters for request mode and body transmission mode for event mode
Backward compatibility mechanism for CMCD v1 through Common Media Library integration

3. New CMCD Reporting Modes

Event Mode (event): CMCD data reporting triggered by specific player events or configurable time intervals
- Supported CMCD Events: ps, e, t, rr
- Play State Events: s, p, k, r, a, w, e, f
- Response Received: Reports after media segment/manifest response with metrics like ttfb, ttlb, and rc

4. Multiple Reporting Targets & Granular Configuration

New streaming.cmcd.targets array for configuring multiple CMCD reporting endpoints
Per-target configuration:
- url: Destination URL for CMCD reports
- mode: Transmission mode (query or header)
- enabledKeys: Specific CMCD keys to include (defaults to only mandatory if not defined)
- events: Player events that trigger reports (defaults to none if not defined)
- timeInterval: Interval in seconds for periodic reports (0 disables)
- includeInRequests: HTTP request types to include CMCD data for

5. Enhanced Architecture & Separation of Concerns

CmcdController: Orchestrates CMCD v2 data collection, manages CmcdReporter instances, and coordinates with interceptors
CmcdModel: Calculates CMCD data for various request types with renamed methods (calculateCmcdDataForRequest) for clarity
Removed Redundant Code: Eliminated manual event handling, sequence tracking, and custom HTTP request logic (now handled by CmcdReporter)

6. Request/Response Interceptors

_cmcdRequestModeInterceptor: Injects CMCD data into outgoing requests (for query and header modes)
_cmcdResponseReceivedInterceptor: Processes incoming responses to gather data and trigger reports

7. Batching Mechanism via CmcdReporter

Batching by Size (batchSize): Sends batch immediately when count reaches configured size

8. Settings Abstraction Layer

CmcdPropertyMap: Declarative configuration mapping logical property names to physical paths
- Version-aware properties (different paths for v1 vs v2)
- Priority-based fallback: manifest → settings → default
- Context-aware paths with variables
CmcdConfigAccessor: Unified API for CMCD configuration access
- Core methods: get(), has(), getVersion(), isEnabled(), getTargets(), getTarget()
- Automatic version detection with caching
- Smart path resolution supporting dot-notation and array notation
Benefits:
- Single source of truth for property mappings
- Version-agnostic business logic
- Future-proof for CMCD v3+ (only PropertyMap updates needed)

9. Common Media Library Integration

Updated @svta/common-media-library dependency
Leverages enhanced encodeCmcd function for key filtering, whitelisting, and custom key management
Integrated CmcdReporter for standardized reporting across SVTA ecosystem

10. New Sample Pages

CMCD v2 Reporting: Showcases v2 setup and target configurations for each mode
CMCD v2 Callbacks with Network Interceptors: Demonstrates custom keys via callbacks and post-response data processing

11. Unit Testing

Expanded test suite covering CMCD v2 scenarios, configurations, and CmcdReporter integration

Main Files Affected:

src/streaming/controllers/CmcdController.js: Refactored to instantiate and manage CmcdReporter, removed manual event/reporting logic, uses CmcdConfigAccessor
src/streaming/models/CmcdModel.js: Simplified to focus on CMCD data calculation with renamed methods, uses CmcdConfigAccessor
src/core/Settings.js: Updated with new CMCD v2 configuration options (streaming.cmcd.targets, version selection)
src/streaming/cmcd/config/CmcdPropertyMap.js: Declarative configuration for version-aware property mappings
src/streaming/cmcd/config/CmcdConfigAccessor.js: Abstraction layer providing unified configuration API
package.json: Updated dependencies for @svta/cml-cmcd library integration

Future Work

Implement Remaining CMCD v2 Keys: Review specification and implement any unsupported keys based on use cases and community feedback

cotid-qualabs · 2025-08-11T13:57:13Z

Hi @gorkemg , I just renamed the timeOuts variable to timeouts as requested. Also added a PR from a contributor on our fork, adding aggregated bitrate keys (ab, lab, tab).

dsilhavy · 2025-08-19T15:20:55Z

Related issue #4507

Jason239 · 2025-08-25T07:56:39Z

@cotid-qualabs
I'm not sure if it's appropriate to write this here, but in the _doLicenseRequest function of ProtectionController.js, the getCmcdParametersFromManifest() function is called through the cmcdController instance, but this function has not yet been moved to CmcdController and still exists in CmcdModel, causing an error when playing DRM content.

cotid-qualabs · 2025-08-27T21:41:32Z

Thank you @Jason239 , I will take a look at this as soon as I can. Good catch!

cotid-qualabs · 2025-09-04T19:05:02Z

I have fixed the getCmcdParametersFromManifest function call and included unit test coverage for cmcd implementation on ProtectionController.js

This reverts commit bf31094.

…validity-expiration Revert "Feature MPD update on validity expiration"

cotid-qualabs · 2025-10-22T17:46:22Z

Hi @dsilhavy ! All requested changes have been implemented, including removing Response Mode and adding Response Received. However, this implementation depends on Common Media Library "response received" PR (streaming-video-technology-alliance/common-media-library#268) being merged and version 0.18.2 being released. Then I need to update CML version on dash.js

dsilhavy · 2026-01-13T13:55:33Z

@cotid-qualabs I would like to review this PR for v5.2.0. Can I please ask you to rebase your changes against the latest development branch

cotid-qualabs · 2026-02-02T15:13:49Z

Hi @dsilhavy ! Just wanted to let you know that new implementation for CMCDv2 using CML CmcdReporter is almost ready on this Draft PR qualabs#159 . We just need to wait for CML release.

* cmcd reporter initialization * request mode migration * event mode migration * cmcd model migration * fix cmcd model unit tests * fixes for cmcd parameters and cleanup - protection controller fixes WIP * cleanup and update unit tests * refactor unit tests and fixes * fix unit tests and remove batchTimer

* ab, lab and tab inner list and request mode * ab, tab and lab inner list for v2 * bl inner list and event mode * br inner list and event mode * toInnerList helper * bsd inner list * mtp inner list and event mode * nor inner list * pb inner list and event mode * tp inner list and event mode * tpb inner list and event mode * fix unit tests

* chore: update CML dependencies * fix: update common media request * fix: update resourceTiming properties to use performance.now() * fix: update cmcd data formatting * fix: remove redundant rr values * refactor: simplify cmcd reporting * fix: test mock requests missing parameters * chore: update cml cmcd version * should not send report if events are undefined * fix unit tests --------- Co-authored-by: cotid-qualabs <constanzad@qualabs.com>

dsilhavy · 2026-02-17T16:48:38Z

Related discussion: video-dev/hls.js#7725

* feat: add CMCD v2 Playwright E2E tests with spec validation Adds comprehensive E2E tests using Playwright to validate CMCD v2 payloads at the network level during real playback. Uses @svta/cml-cmcd validation functions (validateCmcd, validateCmcdHeaders, validateCmcdEvent, validateCmcdKeys) for spec-level compliance checks across query, header, and event modes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: replace Playwright E2E tests with Karma functional tests for CMCD v2 Replace the Playwright-based E2E test suite with Karma functional tests that use XHR interceptors to validate CMCD v2 spec compliance. This eliminates the @playwright/test dependency (~100MB) while maintaining full test coverage across all three transmission modes (query, header, event), key filtering, and version validation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: remove double parsing from CMCD v2 tests CmcdRequestCollector now stores raw CMCD strings instead of pre-parsed objects, removing its dependency on @svta/cml-cmcd entirely. Tests use validation function return values (result.data) for both spec validation and data assertions in a single pass. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: update cml packages * fix: add logging to xhr collector * refactor: use unified collector and validateCmcdRequest for CMCD v2 tests Rewrite CmcdRequestCollector with a single requests array storing httpRequest objects compatible with CML's validateCmcdRequest(). Replace mode-specific validators (validateCmcd, validateCmcdHeaders) with the unified validateCmcdRequest() and remove the invalid validateCmcdKeys test that was passing a string to a function expecting a parsed object. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

dsilhavy · 2026-04-27T09:30:42Z

@cotid-qualabs I finally found the time to look into the PR again. Would it be possible to grant me write access to the upstream repo? I will probably want to apply some minor changes to the PR and I think it would be easier if I can add changes to the PR myself rather than putting everything in review comments

cotid-qualabs · 2026-04-27T13:27:00Z

Hi @dsilhavy ! Check if you have access now

dsilhavy · 2026-04-27T13:32:22Z

Hi @dsilhavy ! Check if you have access now

Thanks @cotid-qualabs , works :)

Rename targets->eventTargets, timeInterval->interval, includeOnRequests-> includeInRequests across settings, samples, and tests. Switch event validation to validateCmcdEvents (batch). HTTPLoader now accepts empty POST bodies so CMCD event endpoints don't trigger retries. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cotid-qualabs marked this pull request as ready for review August 1, 2025 19:52

dsilhavy requested review from dsilhavy, gorkemg and minhkstn August 2, 2025 12:37

gorkemg reviewed Aug 10, 2025

View reviewed changes

Comment thread src/streaming/controllers/CmcdController.js Outdated

dsilhavy added this to dash.js Version 5.1.0 Aug 18, 2025

dsilhavy added this to the 5.1.0 milestone Aug 18, 2025

dsilhavy removed the request for review from minhkstn August 19, 2025 09:34

dsilhavy added the Pri-High label Aug 28, 2025

dsilhavy requested changes Sep 15, 2025

View reviewed changes

dsilhavy added the Awaiting Feedback label Sep 16, 2025

dsilhavy removed this from dash.js Version 5.1.0 Oct 1, 2025

dsilhavy added this to dash.js Version 5.2.0 Oct 1, 2025

dsilhavy modified the milestones: 5.1.0, 5.2.0 Oct 1, 2025

cotid-qualabs and others added 5 commits October 9, 2025 11:34

Feature MPD update on validity expiration (#68)

bf31094

Revert "Feature MPD update on validity expiration (#68)"

e4fdc71

This reverts commit bf31094.

Merge pull request #146 from qualabs/revert-68-feature/mpd-update-on-…

db74be1

…validity-expiration Revert "Feature MPD update on validity expiration"

Merge branch 'Dash-Industry-Forum:development' into development

8e42370

Merge branch 'Dash-Industry-Forum:development' into development

8a496ea

cotid-qualabs and others added 3 commits December 11, 2025 15:46

Merge branch 'Dash-Industry-Forum:development' into development

8f2ef0f

Merge branch 'Dash-Industry-Forum:development' into development

14a2337

Merge branch 'Dash-Industry-Forum:development' into development

7166e2a

cotid-qualabs and others added 4 commits February 2, 2026 15:07

feat: update CML dependencies

c0ee7ec

fix race condition on cmcd contrller for cmcd parameters

62f99af

dsilhavy moved this to Selected for Development in dash.js Version 5.2.0 Feb 10, 2026

littlespex and others added 2 commits March 4, 2026 14:29

Merge branch 'development' into feature/cmcdv2

e91f2a1

dsilhavy moved this from Selected for Development to In Progress in dash.js Version 5.2.0 Mar 10, 2026

littlespex added 2 commits April 13, 2026 21:07

Merge branch 'development' into feature/cmcdv2

ef0f384

chore: update CMCD version

5d72690

dsilhavy added 3 commits April 27, 2026 13:08

Merge branch 'development' into feature/cmcdv2

889a0a8

Dedicated sample section for CMCD

0a80def

Use headers transmission mode string from CML

6e10b59

dsilhavy mentioned this pull request Apr 27, 2026

CMCD Implementation - Findings from dash.js implementation streaming-video-technology-alliance/common-media-library#357

Open

littlespex and others added 10 commits April 29, 2026 16:15

chore: update cml versions

0a37f91

Catch errors in recordResponseReceived

ed87b36

Fix wrong URLs in CMCD demos

1878bca

Small refactoring in DashManifestModel.js

46178e2

Minor refactoring

cfb9d75

Cleanup all events in CmcdController.js when resetting

3ffe160

Refactor CustomParametersModel.js

c4892e4

Add CMCD version to reference UI

75c968a

Small refactoring in CmcdModel.js

ad7c194

Uh oh!

Conversation

cotid-qualabs commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CMCD v2 Support - Comprehensive Implementation

Key Features & Enhancements:

1. CMCD Reporter Integration

2. CMCD v2 Specification Adherence

3. New CMCD Reporting Modes

4. Multiple Reporting Targets & Granular Configuration

5. Enhanced Architecture & Separation of Concerns

6. Request/Response Interceptors

7. Batching Mechanism via CmcdReporter

8. Settings Abstraction Layer

9. Common Media Library Integration

10. New Sample Pages

11. Unit Testing

Main Files Affected:

Future Work

Uh oh!

Uh oh!

cotid-qualabs commented Aug 11, 2025

Uh oh!

dsilhavy commented Aug 19, 2025

Uh oh!

Jason239 commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cotid-qualabs commented Aug 27, 2025

Uh oh!

cotid-qualabs commented Sep 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cotid-qualabs commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dsilhavy commented Jan 13, 2026

Uh oh!

cotid-qualabs commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dsilhavy commented Feb 17, 2026

Uh oh!

dsilhavy commented Apr 27, 2026

Uh oh!

cotid-qualabs commented Apr 27, 2026

Uh oh!

dsilhavy commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

cotid-qualabs commented Aug 1, 2025 •

edited

Loading

Jason239 commented Aug 25, 2025 •

edited

Loading

cotid-qualabs commented Oct 22, 2025 •

edited

Loading

cotid-qualabs commented Feb 2, 2026 •

edited

Loading