Source: externs/shaka/manifest_parser.js

  1. /*! @license
  2. * Shaka Player
  3. * Copyright 2016 Google LLC
  4. * SPDX-License-Identifier: Apache-2.0
  5. */
  6. /**
  7. * @externs
  8. */
  9. /**
  10. * Parses media manifests and handles manifest updates.
  11. *
  12. * Given a URI where the initial manifest is found, a parser will request the
  13. * manifest, parse it, and return the resulting Manifest object.
  14. *
  15. * If the manifest requires updates (e.g. for live media), the parser will use
  16. * background timers to update the same Manifest object.
  17. *
  18. * There are many ways for |start| and |stop| to be called. Implementations
  19. * should support all cases:
  20. *
  21. * BASIC
  22. * await parser.start(uri, playerInterface);
  23. * await parser.stop();
  24. *
  25. * INTERRUPTING
  26. * const p = parser.start(uri, playerInterface);
  27. * await parser.stop();
  28. * await p;
  29. *
  30. * |p| should be rejected with an OPERATION_ABORTED error.
  31. *
  32. * STOPPED BEFORE STARTING
  33. * await parser.stop();
  34. *
  35. * @interface
  36. * @exportDoc
  37. */
  38. shaka.extern.ManifestParser = class {
  39. constructor() {}
  40. /**
  41. * Called by the Player to provide an updated configuration any time the
  42. * configuration changes. Will be called at least once before start().
  43. *
  44. * @param {shaka.extern.ManifestConfiguration} config
  45. * @exportDoc
  46. */
  47. configure(config) {}
  48. /**
  49. * Initialize and start the parser. When |start| resolves, it should return
  50. * the initial version of the manifest. |start| will only be called once. If
  51. * |stop| is called while |start| is pending, |start| should reject.
  52. *
  53. * @param {string} uri The URI of the manifest.
  54. * @param {shaka.extern.ManifestParser.PlayerInterface} playerInterface
  55. * The player interface contains the callbacks and members that the parser
  56. * can use to communicate with the player and outside world.
  57. * @return {!Promise.<shaka.extern.Manifest>}
  58. * @exportDoc
  59. */
  60. start(uri, playerInterface) {}
  61. /**
  62. * Tell the parser that it must stop and free all internal resources as soon
  63. * as possible. Only once all internal resources are stopped and freed will
  64. * the promise resolve. Once stopped a parser will not be started again.
  65. *
  66. * The parser should support having |stop| called multiple times and the
  67. * promise should always resolve.
  68. *
  69. * @return {!Promise}
  70. * @exportDoc
  71. */
  72. stop() {}
  73. /**
  74. * Tells the parser to do a manual manifest update. Implementing this is
  75. * optional. This is only called when 'emsg' boxes are present.
  76. * @exportDoc
  77. */
  78. update() {}
  79. /**
  80. * Tells the parser that the expiration time of an EME session has changed.
  81. * Implementing this is optional.
  82. *
  83. * @param {string} sessionId
  84. * @param {number} expiration
  85. * @exportDoc
  86. */
  87. onExpirationUpdated(sessionId, expiration) {}
  88. /**
  89. * Tells the parser that the initial variant has been chosen.
  90. *
  91. * @param {shaka.extern.Variant} variant
  92. * @exportDoc
  93. */
  94. onInitialVariantChosen(variant) {}
  95. /**
  96. * Tells the parser that a location should be banned. This is called on
  97. * retry.
  98. *
  99. * @param {string} uri
  100. * @exportDoc
  101. */
  102. banLocation(uri) {}
  103. };
  104. /**
  105. * @typedef {{
  106. * networkingEngine: !shaka.net.NetworkingEngine,
  107. * filter: function(shaka.extern.Manifest):!Promise,
  108. * makeTextStreamsForClosedCaptions: function(shaka.extern.Manifest),
  109. * onTimelineRegionAdded: function(shaka.extern.TimelineRegionInfo),
  110. * onEvent: function(!Event),
  111. * onError: function(!shaka.util.Error),
  112. * isLowLatencyMode: function():boolean,
  113. * isAutoLowLatencyMode: function():boolean,
  114. * enableLowLatencyMode: function(),
  115. * updateDuration: function(),
  116. * newDrmInfo: function(shaka.extern.Stream),
  117. * onManifestUpdated: function(),
  118. * getBandwidthEstimate: function():number
  119. * }}
  120. *
  121. * @description
  122. * Defines the interface of the Player to the manifest parser. This defines
  123. * fields and callback methods that the parser will use to interact with the
  124. * Player. The callback methods do not need to be called as member functions
  125. * (i.e. they can be called as "free" functions).
  126. *
  127. * @property {!shaka.net.NetworkingEngine} networkingEngine
  128. * The networking engine to use for network requests.
  129. * @property {function(shaka.extern.Manifest):!Promise} filter
  130. * Should be called when new variants or text streams are added to the
  131. * Manifest. Note that this operation is asynchronous.
  132. * @property {function(shaka.extern.Manifest)} makeTextStreamsForClosedCaptions
  133. * A callback that adds text streams to represent the closed captions of the
  134. * video streams in the Manifest. Should be called whenever new video streams
  135. * are added to the Manifest.
  136. * @property {function(shaka.extern.TimelineRegionInfo)} onTimelineRegionAdded
  137. * Should be called when a new timeline region is added.
  138. * @property {function(!Event)} onEvent
  139. * Should be called to raise events.
  140. * @property {function(!shaka.util.Error)} onError
  141. * Should be called when an error occurs.
  142. * @property {function():boolean} isLowLatencyMode
  143. * Return true if low latency streaming mode is enabled.
  144. * @property {function():boolean} isAutoLowLatencyMode
  145. * Return true if auto low latency streaming mode is enabled.
  146. * @property {function()} enableLowLatencyMode
  147. * Enable low latency streaming mode.
  148. * @property {function()} updateDuration
  149. * Update the presentation duration based on PresentationTimeline.
  150. * @property {function(shaka.extern.Stream)} newDrmInfo
  151. * Inform the player of new DRM info that needs to be processed for the given
  152. * stream.
  153. * @property {function()} onManifestUpdated
  154. * Should be called when the manifest is updated.
  155. * @property {function():number} getBandwidthEstimate
  156. * Get the estimated bandwidth in bits per second.
  157. * @exportDoc
  158. */
  159. shaka.extern.ManifestParser.PlayerInterface;
  160. /**
  161. * A factory for creating the manifest parser. This function is registered with
  162. * shaka.media.ManifestParser to create parser instances.
  163. *
  164. * @typedef {function():!shaka.extern.ManifestParser}
  165. * @exportDoc
  166. */
  167. shaka.extern.ManifestParser.Factory;