Source: externs/shaka/offline.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. * @typedef {{
  11. * basic: boolean,
  12. * encrypted: !Object.<string, boolean>
  13. * }}
  14. *
  15. * @property {boolean} basic
  16. * True if offline is usable at all.
  17. * @property {!Object.<string, boolean>} encrypted
  18. * A map of key system name to whether it supports offline playback.
  19. * @exportDoc
  20. */
  21. shaka.extern.OfflineSupport;
  22. /**
  23. * @typedef {{
  24. * offlineUri: ?string,
  25. * originalManifestUri: string,
  26. * duration: number,
  27. * size: number,
  28. * expiration: number,
  29. * tracks: !Array.<shaka.extern.Track>,
  30. * appMetadata: Object
  31. * }}
  32. *
  33. * @property {?string} offlineUri
  34. * An offline URI to access the content. This can be passed directly to
  35. * Player. If the uri is null, it means that the content has not finished
  36. * downloading and is not ready to play.
  37. * @property {string} originalManifestUri
  38. * The original manifest URI of the content stored.
  39. * @property {number} duration
  40. * The duration of the content, in seconds.
  41. * @property {number} size
  42. * The size of the content, in bytes.
  43. * @property {number} expiration
  44. * The time that the encrypted license expires, in milliseconds. If the media
  45. * is clear or the license never expires, this will equal Infinity.
  46. * @property {!Array.<shaka.extern.Track>} tracks
  47. * The tracks that are stored.
  48. * @property {Object} appMetadata
  49. * The metadata passed to store().
  50. * @exportDoc
  51. */
  52. shaka.extern.StoredContent;
  53. /**
  54. * @typedef {{
  55. * creationTime: number,
  56. * originalManifestUri: string,
  57. * duration: number,
  58. * size: number,
  59. * expiration: number,
  60. * streams: !Array.<shaka.extern.StreamDB>,
  61. * sessionIds: !Array.<string>,
  62. * drmInfo: ?shaka.extern.DrmInfo,
  63. * appMetadata: Object
  64. * }}
  65. *
  66. * @property {number} creationTime
  67. * The date time when the asset was created.
  68. * @property {string} originalManifestUri
  69. * The URI that the manifest was originally loaded from.
  70. * @property {number} duration
  71. * The total duration of the media, in seconds.
  72. * @property {number} size
  73. * The total size of all stored segments, in bytes.
  74. * @property {number} expiration
  75. * The license expiration, in milliseconds; or Infinity if not applicable.
  76. * Note that upon JSON serialization, Infinity becomes null, and must be
  77. * converted back upon loading from storage.
  78. * @property {!Array.<shaka.extern.StreamDB>} streams
  79. * The Streams that are stored.
  80. * @property {!Array.<string>} sessionIds
  81. * The DRM offline session IDs for the media.
  82. * @property {?shaka.extern.DrmInfo} drmInfo
  83. * The DRM info used to initialize EME.
  84. * @property {Object} appMetadata
  85. * A metadata object passed from the application.
  86. */
  87. shaka.extern.ManifestDB;
  88. /**
  89. * @typedef {{
  90. * id: number,
  91. * originalId: ?string,
  92. * primary: boolean,
  93. * type: string,
  94. * mimeType: string,
  95. * codecs: string,
  96. * frameRate: (number|undefined),
  97. * pixelAspectRatio: (string|undefined),
  98. * hdr: (string|undefined),
  99. * kind: (string|undefined),
  100. * language: string,
  101. * label: ?string,
  102. * width: ?number,
  103. * height: ?number,
  104. * encrypted: boolean,
  105. * keyIds: !Set.<string>,
  106. * segments: !Array.<shaka.extern.SegmentDB>,
  107. * variantIds: !Array.<number>,
  108. * roles: !Array.<string>,
  109. * forced: boolean,
  110. * channelsCount: ?number,
  111. * audioSamplingRate: ?number,
  112. * spatialAudio: boolean,
  113. * closedCaptions: Map.<string, string>,
  114. * tilesLayout: (string|undefined)
  115. * }}
  116. *
  117. * @property {number} id
  118. * The unique id of the stream.
  119. * @property {?string} originalId
  120. * The original ID, if any, that appeared in the manifest. For example, in
  121. * DASH, this is the "id" attribute of the Representation element.
  122. * @property {boolean} primary
  123. * Whether the stream set was primary.
  124. * @property {string} type
  125. * The type of the stream, 'audio', 'text', or 'video'.
  126. * @property {string} mimeType
  127. * The MIME type of the stream.
  128. * @property {string} codecs
  129. * The codecs of the stream.
  130. * @property {(number|undefined)} frameRate
  131. * The Stream's framerate in frames per second.
  132. * @property {(string|undefined)} pixelAspectRatio
  133. * The Stream's pixel aspect ratio
  134. * @property {(string|undefined)} hdr
  135. * The Stream's HDR info
  136. * @property {(string|undefined)} kind
  137. * The kind of text stream; undefined for audio/video.
  138. * @property {string} language
  139. * The language of the stream; '' for video.
  140. * @property {?string} label
  141. * The label of the stream; '' for video.
  142. * @property {?number} width
  143. * The width of the stream; null for audio/text.
  144. * @property {?number} height
  145. * The height of the stream; null for audio/text.
  146. * @property {boolean} encrypted
  147. * Whether this stream is encrypted.
  148. * @property {!Set.<string>} keyIds
  149. * The key IDs this stream is encrypted with.
  150. * @property {!Array.<shaka.extern.SegmentDB>} segments
  151. * An array of segments that make up the stream.
  152. * @property {!Array.<number>} variantIds
  153. * An array of ids of variants the stream is a part of.
  154. * @property {!Array.<string>} roles
  155. * The roles of the stream as they appear on the manifest,
  156. * e.g. 'main', 'caption', or 'commentary'.
  157. * @property {boolean} forced
  158. * Whether the stream set was forced.
  159. * @property {?number} channelsCount
  160. * The channel count information for the audio stream.
  161. * @property {?number} audioSamplingRate
  162. * Specifies the maximum sampling rate of the content.
  163. * @property {boolean} spatialAudio
  164. * Whether the stream set has spatial audio.
  165. * @property {Map.<string, string>} closedCaptions
  166. * A map containing the description of closed captions, with the caption
  167. * channel number (CC1 | CC2 | CC3 | CC4) as the key and the language code
  168. * as the value. If the channel number is not provided by the description,
  169. * we'll set an 0-based index as the key.
  170. * Example: {'CC1': 'eng'; 'CC3': 'swe'}, or {'1', 'eng'; '2': 'swe'}, etc.
  171. * @property {(string|undefined)} tilesLayout
  172. * The value is a grid-item-dimension consisting of two positive decimal
  173. * integers in the format: column-x-row ('4x3'). It describes the arrangement
  174. * of Images in a Grid. The minimum valid LAYOUT is '1x1'.
  175. */
  176. shaka.extern.StreamDB;
  177. /**
  178. * @typedef {{
  179. * initSegmentKey: ?number,
  180. * startTime: number,
  181. * endTime: number,
  182. * appendWindowStart: number,
  183. * appendWindowEnd: number,
  184. * timestampOffset: number,
  185. * tilesLayout: ?string,
  186. * dataKey: number
  187. * }}
  188. *
  189. * @property {?number} initSegmentKey
  190. * The storage key where the init segment is found; null if no init segment.
  191. * @property {number} startTime
  192. * The start time of the segment in the presentation timeline.
  193. * @property {number} endTime
  194. * The end time of the segment in the presentation timeline.
  195. * @property {number} appendWindowStart
  196. * A start timestamp before which media samples will be truncated.
  197. * @property {number} appendWindowEnd
  198. * An end timestamp beyond which media samples will be truncated.
  199. * @property {number} timestampOffset
  200. * An offset which MediaSource will add to the segment's media timestamps
  201. * during ingestion, to align to the presentation timeline.
  202. * @property {?string} tilesLayout
  203. * The value is a grid-item-dimension consisting of two positive decimal
  204. * integers in the format: column-x-row ('4x3'). It describes the
  205. * arrangement of Images in a Grid. The minimum valid LAYOUT is '1x1'.
  206. * @property {number} dataKey
  207. * The key to the data in storage.
  208. */
  209. shaka.extern.SegmentDB;
  210. /**
  211. * @typedef {{
  212. * data: !ArrayBuffer
  213. * }}
  214. *
  215. * @property {!ArrayBuffer} data
  216. * The data contents of the segment.
  217. */
  218. shaka.extern.SegmentDataDB;
  219. /**
  220. * @typedef {{
  221. * sessionId: string,
  222. * keySystem: string,
  223. * licenseUri: string,
  224. * serverCertificate: Uint8Array,
  225. * audioCapabilities: !Array.<MediaKeySystemMediaCapability>,
  226. * videoCapabilities: !Array.<MediaKeySystemMediaCapability>
  227. * }}
  228. *
  229. * @property {string} sessionId
  230. * The EME session ID.
  231. * @property {string} keySystem
  232. * The EME key system string the session belongs to.
  233. * @property {string} licenseUri
  234. * The URI for the license server.
  235. * @property {Uint8Array} serverCertificate
  236. * A key-system-specific server certificate used to encrypt license requests.
  237. * Its use is optional and is meant as an optimization to avoid a round-trip
  238. * to request a certificate.
  239. * @property {!Array.<MediaKeySystemMediacapability>} audioCapabilities
  240. * The EME audio capabilities used to create the session.
  241. * @property {!Array.<MediaKeySystemMediacapability>} videoCapabilities
  242. * The EME video capabilities used to create the session.
  243. */
  244. shaka.extern.EmeSessionDB;
  245. /**
  246. * An interface that defines access to collection of segments and manifests. All
  247. * methods are designed to be batched operations allowing the implementations to
  248. * optimize their operations based on how they store data.
  249. *
  250. * The storage cell is one of two exposed APIs used to control where and how
  251. * offline content is saved. The storage cell is responsible for converting
  252. * information between its internal structures and the external (library)
  253. * structures.
  254. *
  255. * @interface
  256. */
  257. shaka.extern.StorageCell = class {
  258. constructor() {}
  259. /**
  260. * Free all resources used by this cell. This should not affect the stored
  261. * content.
  262. *
  263. * @return {!Promise}
  264. */
  265. destroy() {}
  266. /**
  267. * Check if the cell can support new keys. If a cell has a fixed key space,
  268. * then all add-operations will fail as no new keys can be added. All
  269. * remove-operations and update-operations should still work.
  270. *
  271. * @return {boolean}
  272. */
  273. hasFixedKeySpace() {}
  274. /**
  275. * Add a group of segments. Will return a promise that resolves with a list
  276. * of keys for each segment. If one segment fails to be added, all segments
  277. * should fail to be added.
  278. *
  279. * @param {!Array.<shaka.extern.SegmentDataDB>} segments
  280. * @return {!Promise.<!Array.<number>>}
  281. */
  282. addSegments(segments) {}
  283. /**
  284. * Remove a group of segments using their keys to identify them. If a key
  285. * is not found, then that removal should be considered successful.
  286. *
  287. * @param {!Array.<number>} keys
  288. * @param {function(number)} onRemove A callback for when a segment is removed
  289. * from the cell. The key of the segment
  290. * will be passed to the callback.
  291. * @return {!Promise}
  292. */
  293. removeSegments(keys, onRemove) {}
  294. /**
  295. * Get a group of segments using their keys to identify them. If any key is
  296. * not found, the promise chain will be rejected.
  297. *
  298. * @param {!Array.<number>} keys
  299. * @return {!Promise.<!Array.<shaka.extern.SegmentDataDB>>}
  300. */
  301. getSegments(keys) {}
  302. /**
  303. * Add a group of manifests. Will return a promise that resolves with a list
  304. * of keys for each manifest. If one manifest fails to be added, all manifests
  305. * should fail to be added.
  306. *
  307. * @param {!Array.<shaka.extern.ManifestDB>} manifests
  308. * @return {!Promise<!Array.<number>>} keys
  309. */
  310. addManifests(manifests) {}
  311. /**
  312. * Replace the expiration time of the manifest stored under |key| with
  313. * |newExpiration|. If no manifest is found under |key| then this should
  314. * act as a no-op.
  315. *
  316. * @param {number} key
  317. * @param {number} expiration
  318. * @return {!Promise}
  319. */
  320. updateManifestExpiration(key, expiration) {}
  321. /**
  322. * Remove a group of manifests using their keys to identify them. If a key
  323. * is not found, then that removal should be considered successful.
  324. *
  325. * @param {!Array.<number>} keys
  326. * @param {function(number)} onRemove A callback for when a manifest is
  327. * removed from the cell. The key of the
  328. * manifest will be passed to the callback.
  329. * @return {!Promise}
  330. */
  331. removeManifests(keys, onRemove) {}
  332. /**
  333. * Get a group of manifests using their keys to identify them. If any key is
  334. * not found, the promise chain will be rejected.
  335. *
  336. * @param {!Array.<number>} keys
  337. * @return {!Promise<!Array.<shaka.extern.ManifestDB>>}
  338. */
  339. getManifests(keys) {}
  340. /**
  341. * Get all manifests stored in this cell. Since manifests are small compared
  342. * to the asset they describe, it is assumed that it is feasible to have them
  343. * all in main memory at one time.
  344. *
  345. * @return {!Promise<!Map.<number, shaka.extern.ManifestDB>>}
  346. */
  347. getAllManifests() {}
  348. };
  349. /**
  350. * Similar to storage cells (shaka.extern.StorageCell), an EmeSessionStorageCell
  351. * stores data persistently. This only stores the license's session info, not
  352. * the license itself. The license itself is stored using EME.
  353. *
  354. * @interface
  355. */
  356. shaka.extern.EmeSessionStorageCell = class {
  357. constructor() {}
  358. /**
  359. * Free all resources used by this cell. This won't affect the stored content.
  360. * @return {!Promise}
  361. */
  362. destroy() {}
  363. /**
  364. * Gets the currently stored sessions.
  365. * @return {!Promise.<!Array.<shaka.extern.EmeSessionDB>>}
  366. */
  367. getAll() {}
  368. /**
  369. * Adds the given sessions to the store.
  370. * @param {!Array.<shaka.extern.EmeSessionDB>} sessions
  371. * @return {!Promise}
  372. */
  373. add(sessions) {}
  374. /**
  375. * Removes the given session IDs from the store.
  376. * @param {!Array.<string>} sessionIds
  377. * @return {!Promise}
  378. */
  379. remove(sessionIds) {}
  380. };
  381. /**
  382. * Storage mechanisms are one of two exported storage APIs. Storage mechanisms
  383. * are groups of storage cells (shaka.extern.StorageCell). Storage mechanisms
  384. * are responsible for managing the life cycle of resources shared between
  385. * storage cells in the same block.
  386. *
  387. * For example, a storage mechanism may manage a single database connection
  388. * while each cell would manage different tables in the database via the same
  389. * connection.
  390. *
  391. * @interface
  392. */
  393. shaka.extern.StorageMechanism = class {
  394. constructor() {}
  395. /**
  396. * Initialize the storage mechanism for first use. This should only be called
  397. * once. Calling |init| multiple times has an undefined behaviour.
  398. *
  399. * @return {!Promise}
  400. */
  401. init() {}
  402. /**
  403. * Free all resources used by the storage mechanism and its cells. This should
  404. * not affect the stored content.
  405. *
  406. * @return {!Promise}
  407. */
  408. destroy() {}
  409. /**
  410. * Get a map of all the cells managed by the storage mechanism. Editing the
  411. * map should have no effect on the storage mechanism. The map key is the
  412. * cell's address in the mechanism and should be consistent between calls to
  413. * |getCells|.
  414. *
  415. * @return {!Map.<string, !shaka.extern.StorageCell>}
  416. */
  417. getCells() {}
  418. /**
  419. * Get the current EME session storage cell.
  420. * @return {!shaka.extern.EmeSessionStorageCell}
  421. */
  422. getEmeSessionCell() {}
  423. /**
  424. * Erase all content from storage and leave storage in an empty state. Erase
  425. * may be called with or without |init|. This allows for storage to be wiped
  426. * in case of a version mismatch.
  427. *
  428. * After calling |erase|, the mechanism will be in an initialized state.
  429. *
  430. * @return {!Promise}
  431. */
  432. erase() {}
  433. };