feat(cmcd): upgrade to CMCD v2 using @svta/cml-cmcd CmcdReporter by littlespex · Pull Request #7725 · video-dev/hls.js

littlespex · 2026-02-12T02:13:47Z

Summary

Implements CMCD v2 support by migrating from @svta/common-media-library to the dedicated @svta/cml-* packages and fully delegating CMCD encoding to CmcdReporter from @svta/cml-cmcd.

Resolves #7723.

Changes

Migrate dependencies: Replace @svta/common-media-library with @svta/cml-cmcd, @svta/cml-id3, @svta/cml-utils, and @svta/cml-structured-field-values
CMCD v2 data fields: Add version, st (stream type), sta (player state), sn (sequence number) to CMCD output. Inner list encoding for br, tb, bl, mtp, nor per v2 spec
CmcdReporter integration: Delegate all CMCD request encoding to CmcdReporter.createRequestReport(), removing manual appendCmcdHeaders/appendCmcdQuery calls and the createData() method
Event-mode reporting: Support v2 event targets for play state changes (PLAY_STATE), fatal errors (ERROR), and bitrate changes (BITRATE_CHANGE)
Configuration: Add version, enabledKeys, and eventTargets to CMCDControllerConfig. Default enabledKeys to CMCD_V1_KEYS (v1) or CMCD_KEYS (v2)
Exported types: Re-export CMCD v2 types (CmcdVersion, CmcdPlayerState, CmcdStreamType, etc.) from exports-named.ts
Tests: Comprehensive unit test coverage for v1 defaults, v2 fields (query and headers modes), stream type detection, event reporting, and reporter lifecycle

Behavioral notes

v=1 is omitted from output per CMCD spec (it is the default)
sn (sequence number) is automatically included in v2 output, filtered out for v1
nor uses root-relative paths (via url.origin as baseUrl) instead of path-relative
Inner list values (bl, tb) are guarded against NaN to prevent Structured Fields serialization errors

Test plan

All 912 unit tests pass
Manual verification with a CMCD v1 configuration (query and headers modes)
Manual verification with a CMCD v2 configuration (query, headers, and event modes)
Verify no source map warnings in downstream bundlers (Vite/Nuxt)

…d v2 version support Replace the monolithic @svta/common-media-library package with the scoped @svta/[email protected] and @svta/[email protected] packages for CMCD functionality. The old package is retained for non-CMCD imports (ID3, UTF8). Add a `version` option to CMCDControllerConfig (defaults to 1 for backwards compatibility) that controls CMCD encoding version. When set to 2, the controller uses CMCD v2 Structured Field Value encoding via the new library. Key changes: - Update all CMCD imports to use @svta/cml-cmcd single entry point - Update uuid import to use @svta/cml-utils - Update tsconfig moduleResolution to "bundler" for exports field support - Adapt CMCD data fields (br, bl, mtp, tb, nor) to v2 array types - Pass version through to CmcdEncodeOptions for version-aware encoding https://claude.ai/code/session_01FmnN6xNSm9Qo17tp52ag3U

Phase 3: Add new CMCD v2 data fields to the controller: - Stream type (st): Detect VOD/LIVE/LOW_LATENCY from level details based on live flag, canBlockReload, and canSkipUntil properties - Player state (sta): Track player state transitions via media element events (waiting, playing, pause, seeking, ended) and hls.js ERROR events for fatal errors. Maps to CmcdPlayerState enum values. - Both fields are only included when version >= 2 Phase 4: Integrate CmcdReporter for event-mode reporting: - Add eventTargets config option (CmcdEventReportConfig[]) for v2 event reporting endpoints - Instantiate CmcdReporter when version >= 2 and eventTargets are configured, with session/content ID and transmission mode - Record PLAY_STATE events on player state transitions - Record ERROR events on fatal hls.js errors - Record BITRATE_CHANGE events on level switches - Stop and flush reporter on controller destroy Add unit tests for v2 version encoding, stream type detection (VOD, LIVE, LOW_LATENCY), and player state inclusion. https://claude.ai/code/session_01FmnN6xNSm9Qo17tp52ag3U

