feat: CMCD v2 LTC and MSD keys #7412

JoaquinBCh · 2024-10-10T18:58:43Z

This PR introduces two new CMCD v2 keys to shaka player:

ltc (live stream latency): The time delta between when a given media timestamp was made available at the origin and when it was rendered by the client.
msd (media start delay): Measures the initial delay in wall-clock time from when a player is instructed to play media for a given session to when any media begins playback. (This is sent only once when it is calculated)

While this update does not implement full CMCD v2 support, it extends the CMCD v1 implementation to handle these two new values when requested.

Summary:

Updated the player settings: cmcd.reporting.requestMode.version must be set to 2 to use these new CMCD v2 keys.
Implemented logic to retrieve the values for ltc and msd if requested and if the version is set to 2.
Implemented logic to send the msd value only once.
Created getLiveLatency() method in player to calculate the latency and use it for ltc.
Created unit tests for the two new keys (ltc and msd) to ensure their correct behavior when cmcd.reporting.requestMode.version is set to 2.

Testing:

Verified that the ltc and msd keys are included when the reporting version is set to 2 and these keys are requested. And the msd key is sent only once when it is calculated.
Verified that these keys are not included when the version is set to 1 or it is not set.

How to Test manually:

Test that msd and ltc values are sent correctly

Set the following configuration to the player:

player.configure({
  cmcd: {
    enabled: true,
    reporting: {
      requestMode: {
        version: 2,
      },
    },
    includeKeys: ['sid', 'cid', 'v', 'msd', 'ltc'],
  }
});

Verify that the msd value is sent only once after being calculated, and the ltc value is sent with every request.

Test the msd value is calculated correctly

Use throttling in your browser to slow down your connection and reproduce the streaming.

The msd value should be higher than usual.

Notes:

This PR adds support for the ltc and msd keys but does not implement the entire CMCD v2

google-cla · 2024-10-10T18:58:48Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

shaka-bot · 2024-10-10T19:26:08Z

Incremental code coverage: 95.77%

tykus160

Thanks for your contribution! Here are a few suggestions.
Additionally, it looks like you didn't sign CLA. Please check it.

tykus160 · 2024-10-11T13:24:27Z

externs/shaka/player.js

+/**
+ * @typedef {{
+ *   version: number
+ * }}
+ * @property {number} version
+ */
+shaka.extern.RequestMode;
+
+/**
+ * @typedef {{
+ *   requestMode: shaka.extern.RequestMode
+ * }}
+ */
+shaka.extern.Reporting;


Please add description for those typedefs and their properties.

tykus160 · 2024-10-11T13:29:46Z

lib/player.js

