Source: externs/shaka/offline.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. /** @externs */
  22. /**
  23.  * @typedef {{
  24.  *   basic: boolean,
  25.  *   encrypted: !Object.<string, boolean>
  26.  * }}
  27.  *
  28.  * @property {boolean} basic
  29.  *   True if offline is usable at all.
  30.  * @property {!Object.<string, boolean>} encrypted
  31.  *   A map of key system name to whether it supports offline playback.
  32.  * @exportDoc
  33.  */
  34. shakaExtern.OfflineSupport;
  37. /**
  38.  * @typedef {{
  39.  *   trackSelectionCallback:
  40.  *       function(!Array.<shakaExtern.Track>):!Array.<shakaExtern.Track>,
  41.  *   progressCallback: function(shakaExtern.StoredContent,number),
  42.  *   usePersistentLicense: boolean
  43.  * }}
  44.  *
  45.  * @property {function(!Array.<shakaExtern.Track>):!Array.<shakaExtern.Track>}
  46.  *     trackSelectionCallback
  47.  *   Called inside store() to determine which tracks to save from a manifest.
  48.  *   It is passed an array of Tracks from the manifest and it should return
  49.  *   an array of the tracks to store.  This is called for each Period in the
  50.  *   manifest (in order).
  51.  * @property {function(shakaExtern.StoredContent,number)} progressCallback
  52.  *   Called inside store() to give progress info back to the app.  It is given
  53.  *   the current manifest being stored and the progress of it being stored.
  54.  * @property {boolean} usePersistentLicense
  55.  *   If true, store protected content with a persistent license so that no
  56.  *   network is required to view.
  57.  *   If false, store protected content without a persistent license.  A network
  58.  *   will be required to retrieve a temporary license to view.
  59.  *   Defaults to true.
  60.  * @exportDoc
  61.  */
  62. shakaExtern.OfflineConfiguration;
  65. /**
  66.  * @typedef {{
  67.  *   offlineUri: ?string,
  68.  *   originalManifestUri: string,
  69.  *   duration: number,
  70.  *   size: number,
  71.  *   expiration: number,
  72.  *   tracks: !Array.<shakaExtern.Track>,
  73.  *   appMetadata: Object
  74.  * }}
  75.  *
  76.  * @property {?string} offlineUri
  77.  *   An offline URI to access the content. This can be passed directly to
  78.  *   Player. If the uri is null, it means that the content has not finished
  79.  *   downloading and is not ready to play.
  80.  * @property {string} originalManifestUri
  81.  *   The original manifest URI of the content stored.
  82.  * @property {number} duration
  83.  *   The duration of the content, in seconds.
  84.  * @property {number} size
  85.  *   The size of the content, in bytes.
  86.  * @property {number} expiration
  87.  *   The time that the encrypted license expires, in milliseconds.  If the media
  88.  *   is clear or the license never expires, this will equal Infinity.
  89.  * @property {!Array.<shakaExtern.Track>} tracks
  90.  *   The tracks that are stored.  This only lists those found in the first
  91.  *   Period.
  92.  * @property {Object} appMetadata
  93.  *   The metadata passed to store().
  94.  * @exportDoc
  95.  */
  96. shakaExtern.StoredContent;
  99. /**
  100.  * @typedef {{
  101.  *   originalManifestUri: string,
  102.  *   duration: number,
  103.  *   size: number,
  104.  *   expiration: number,
  105.  *   periods: !Array.<shakaExtern.PeriodDB>,
  106.  *   sessionIds: !Array.<string>,
  107.  *   drmInfo: ?shakaExtern.DrmInfo,
  108.  *   appMetadata: Object
  109.  * }}
  110.  *
  111.  * @property {string} originalManifestUri
  112.  *   The URI that the manifest was originally loaded from.
  113.  * @property {number} duration
  114.  *   The total duration of the media, in seconds.
  115.  * @property {number} size
  116.  *   The total size of all stored segments, in bytes.
  117.  * @property {number} expiration
  118.  *   The license expiration, in milliseconds; or Infinity if not applicable.
  119.  * @property {!Array.<shakaExtern.PeriodDB>} periods
  120.  *   The Periods that are stored.
  121.  * @property {!Array.<string>} sessionIds
  122.  *   The DRM offline session IDs for the media.
  123.  * @property {?shakaExtern.DrmInfo} drmInfo
  124.  *   The DRM info used to initialize EME.
  125.  * @property {Object} appMetadata
  126.  *   A metadata object passed from the application.
  127.  */
  128. shakaExtern.ManifestDB;
  131. /**
  132.  * @typedef {{
  133.  *   startTime: number,
  134.  *   streams: !Array.<shakaExtern.StreamDB>
  135.  * }}
  136.  *
  137.  * @property {number} startTime
  138.  *   The start time of the period, in seconds.
  139.  * @property {!Array.<shakaExtern.StreamDB>} streams
  140.  *   The streams that define the Period.
  141.  */
  142. shakaExtern.PeriodDB;
  145. /**
  146.  * @typedef {{
  147.  *   id: number,
  148.  *   primary: boolean,
  149.  *   presentationTimeOffset: number,
  150.  *   contentType: string,
  151.  *   mimeType: string,
  152.  *   codecs: string,
  153.  *   frameRate: (number|undefined),
  154.  *   kind: (string|undefined),
  155.  *   language: string,
  156.  *   label: ?string,
  157.  *   width: ?number,
  158.  *   height: ?number,
  159.  *   initSegmentKey: ?number,
  160.  *   encrypted: boolean,
  161.  *   keyId: ?string,
  162.  *   segments: !Array.<shakaExtern.SegmentDB>,
  163.  *   variantIds: !Array.<number>
  164.  * }}
  165.  *
  166.  * @property {number} id
  167.  *   The unique id of the stream.
  168.  * @property {boolean} primary
  169.  *   Whether the stream set was primary.
  170.  * @property {number} presentationTimeOffset
  171.  *   The presentation time offset of the stream, in seconds.
  172.  * @property {string} contentType
  173.  *   The type of the stream, 'audio', 'text', or 'video'.
  174.  * @property {string} mimeType
  175.  *   The MIME type of the stream.
  176.  * @property {string} codecs
  177.  *   The codecs of the stream.
  178.  * @property {(number|undefined)} frameRate
  179.  *   The Stream's framerate in frames per second.
  180.  * @property {(string|undefined)} kind
  181.  *   The kind of text stream; undefined for audio/video.
  182.  * @property {string} language
  183.  *   The language of the stream; '' for video.
  184.  * @property {?string} label
  185.  *   The label of the stream; '' for video.
  186.  * @property {?number} width
  187.  *   The width of the stream; null for audio/text.
  188.  * @property {?number} height
  189.  *   The height of the stream; null for audio/text.
  190.  * @property  {?number} initSegmentKey
  191.  *   The storage key where the init segment is found; null if no init segment.
  192.  * @property {boolean} encrypted
  193.  *   Whether this stream is encrypted.
  194.  * @property {?string} keyId
  195.  *   The key ID this stream is encrypted with.
  196.  * @property {!Array.<shakaExtern.SegmentDB>} segments
  197.  *   An array of segments that make up the stream.
  198.  * @property {!Array.<number>} variantIds
  199.  *   An array of ids of variants the stream is a part of.
  200.  */
  201. shakaExtern.StreamDB;
  204. /**
  205.  * @typedef {{
  206.  *   startTime: number,
  207.  *   endTime: number,
  208.  *   dataKey: number
  209.  * }}
  210.  *
  211.  * @property {number} startTime
  212.  *   The start time of the segment, in seconds from the start of the Period.
  213.  * @property {number} endTime
  214.  *   The end time of the segment, in seconds from the start of the Period.
  215.  * @property {number} dataKey
  216.  *   The key to the data in storage.
  217.  */
  218. shakaExtern.SegmentDB;
  221. /**
  222.  * @typedef {{
  223.  *   data: !ArrayBuffer
  224.  * }}
  225.  *
  226.  * @property {!ArrayBuffer} data
  227.  *   The data contents of the segment.
  228.  */
  229. shakaExtern.SegmentDataDB;
  232. /**
  233.  * An interface that defines access to collection of segments and manifests. All
  234.  * methods are designed to be batched operations allowing the implementations to
  235.  * optimize their operations based on how they store data.
  236.  *
  237.  * The storage cell is one of two exposed APIs used to control where and how
  238.  * offline content is saved. The storage cell is responsible for converting
  239.  * information between its internal structures and the external (library)
  240.  * structures.
  241.  *
  242.  * @interface
  243.  */
  244. shakaExtern.StorageCell = function() {};
  247. /**
  248.  * Free all resources used by this cell. This should not affect the stored
  249.  * content.
  250.  *
  251.  * @return {!Promise}
  252.  */
  253. shakaExtern.StorageCell.prototype.destroy = function() {};
  256. /**
  257.  * Check if the cell can support new keys. If a cell has a fixed key space,
  258.  * then all add-operations will fail as no new keys can be added. All
  259.  * remove-operations and update-operations should still work.
  260.  *
  261.  * @return {boolean}
  262.  */
  263. shakaExtern.StorageCell.prototype.hasFixedKeySpace = function() {};
  266. /**
  267.  * Add a group of segments. Will return a promise that resolves with a list
  268.  * of keys for each segment. If one segment fails to be added, all segments
  269.  * should fail to be added.
  270.  *
  271.  * @param {!Array.<shakaExtern.SegmentDataDB>} segments
  272.  * @return {!Promise.<!Array.<number>>}
  273.  */
  274. shakaExtern.StorageCell.prototype.addSegments = function(segments) {};
  277. /**
  278.  * Remove a group of segments using their keys to identify them. If a key
  279.  * is not found, then that removal should be considered successful.
  280.  *
  281.  * @param {!Array.<number>} keys
  282.  * @param {function(number)} onRemove A callback for when a segment is removed
  283.  *                                    from the cell. The key of the segment
  284.  *                                    will be passed to the callback.
  285.  * @return {!Promise}
  286.  */
  287. shakaExtern.StorageCell.prototype.removeSegments = function(keys, onRemove) {};
  290. /**
  291.  * Get a group of segments using their keys to identify them. If any key is
  292.  * not found, the promise chain will be rejected.
  293.  *
  294.  * @param {!Array.<number>} keys
  295.  * @return {!Promise.<!Array.<shakaExtern.SegmentDataDB>>}
  296.  */
  297. shakaExtern.StorageCell.prototype.getSegments = function(keys) {};
  300. /**
  301.  * Add a group of manifests. Will return a promise that resolves with a list
  302.  * of keys for each manifest. If one manifest fails to be added, all manifests
  303.  * should fail to be added.
  304.  *
  305.  * @param {!Array.<shakaExtern.ManifestDB>} manifests
  306.  * @return {!Promise<!Array.<number>>} keys
  307.  */
  308. shakaExtern.StorageCell.prototype.addManifests = function(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. shakaExtern.StorageCell.prototype.updateManifestExpiration =
  321.     function(key, expiration) {};
  324. /**
  325.  * Remove a group of manifests using their keys to identify them. If a key
  326.  * is not found, then that removal should be considered successful.
  327.  *
  328.  * @param {!Array.<number>} keys
  329.  * @param {function(number)} onRemove A callback for when a manifest is removed
  330.  *                                    from the cell. The key of the manifest
  331.  *                                    will be passed to the callback.
  332.  * @return {!Promise}
  333.  */
  334. shakaExtern.StorageCell.prototype.removeManifests =
  335.     function(keys, onRemove) {};
  338. /**
  339.  * Get a group of manifests using their keys to identify them. If any key is
  340.  * not found, the promise chain will be rejected.
  341.  *
  342.  * @param {!Array.<number>} keys
  343.  * @return {!Promise<!Array.<shakaExtern.ManifestDB>>}
  344.  */
  345. shakaExtern.StorageCell.prototype.getManifests = function(keys) {};
  348. /**
  349.  * Get all manifests stored in this cell. Since manifests are small compared to
  350.  * the asset they describe, it is assumed that it is feasible to have them all
  351.  * in main memory at one time.
  352.  *
  353.  * @return {!Promise<!Object.<number, shakaExtern.ManifestDB>>}
  354.  */
  355. shakaExtern.StorageCell.prototype.getAllManifests = function() {};
  358. /**
  359.  * Storage mechanisms are one of two exported storage APIs. Storage mechanisms
  360.  * are groups of storage cells (shakaExtern.StorageCell). Storage mechanisms
  361.  * are responsible for managing the life cycle of resources shared between
  362.  * storage cells in the same block.
  363.  *
  364.  * For example, a storage mechanism may manage a single database connection
  365.  * while each cell would manage different tables in the database via the same
  366.  * connection.
  367.  *
  368.  * @interface
  369.  */
  370. shakaExtern.StorageMechanism = function() {};
  373. /**
  374.  * Initialize the storage mechanism for first use. This should only be called
  375.  * once. Calling |init| multiple times has an undefined behaviour.
  376.  *
  377.  * @return {!Promise}
  378.  */
  379. shakaExtern.StorageMechanism.prototype.init = function() {};
  382. /**
  383.  * Free all resources used by the storage mechanism and its cells. This should
  384.  * not affect the stored content.
  385.  *
  386.  * @return {!Promise}
  387.  */
  388. shakaExtern.StorageMechanism.prototype.destroy = function() {};
  391. /**
  392.  * Get a map of all the cells managed by the storage mechanism. Editing the map
  393.  * should have no effect on the storage mechanism. The map key is the cell's
  394.  * address in the mechanism and should be consistent between calls to
  395.  * |getCells|.
  396.  *
  397.  * @return {!Object.<string, !shakaExtern.StorageCell>}
  398.  */
  399. shakaExtern.StorageMechanism.prototype.getCells = function() {};
  402. /**
  403.  * Erase all content from storage and leave storage in an empty state. Erase may
  404.  * be called with or without |init|.  This allows for storage to be wiped in
  405.  * case of a version mismatch.
  406.  *
  407.  * After calling |erase|, the mechanism will be in an initialized state.
  408.  *
  409.  * @return {!Promise}
  410.  */
  411. shakaExtern.StorageMechanism.prototype.erase = function() {};