Source: externs/shaka/manifest_parser.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  19. /**
  20.  * @externs
  21.  */
  24. /**
  25.  * Parses media manifests and handles manifest updates.
  26.  *
  27.  * Given a URI where the initial manifest is found, a parser will request the
  28.  * manifest, parse it, and return the resulting Manifest object.
  29.  *
  30.  * If the manifest requires updates (e.g. for live media), the parser will use
  31.  * background timers to update the same Manifest object.
  32.  *
  33.  * There are many ways for |start| and |stop| to be called. Implementations
  34.  * should support all cases:
  35.  *
  36.  *  BASIC
  37.  *    await parser.start(uri, playerInterface);
  38.  *    await parser.stop();
  39.  *
  40.  *  INTERRUPTING
  41.  *    const p = parser.start(uri, playerInterface);
  42.  *    await parser.stop();
  43.  *    await p;
  44.  *
  45.  *    |p| should be rejected with an OPERATION_ABORTED error.
  46.  *
  47.  *  STOPPED BEFORE STARTING
  48.  *    await parser.stop();
  49.  *
  50.  * @interface
  51.  * @exportDoc
  52.  */
  53. shaka.extern.ManifestParser = function() {};
  56. /**
  57.  * @typedef {{
  58.  *   networkingEngine: !shaka.net.NetworkingEngine,
  59.  *   filterNewPeriod: function(shaka.extern.Period),
  60.  *   filterAllPeriods: function(!Array.<!shaka.extern.Period>),
  61.  *   onTimelineRegionAdded: function(shaka.extern.TimelineRegionInfo),
  62.  *   onEvent: function(!Event),
  63.  *   onError: function(!shaka.util.Error)
  64.  * }}
  65.  *
  66.  * @description
  67.  * Defines the interface of the Player to the manifest parser.  This defines
  68.  * fields and callback methods that the parser will use to interact with the
  69.  * Player.  The callback methods do not need to be called as member functions
  70.  * (i.e. they can be called as "free" functions).
  71.  *
  72.  * @property {!shaka.net.NetworkingEngine} networkingEngine
  73.  *   The networking engine to use for network requests.
  74.  * @property {function(shaka.extern.Period)} filterNewPeriod
  75.  *   Should be called on a new Period so that it can be filtered.
  76.  * @property {function(!Array.<!shaka.extern.Period>)} filterAllPeriods
  77.  *   Should be called on all Periods so that they can be filtered.
  78.  * @property {function(shaka.extern.TimelineRegionInfo)} onTimelineRegionAdded
  79.  *   Should be called when a new timeline region is added.
  80.  * @property {function(!Event)} onEvent
  81.  *   Should be called to raise events.
  82.  * @property {function(!shaka.util.Error)} onError
  83.  *   Should be called when an error occurs.
  84.  * @exportDoc
  85.  */
  86. shaka.extern.ManifestParser.PlayerInterface;
  89. /**
  90.  * A factory for creating the manifest parser.  This will be called with 'new'.
  91.  * This function is registered with shaka.media.ManifestParser to create parser
  92.  * instances.
  93.  *
  94.  * @typedef {function(new:shaka.extern.ManifestParser)}
  95.  * @exportDoc
  96.  */
  97. shaka.extern.ManifestParser.Factory;
  100. /**
  101.  * Called by the Player to provide an updated configuration any time the
  102.  * configuration changes.  Will be called at least once before start().
  103.  *
  104.  * @param {shaka.extern.ManifestConfiguration} config
  105.  * @exportDoc
  106.  */
  107. shaka.extern.ManifestParser.prototype.configure = function(config) {};
  110. /**
  111.  * Initialize and start the parser. When |start| resolves, it should return the
  112.  * initial version of the manifest. |start| will only be called once. If |stop|
  113.  * is called while |start| is pending, |start| should reject.
  114.  *
  115.  * @param {string} uri The URI of the manifest.
  116.  * @param {shaka.extern.ManifestParser.PlayerInterface} playerInterface
  117.  *    The player interface contains the callbacks and members that the parser
  118.  *    can use to communicate with the player and outside world.
  119.  * @return {!Promise.<shaka.extern.Manifest>}
  120.  * @exportDoc
  121.  */
  122. shaka.extern.ManifestParser.prototype.start = function(uri, playerInterface) {};
  125. /**
  126.  * Tell the parser that it must stop and free all internal resources as soon as
  127.  * possible. Only once all internal resources are stopped and freed will the
  128.  * promise resolve. Once stopped a parser will not be started again.
  129.  *
  130.  * The parser should support having |stop| called multiple times and the promise
  131.  * should always resolve.
  132.  *
  133.  * @return {!Promise}
  134.  * @exportDoc
  135.  */
  136. shaka.extern.ManifestParser.prototype.stop = function() {};
  139. /**
  140.  * Tells the parser to do a manual manifest update.  Implementing this is
  141.  * optional.  This is only called when 'emsg' boxes are present.
  142.  * @exportDoc
  143.  */
  144. shaka.extern.ManifestParser.prototype.update = function() {};
  147. /**
  148.  * Tells the parser that the expiration time of an EME session has changed.
  149.  * Implementing this is optional.
  150.  *
  151.  * @param {string} sessionId
  152.  * @param {number} expiration
  153.  * @exportDoc
  154.  */
  155. shaka.extern.ManifestParser.prototype.onExpirationUpdated = function(
  156.     sessionId, expiration) {};