Phase 6: Re-export CMCD types and constants from exports-named.ts for ESM consumers: CmcdObjectType, CmcdStreamType, CmcdStreamingFormat, CmcdPlayerState, CmcdEventType, CmcdHeaderField, CMCD_V1, CMCD_V2, and type exports for Cmcd, CmcdEncodeOptions, CmcdEventReportConfig, CmcdVersion. Add @svta/cml-cmcd, @svta/cml-utils, and @svta/cml-structured-field-values to api-extractor bundledPackages so external types are inlined in the rolled-up dist/hls.d.ts. Phase 7: Add tests for: - v2 fragment data includes version, stream type, and player state - v2 headers mode includes v2 fields in CMCD headers - Reporter is not created without eventTargets or for v1 - Reporter is created with v2 + eventTargets - Reporter.stop(true) is called on destroy - Play state events are recorded on state transitions - Error events are recorded on fatal hls.js errors - Duplicate player state events are deduplicated Phase 8: Verified TypeScript type-check, all Rollup build configs (full, fullEsm, light), and api-extractor declaration bundling. https://claude.ai/code/session_01FmnN6xNSm9Qo17tp52ag3U

littlespex · 2026-02-12T02:19:33Z

+    // TODO: Is this the best way to determine the low-latency stream type?
+    if (details.canBlockReload || details.canSkipUntil) {
+      return CmcdStreamType.LOW_LATENCY;
+    }


@robwalch I'm not sure about this check. Is there a better way to determine if a stream is low latency?

Good question!

Only checking EXT-X-SERVER-CONTROL for blocking reload or delta playlist capabilities is not enough. Both of these features can be used without partial segments (details.partList) for live playback at a standard three target duration hold back.

If we follow the requirements of a "Low-Latency Server Configuration Profile":

