Source: lib/util/cmcd_manager.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.CmcdManager');
  9. goog.require('goog.Uri');
  10. goog.require('shaka.log');
  13. /**
  14.  * @summary
  15.  * A CmcdManager maintains CMCD state as well as a collection of utility
  16.  * functions.
  17.  */
  18. shaka.util.CmcdManager = class {
  19.   /**
  20.    * @param {shaka.util.CmcdManager.PlayerInterface} playerInterface
  21.    * @param {shaka.extern.CmcdConfiguration} config
  22.    */
  23.   constructor(playerInterface, config) {
  24.     /** @private {shaka.util.CmcdManager.PlayerInterface} */
  25.     this.playerInterface_ = playerInterface;
  27.     /** @private {?shaka.extern.CmcdConfiguration} */
  28.     this.config_ = config;
  30.     /**
  31.      * Session ID
  32.      *
  33.      * @private {string}
  34.      */
  35.     this.sid_ = '';
  37.     /**
  38.      * Streaming format
  39.      *
  40.      * @private {(shaka.util.CmcdManager.StreamingFormat|undefined)}
  41.      */
  42.     this.sf_ = undefined;
  44.     /**
  45.      * @private {boolean}
  46.      */
  47.     this.playbackStarted_ = false;
  49.     /**
  50.     * @private {boolean}
  51.     */
  52.     this.buffering_ = true;
  54.     /**
  55.      * @private {boolean}
  56.      */
  57.     this.starved_ = false;
  58.   }
  60.   /**
  61.    * Set the buffering state
  62.    *
  63.    * @param {boolean} buffering
  64.    */
  65.   setBuffering(buffering) {
  66.     if (!buffering && !this.playbackStarted_) {
  67.       this.playbackStarted_ = true;
  68.     }
  70.     if (this.playbackStarted_ && buffering) {
  71.       this.starved_ = true;
  72.     }
  74.     this.buffering_ = buffering;
  75.   }
  77.   /**
  78.    * Apply CMCD data to a manifest request.
  79.    *
  80.    * @param {!shaka.extern.Request} request
  81.    *   The request to apply CMCD data to
  82.    * @param {shaka.util.CmcdManager.ManifestInfo} manifestInfo
  83.    *   The manifest format
  84.    */
  85.   applyManifestData(request, manifestInfo) {
  86.     try {
  87.       if (!this.config_.enabled) {
  88.         return;
  89.       }
  91.       this.sf_ = manifestInfo.format;
  93.       this.apply_(request, {
  94.         ot: shaka.util.CmcdManager.ObjectType.MANIFEST,
  95.         su: !this.playbackStarted_,
  96.       });
  97.     } catch (error) {
  98.       shaka.log.warnOnce('CMCD_MANIFEST_ERROR',
  99.           'Could not generate manifest CMCD data.', error);
  100.     }
  101.   }
  103.   /**
  104.    * Apply CMCD data to a segment request
  105.    *
  106.    * @param {!shaka.extern.Request} request
  107.    * @param {shaka.util.CmcdManager.SegmentInfo} segmentInfo
  108.    */
  109.   applySegmentData(request, segmentInfo) {
  110.     try {
  111.       if (!this.config_.enabled) {
  112.         return;
  113.       }
  115.       const data = {
  116.         d: segmentInfo.duration * 1000,
  117.         st: this.getStreamType_(),
  118.       };
  120.       data.ot = this.getObjectType_(segmentInfo);
  122.       const ObjectType = shaka.util.CmcdManager.ObjectType;
  123.       const isMedia = data.ot === ObjectType.VIDEO ||
  124.                       data.ot === ObjectType.AUDIO ||
  125.                       data.ot === ObjectType.MUXED ||
  126.                       data.ot === ObjectType.TIMED_TEXT;
  128.       if (isMedia) {
  129.         data.bl = this.getBufferLength_(segmentInfo.type);
  130.       }
  132.       if (segmentInfo.bandwidth) {
  133.         data.br = segmentInfo.bandwidth / 1000;
  134.       }
  136.       if (isMedia && data.ot !== ObjectType.TIMED_TEXT) {
  137.         data.tb = this.getTopBandwidth_(data.ot) / 1000;
  138.       }
  140.       this.apply_(request, data);
  141.     } catch (error) {
  142.       shaka.log.warnOnce('CMCD_SEGMENT_ERROR',
  143.           'Could not generate segment CMCD data.', error);
  144.     }
  145.   }
  147.   /**
  148.    * Apply CMCD data to a text request
  149.    *
  150.    * @param {!shaka.extern.Request} request
  151.    */
  152.   applyTextData(request) {
  153.     try {
  154.       if (!this.config_.enabled) {
  155.         return;
  156.       }
  158.       this.apply_(request, {
  159.         ot: shaka.util.CmcdManager.ObjectType.CAPTION,
  160.         su: true,
  161.       });
  162.     } catch (error) {
  163.       shaka.log.warnOnce('CMCD_TEXT_ERROR',
  164.           'Could not generate text CMCD data.', error);
  165.     }
  166.   }
  168.   /**
  169.    * Apply CMCD data to streams loaded via src=.
  170.    *
  171.    * @param {string} uri
  172.    * @param {string} mimeType
  173.    * @return {string}
  174.    */
  175.   appendSrcData(uri, mimeType) {
  176.     try {
  177.       if (!this.config_.enabled) {
  178.         return uri;
  179.       }
  181.       const data = this.createData_();
  182.       data.ot = this.getObjectTypeFromMimeType_(mimeType);
  183.       data.su = true;
  185.       const query = shaka.util.CmcdManager.toQuery(data);
  187.       return shaka.util.CmcdManager.appendQueryToUri(uri, query);
  188.     } catch (error) {
  189.       shaka.log.warnOnce('CMCD_SRC_ERROR',
  190.           'Could not generate src CMCD data.', error);
  191.       return uri;
  192.     }
  193.   }
  195.   /**
  196.    * Apply CMCD data to side car text track uri.
  197.    *
  198.    * @param {string} uri
  199.    * @return {string}
  200.    */
  201.   appendTextTrackData(uri) {
  202.     try {
  203.       if (!this.config_.enabled) {
  204.         return uri;
  205.       }
  207.       const data = this.createData_();
  208.       data.ot = shaka.util.CmcdManager.ObjectType.CAPTION;
  209.       data.su = true;
  211.       const query = shaka.util.CmcdManager.toQuery(data);
  213.       return shaka.util.CmcdManager.appendQueryToUri(uri, query);
  214.     } catch (error) {
  215.       shaka.log.warnOnce('CMCD_TEXT_TRACK_ERROR',
  216.           'Could not generate text track CMCD data.', error);
  217.       return uri;
  218.     }
  219.   }
  221.   /**
  222.    * Create baseline CMCD data
  223.    *
  224.    * @return {CmcdData}
  225.    * @private
  226.    */
  227.   createData_() {
  228.     if (!this.sid_) {
  229.       this.sid_ = this.config_.sessionId || window.crypto.randomUUID();
  230.     }
  231.     return {
  232.       v: shaka.util.CmcdManager.Version,
  233.       sf: this.sf_,
  234.       sid: this.sid_,
  235.       cid: this.config_.contentId,
  236.       mtp: this.playerInterface_.getBandwidthEstimate() / 1000,
  237.     };
  238.   }
  240.   /**
  241.    * Apply CMCD data to a request.
  242.    *
  243.    * @param {!shaka.extern.Request} request The request to apply CMCD data to
  244.    * @param {!CmcdData} data The data object
  245.    * @param {boolean} useHeaders Send data via request headers
  246.    * @private
  247.    */
  248.   apply_(request, data = {}, useHeaders = this.config_.useHeaders) {
  249.     if (!this.config_.enabled) {
  250.       return;
  251.     }
  253.     // apply baseline data
  254.     Object.assign(data, this.createData_());
  256.     data.pr = this.playerInterface_.getPlaybackRate();
  258.     const isVideo = data.ot === shaka.util.CmcdManager.ObjectType.VIDEO ||
  259.       data.ot === shaka.util.CmcdManager.ObjectType.MUXED;
  261.     if (this.starved_ && isVideo) {
  262.       data.bs = true;
  263.       data.su = true;
  264.       this.starved_ = false;
  265.     }
  267.     if (data.su == null) {
  268.       data.su = this.buffering_;
  269.     }
  271.     // TODO: Implement rtp, nrr, nor, dl
  273.     if (useHeaders) {
  274.       const headers = shaka.util.CmcdManager.toHeaders(data);
  275.       if (!Object.keys(headers).length) {
  276.         return;
  277.       }
  279.       Object.assign(request.headers, headers);
  280.     } else {
  281.       const query = shaka.util.CmcdManager.toQuery(data);
  282.       if (!query) {
  283.         return;
  284.       }
  286.       request.uris = request.uris.map((uri) => {
  287.         return shaka.util.CmcdManager.appendQueryToUri(uri, query);
  288.       });
  289.     }
  290.   }
  292.   /**
  293.    * The CMCD object type.
  294.    *
  295.    * @param {shaka.util.CmcdManager.SegmentInfo} segmentInfo
  296.    * @private
  297.    */
  298.   getObjectType_(segmentInfo) {
  299.     const type = segmentInfo.type;
  301.     if (segmentInfo.init) {
  302.       return shaka.util.CmcdManager.ObjectType.INIT;
  303.     }
  305.     if (type == 'video') {
  306.       if (segmentInfo.codecs.includes(',')) {
  307.         return shaka.util.CmcdManager.ObjectType.MUXED;
  308.       }
  309.       return shaka.util.CmcdManager.ObjectType.VIDEO;
  310.     }
  312.     if (type == 'audio') {
  313.       return shaka.util.CmcdManager.ObjectType.AUDIO;
  314.     }
  316.     if (type == 'text') {
  317.       if (segmentInfo.mimeType === 'application/mp4') {
  318.         return shaka.util.CmcdManager.ObjectType.TIMED_TEXT;
  319.       }
  320.       return shaka.util.CmcdManager.ObjectType.CAPTION;
  321.     }
  323.     return undefined;
  324.   }
  326.   /**
  327.    * The CMCD object type from mimeType.
  328.    *
  329.    * @param {!string} mimeType
  330.    * @return {(shaka.util.CmcdManager.ObjectType|undefined)}
  331.    * @private
  332.    */
  333.   getObjectTypeFromMimeType_(mimeType) {
  334.     switch (mimeType) {
  335.       case 'video/webm':
  336.       case 'video/mp4':
  337.         return shaka.util.CmcdManager.ObjectType.MUXED;
  339.       case 'application/x-mpegurl':
  340.         return shaka.util.CmcdManager.ObjectType.MANIFEST;
  342.       default:
  343.         return undefined;
  344.     }
  345.   }
  347.   /**
  348.    * Get the buffer length for a media type in milliseconds
  349.    *
  350.    * @param {string} type
  351.    * @return {number}
  352.    * @private
  353.    */
  354.   getBufferLength_(type) {
  355.     const ranges = this.playerInterface_.getBufferedInfo()[type];
  357.     if (!ranges.length) {
  358.       return NaN;
  359.     }
  361.     const start = this.playerInterface_.getCurrentTime();
  362.     const range = ranges.find((r) => r.start <= start && r.end >= start);
  364.     if (!range) {
  365.       return NaN;
  366.     }
  368.     return (range.end - start) * 1000;
  369.   }
  371.   /**
  372.    * Get the stream type
  373.    *
  374.    * @return {shaka.util.CmcdManager.StreamType}
  375.    * @private
  376.    */
  377.   getStreamType_() {
  378.     const isLive = this.playerInterface_.isLive();
  379.     if (isLive) {
  380.       return shaka.util.CmcdManager.StreamType.LIVE;
  381.     } else {
  382.       return shaka.util.CmcdManager.StreamType.VOD;
  383.     }
  384.   }
  386.   /**
  387.    * Get the highest bandwidth for a given type.
  388.    *
  389.    * @param {string} type
  390.    * @return {number}
  391.    * @private
  392.    */
  393.   getTopBandwidth_(type) {
  394.     const variants = this.playerInterface_.getVariantTracks();
  395.     if (!variants.length) {
  396.       return NaN;
  397.     }
  399.     let top = variants[0];
  401.     for (const variant of variants) {
  402.       if (variant.type === 'variant' && variant.bandwidth > top.bandwidth) {
  403.         top = variant;
  404.       }
  405.     }
  407.     const ObjectType = shaka.util.CmcdManager.ObjectType;
  409.     switch (type) {
  410.       case ObjectType.VIDEO:
  411.         return top.videoBandwidth || NaN;
  413.       case ObjectType.AUDIO:
  414.         return top.audioBandwidth || NaN;
  416.       default:
  417.         return top.bandwidth;
  418.     }
  419.   }
  421.   /**
  422.    * Serialize a CMCD data object according to the rules defined in the
  423.    * section 3.2 of
  424.    * [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf).
  425.    *
  426.    * @param {CmcdData} data The CMCD data object
  427.    * @return {string}
  428.    */
  429.   static serialize(data) {
  430.     const results = [];
  431.     const isValid = (value) =>
  432.       !Number.isNaN(value) && value != null && value !== '' && value !== false;
  433.     const toRounded = (value) => Math.round(value);
  434.     const toHundred = (value) => toRounded(value / 100) * 100;
  435.     const toUrlSafe = (value) => encodeURIComponent(value);
  436.     const formatters = {
  437.       br: toRounded,
  438.       d: toRounded,
  439.       bl: toHundred,
  440.       dl: toHundred,
  441.       mtp: toHundred,
  442.       nor: toUrlSafe,
  443.       rtp: toHundred,
  444.       tb: toRounded,
  445.     };
  447.     const keys = Object.keys(data || {}).sort();
  449.     for (const key of keys) {
  450.       let value = data[key];
  452.       // ignore invalid values
  453.       if (!isValid(value)) {
  454.         continue;
  455.       }
  457.       // Version should only be reported if not equal to 1.
  458.       if (key === 'v' && value === 1) {
  459.         continue;
  460.       }
  462.       // Playback rate should only be sent if not equal to 1.
  463.       if (key == 'pr' && value === 1) {
  464.         continue;
  465.       }
  467.       // Certain values require special formatting
  468.       const formatter = formatters[key];
  469.       if (formatter) {
  470.         value = formatter(value);
  471.       }
  473.       // Serialize the key/value pair
  474.       const type = typeof value;
  475.       let result;
  477.       if (type === 'string' && key !== 'ot' && key !== 'sf' && key !== 'st') {
  478.         result = `${key}=${JSON.stringify(value)}`;
  479.       } else if (type === 'boolean') {
  480.         result = key;
  481.       } else if (type === 'symbol') {
  482.         result = `${key}=${value.description}`;
  483.       } else {
  484.         result = `${key}=${value}`;
  485.       }
  487.       results.push(result);
  488.     }
  490.     return results.join(',');
  491.   }
  493.   /**
  494.    * Convert a CMCD data object to request headers according to the rules
  495.    * defined in the section 2.1 and 3.2 of
  496.    * [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf).
  497.    *
  498.    * @param {CmcdData} data The CMCD data object
  499.    * @return {!Object}
  500.    */
  501.   static toHeaders(data) {
  502.     const keys = Object.keys(data);
  503.     const headers = {};
  504.     const headerNames = ['Object', 'Request', 'Session', 'Status'];
  505.     const headerGroups = [{}, {}, {}, {}];
  506.     const headerMap = {
  507.       br: 0, d: 0, ot: 0, tb: 0,
  508.       bl: 1, dl: 1, mtp: 1, nor: 1, nrr: 1, su: 1,
  509.       cid: 2, pr: 2, sf: 2, sid: 2, st: 2, v: 2,
  510.       bs: 3, rtp: 3,
  511.     };
  513.     for (const key of keys) {
  514.       // Unmapped fields are mapped to the Request header
  515.       const index = (headerMap[key] != null) ? headerMap[key] : 1;
  516.       headerGroups[index][key] = data[key];
  517.     }
  519.     for (let i = 0; i < headerGroups.length; i++) {
  520.       const value = shaka.util.CmcdManager.serialize(headerGroups[i]);
  521.       if (value) {
  522.         headers[`CMCD-${headerNames[i]}`] = value;
  523.       }
  524.     }
  526.     return headers;
  527.   }
  529.   /**
  530.    * Convert a CMCD data object to query args according to the rules
  531.    * defined in the section 2.2 and 3.2 of
  532.    * [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf).
  533.    *
  534.    * @param {CmcdData} data The CMCD data object
  535.    * @return {string}
  536.    */
  537.   static toQuery(data) {
  538.     return shaka.util.CmcdManager.serialize(data);
  539.   }
  541.   /**
  542.    * Append query args to a uri.
  543.    *
  544.    * @param {string} uri
  545.    * @param {string} query
  546.    * @return {string}
  547.    */
  548.   static appendQueryToUri(uri, query) {
  549.     if (!query) {
  550.       return uri;
  551.     }
  553.     if (uri.includes('offline:')) {
  554.       return uri;
  555.     }
  557.     const url = new goog.Uri(uri);
  558.     url.getQueryData().set('CMCD', query);
  559.     return url.toString();
  560.   }
  561. };
  564. /**
  565.  * @typedef {{
  566.  *   getBandwidthEstimate: function():number,
  567.  *   getBufferedInfo: function():shaka.extern.BufferedInfo,
  568.  *   getCurrentTime: function():number,
  569.  *   getVariantTracks: function():Array.<shaka.extern.Track>,
  570.  *   getPlaybackRate: function():number,
  571.  *   isLive: function():boolean
  572.  * }}
  573.  *
  574.  * @property {function():number} getBandwidthEstimate
  575.  *   Get the estimated bandwidth in bits per second.
  576.  * @property {function():shaka.extern.BufferedInfo} getBufferedInfo
  577.  *   Get information about what the player has buffered.
  578.  * @property {function():number} getCurrentTime
  579.  *   Get the current time
  580.  * @property {function():Array.<shaka.extern.Track>} getVariantTracks
  581.  *   Get the variant tracks
  582.  * @property {function():number} getPlaybackRate
  583.  *   Get the playback rate
  584.  * @property {function():boolean} isLive
  585.  *   Get if the player is playing live content.
  586.  */
  587. shaka.util.CmcdManager.PlayerInterface;
  590. /**
  591.  * @typedef {{
  592.  *   type: string,
  593.  *   init: boolean,
  594.  *   duration: number,
  595.  *   mimeType: string,
  596.  *   codecs: string,
  597.  *   bandwidth: (number|undefined)
  598.  * }}
  599.  *
  600.  * @property {string} type
  601.  *   The media type
  602.  * @property {boolean} init
  603.  *   Flag indicating whether the segment is an init segment
  604.  * @property {number} duration
  605.  *   The duration of the segment in seconds
  606.  * @property {string} mimeType
  607.  *   The segment's mime type
  608.  * @property {string} codecs
  609.  *   The segment's codecs
  610.  * @property {(number|undefined)} bandwidth
  611.  *   The segment's variation bandwidth
  612.  *
  613.  * @export
  614.  */
  615. shaka.util.CmcdManager.SegmentInfo;
  618. /**
  619.  * @typedef {{
  620.  *   format: shaka.util.CmcdManager.StreamingFormat
  621.  * }}
  622.  *
  623.  * @property {shaka.util.CmcdManager.StreamingFormat} format
  624.  *   The manifest's stream format
  625.  *
  626.  * @export
  627.  */
  628. shaka.util.CmcdManager.ManifestInfo;
  631. /**
  632.  * @enum {string}
  633.  */
  634. shaka.util.CmcdManager.ObjectType = {
  635.   MANIFEST: 'm',
  636.   AUDIO: 'a',
  637.   VIDEO: 'v',
  638.   MUXED: 'av',
  639.   INIT: 'i',
  640.   CAPTION: 'c',
  641.   TIMED_TEXT: 'tt',
  642.   KEY: 'k',
  643.   OTHER: 'o',
  644. };
  647. /**
  648.  * @enum {string}
  649.  */
  650. shaka.util.CmcdManager.StreamType = {
  651.   VOD: 'v',
  652.   LIVE: 'l',
  653. };
  656. /**
  657.  * @enum {string}
  658.  * @export
  659.  */
  660. shaka.util.CmcdManager.StreamingFormat = {
  661.   DASH: 'd',
  662.   HLS: 'h',
  663.   SMOOTH: 's',
  664.   OTHER: 'o',
  665. };
  668. /**
  669.  * The CMCD spec version
  670.  * @const {number}
  671.  */
  672. shaka.util.CmcdManager.Version = 1;