+   */
+  getLiveLatency() {
+    const element = this.video_;
+    const now = this.getPresentationStartTimeAsDate().valueOf() +


I know it's technically the same but a bit easier to read

Suggested change

const now = this.getPresentationStartTimeAsDate().valueOf() +

const now = this.getPresentationStartTimeAsDate().getTime() +

tykus160 · 2024-10-11T13:30:35Z

lib/player.js

+   *
+   * @return {number}
+   */
+  getLiveLatency() {


Please add unit test for this method.

tykus160 · 2024-10-11T13:31:41Z

lib/player.js

+   * @return {number}
+   */


Return null if nothing is playing.

tykus160 · 2024-10-11T13:32:04Z

lib/player.js

+   * @return {number}
+   */
+  getLiveLatency() {
+    const element = this.video_;


Please check does video element exists.

tykus160 · 2024-10-11T13:34:43Z

lib/util/cmcd_manager.js

+      this.playbackPlayTime_ = performance.now();
+    }
+  }
+
+  /**
+   * Apply CMCD data to a manifest request.
+   */
+  onPlaybackPlaying() {
+    if (!this.playbackPlayingTime_) {
+      this.playbackPlayingTime_ = performance.now();


performance.now() is not available on all supported platforms. Please either switch to Date.now() or add some utility method which checks which one is supported.

avelad

Please sign the CLA!

joeyparrish · 2024-10-18T16:09:12Z

I would also like @littlespex to review this. This week, he and I discussed his plans for CMCD v2, so I want to make sure this does not complicate those plans.

littlespex · 2024-10-18T16:59:49Z

My initial thoughts:

The new CMCD keys and serialization rules will all be replaced by the CML enums and utilities. Until that happens I don't see anything wrong with defining them along with the other internal CMCD type defs.
New internal functions for tracking state like getLiveLatency will be useful even after CML is introduced.
Changes to the player config need thorough review as they are the only public API facing code, and we won't be able to change that later without introducing a breaking change/version. V2 adds some complexity with the different delivery modes, and calls into question some how some of the current properties like includeKeys will work with these new modes. The config changes in this PR are based on similar work in dash.js. I am reviewing this proposed structure to see if it will also work for shaka.

JoaquinBCh · 2024-10-18T19:26:54Z

Thanks everyone for the reviews.
@avelad we've already signed the CLA, but we haven't been added as members of the organization yet. We're expecting to have this resolved as soon as possible

littlespex · 2024-10-23T18:35:51Z

I would like to get an answer to this question before approving/rejecting this PR:

cta-wave/common-media-client-data#138 (comment)
cta-wave/common-media-client-data#146

JoaquinBCh and others added 10 commits September 20, 2024 16:57

feature: play and playing time obtained for msd key

f805efe

Implement msd CMCDv2 key

d224c7b

Implement ltc CMCDv2 key

51b6866

Add unit tests for CMCDv2 keys

e91b872

Unit tests fixed

be1c4bf

Merge branch 'main' into feature/cmcd-v2-keys

6ae4894

fix: listenOnce instead of listen for msd calculation

459c766

constants for version added

29a7634

Merge branch 'main' into feature/cmcd-v2-keys

123163d

feat: contributors updated

2d840b5

tykus160 added the type: enhancement New feature or request label Oct 11, 2024

tykus160 requested changes Oct 11, 2024

View reviewed changes

avelad requested changes Oct 18, 2024

View reviewed changes

avelad added the priority: P3 Useful but not urgent label Oct 18, 2024

avelad added this to the v4.12 milestone Oct 18, 2024

avelad added the status: waiting on response Waiting on a response from the reporter(s) of the issue label Oct 18, 2024

joeyparrish requested a review from littlespex October 18, 2024 16:09

joeyparrish assigned littlespex Oct 18, 2024

JoaquinBCh added 2 commits October 18, 2024 16:09

fix: getLiveLatency() and add unit tests, enhance CMCD typedefs

f0a5843

Merge branch 'main' into feature/cmcd-v2-keys

ccd9d3e

JoaquinBCh requested a review from tykus160 October 18, 2024 19:27

shaka-bot removed the status: waiting on response Waiting on a response from the reporter(s) of the issue label Oct 18, 2024

avelad added the component: CMCD The issue involves CMCD specifically label Oct 21, 2024

fix: linter errors

0730e20

JoaquinBCh requested a review from avelad October 21, 2024 18:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: CMCD v2 LTC and MSD keys #7412

feat: CMCD v2 LTC and MSD keys #7412

JoaquinBCh commented Oct 10, 2024

google-cla bot commented Oct 10, 2024

shaka-bot commented Oct 10, 2024 •

edited

Loading

tykus160 left a comment

tykus160 Oct 11, 2024

tykus160 Oct 11, 2024

tykus160 Oct 11, 2024

tykus160 Oct 11, 2024

tykus160 Oct 11, 2024

tykus160 Oct 11, 2024

avelad left a comment

joeyparrish commented Oct 18, 2024

littlespex commented Oct 18, 2024

JoaquinBCh commented Oct 18, 2024

littlespex commented Oct 23, 2024

	const now = this.getPresentationStartTimeAsDate().valueOf() +
	const now = this.getPresentationStartTimeAsDate().getTime() +

feat: CMCD v2 LTC and MSD keys #7412

Are you sure you want to change the base?

feat: CMCD v2 LTC and MSD keys #7412

Conversation

JoaquinBCh commented Oct 10, 2024

Summary:

Testing:

How to Test manually:

Test that msd and ltc values are sent correctly

Test the msd value is calculated correctly

Notes:

google-cla bot commented Oct 10, 2024

shaka-bot commented Oct 10, 2024 • edited Loading

tykus160 left a comment

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

tykus160 Oct 11, 2024

Choose a reason for hiding this comment

avelad left a comment

Choose a reason for hiding this comment

joeyparrish commented Oct 18, 2024

littlespex commented Oct 18, 2024

JoaquinBCh commented Oct 18, 2024

littlespex commented Oct 23, 2024

shaka-bot commented Oct 10, 2024 •

edited

Loading