if ( // Playlist has EXT-X-PROGRAM-DATE-TIME details.hasProgramDateTime && // Segments have at least one key-frame (EXT-X-INDEPENDENT-SEGMENTS or track violations) // skip this requirement - something like `couldBacktrack` on LevelDetails could be nice to have // Playlist has EXT-X-PART(s) !!details.partList && // Playlist has EXT-X-PRELOAD-HINT // skip this requirement - support will be added with #6356 // Playlists has at least one EXT-X-RENDITION-REPORT or only one variant (!!details.renditionReports || this.hls.levels.length === 1) && // Blocking Playlist Reload is required details.canBlockReload ) { return CmcdStreamType.LOW_LATENCY; }

Delta playlists are not required because playlist can be short enough that skipping segments doesn't add much if any benefit. Blocking reload is critical - servers that don't implement it, and worse only signal they do, perform miserably. HLS.js today may still use parts without PDT and Rendition Reports (I'll have to check), but it should not. I'll file an issue to follow up with other scheduled LL-HLS enhancements.

Filed Make sure Low-Latency Server Configuration Profile is met before using Parts #7729

…ooks CmcdReporter sends CMCD v2 event reports via a requester function that defaults to bare fetch(), bypassing customer auth headers and credentials configured via xhrSetup/fetchSetup. Add a createCmcdRequester adapter that routes through the same setup hooks applied to media/playlist requests. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Add end-to-end tests for CMCD v2 covering query mode, header mode, event mode, key filtering, and version comparison (v1 vs v2). Fix eventTargets enabledKeys mapping bug in CMCDController where includeKeys was not being mapped to the library's enabledKeys parameter, causing event reports to have no enabled keys. Co-Authored-By: Claude Opus 4.6 <[email protected]>

littlespex · 2026-02-26T04:06:36Z

I'm not sure if these should just be merged with the tests/unit/controller/cmcd-controller.ts tests. They are different in that they actually load media and inspect the outgoing traffic for correct CMCD data.

littlespex · 2026-02-26T04:08:15Z

This helper monkey patches fetch so that outgoing requests can be inspected. It also acts as an "event" server for CMCD event mode, generating the 204 response.

… option Remove createCmcdRequester function and allow users to pass a custom loader via cmcd.loader config. When not provided, CmcdReporter uses its default fetch-based requester. Co-Authored-By: Claude Opus 4.5 <[email protected]>

robwalch

Preliminary review. I still need to run some tests before I can sign off.

robwalch · 2026-04-21T21:04:13Z

+    if (this.version >= CMCD_V2) {
+      hls.off(Events.ERROR, this.onError, this);
+      hls.off(Events.LEVEL_SWITCHING, this.onLevelSwitching, this);
+    }


We don't need to guard here. It's safe to call off whether or not the listener was registered.

The if (this.version >= CMCD_V2) guard was removed from both registerListeners and unregisterListeners in c148687.

robwalch · 2026-04-21T21:08:17Z

+    if (this.version >= CMCD_V2) {
+      this.media.addEventListener('pause', this.onPause);
+      this.media.addEventListener('seeking', this.onSeeking);
+      this.media.addEventListener('ended', this.onEnded);


You might consider using Events.MEDIA_ENDED. The event has a stalled flag that signals whether a stall (waiting) was reached near the end or "ended" was received.

Done in c10b1f5, replaced the native 'ended' listener with hls.on(Events.MEDIA_ENDED, this.onMediaEnded). Both stalled and non-stalled variants map to CmcdPlayerState.ENDED; REBUFFERING is already set by the 'waiting' handler when a pre-end stall occurs.

robwalch · 2026-04-21T21:09:14Z

+    this.reporter?.update({ br: [data.bitrate / 1000] });
+    this.reporter?.recordEvent(CmcdEventType.BITRATE_CHANGE);


Prefer if (this.reporter) { block to multiple optional operators.

Done in c10b1f5, onError, onLevelSwitching, setPlayerState, and apply now guard with if (this.reporter) { ... } blocks instead of ! assertions.

robwalch · 2026-04-21T21:13:17Z

+    version?: CmcdVersion;
+    eventTargets?: (Omit<CmcdEventReportConfig, 'enabledKeys'> & {
+        includeKeys?: CmcdKey[];
+    })[];
+    loader?: (request: {


Can you add these new options to docs/API.md#cmcd?

Done in c10b1f5, added version, eventTargets (with a child list covering url, events, interval, batchSize, and per-target includeKeys), and loader to the CMCD section in docs/API.md. Also extended the existing includeKeys line to note the version-aware default.

robwalch · 2026-04-21T21:19:17Z

  private initialized: boolean = false;
  private starved: boolean = false;
  private buffering: boolean = true;
+  private playerState: CmcdPlayerState = CmcdPlayerState.STARTING;


How is CMCD supposed to behave when another item is loaded using the same player instance? Same as if a new instance was used?

Maybe the player state should also get set to STARTING on Events.MANIFEST_LOADING? We use this event to reset controllers whenever hls.loadSource(<m3u8>) is called to load a new item.

Done in c10b1f5, added an onManifestLoading handler that stops and recreates the CmcdReporter, resets playerState to STARTING, and clears the initialized/starved/buffering flags. The reporter is recreated with the same config so sid / cid persist across loadSource() calls on the same Hls instance (same player session = same CMCD session).

robwalch · 2026-04-21T21:21:13Z

+    const loadLevel = this.hls.loadLevel;
+    const details =
+      loadLevel >= 0 ? this.hls.levels[loadLevel]?.details : undefined;


Use top-level API to get latest loaded details:

Suggested change

const loadLevel = this.hls.loadLevel;

const details =

loadLevel >= 0 ? this.hls.levels[loadLevel]?.details : undefined;

const details = this.hls.latestLevelDetails;

Done in c10b1f5.

robwalch · 2026-04-21T21:28:26Z

+    // TODO: Is this the best way to determine the low-latency stream type?
+    if (details.canBlockReload || details.canSkipUntil) {


Until #7729 do

Suggested change

// TODO: Is this the best way to determine the low-latency stream type?

if (details.canBlockReload || details.canSkipUntil) {

// TODO: Replace with an `isLowLatency` check in #7729

if (!!details.partList && details.canBlockReload) {

It's not low-latency without parts. The potential to deliver playlist deltas (canSkipUntil) does not make the playlist low-latency.

Done in c10b1f5, getStreamType now checks !!details.partList && details.canBlockReload, with the suggested TODO comment referencing #7729.

- Swap native 'ended' listener for hls Events.MEDIA_ENDED - Reset + recreate reporter on MANIFEST_LOADING so loadSource() on an existing Hls instance behaves like a fresh CMCD session - Replace this.reporter! assertions with if (this.reporter) blocks - Use hls.latestLevelDetails in getStreamType - Tighten low-latency detection to require details.partList (TODO video-dev#7729) - Document version, eventTargets (with child properties), and loader config options in docs/API.md - Extend setupEach test harness with a streamController.getLevelDetails mock to support latestLevelDetails lookup Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

claude and others added 6 commits February 8, 2026 17:45

fix: remove @svta/common-media-library

db011bc

feat: update cmcd-controller to use CML's CmcdReporter

5f83511

Merge branch 'master' into issue/7723-cmcd-v2

a0ff463

littlespex commented Feb 12, 2026

View reviewed changes

littlespex added 6 commits February 11, 2026 21:18

chore: update CML packages

ba31f04

fix: build system cleanup

b65b1e0

fix: export clean up

8c5f8ca

fix: api-extractor rebuild

cf201b6

revert: build config change

214bcbb

Merge branch 'master' into issue/7723-cmcd-v2

1fd0cdc

littlespex commented Feb 12, 2026

View reviewed changes

Comment thread src/controller/cmcd-controller.ts

Merge branch 'master' into issue/7723-cmcd-v2

f949091

robwalch reviewed Feb 13, 2026

View reviewed changes

Comment thread src/controller/cmcd-controller.ts Outdated

robwalch added this to HLS.js Release Planning and Backlog Feb 13, 2026

github-project-automation Bot moved this to Top priorities in HLS.js Release Planning and Backlog Feb 13, 2026

fix: address code review comment about muxed buffers

62203b6

robwalch linked an issue Feb 14, 2026 that may be closed by this pull request

CMCD Version 2 (CTA-5004) Support #7724

Open

robwalch added the CMCD label Feb 16, 2026

dsilhavy mentioned this pull request Feb 17, 2026

Feature: CMCD v2 Dash-Industry-Forum/dash.js#4816

Open

littlespex and others added 4 commits February 23, 2026 13:08

Merge branch 'master' into issue/7723-cmcd-v2

4ef9d6d

Merge branch 'master' into issue/7723-cmcd-v2

a85caae

littlespex commented Feb 26, 2026

View reviewed changes

littlespex and others added 2 commits February 25, 2026 20:09

fix: return 204 for event mode responses

f2e021e

littlespex added 4 commits March 3, 2026 10:47

chore: update api file

1ef698a

Merge branch 'master' into issue/7723-cmcd-v2

2c7cab3

Merge branch 'master' into issue/7723-cmcd-v2

a35400d

chore: update CMCD package for revision B changes

c148687

littlespex marked this pull request as ready for review April 15, 2026 17:16

littlespex requested a review from robwalch April 15, 2026 17:16

robwalch requested changes Apr 21, 2026

View reviewed changes

littlespex and others added 2 commits April 21, 2026 17:55

Merge branch 'master' into issue/7723-cmcd-v2

f06bd8d

		this.reporter?.update({ br: [data.bitrate / 1000] });
		this.reporter?.recordEvent(CmcdEventType.BITRATE_CHANGE);

		// TODO: Is this the best way to determine the low-latency stream type?
		if (details.canBlockReload \|\| details.canSkipUntil) {

Conversation

littlespex commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Behavioral notes

Test plan

Uh oh!

littlespex Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robwalch Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robwalch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

littlespex Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

littlespex commented Feb 12, 2026 •

edited

Loading

littlespex Feb 12, 2026 •

edited

Loading

robwalch Feb 13, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading

littlespex Apr 22, 2026 •

edited

Loading