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 (value instanceof Uint8Array) {
  70.         // Some of our code cares about Uint8Arrays actually being Uint8Arrays,
  71.         // so this gives them special treatment.
  72.         return shaka.cast.CastUtils.unpackUint8Array_(value);
  73.       }
  75.       if (typeof value == 'number') {
  76.         // NaN and infinity cannot be represented directly in JSON.
  77.         if (isNaN(value)) {
  78.           return 'NaN';
  79.         }
  80.         if (isFinite(value)) {
  81.           return value;
  82.         }
  83.         if (value < 0) {
  84.           return '-Infinity';
  85.         }
  86.         return 'Infinity';
  87.       }
  89.       return value;
  90.     });
  91.   }
  94.   /**
  95.    * Deserialize JSON using our special encodings.
  96.    * @param {string} str
  97.    * @return {?}
  98.    */
  99.   static deserialize(str) {
  100.     return JSON.parse(str, (key, value) => {
  101.       if (value == 'NaN') {
  102.         return NaN;
  103.       } else if (value == '-Infinity') {
  104.         return -Infinity;
  105.       } else if (value == 'Infinity') {
  106.         return Infinity;
  107.       } else if (value && typeof value == 'object' &&
  108.                  value['__type__'] == 'TimeRanges') {
  109.         // TimeRanges objects have been unpacked and sent as plain data.
  110.         // Simulate the original TimeRanges object.
  111.         return shaka.cast.CastUtils.simulateTimeRanges_(value);
  112.       } else if (value && typeof value == 'object' &&
  113.                  value['__type__'] == 'Uint8Array') {
  114.         return shaka.cast.CastUtils.makeUint8Array_(value);
  115.       } else if (value && typeof value == 'object' &&
  116.                  value['__type__'] == 'Error') {
  117.         return shaka.cast.CastUtils.makeError_(value);
  118.       }
  119.       return value;
  120.     });
  121.   }
  124.   /**
  125.    * @param {!TimeRanges} ranges
  126.    * @return {!Object}
  127.    * @private
  128.    */
  129.   static unpackTimeRanges_(ranges) {
  130.     const obj = {
  131.       '__type__': 'TimeRanges',  // a signal to deserialize
  132.       'length': ranges.length,
  133.       'start': [],
  134.       'end': [],
  135.     };
  137.     const TimeRangesUtils = shaka.media.TimeRangesUtils;
  138.     for (const {start, end} of TimeRangesUtils.getBufferedInfo(ranges)) {
  139.       obj['start'].push(start);
  140.       obj['end'].push(end);
  141.     }
  143.     return obj;
  144.   }
  147.   /**
  148.    * Creates a simulated TimeRanges object from data sent by the cast receiver.
  149.    * @param {?} obj
  150.    * @return {{
  151.    *   length: number,
  152.    *   start: function(number): number,
  153.    *   end: function(number): number
  154.    * }}
  155.    * @private
  156.    */
  157.   static simulateTimeRanges_(obj) {
  158.     return {
  159.       length: obj.length,
  160.       // NOTE: a more complete simulation would throw when |i| was out of range,
  161.       // but for simplicity we will assume a well-behaved application that uses
  162.       // length instead of catch to stop iterating.
  163.       start: (i) => { return obj.start[i]; },
  164.       end: (i) => { return obj.end[i]; },
  165.     };
  166.   }
  169.   /**
  170.    * @param {!Uint8Array} array
  171.    * @return {!Object}
  172.    * @private
  173.    */
  174.   static unpackUint8Array_(array) {
  175.     return {
  176.       '__type__': 'Uint8Array',  // a signal to deserialize
  177.       'entries': Array.from(array),
  178.     };
  179.   }
  182.   /**
  183.    * Creates a Uint8Array object from data sent by the cast receiver.
  184.    * @param {?} obj
  185.    * @return {!Uint8Array}
  186.    * @private
  187.    */
  188.   static makeUint8Array_(obj) {
  189.     return new Uint8Array(/** @type {!Array.<number>} */ (obj['entries']));
  190.   }
  193.   /**
  194.    * @param {!Error} error
  195.    * @return {!Object}
  196.    * @private
  197.    */
  198.   static unpackError_(error) {
  199.     // None of the properties in TypeError are enumerable, but there are some
  200.     // common Error properties we expect.  We also enumerate any enumerable
  201.     // properties and "own" properties of the type, in case there is an Error
  202.     // subtype with additional properties we don't know about in advance.
  203.     const properties = new Set(['name', 'message', 'stack']);
  204.     for (const key in error) {
  205.       properties.add(key);
  206.     }
  207.     for (const key of Object.getOwnPropertyNames(error)) {
  208.       properties.add(key);
  209.     }
  211.     const contents = {};
  212.     for (const key of properties) {
  213.       contents[key] = error[key];
  214.     }
  216.     return {
  217.       '__type__': 'Error',  // a signal to deserialize
  218.       'contents': contents,
  219.     };
  220.   }
  223.   /**
  224.    * Creates an Error object from data sent by the cast receiver.
  225.    * @param {?} obj
  226.    * @return {!Error}
  227.    * @private
  228.    */
  229.   static makeError_(obj) {
  230.     const contents = obj['contents'];
  231.     const error = new Error(contents['message']);
  232.     for (const key in contents) {
  233.       error[key] = contents[key];
  234.     }
  235.     return error;
  236.   }
  237. };
  239. /**
  240.  * HTMLMediaElement events that are proxied while casting.
  241.  * @const {!Array.<string>}
  242.  */
  243. shaka.cast.CastUtils.VideoEvents = [
  244.   'ended',
  245.   'play',
  246.   'playing',
  247.   'pause',
  248.   'pausing',
  249.   'ratechange',
  250.   'seeked',
  251.   'seeking',
  252.   'timeupdate',
  253.   'volumechange',
  254. ];
  257. /**
  258.  * HTMLMediaElement attributes that are proxied while casting.
  259.  * @const {!Array.<string>}
  260.  */
  261. shaka.cast.CastUtils.VideoAttributes = [
  262.   'buffered',
  263.   'currentTime',
  264.   'duration',
  265.   'ended',
  266.   'loop',
  267.   'muted',
  268.   'paused',
  269.   'playbackRate',
  270.   'seeking',
  271.   'videoHeight',
  272.   'videoWidth',
  273.   'volume',
  274. ];
  277. /**
  278.  * HTMLMediaElement attributes that are transferred when casting begins.
  279.  * @const {!Array.<string>}
  280.  */
  281. shaka.cast.CastUtils.VideoInitStateAttributes = [
  282.   'loop',
  283.   'playbackRate',
  284. ];
  287. /**
  288.  * HTMLMediaElement methods with no return value that are proxied while casting.
  289.  * @const {!Array.<string>}
  290.  */
  291. shaka.cast.CastUtils.VideoVoidMethods = [
  292.   'pause',
  293.   'play',
  294. ];
  297. /**
  298.  * Player getter methods that are proxied while casting.
  299.  * The key is the method, the value is the frequency of updates.
  300.  * Frequency 1 translates to every update; frequency 2 to every 2 updates, etc.
  301.  * @const {!Object.<string, number>}
  302.  */
  303. shaka.cast.CastUtils.PlayerGetterMethods = {
  304.   // NOTE: The 'drmInfo' property is not proxied, as it is very large.
  305.   'getAssetUri': 2,
  306.   'getAudioLanguages': 4,
  307.   'getAudioLanguagesAndRoles': 4,
  308.   'getBufferFullness': 1,
  309.   'getBufferedInfo': 2,
  310.   'getExpiration': 2,
  311.   'getKeyStatuses': 2,
  312.   // NOTE: The 'getManifest' property is not proxied, as it is very large.
  313.   // NOTE: The 'getManifestParserFactory' property is not proxied, as it would
  314.   // not serialize.
  315.   'getPlaybackRate': 2,
  316.   'getTextLanguages': 4,
  317.   'getTextLanguagesAndRoles': 4,
  318.   'getImageTracks': 2,
  319.   'getThumbnails': 2,
  320.   'isAudioOnly': 10,
  321.   'isBuffering': 1,
  322.   'isInProgress': 1,
  323.   'isLive': 10,
  324.   'isTextTrackVisible': 1,
  325.   'keySystem': 10,
  326.   'seekRange': 1,
  327.   'getLoadMode': 10,
  328.   'getManifestType': 10,
  329. };
  332. /**
  333.  * Player getter methods with data large enough to be sent in their own update
  334.  * messages, to reduce the size of each message.  The format of this is
  335.  * identical to PlayerGetterMethods.
  336.  * @const {!Object.<string, number>}
  337.  */
  338. shaka.cast.CastUtils.LargePlayerGetterMethods = {
  339.   // NOTE: The 'getSharedConfiguration' property is not proxied as it would
  340.   //       not be possible to share a reference.
  341.   'getConfiguration': 4,
  342.   'getStats': 5,
  343.   'getTextTracks': 2,
  344.   'getVariantTracks': 2,
  345. };
  348. /**
  349.  * Player getter methods that are proxied while casting, but only when casting
  350.  * a livestream.
  351.  * The key is the method, the value is the frequency of updates.
  352.  * Frequency 1 translates to every update; frequency 2 to every 2 updates, etc.
  353.  * @const {!Object.<string, number>}
  354.  */
  355. shaka.cast.CastUtils.PlayerGetterMethodsThatRequireLive = {
  356.   'getPlayheadTimeAsDate': 1,
  357.   'getPresentationStartTimeAsDate': 20,
  358.   'getSegmentAvailabilityDuration': 20,
  359. };
  362. /**
  363.  * Player getter and setter methods that are used to transfer state when casting
  364.  * begins.
  365.  * @const {!Array.<!Array.<string>>}
  366.  */
  367. shaka.cast.CastUtils.PlayerInitState = [
  368.   ['getConfiguration', 'configure'],
  369. ];
  372. /**
  373.  * Player getter and setter methods that are used to transfer state after
  374.  * load() is resolved.
  375.  * @const {!Array.<!Array.<string>>}
  376.  */
  377. shaka.cast.CastUtils.PlayerInitAfterLoadState = [
  378.   ['isTextTrackVisible', 'setTextTrackVisibility'],
  379. ];
  382. /**
  383.  * Player methods with no return value that are proxied while casting.
  384.  * @const {!Array.<string>}
  385.  */
  386. shaka.cast.CastUtils.PlayerVoidMethods = [
  387.   'addChaptersTrack',
  388.   'addTextTrackAsync',
  389.   'addThumbnailsTrack',
  390.   'cancelTrickPlay',
  391.   'configure',
  392.   'getChapters',
  393.   'getChaptersTracks',
  394.   'resetConfiguration',
  395.   'retryStreaming',
  396.   'selectAudioLanguage',
  397.   'selectTextLanguage',
  398.   'selectTextTrack',
  399.   'selectVariantTrack',
  400.   'selectVariantsByLabel',
  401.   'setTextTrackVisibility',
  402.   'trickPlay',
  403.   'updateStartTime',
  404.   'goToLive',
  405. ];
  408. /**
  409.  * Player methods returning a Promise that are proxied while casting.
  410.  * @const {!Array.<string>}
  411.  */
  412. shaka.cast.CastUtils.PlayerPromiseMethods = [
  413.   'attach',
  414.   'attachCanvas',
  415.   'detach',
  416.   // The manifestFactory parameter of load is not supported.
  417.   'load',
  418.   'unload',
  419. ];
  422. /**
  423.  * @typedef {{
  424.  *   video: Object,
  425.  *   player: Object,
  426.  *   manifest: ?string,
  427.  *   startTime: ?number
  428.  * }}
  429.  * @property {Object} video
  430.  *   Dictionary of video properties to be set.
  431.  * @property {Object} player
  432.  *   Dictionary of player setters to be called.
  433.  * @property {?string} manifest
  434.  *   The currently-selected manifest, if present.
  435.  * @property {?number} startTime
  436.  *   The playback start time, if currently playing.
  437.  */
  438. shaka.cast.CastUtils.InitStateType;
  441. /**
  442.  * The namespace for Shaka messages on the cast bus.
  443.  * @const {string}
  444.  */
  445. shaka.cast.CastUtils.SHAKA_MESSAGE_NAMESPACE = 'urn:x-cast:com.google.shaka.v2';
  448. /**
  449.  * The namespace for generic messages on the cast bus.
  450.  * @const {string}
  451.  */
  452. shaka.cast.CastUtils.GENERIC_MESSAGE_NAMESPACE =
  453.     'urn:x-cast:com.google.cast.media';