Source: externs/shaka/player.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. */
  17. /** @externs */
  18. /**
  19. * @typedef {{
  20. * timestamp: number,
  21. * id: number,
  22. * type: string,
  23. * fromAdaptation: boolean,
  24. * bandwidth: ?number
  25. * }}
  26. *
  27. * @property {number} timestamp
  28. * The timestamp the choice was made, in seconds since 1970
  29. * (i.e. Date.now() / 1000).
  30. * @property {number} id
  31. * The id of the track that was chosen.
  32. * @property {string} type
  33. * The type of track chosen ('variant' or 'text')
  34. * @property {boolean} fromAdaptation
  35. * True if the choice was made by AbrManager for adaptation; false if it
  36. * was made by the application through selectTrack.
  37. * @property {?number} bandwidth
  38. * The bandwidth of the chosen track (null for text).
  39. * @exportDoc
  40. */
  41. shakaExtern.TrackChoice;
  42. /**
  43. * @typedef {{
  44. * timestamp: number,
  45. * state: string,
  46. * duration: number
  47. * }}
  48. *
  49. * @property {number} timestamp
  50. * The timestamp the state was entered, in seconds since 1970
  51. * (i.e. Date.now() / 1000).
  52. * @property {string} state
  53. * The state the player entered. This could be 'buffering', 'playing',
  54. * 'paused', or 'ended'.
  55. * @property {number} duration
  56. * The number of seconds the player was in this state. If this is the last
  57. * entry in the list, the player is still in this state, so the duration will
  58. * continue to increase.
  59. * @exportDoc
  60. */
  61. shakaExtern.StateChange;
  62. /**
  63. * @typedef {{
  64. * width: number,
  65. * height: number,
  66. * streamBandwidth: number,
  67. *
  68. * decodedFrames: number,
  69. * droppedFrames: number,
  70. * estimatedBandwidth: number,
  71. *
  72. * loadLatency: number,
  73. * playTime: number,
  74. * bufferingTime: number,
  75. *
  76. * switchHistory: !Array.<shakaExtern.TrackChoice>,
  77. * stateHistory: !Array.<shakaExtern.StateChange>
  78. * }}
  79. *
  80. * @description
  81. * Contains statistics and information about the current state of the player.
  82. * This is meant for applications that want to log quality-of-experience (QoE)
  83. * or other stats. These values will reset when load() is called again.
  84. *
  85. * @property {number} width
  86. * The width of the current video track.
  87. * @property {number} height
  88. * The height of the current video track.
  89. * @property {number} streamBandwidth
  90. * The bandwidth required for the current streams (total, in bit/sec).
  91. *
  92. * @property {number} decodedFrames
  93. * The total number of frames decoded by the Player. This may be NaN if this
  94. * is not supported by the browser.
  95. * @property {number} droppedFrames
  96. * The total number of frames dropped by the Player. This may be NaN if this
  97. * is not supported by the browser.
  98. * @property {number} estimatedBandwidth
  99. * The current estimated network bandwidth (in bit/sec).
  100. *
  101. * @property {number} loadLatency
  102. * This is the number of seconds it took for the video element to have enough
  103. * data to begin playback. This is measured from the time load() is called to
  104. * the time the 'loadeddata' event is fired by the media element.
  105. * @property {number} playTime
  106. * The total time spent in a playing state in seconds.
  107. * @property {number} bufferingTime
  108. * The total time spent in a buffering state in seconds.
  109. *
  110. * @property {!Array.<shakaExtern.TrackChoice>} switchHistory
  111. * A history of the stream changes.
  112. * @property {!Array.<shakaExtern.StateChange>} stateHistory
  113. * A history of the state changes.
  114. * @exportDoc
  115. */
  116. shakaExtern.Stats;
  117. /**
  118. * @typedef {{
  119. * id: number,
  120. * active: boolean,
  121. *
  122. * type: string,
  123. * bandwidth: number,
  124. *
  125. * language: string,
  126. * label: ?string,
  127. * kind: ?string,
  128. * width: ?number,
  129. * height: ?number,
  130. * frameRate: ?number,
  131. * mimeType: ?string,
  132. * codecs: ?string,
  133. * audioCodec: ?string,
  134. * videoCodec: ?string,
  135. * primary: boolean,
  136. * roles: !Array.<string>,
  137. * videoId: ?number,
  138. * audioId: ?number,
  139. * channelsCount: ?number,
  140. * audioBandwidth: ?number,
  141. * videoBandwidth: ?number
  142. * }}
  143. *
  144. * @description
  145. * An object describing a media track. This object should be treated as
  146. * read-only as changing any values does not have any effect. This is the
  147. * public view of an audio/video paring (variant type) or text track (text
  148. * type).
  149. *
  150. * @property {number} id
  151. * The unique ID of the track.
  152. * @property {boolean} active
  153. * If true, this is the track is being streamed (another track may be
  154. * visible/audible in the buffer).
  155. *
  156. * @property {string} type
  157. * The type of track, either 'variant' or 'text'.
  158. * @property {number} bandwidth
  159. * The bandwidth required to play the track, in bits/sec.
  160. *
  161. * @property {string} language
  162. * The language of the track, or 'und' if not given. This is the exact
  163. * value provided in the manifest; it may need to be normalized.
  164. * @property {?string} label
  165. * The track label, unique text that should describe the track.
  166. * @property {?string} kind
  167. * (only for text tracks) The kind of text track, either 'caption' or
  168. * 'subtitle'.
  169. * @property {?number} width
  170. * The video width provided in the manifest, if present.
  171. * @property {?number} height
  172. * The video height provided in the manifest, if present.
  173. * @property {?number} frameRate
  174. * The video framerate provided in the manifest, if present.
  175. * @property {?string} mimeType
  176. * The MIME type of the content provided in the manifest.
  177. * @property {?string} codecs
  178. * The audio/video codecs string provided in the manifest, if present.
  179. * @property {?string} audioCodec
  180. * The audio codecs string provided in the manifest, if present.
  181. * @property {?string} videoCodec
  182. * The video codecs string provided in the manifest, if present.
  183. * @property {boolean} primary
  184. * True indicates that this in the primary language for the content.
  185. * This flag is based on signals from the manifest.
  186. * This can be a useful hint about which language should be the default, and
  187. * indicates which track Shaka will use when the user's language preference
  188. * cannot be satisfied.
  189. * @property {!Array.<string>} roles
  190. * The roles of the track, e.g. 'main', 'caption', or 'commentary'.
  191. * @property {?number} videoId
  192. * (only for variant tracks) The video stream id.
  193. * @property {?number} audioId
  194. * (only for variant tracks) The audio stream id.
  195. * @property {?number} channelsCount
  196. * The count of the audio track channels.
  197. * @property {?number} audioBandwidth
  198. * (only for variant tracks) The audio stream's bandwidth if known.
  199. * @property {?number} videoBandwidth
  200. * (only for variant tracks) The video stream's bandwidth if known.
  201. * @exportDoc
  202. */
  203. shakaExtern.Track;
  204. /**
  205. * @typedef {{
  206. * minWidth: number,
  207. * maxWidth: number,
  208. * minHeight: number,
  209. * maxHeight: number,
  210. * minPixels: number,
  211. * maxPixels: number,
  212. *
  213. * minBandwidth: number,
  214. * maxBandwidth: number
  215. * }}
  216. *
  217. * @description
  218. * An object describing application restrictions on what tracks can play. All
  219. * restrictions must be fulfilled for a track to be playable. If a track does
  220. * not meet the restrictions, it will not appear in the track list and it will
  221. * not be played.
  222. *
  223. * @property {number} minWidth
  224. * The minimum width of a video track, in pixels.
  225. * @property {number} maxWidth
  226. * The maximum width of a video track, in pixels.
  227. * @property {number} minHeight
  228. * The minimum height of a video track, in pixels.
  229. * @property {number} maxHeight
  230. * The maximum height of a video track, in pixels.
  231. * @property {number} minPixels
  232. * The minimum number of total pixels in a video track (i.e. width * height).
  233. * @property {number} maxPixels
  234. * The maximum number of total pixels in a video track (i.e. width * height).
  235. *
  236. * @property {number} minBandwidth
  237. * The minimum bandwidth of a variant track, in bit/sec.
  238. * @property {number} maxBandwidth
  239. * The maximum bandwidth of a variant track, in bit/sec.
  240. * @exportDoc
  241. */
  242. shakaExtern.Restrictions;
  243. /**
  244. * @typedef {{
  245. * persistentState: boolean
  246. * }}
  247. *
  248. * @property {boolean} persistentState
  249. * Whether this key system supports persistent state.
  250. */
  251. shakaExtern.DrmSupportType;
  252. /**
  253. * @typedef {{
  254. * manifest: !Object.<string, boolean>,
  255. * media: !Object.<string, boolean>,
  256. * drm: !Object.<string, ?shakaExtern.DrmSupportType>
  257. * }}
  258. *
  259. * @description
  260. * An object detailing browser support for various features.
  261. *
  262. * @property {!Object.<string, boolean>} manifest
  263. * A map of supported manifest types.
  264. * The keys are manifest MIME types and file extensions.
  265. * @property {!Object.<string, boolean>} media
  266. * A map of supported media types.
  267. * The keys are media MIME types.
  268. * @property {!Object.<string, ?shakaExtern.DrmSupportType>} drm
  269. * A map of supported key systems.
  270. * The keys are the key system names. The value is null if it is not
  271. * supported. Key systems not probed will not be in this dictionary.
  272. *
  273. * @exportDoc
  274. */
  275. shakaExtern.SupportType;
  276. /**
  277. * @typedef {{
  278. * schemeIdUri: string,
  279. * value: string,
  280. * startTime: number,
  281. * endTime: number,
  282. * id: string,
  283. * eventElement: Element
  284. * }}
  285. *
  286. * @description
  287. * Contains information about a region of the timeline that will cause an event
  288. * to be raised when the playhead enters or exits it. In DASH this is the
  289. * EventStream element.
  290. *
  291. * @property {string} schemeIdUri
  292. * Identifies the message scheme.
  293. * @property {string} value
  294. * Specifies the value for the region.
  295. * @property {number} startTime
  296. * The presentation time (in seconds) that the region should start.
  297. * @property {number} endTime
  298. * The presentation time (in seconds) that the region should end.
  299. * @property {string} id
  300. * Specifies an identifier for this instance of the region.
  301. * @property {Element} eventElement
  302. * The XML element that defines the Event.
  303. */
  304. shakaExtern.TimelineRegionInfo;
  305. /**
  306. * @typedef {{
  307. * schemeIdUri: string,
  308. * value: string,
  309. * startTime: number,
  310. * endTime: number,
  311. * timescale: number,
  312. * presentationTimeDelta: number,
  313. * eventDuration: number,
  314. * id: number,
  315. * messageData: Uint8Array
  316. * }}
  317. *
  318. * @description
  319. * Contains information about an EMSG MP4 box.
  320. *
  321. * @property {string} schemeIdUri
  322. * Identifies the message scheme.
  323. * @property {string} value
  324. * Specifies the value for the event.
  325. * @property {number} startTime
  326. * The time that the event starts (in presentation time).
  327. * @property {number} endTime
  328. * The time that the event ends (in presentation time).
  329. * @property {number} timescale
  330. * Provides the timescale, in ticks per second.
  331. * @property {number} presentationTimeDelta
  332. * The offset that the event starts, relative to the start of the segment
  333. * this is contained in (in units of timescale).
  334. * @property {number} eventDuration
  335. * The duration of the event (in units of timescale).
  336. * @property {number} id
  337. * A field identifying this instance of the message.
  338. * @property {Uint8Array} messageData
  339. * Body of the message.
  340. * @exportDoc
  341. */
  342. shakaExtern.EmsgInfo;
  343. /**
  344. * @typedef {function(!Element):Array.<shakaExtern.DrmInfo>}
  345. * @see shakaExtern.DashManifestConfiguration
  346. * @exportDoc
  347. */
  348. shakaExtern.DashContentProtectionCallback;
  349. /**
  350. * @typedef {{
  351. * distinctiveIdentifierRequired: boolean,
  352. * persistentStateRequired: boolean,
  353. * videoRobustness: string,
  354. * audioRobustness: string,
  355. * serverCertificate: Uint8Array
  356. * }}
  357. *
  358. * @property {boolean} distinctiveIdentifierRequired
  359. * <i>Defaults to false.</i> <br>
  360. * True if the application requires the key system to support distinctive
  361. * identifiers.
  362. * @property {boolean} persistentStateRequired
  363. * <i>Defaults to false.</i> <br>
  364. * True if the application requires the key system to support persistent
  365. * state, e.g., for persistent license storage.
  366. * @property {string} videoRobustness
  367. * A key-system-specific string that specifies a required security level for
  368. * video.
  369. * <i>Defaults to '', i.e., no specific robustness required.</i> <br>
  370. * @property {string} audioRobustness
  371. * A key-system-specific string that specifies a required security level for
  372. * audio.
  373. * <i>Defaults to '', i.e., no specific robustness required.</i> <br>
  374. * @property {Uint8Array} serverCertificate
  375. * <i>Defaults to null.</i> <br>
  376. * <i>An empty certificate (byteLength 0) will be treated as null.</i> <br>
  377. * <i>A certificate will be requested from the license server if
  378. * required.</i> <br>
  379. * A key-system-specific server certificate used to encrypt license requests.
  380. * Its use is optional and is meant as an optimization to avoid a round-trip
  381. * to request a certificate.
  382. *
  383. * @exportDoc
  384. */
  385. shakaExtern.AdvancedDrmConfiguration;
  386. /**
  387. * @typedef {{
  388. * retryParameters: shakaExtern.RetryParameters,
  389. * servers: !Object.<string, string>,
  390. * clearKeys: !Object.<string, string>,
  391. * delayLicenseRequestUntilPlayed: boolean,
  392. * advanced: Object.<string, shakaExtern.AdvancedDrmConfiguration>
  393. * }}
  394. *
  395. * @property {shakaExtern.RetryParameters} retryParameters
  396. * Retry parameters for license requests.
  397. * @property {!Object.<string, string>} servers
  398. * <i>Required for all but the clear key CDM.</i> <br>
  399. * A dictionary which maps key system IDs to their license servers.
  400. * For example, {'com.widevine.alpha': 'http://example.com/drm'}.
  401. * @property {!Object.<string, string>} clearKeys
  402. * <i>Forces the use of the Clear Key CDM.</i>
  403. * A map of key IDs (hex) to keys (hex).
  404. * @property {boolean} delayLicenseRequestUntilPlayed
  405. * <i>Defaults to false.</i> <br>
  406. * True to configure drm to delay sending a license request until a user
  407. * actually starts playing content.
  408. * @property {Object.<string, shakaExtern.AdvancedDrmConfiguration>} advanced
  409. * <i>Optional.</i> <br>
  410. * A dictionary which maps key system IDs to advanced DRM configuration for
  411. * those key systems.
  412. *
  413. * @exportDoc
  414. */
  415. shakaExtern.DrmConfiguration;
  416. /**
  417. * @typedef {{
  418. * customScheme: shakaExtern.DashContentProtectionCallback,
  419. * clockSyncUri: string,
  420. * ignoreDrmInfo: boolean,
  421. * xlinkFailGracefully: boolean
  422. * }}
  423. *
  424. * @property {shakaExtern.DashContentProtectionCallback} customScheme
  425. * If given, invoked by a DASH manifest parser to interpret custom or
  426. * non-standard DRM schemes found in the manifest. The argument is a
  427. * ContentProtection node. Return null if not recognized.
  428. * @property {string} clockSyncUri
  429. * A default clock sync URI to be used with live streams which do not
  430. * contain any clock sync information. The "Date" header from this URI
  431. * will be used to determine the current time.
  432. * @property {boolean} ignoreDrmInfo
  433. * If true will cause DASH parser to ignore DRM information specified
  434. * by the manifest and treat it as if it signaled no particular key
  435. * system and contained no init data. Defaults to false if not provided.
  436. * @property {boolean} xlinkFailGracefully
  437. * If true, xlink-related errors will result in a fallback to the tag's
  438. * existing contents. If false, xlink-related errors will be propagated
  439. * to the application and will result in a playback failure. Defaults to
  440. * false if not provided.
  441. *
  442. * @exportDoc
  443. */
  444. shakaExtern.DashManifestConfiguration;
  445. /**
  446. * @typedef {{
  447. * defaultTimeOffset: number
  448. * }}
  449. *
  450. * @property {number} defaultTimeOffset
  451. * Default time offset (in seconds) for hls content used when no offset
  452. * is specified by the manifest. Defaults to 0 if not provided.
  453. * NOTE: Default time offset for Apple encoded content is 10 seconds.
  454. *
  455. * @exportDoc
  456. */
  457. shakaExtern.HlsManifestConfiguration;
  458. /**
  459. * @typedef {{
  460. * retryParameters: shakaExtern.RetryParameters,
  461. * dash: shakaExtern.DashManifestConfiguration,
  462. * hls: shakaExtern.HlsManifestConfiguration
  463. * }}
  464. *
  465. * @property {shakaExtern.RetryParameters} retryParameters
  466. * Retry parameters for manifest requests.
  467. * @property {shakaExtern.DashManifestConfiguration} dash
  468. * Advanced parameters used by the DASH manifest parser.
  469. * @property {shakaExtern.HlsManifestConfiguration} hls
  470. * Advanced parameters used by the HLS manifest parser.
  471. *
  472. * @exportDoc
  473. */
  474. shakaExtern.ManifestConfiguration;
  475. /**
  476. * @typedef {{
  477. * retryParameters: shakaExtern.RetryParameters,
  478. * failureCallback: function(!shaka.util.Error),
  479. * rebufferingGoal: number,
  480. * bufferingGoal: number,
  481. * bufferBehind: number,
  482. * ignoreTextStreamFailures: boolean,
  483. * startAtSegmentBoundary: boolean,
  484. * smallGapLimit: number,
  485. * jumpLargeGaps: boolean
  486. * }}
  487. *
  488. * @description
  489. * The StreamingEngine's configuration options.
  490. *
  491. * @property {shakaExtern.RetryParameters} retryParameters
  492. * Retry parameters for segment requests.
  493. * @property {function(!shaka.util.Error)} failureCallback
  494. * A callback to decide what to do on a streaming failure. Default behavior
  495. * is to retry on live streams and not on VOD.
  496. * @property {number} rebufferingGoal
  497. * The minimum number of seconds of content that the StreamingEngine must
  498. * buffer before it can begin playback or can continue playback after it has
  499. * entered into a buffering state (i.e., after it has depleted one more
  500. * more of its buffers).
  501. * @property {number} bufferingGoal
  502. * The number of seconds of content that the StreamingEngine will attempt to
  503. * buffer ahead of the playhead. This value must be greater than or equal to
  504. * the rebuffering goal.
  505. * @property {number} bufferBehind
  506. * The maximum number of seconds of content that the StreamingEngine will keep
  507. * in buffer behind the playhead when it appends a new media segment.
  508. * The StreamingEngine will evict content to meet this limit.
  509. * @property {boolean} ignoreTextStreamFailures
  510. * If true, the player will ignore text stream failures and proceed to play
  511. * other streams.
  512. * @property {boolean} startAtSegmentBoundary
  513. * If true, adjust the start time backwards so it is at the start of a
  514. * segment. This affects both explicit start times and calculated start time
  515. * for live streams. This can put us further from the live edge. Defaults to
  516. * false.
  517. * @property {number} smallGapLimit
  518. * The limit (in seconds) for a gap in the media to be considered "small".
  519. * Small gaps are jumped automatically without events. Large gaps result
  520. * in a Player event and can be jumped.
  521. * @property {boolean} jumpLargeGaps
  522. * If true, jump large gaps in addition to small gaps. The event will be
  523. * raised first. Then, if the app doesn't call preventDefault() on the event,
  524. * the Player will jump the gap. If false, then the event will be raised,
  525. * but the gap will not be jumped.
  526. * @exportDoc
  527. */
  528. shakaExtern.StreamingConfiguration;
  529. /**
  530. * @typedef {{
  531. * enabled: boolean,
  532. * defaultBandwidthEstimate: number,
  533. * restrictions: shakaExtern.Restrictions,
  534. * switchInterval: number,
  535. * bandwidthUpgradeTarget: number,
  536. * bandwidthDowngradeTarget: number
  537. * }}
  538. *
  539. * @property {boolean} enabled
  540. * If true, enable adaptation by the current AbrManager. Defaults to true.
  541. * @property {number} defaultBandwidthEstimate
  542. * The default bandwidth estimate to use if there is not enough data, in
  543. * bit/sec.
  544. * @property {shakaExtern.Restrictions} restrictions
  545. * The restrictions to apply to ABR decisions. The AbrManager will not
  546. * choose any streams that do not meet these restrictions. (Note that
  547. * they can still be chosen by the application)
  548. * @property {number} switchInterval
  549. * The minimum amount of time that must pass between switches, in
  550. * seconds. This keeps us from changing too often and annoying the user.
  551. * @property {number} bandwidthUpgradeTarget
  552. * The fraction of the estimated bandwidth which we should try to use when
  553. * upgrading.
  554. * @property {number} bandwidthDowngradeTarget
  555. * The largest fraction of the estimated bandwidth we should use. We should
  556. * downgrade to avoid this.
  557. * @exportDoc
  558. */
  559. shakaExtern.AbrConfiguration;
  560. /**
  561. * @typedef {{
  562. * drm: shakaExtern.DrmConfiguration,
  563. * manifest: shakaExtern.ManifestConfiguration,
  564. * streaming: shakaExtern.StreamingConfiguration,
  565. * abrFactory: shakaExtern.AbrManager.Factory,
  566. * abr: shakaExtern.AbrConfiguration,
  567. * preferredAudioLanguage: string,
  568. * preferredTextLanguage: string,
  569. * restrictions: shakaExtern.Restrictions,
  570. * playRangeStart: number,
  571. * playRangeEnd: number,
  572. * textDisplayFactory: shakaExtern.TextDisplayer.Factory
  573. * }}
  574. *
  575. * @property {shakaExtern.DrmConfiguration} drm
  576. * DRM configuration and settings.
  577. * @property {shakaExtern.ManifestConfiguration} manifest
  578. * Manifest configuration and settings.
  579. * @property {shakaExtern.StreamingConfiguration} streaming
  580. * Streaming configuration and settings.
  581. * @property {shakaExtern.AbrManager.Factory} abrFactory
  582. * A factory to construct an abr manager.
  583. * @property {shakaExtern.AbrConfiguration} abr
  584. * ABR configuration and settings.
  585. * @property {string} preferredAudioLanguage
  586. * The preferred language to use for audio tracks. If not given it will use
  587. * the 'main' track.
  588. * Changing this during playback will not affect the current playback.
  589. * @property {string} preferredTextLanguage
  590. * The preferred language to use for text tracks. If a matching text track
  591. * is found, and the selected audio and text tracks have different languages,
  592. * the text track will be shown.
  593. * Changing this during playback will not affect the current playback.
  594. * @property {shakaExtern.Restrictions} restrictions
  595. * The application restrictions to apply to the tracks. The track must
  596. * meet all the restrictions to be playable.
  597. * @property {number} playRangeStart
  598. * Optional playback and seek start time in seconds. Defaults to 0 if
  599. * not provided.
  600. * @property {number} playRangeEnd
  601. * Optional playback and seek end time in seconds. Defaults to the end of
  602. * the presentation if not provided.
  603. * @property {shakaExtern.TextDisplayer.Factory} textDisplayFactory
  604. * A factory to construct text displayer.
  605. * @exportDoc
  606. */
  607. shakaExtern.PlayerConfiguration;