Source: lib/cast/cast_utils.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.cast.CastUtils');
  9. goog.require('shaka.media.TimeRangesUtils');
  10. goog.require('shaka.util.FakeEvent');
  13. /**
  14.  * @summary A set of cast utility functions and variables shared between sender
  15.  *   and receiver.
  16.  */
  17. shaka.cast.CastUtils = class {
  18.   /**
  19.    * Serialize as JSON, but specially encode things JSON will not otherwise
  20.    * represent.
  21.    * @param {?} thing
  22.    * @return {string}
  23.    */
  24.   static serialize(thing) {
  25.     return JSON.stringify(thing, (key, value) => {
  26.       if (typeof value == 'function') {
  27.         // Functions can't be (safely) serialized.
  28.         return undefined;
  29.       }
  31.       if (value instanceof Event || value instanceof shaka.util.FakeEvent) {
  32.         // Events don't serialize to JSON well because of the DOM objects
  33.         // and other complex objects they contain, so we strip these out.
  34.         // Note that using Object.keys or JSON.stringify directly on the event
  35.         // will not capture its properties.  We must use a for loop.
  36.         const simpleEvent = {};
  37.         for (const eventKey in value) {
  38.           const eventValue = value[eventKey];
  39.           if (eventValue && typeof eventValue == 'object') {
  40.             if (eventKey == 'detail') {
  41.               // Keep the detail value, because it contains important
  42.               // information for diagnosing errors.
  43.               simpleEvent[eventKey] = eventValue;
  44.             }
  45.             // Strip out non-null object types because they are complex and we
  46.             // don't need them.
  47.           } else if (eventKey in Event) {
  48.             // Strip out keys that are found on Event itself because they are
  49.             // class-level constants we don't need, like Event.MOUSEMOVE == 16.
  50.           } else {
  51.             simpleEvent[eventKey] = eventValue;
  52.           }
  53.         }
  54.         return simpleEvent;
  55.       }
  57.       if (value instanceof Error) {
  58.         // Errors don't serialize to JSON well, either.  TypeError, for example,
  59.         // turns in "{}", leading to messages like "Error UNKNOWN.UNKNOWN" when
  60.         // deserialized on the sender and displayed in the demo app.
  61.         return shaka.cast.CastUtils.unpackError_(value);
  62.       }
  64.       if (value instanceof TimeRanges) {
  65.         // TimeRanges must be unpacked into plain data for serialization.
  66.         return shaka.cast.CastUtils.unpackTimeRanges_(value);
  67.       }
  69.       if (ArrayBuffer.isView(value) &&
  70.       /** @type {TypedArray} */(value).BYTES_PER_ELEMENT === 1) {
  71.         // Some of our code cares about Uint8Arrays actually being Uint8Arrays,
  72.         // so this gives them special treatment.
  73.         return shaka.cast.CastUtils.unpackUint8Array_(
  74.             /** @type {!Uint8Array} */(value));
  75.       }
  77.       if (typeof value == 'number') {
  78.         // NaN and infinity cannot be represented directly in JSON.
  79.         if (isNaN(value)) {
  80.           return 'NaN';
  81.         }
  82.         if (isFinite(value)) {
  83.           return value;
  84.         }
  85.         if (value < 0) {
  86.           return '-Infinity';
  87.         }
  88.         return 'Infinity';
  89.       }
  91.       return value;
  92.     });
  93.   }
  96.   /**
  97.    * Deserialize JSON using our special encodings.
  98.    * @param {string} str
  99.    * @return {?}
  100.    */
  101.   static deserialize(str) {
  102.     return JSON.parse(str, (key, value) => {
  103.       if (value == 'NaN') {
  104.         return NaN;
  105.       } else if (value == '-Infinity') {
  106.         return -Infinity;
  107.       } else if (value == 'Infinity') {
  108.         return Infinity;
  109.       } else if (value && typeof value == 'object' &&
  110.                  value['__type__'] == 'TimeRanges') {
  111.         // TimeRanges objects have been unpacked and sent as plain data.
  112.         // Simulate the original TimeRanges object.
  113.         return shaka.cast.CastUtils.simulateTimeRanges_(value);
  114.       } else if (value && typeof value == 'object' &&
  115.                  value['__type__'] == 'Uint8Array') {
  116.         return shaka.cast.CastUtils.makeUint8Array_(value);
  117.       } else if (value && typeof value == 'object' &&
  118.                  value['__type__'] == 'Error') {
  119.         return shaka.cast.CastUtils.makeError_(value);
  120.       }
  121.       return value;
  122.     });
  123.   }
  126.   /**
  127.    * @param {!TimeRanges} ranges
  128.    * @return {!Object}
  129.    * @private
  130.    */
  131.   static unpackTimeRanges_(ranges) {
  132.     const obj = {
  133.       '__type__': 'TimeRanges',  // a signal to deserialize
  134.       'length': ranges.length,
  135.       'start': [],
  136.       'end': [],
  137.     };
  139.     const TimeRangesUtils = shaka.media.TimeRangesUtils;
  140.     for (const {start, end} of TimeRangesUtils.getBufferedInfo(ranges)) {
  141.       obj['start'].push(start);
  142.       obj['end'].push(end);
  143.     }
  145.     return obj;
  146.   }
  149.   /**
  150.    * Creates a simulated TimeRanges object from data sent by the cast receiver.
  151.    * @param {?} obj
  152.    * @return {{
  153.    *   length: number,
  154.    *   start: function(number): number,
  155.    *   end: function(number): number
  156.    * }}
  157.    * @private
  158.    */
  159.   static simulateTimeRanges_(obj) {
  160.     return {
  161.       length: obj.length,
  162.       // NOTE: a more complete simulation would throw when |i| was out of range,
  163.       // but for simplicity we will assume a well-behaved application that uses
  164.       // length instead of catch to stop iterating.
  165.       start: (i) => { return obj.start[i]; },
  166.       end: (i) => { return obj.end[i]; },
  167.     };
  168.   }
  171.   /**
  172.    * @param {!Uint8Array} array
  173.    * @return {!Object}
  174.    * @private
  175.    */
  176.   static unpackUint8Array_(array) {
  177.     return {
  178.       '__type__': 'Uint8Array',  // a signal to deserialize
  179.       'entries': Array.from(array),
  180.     };
  181.   }
  184.   /**
  185.    * Creates a Uint8Array object from data sent by the cast receiver.
  186.    * @param {?} obj
  187.    * @return {!Uint8Array}
  188.    * @private
  189.    */
  190.   static makeUint8Array_(obj) {
  191.     return new Uint8Array(/** @type {!Array.<number>} */ (obj['entries']));
  192.   }
  195.   /**
  196.    * @param {!Error} error
  197.    * @return {!Object}
  198.    * @private
  199.    */
  200.   static unpackError_(error) {
  201.     // None of the properties in TypeError are enumerable, but there are some
  202.     // common Error properties we expect.  We also enumerate any enumerable
  203.     // properties and "own" properties of the type, in case there is an Error
  204.     // subtype with additional properties we don't know about in advance.
  205.     const properties = new Set(['name', 'message', 'stack']);
  206.     for (const key in error) {
  207.       properties.add(key);
  208.     }
  209.     for (const key of Object.getOwnPropertyNames(error)) {
  210.       properties.add(key);
  211.     }
  213.     const contents = {};
  214.     for (const key of properties) {
  215.       contents[key] = error[key];
  216.     }
  218.     return {
  219.       '__type__': 'Error',  // a signal to deserialize
  220.       'contents': contents,
  221.     };
  222.   }
  225.   /**
  226.    * Creates an Error object from data sent by the cast receiver.
  227.    * @param {?} obj
  228.    * @return {!Error}
  229.    * @private
  230.    */
  231.   static makeError_(obj) {
  232.     const contents = obj['contents'];
  233.     const error = new Error(contents['message']);
  234.     for (const key in contents) {
  235.       error[key] = contents[key];
  236.     }
  237.     return error;
  238.   }
  239. };
  241. /**
  242.  * HTMLMediaElement events that are proxied while casting.
  243.  * @const {!Array.<string>}
  244.  */
  245. shaka.cast.CastUtils.VideoEvents = [
  246.   'ended',
  247.   'play',
  248.   'playing',
  249.   'pause',
  250.   'pausing',
  251.   'ratechange',
  252.   'seeked',
  253.   'seeking',
  254.   'timeupdate',
  255.   'volumechange',
  256. ];
  259. /**
  260.  * HTMLMediaElement attributes that are proxied while casting.
  261.  * @const {!Array.<string>}
  262.  */
  263. shaka.cast.CastUtils.VideoAttributes = [
  264.   'buffered',
  265.   'currentTime',
  266.   'duration',
  267.   'ended',
  268.   'loop',
  269.   'muted',
  270.   'paused',
  271.   'playbackRate',
  272.   'seeking',
  273.   'videoHeight',
  274.   'videoWidth',
  275.   'volume',
  276. ];
  279. /**
  280.  * HTMLMediaElement attributes that are transferred when casting begins.
  281.  * @const {!Array.<string>}
  282.  */
  283. shaka.cast.CastUtils.VideoInitStateAttributes = [
  284.   'loop',
  285.   'playbackRate',
  286. ];
  289. /**
  290.  * HTMLMediaElement methods with no return value that are proxied while casting.
  291.  * @const {!Array.<string>}
  292.  */
  293. shaka.cast.CastUtils.VideoVoidMethods = [
  294.   'pause',
  295.   'play',
  296. ];
  299. /**
  300.  * Player getter methods that are proxied while casting.
  301.  * The key is the method, the value is the frequency of updates.
  302.  * Frequency 1 translates to every update; frequency 2 to every 2 updates, etc.
  303.  * @const {!Object.<string, number>}
  304.  */
  305. shaka.cast.CastUtils.PlayerGetterMethods = {
  306.   // NOTE: The 'drmInfo' property is not proxied, as it is very large.
  307.   'getAssetUri': 2,
  308.   'getAudioLanguages': 4,
  309.   'getAudioLanguagesAndRoles': 4,
  310.   'getBufferFullness': 1,
  311.   'getBufferedInfo': 2,
  312.   'getExpiration': 2,
  313.   'getKeyStatuses': 2,
  314.   // NOTE: The 'getManifest' property is not proxied, as it is very large.
  315.   // NOTE: The 'getManifestParserFactory' property is not proxied, as it would
  316.   // not serialize.
  317.   'getPlaybackRate': 2,
  318.   'getTextLanguages': 4,
  319.   'getTextLanguagesAndRoles': 4,
  320.   'getImageTracks': 2,
  321.   'getThumbnails': 2,
  322.   'isAudioOnly': 10,
  323.   'isBuffering': 1,
  324.   'isInProgress': 1,
  325.   'isLive': 10,
  326.   'isTextTrackVisible': 1,
  327.   'keySystem': 10,
  328.   'seekRange': 1,
  329.   'getLoadMode': 10,
  330.   'getManifestType': 10,
  331.   'isFullyLoaded': 1,
  332. };
  335. /**
  336.  * Player getter methods with data large enough to be sent in their own update
  337.  * messages, to reduce the size of each message.  The format of this is
  338.  * identical to PlayerGetterMethods.
  339.  * @const {!Object.<string, number>}
  340.  */
  341. shaka.cast.CastUtils.LargePlayerGetterMethods = {
  342.   // NOTE: The 'getSharedConfiguration' property is not proxied as it would
  343.   //       not be possible to share a reference.
  344.   'getConfiguration': 4,
  345.   'getStats': 5,
  346.   'getTextTracks': 2,
  347.   'getVariantTracks': 2,
  348. };
  351. /**
  352.  * Player getter methods that are proxied while casting, but only when casting
  353.  * a livestream.
  354.  * The key is the method, the value is the frequency of updates.
  355.  * Frequency 1 translates to every update; frequency 2 to every 2 updates, etc.
  356.  * @const {!Object.<string, number>}
  357.  */
  358. shaka.cast.CastUtils.PlayerGetterMethodsThatRequireLive = {
  359.   'getPlayheadTimeAsDate': 1,
  360.   'getPresentationStartTimeAsDate': 20,
  361.   'getSegmentAvailabilityDuration': 20,
  362. };
  365. /**
  366.  * Player getter and setter methods that are used to transfer state when casting
  367.  * begins.
  368.  * @const {!Array.<!Array.<string>>}
  369.  */
  370. shaka.cast.CastUtils.PlayerInitState = [
  371.   ['getConfiguration', 'configure'],
  372. ];
  375. /**
  376.  * Player getter and setter methods that are used to transfer state after
  377.  * load() is resolved.
  378.  * @const {!Array.<!Array.<string>>}
  379.  */
  380. shaka.cast.CastUtils.PlayerInitAfterLoadState = [
  381.   ['isTextTrackVisible', 'setTextTrackVisibility'],
  382. ];
  385. /**
  386.  * Player methods with no return value that are proxied while casting.
  387.  * @const {!Array.<string>}
  388.  */
  389. shaka.cast.CastUtils.PlayerVoidMethods = [
  390.   'addChaptersTrack',
  391.   'addTextTrackAsync',
  392.   'addThumbnailsTrack',
  393.   'cancelTrickPlay',
  394.   'configure',
  395.   'getChapters',
  396.   'getChaptersTracks',
  397.   'resetConfiguration',
  398.   'retryStreaming',
  399.   'selectAudioLanguage',
  400.   'selectTextLanguage',
  401.   'selectTextTrack',
  402.   'selectVariantTrack',
  403.   'selectVariantsByLabel',
  404.   'setTextTrackVisibility',
  405.   'trickPlay',
  406.   'updateStartTime',
  407.   'goToLive',
  408. ];
  411. /**
  412.  * Player methods returning a Promise that are proxied while casting.
  413.  * @const {!Array.<string>}
  414.  */
  415. shaka.cast.CastUtils.PlayerPromiseMethods = [
  416.   'attach',
  417.   'attachCanvas',
  418.   'detach',
  419.   // The manifestFactory parameter of load is not supported.
  420.   'load',
  421.   'unload',
  422. ];
  425. /**
  426.  * @typedef {{
  427.  *   video: Object,
  428.  *   player: Object,
  429.  *   manifest: ?string,
  430.  *   startTime: ?number
  431.  * }}
  432.  * @property {Object} video
  433.  *   Dictionary of video properties to be set.
  434.  * @property {Object} player
  435.  *   Dictionary of player setters to be called.
  436.  * @property {?string} manifest
  437.  *   The currently-selected manifest, if present.
  438.  * @property {?number} startTime
  439.  *   The playback start time, if currently playing.
  440.  */
  441. shaka.cast.CastUtils.InitStateType;
  444. /**
  445.  * The namespace for Shaka messages on the cast bus.
  446.  * @const {string}
  447.  */
  448. shaka.cast.CastUtils.SHAKA_MESSAGE_NAMESPACE = 'urn:x-cast:com.google.shaka.v2';
  451. /**
  452.  * The namespace for generic messages on the cast bus.
  453.  * @const {string}
  454.  */
  455. shaka.cast.CastUtils.GENERIC_MESSAGE_NAMESPACE =
  456.     'urn:x-cast:com.google.cast.media';