feat: Add Common Media Client Data (CMCD) logging support (shaka-proj…

…ect#3662)

Add support for including Common Media Client Data (CMCD) in outgoing requests.

Fixes shaka-project#3619

NOTE: The following fields have not been implemented: rtp, nrr, nor, dl

Co-authored-by: Dan Sparacio <[email protected]>

.gitignore

@@ -6,3 +6,4 @@ dist/
 docs/api/
 coverage/
 .DS_Store
+.vscode

AUTHORS

@@ -70,5 +70,6 @@ Tomohiro Matsuzawa <[email protected]>
 Toshihiro Suzuki <[email protected]>
 uStudio Inc. <*@ustudio.com>
 Verizon Digital Media Services <*@verizondigitalmedia.com>
+ViacomCBS <*@viacomcbs.com>
 Vincent Valot <[email protected]>
 Wayne Morgan <[email protected]>

CONTRIBUTORS

@@ -36,6 +36,7 @@ Benjamin Wallberg <[email protected]>
 Boris Cupac <[email protected]>
 Brad Nadler <[email protected]>
 Bryan Huh <[email protected]>
+Casey Occhialini <[email protected]>
 Chad Assareh <[email protected]>
 Chris Fillmore <[email protected]>
 Costel Madalin Grecu <[email protected]>

build/types/core

@@ -58,6 +58,7 @@
 +../../lib/util/abortable_operation.js
 +../../lib/util/array_utils.js
 +../../lib/util/buffer_utils.js
++../../lib/util/cmcd_manager.js
 +../../lib/util/config_utils.js
 +../../lib/util/data_view_reader.js
 +../../lib/util/delayed_tick.js

demo/common/message_ids.js

@@ -157,7 +157,9 @@ shakaDemo.MessageIds = {
   BUFFER_BEHIND: 'DEMO_BUFFER_BEHIND',
   BUFFERING_GOAL: 'DEMO_BUFFERING_GOAL',
   CLOCK_SYNC_URI: 'DEMO_CLOCK_SYNC_URI',
+  CMCD_SECTION_HEADER: 'DEMO_CMCD_SECTION_HEADER',
   CONNECTION_TIMEOUT: 'DEMO_CONNECTION_TIMEOUT',
+  CONTENT_ID: 'DEMO_CONTENT_ID',
   DEFAULT_AUDIO_CODEC: 'DEMO_DEFAULT_AUDIO_CODEC',
   DEFAULT_PRESENTATION_DELAY: 'DEMO_DEFAULT_PRESENTATION_DELAY',
   DEFAULT_VIDEO_CODEC: 'DEMO_DEFAULT_VIDEO_CODEC',
@@ -226,6 +228,7 @@ shakaDemo.MessageIds = {
   RESTRICTIONS_SECTION_HEADER: 'DEMO_RESTRICTIONS_SECTION_HEADER',
   SAFE_SEEK_OFFSET: 'DEMO_SAFE_SEEK_OFFSET',
   SAFE_SKIP_DISTANCE: 'DEMO_SAFE_SKIP_DISTANCE',
+  SESSION_ID: 'DEMO_SESSION_ID',
   SHAKA_CONTROLS: 'DEMO_SHAKA_CONTROLS',
   SLOW_HALF_LIFE: 'DEMO_SLOW_HALF_LIFE',
   STALL_DETECTOR_ENABLED: 'DEMO_STALL_DETECTOR_ENABLED',
@@ -243,6 +246,7 @@ shakaDemo.MessageIds = {
   UI_LOCALE: 'DEMO_UI_LOCALE',
   UPDATE_EXPIRATION_TIME: 'DEMO_UPDATE_EXPIRATION_TIME',
   UPDATE_INTERVAL_SECONDS: 'DEMO_UPDATE_INTERVAL_SECONDS',
+  USE_HEADERS: 'DEMO_USE_HEADERS',
   USE_NATIVE_HLS_SAFARI: 'DEMO_USE_NATIVE_HLS_SAFARI',
   USE_PERSISTENT_LICENSES: 'DEMO_USE_PERSISTENT_LICENSES',
   VIDEO_ROBUSTNESS: 'DEMO_VIDEO_ROBUSTNESS',

demo/config.js

@@ -96,6 +96,7 @@ shakaDemo.Config = class {
     this.addManifestSection_();
     this.addRetrictionsSection_('',
         shakaDemo.MessageIds.RESTRICTIONS_SECTION_HEADER);
+    this.addCmcdSection_();
   }
 
   /**
@@ -274,6 +275,17 @@ shakaDemo.Config = class {
         MessageIds.ADAPTATION_RESTRICTIONS_SECTION_HEADER);
   }
 
+  /** @private */
+  addCmcdSection_() {
+    const MessageIds = shakaDemo.MessageIds;
+    const docLink = this.resolveExternLink_('.CmcdConfiguration');
+    this.addSection_(MessageIds.CMCD_SECTION_HEADER, docLink)
+        .addBoolInput_(MessageIds.ENABLED, 'cmcd.enabled')
+        .addTextInput_(MessageIds.SESSION_ID, 'cmcd.sessionId')
+        .addTextInput_(MessageIds.CONTENT_ID, 'cmcd.contentId')
+        .addBoolInput_(MessageIds.USE_HEADERS, 'cmcd.useHeaders');
+  }
+
   /**
    * @param {string} category
    * @param {!shakaDemo.MessageIds} sectionName

demo/locales/en.json

@@ -33,11 +33,13 @@
   "DEMO_CLEAR": "No DRM protection",
   "DEMO_CLEAR_KEY": "Clear Key DRM",
   "DEMO_CLOCK_SYNC_URI": "Clock Sync URI",
+  "DEMO_CMCD_SECTION_HEADER": "CMCD",
   "DEMO_COMPILED_DEBUG": "Compiled (Debug)",
   "DEMO_COMPILED_RELEASE": "Compiled (Release)",
   "DEMO_CONNECTION_TIMEOUT": "Connection timeout",
   "DEMO_CONFIG": "Shaka Player Demo Config",
   "DEMO_CONTAINER_SEARCH": "Container",
+  "DEMO_CONTENT_ID": "Content ID",
   "DEMO_CUSTOM": "Custom",
   "DEMO_CUSTOM_CONTENT": "CUSTOM CONTENT",
   "DEMO_CUSTOM_INTRO_ONE": "Try Shaka Player with your own content!",
@@ -173,6 +175,7 @@
   "DEMO_RESTRICTIONS_SECTION_HEADER": "Restrictions",
   "DEMO_SAFE_SEEK_OFFSET": "Safe Seek Offset",
   "DEMO_SAFE_SKIP_DISTANCE": "Safe Skip Distance",
+  "DEMO_SESSION_ID": "Session ID",
   "DEMO_SAVE_BUTTON": "Save",
   "DEMO_SHAKA": "Shaka",
   "DEMO_SHAKA_CONTROLS": "Shaka Controls",
@@ -218,6 +221,7 @@
   "DEMO_UPDATE_INTERVAL_SECONDS": "Update interval seconds",
   "DEMO_UPLYNK": "Verizon Digital Media Services",
   "DEMO_USE_FULL_SEGMENTS_FOR_START_TIME": "Use Full Segments For Start Time",
+  "DEMO_USE_HEADERS": "Use Headers",
   "DEMO_USE_NATIVE_HLS_SAFARI": "Use native HLS on Safari",
   "DEMO_USE_PERSISTENT_LICENSES": "Use Persistent Licenses",
   "DEMO_VIDEO_ROBUSTNESS": "Video Robustness",

demo/locales/source.json

@@ -135,6 +135,10 @@
     "description": "The name of a configuration value.",
     "message": "Clock Sync URI"
   },
+  "DEMO_CMCD_SECTION_HEADER": {
+    "description": "The header for a section of configuration values.",
+    "message": "[JARGON:CMCD]"
+  },
   "DEMO_COMPILED_DEBUG": {
     "description": "A link in the footer, to the debug build of the demo.",
     "message": "Compiled (Debug)"
@@ -155,6 +159,10 @@
     "description": "A header on a search field that filters by container type.",
     "message": "Container"
   },
+  "DEMO_CONTENT_ID": {
+    "description": "The name of a configuration value.",
+    "message": "Content ID"
+  },
   "DEMO_CUSTOM": {
     "description": "Text that describes an asset that was defined by the user.",
     "message": "Custom"
@@ -703,6 +711,10 @@
     "description": "A button to save a custom asset.",
     "message": "Save"
   },
+  "DEMO_SESSION_ID": {
+    "description": "The name of a configuration value.",
+    "message": "Session ID"
+  },
   "DEMO_SHAKA": {
     "description": "Text that describes an asset that comes from the Shaka Player asset library.",
     "message": "[PROPER_NAME:Shaka]"
@@ -875,6 +887,10 @@
     "description": "Text that describes an asset that comes from the Verizon Digital Media Services asset library.",
     "message": "[PROPER_NAME:Verizon Digital Media Services]"
   },
+  "DEMO_USE_HEADERS": {
+    "description": "The name of a configuration value.",
+    "message": "Use Headers"
+  },
   "DEMO_USE_NATIVE_HLS_SAFARI": {
     "description": "The name of a configuration value.",
     "message": "Use native [PROPER_NAME:HLS] on Safari"

externs/shaka/manifest_parser.js

@@ -100,6 +100,10 @@ shaka.extern.ManifestParser = class {
 /**
  * @typedef {{
  *   networkingEngine: !shaka.net.NetworkingEngine,
+ *   modifyManifestRequest: function(!shaka.extern.Request,
+ *      shaka.util.CmcdManager.ManifestInfo),
+ *   modifySegmentRequest: function(!shaka.extern.Request,
+ *      shaka.util.CmcdManager.SegmentInfo),
  *   filter: function(shaka.extern.Manifest):!Promise,
  *   makeTextStreamsForClosedCaptions: function(shaka.extern.Manifest),
  *   onTimelineRegionAdded: function(shaka.extern.TimelineRegionInfo),
@@ -118,6 +122,12 @@ shaka.extern.ManifestParser = class {
  *
  * @property {!shaka.net.NetworkingEngine} networkingEngine
  *   The networking engine to use for network requests.
+ * @property {function(!shaka.extern.Request,
+ *    shaka.util.CmcdManager.ManifestInfo)} modifyManifestRequest
+ *   Modify a manifest request
+ * @property {function(!shaka.extern.Request,
+ *   shaka.util.CmcdManager.SegmentInfo)} modifySegmentRequest
+ *   Modify a segment request
  * @property {function(shaka.extern.Manifest):!Promise} filter
  *   Should be called when new variants or text streams are added to the
  *   Manifest.  Note that this operation is asynchronous.
@@ -150,4 +160,3 @@ shaka.extern.ManifestParser.PlayerInterface;
  * @exportDoc
  */
 shaka.extern.ManifestParser.Factory;
-

externs/shaka/player.js

@@ -942,7 +942,7 @@ shaka.extern.StreamingConfiguration;
  *   automatically, but will still appear in the track list and can still be
  *   selected via <code>selectVariantTrack()</code>.  If no tracks meet these
  *   restrictions, AbrManager should not fail, but choose a low-res or
- *   low-bandwidth variant instead.  It is the responsibiliy of AbrManager
+ *   low-bandwidth variant instead.  It is the responsibility of AbrManager
  *   implementations to follow these rules and implement this behavior.
  * @property {number} switchInterval
  *   The minimum amount of time that must pass between switches, in
@@ -990,6 +990,39 @@ shaka.extern.AbrConfiguration;
 shaka.extern.AdvancedAbrConfiguration;
 
 
+/**
+ * @typedef {{
+ *   enabled: boolean,
+ *   useHeaders: boolean,
+ *   sessionId: string,
+ *   contentId: string
+ * }}
+ *
+ * @description
+ *   Common Media Client Data (CMCD) configuration.
+ *
+ * @property {boolean} enabled
+ *   If <code>true</code>, enable CMCD data to be sent with media requests.
+ *   Defaults to <code>false</code>.
+ * @property {boolean} useHeaders
+ *   If <code>true</code>, send CMCD data using the header transmission mode
+ *   instead of query args.  Defaults to <code>false</code>.
+ * @property {string} sessionId
+ *   A GUID identifying the current playback session. A playback session
+ *   typically ties together segments belonging to a single media asset.
+ *   Maximum length is 64 characters. It is RECOMMENDED to conform to the UUID
+ *   specification. By default the sessionId is automatically generated on each
+ *   <code>load()</code> call.
+ * @property {string} contentId
+ *   A unique string identifying the current content. Maximum length is 64
+ *   characters. This value is consistent across multiple different sessions and
+ *   devices and is defined and updated at the discretion of the service
+ *   provider.
+ * @exportDoc
+ */
+shaka.extern.CmcdConfiguration;
+
+
 /**
  * @typedef {{
  *   trackSelectionCallback:
@@ -1031,6 +1064,7 @@ shaka.extern.OfflineConfiguration;
  *   streaming: shaka.extern.StreamingConfiguration,
  *   abrFactory: shaka.extern.AbrManager.Factory,
  *   abr: shaka.extern.AbrConfiguration,
+ *   cmcd: shaka.extern.CmcdConfiguration,
  *   offline: shaka.extern.OfflineConfiguration,
  *   preferredAudioLanguage: string,
  *   preferredTextLanguage: string,
@@ -1057,6 +1091,8 @@ shaka.extern.OfflineConfiguration;
  *   A factory to construct an abr manager.
  * @property {shaka.extern.AbrConfiguration} abr
  *   ABR configuration and settings.
+ * @property {shaka.extern.CmcdConfiguration} cmcd
+ *   CMCD configuration and settings. (Common Media Client Data)
  * @property {shaka.extern.OfflineConfiguration} offline
  *   Offline configuration and settings.
  * @property {string} preferredAudioLanguage

lib/dash/dash_parser.js

@@ -19,6 +19,7 @@ goog.require('shaka.media.PresentationTimeline');
 goog.require('shaka.media.SegmentIndex');
 goog.require('shaka.net.NetworkingEngine');
 goog.require('shaka.text.TextEngine');
+goog.require('shaka.util.CmcdManager');
 goog.require('shaka.util.Error');
 goog.require('shaka.util.Functional');
 goog.require('shaka.util.Iterables');
@@ -214,6 +215,9 @@ shaka.dash.DashParser = class {
         this.manifestUris_, this.config_.retryParameters);
     const networkingEngine = this.playerInterface_.networkingEngine;
 
+    const format = shaka.util.CmcdManager.StreamingFormat.DASH;
+    this.playerInterface_.modifyManifestRequest(request, {format: format});
+
     const startTime = Date.now();
     const operation = networkingEngine.request(requestType, request);
     this.operationManager_.manage(operation);