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 {!Map<string, number>}
  304.  */
  305. shaka.cast.CastUtils.PlayerGetterMethods = new Map()
  306.     // NOTE: The 'drmInfo' property is not proxied, as it is very large.
  307.     .set('getAssetUri', 2)
  308.     .set('getAudioLanguages', 4)
  309.     .set('getAudioLanguagesAndRoles', 4)
  310.     .set('getBufferFullness', 1)
  311.     .set('getBufferedInfo', 2)
  312.     .set('getExpiration', 2)
  313.     .set('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.     .set('getPlaybackRate', 2)
  318.     .set('getTextLanguages', 4)
  319.     .set('getTextLanguagesAndRoles', 4)
  320.     .set('getImageTracks', 2)
  321.     .set('getThumbnails', 2)
  322.     .set('isAudioOnly', 10)
  323.     .set('isBuffering', 1)
  324.     .set('isInProgress', 1)
  325.     .set('isLive', 10)
  326.     .set('isTextTrackVisible', 1)
  327.     .set('keySystem', 10)
  328.     .set('seekRange', 1)
  329.     .set('getLoadMode', 10)
  330.     .set('getManifestType', 10)
  331.     .set('isFullyLoaded', 1)
  332.     .set('isEnded', 1);
  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 {!Map<string, number>}
  340.  */
  341. shaka.cast.CastUtils.LargePlayerGetterMethods = new Map()
  342.     // NOTE: The 'getSharedConfiguration' property is not proxied as it would
  343.     //       not be possible to share a reference.
  344.     .set('getConfiguration', 4)
  345.     .set('getConfigurationForLowLatency', 4)
  346.     .set('getStats', 5)
  347.     .set('getAudioTracks', 2)
  348.     .set('getTextTracks', 2)
  349.     .set('getVariantTracks', 2);
  352. /**
  353.  * Player getter methods that are proxied while casting, but only when casting
  354.  * a livestream.
  355.  * The key is the method, the value is the frequency of updates.
  356.  * Frequency 1 translates to every update; frequency 2 to every 2 updates, etc.
  357.  * @const {!Map<string, number>}
  358.  */
  359. shaka.cast.CastUtils.PlayerGetterMethodsThatRequireLive = new Map()
  360.     .set('getPlayheadTimeAsDate', 1)
  361.     .set('getPresentationStartTimeAsDate', 20)
  362.     .set('getSegmentAvailabilityDuration', 20);
  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.   [
  372.     'getConfiguration',
  373.     'configure',
  374.     'getConfigurationForLowLatency',
  375.     'configurationForLowLatency',
  376.   ],
  377. ];
  380. /**
  381.  * Player getter and setter methods that are used to transfer state after
  382.  * load() is resolved.
  383.  * @const {!Array<!Array<string>>}
  384.  */
  385. shaka.cast.CastUtils.PlayerInitAfterLoadState = [
  386.   ['isTextTrackVisible', 'setTextTrackVisibility'],
  387. ];
  390. /**
  391.  * Player methods with no return value that are proxied while casting.
  392.  * @const {!Array<string>}
  393.  */
  394. shaka.cast.CastUtils.PlayerVoidMethods = [
  395.   'addChaptersTrack',
  396.   'addTextTrackAsync',
  397.   'addThumbnailsTrack',
  398.   'cancelTrickPlay',
  399.   'configure',
  400.   'configurationForLowLatency',
  401.   'getChapters',
  402.   'getChaptersTracks',
  403.   'resetConfiguration',
  404.   'retryStreaming',
  405.   'selectAudioLanguage',
  406.   'selectAudioTrack',
  407.   'selectTextLanguage',
  408.   'selectTextTrack',
  409.   'selectVariantTrack',
  410.   'selectVariantsByLabel',
  411.   'setTextTrackVisibility',
  412.   'trickPlay',
  413.   'updateStartTime',
  414.   'goToLive',
  415. ];
  418. /**
  419.  * Player methods returning a Promise that are proxied while casting.
  420.  * @const {!Array<string>}
  421.  */
  422. shaka.cast.CastUtils.PlayerPromiseMethods = [
  423.   'attach',
  424.   'attachCanvas',
  425.   'detach',
  426.   // The manifestFactory parameter of load is not supported.
  427.   'load',
  428.   'unload',
  429. ];
  432. /**
  433.  * @typedef {{
  434.  *   video: Object,
  435.  *   player: Object,
  436.  *   manifest: ?string,
  437.  *   startTime: ?number
  438.  * }}
  439.  * @property {Object} video
  440.  *   Dictionary of video properties to be set.
  441.  * @property {Object} player
  442.  *   Dictionary of player setters to be called.
  443.  * @property {?string} manifest
  444.  *   The currently-selected manifest, if present.
  445.  * @property {?number} startTime
  446.  *   The playback start time, if currently playing.
  447.  */
  448. shaka.cast.CastUtils.InitStateType;
  451. /**
  452.  * The namespace for Shaka messages on the cast bus.
  453.  * @const {string}
  454.  */
  455. shaka.cast.CastUtils.SHAKA_MESSAGE_NAMESPACE = 'urn:x-cast:com.google.shaka.v2';
  458. /**
  459.  * The namespace for generic messages on the cast bus.
  460.  * @const {string}
  461.  */
  462. shaka.cast.CastUtils.GENERIC_MESSAGE_NAMESPACE =
  463.     'urn:x-cast:com.google.cast.media';