@castlabs/prestoplay 6.14.0 → 6.15.0

package/typings.d.ts

@@ -1161,6 +1161,13 @@ export namespace clpp {
      * HtmlCue component configuration.
      */
     htmlcue?: Partial<clpp.HtmlCueConfiguration>;
+    /**
+     * A unique identifier of this configuration object.
+     * This attribute is optional, except for configuration objects passed to
+     * {@link clpp.plist.ScPlaylist} for which the ID is mandatory, since we
+     * need a clear way to distinguish different items of the playlist.
+     */
+    id?: string;
     /**
      * Ads plugin configuration.
      */
@@ -1204,6 +1211,10 @@ export namespace clpp {
      * back into foreground.
      */
     pauseWhenInBackground?: boolean;
+    /**
+     * Playlist-related configuration.
+     */
+    playlist?: Partial<clpp.PlaylistConfiguration>;
     /**
      * Defaults to `false`. 
      * 
@@ -1290,8 +1301,7 @@ export namespace clpp {
      */
     safari?: Partial<clpp.SafariConfiguration>;
     /**
-     * SIMID plugin
-     * configuration
+     * SIMID plugin configuration
      */
     simid?: Partial<clpp.SimidConfiguration>;
     /**
@@ -1391,6 +1401,49 @@ export namespace clpp {
     webOSStartupPatch: boolean;
   }
   
+  /**
+   * Playlist-related configuration.
+   */
+  export type PlaylistConfiguration = {
+    /**
+     * Defaults to "VOD". 
+     * 
+     * This option applies to the single-controller playlist and the accepted
+     * values are "VOD" and "DVR". In "VOD" mode the playlist can contain
+     * VOD items only. In "DVR" mode the playlist can contain VOD items and
+     * one DVR item at the end of the playlist.
+     */
+    content?: string;
+    /**
+     * Defaults to false. 
+     * 
+     * This option applies to the single-controller playlist. If true, the
+     * timeline will be cropped based on the values of `startTime` and `endTime`.
+     */
+    cropTimeline?: boolean;
+    /**
+     * This option applies to the single-controller playlist. It is the time
+     * at which the playlist should stop. The time is relative to the
+     * start of the first playlist item and may span several items.
+     */
+    endTime?: number;
+    /**
+     * This option applies to the single-controller playlist. IT is the time
+     * within the first playlist item at which the playlist should start
+     * playback. The time is relative to the start of the first playlist item.
+     */
+    startTime?: number;
+    /**
+     * Defaults to "basic". 
+     * 
+     * This option applies to the single-controller playlist and the accepted
+     * values are "basic" and "flat". In "basic" mode each item has its own
+     * timeline, in "flat" mode all items of the playlist are concatenated into
+     * a single timeline.
+     */
+    timeline?: string;
+  }
+  
   /**
    * Playlist item.
    */
@@ -2240,14 +2293,22 @@ export namespace clpp {
    * EventStream element. In HLS this is the EXT-X-DATERANGE tag.
    */
   export type TimelineCue = {
+    /**
+     * ID of the configuration object of the asset to which this cue belongs
+     * if it is defined in {@link clpp.PlayerConfiguration}.
+     */
+    configurationId?: string;
     /**
      * The presentation time (in seconds) that the cue should end.
+     * Allowed values follow the same rules as startTime. It is possible
+     * for endTime and startTime to be equal, in which case the cue is
+     * considered to be a discrete point on the timeline.
      */
     endTime: number;
     /**
-     * The XML element that defines the Event.
+     * The XML element that defines the Event. Defined only for DASH.
      */
-    eventElement: Element;
+    eventElement: Element|null;
     /**
      * Specifies an identifier for this instance of the cue.
      */
@@ -2258,6 +2319,11 @@ export namespace clpp {
     schemeIdUri: string;
     /**
      * The presentation time (in seconds) that the cue should start.
+     * Specifically for VOD streams the startTime is relative to the start of
+     * the stream, so the value is something between 0 and duration.
+     * For live streams the startTime is absolute, so the value is something
+     * between the start of the first period and the end of the last period
+     * of the stream.
      */
     startTime: number;
     /**
@@ -3100,8 +3166,18 @@ export namespace clpp {
     TIMELINE_CUE_EXIT = "timeline-cue-exit",
     /**
      * Triggered when a MPD type has changed from dynamic to static.
+     * Note: You can also listen to the {@link clpp.events.LIVE_TURNED_STATIC}
+     * event instead.
      */
     MPD_TYPE_CHANGED = "mpd-type-changed",
+    /**
+     * Triggered when a live stream turned in to a static stream.
+     * In HLS this happens when EXT-X-ENDLIST appears in the playlist
+     * and the playlist stops updating. In DASH this happens when
+     * the type attribute of MPD turns from "dynamic" to "static"
+     * and the manifest stops updating.
+     */
+    LIVE_TURNED_STATIC = "live-turned-static",
     /**
      * Triggered when there is a response from Vimond Session API.
      */
@@ -3114,6 +3190,28 @@ export namespace clpp {
      * Triggered when a playlist item has been added, removed or moved.
      */
     PLAYLIST_MODIFIED = "playlist-modified",
+    /**
+     * Triggered when a new timeline window has been added to the timeline of
+     * a single-controller playlist, or when the duration of an existing timeline
+     * window changes.
+     */
+    SC_PLAYLIST_TIMELINE_CHANGED = "sc-playlist-timeline-changed",
+    /**
+     * Triggered when the currently active/selected item of a single-controller
+     * playlist changes.
+     */
+    SC_PLAYLIST_ITEM_CHANGED = "sc-playlist-item-changed",
+    /**
+     * Triggered when playback reaches the end of the last item of
+     * a single-controller playlist, or if `playlist.endTime` is configured
+     * then it's triggered when the end time is reached.
+     */
+    SC_PLAYLIST_ENDED = "sc-playlist-ended",
+    /**
+     * Triggered when the last item of the playlist is an EVENT stream and it
+     * turns from dynamic to static.
+     */
+    SC_PLAYLIST_LIVE_TURNED_STATIC = "sc-playlist-live-turned-static",
     /**
      * Triggered when CDN switch was successful.
      */
@@ -3401,11 +3499,11 @@ export namespace clpp {
     /**
      * Returns the player surface.
      */
-    getSurface(): clpp.IPlayerSurface|null;
+    getSurface(): clpp.IPlayerSurface;
     /**
      * Get the text displayer.
      */
-    getTextDisplayer(): clpp.ITextDisplayer;
+    getTextDisplayer(): clpp.ITextDisplayer|null;
     /**
      * Returns an array of timeline cues.
      */
@@ -3417,7 +3515,7 @@ export namespace clpp {
      */
     getTimelineOffset(): clpp.TimelineOffset|null;
     /**
-     * Returns track manager.
+     * Returns the track manager.
      */
     getTrackManager(): clpp.TrackManager|null;
     /**
@@ -3426,7 +3524,7 @@ export namespace clpp {
      */
     getVolume(): number|null;
     /**
-     * Returns true if playback ended. False otherwise.
+     * Returns true if playback ended, false otherwise.
      */
     isEnded(): boolean;
     /**
@@ -3437,21 +3535,19 @@ export namespace clpp {
      * On the Tizen platform the `http://tizen.org/privilege/tv.audio` privilege
      * is required.
      */
-    isMuted(): boolean|null;
+    isMuted(): boolean;
     /**
-     * Returns true if playback is paused. False otherwise.
+     * Returns true if playback is paused, false otherwise.
      */
     isPaused(): boolean;
     /**
      * Tell the player to load given content.
-     * 
      * You may load content by passing a `string`, a {@link clpp.Source}, an array
      * of sources or player configuration. If multiple sources are passed to a
      * `load` method, player will play first source, that can be played on given
      * platform. Please refer to examples below for more details.
-     * 
-     * If the player already playing another source, it will release itself first
-     * before loading the new source.
+     * If the player is already playing another source, it will release itself
+     * first before loading the new source.
      *
      * @example // Passing a string
      *
@@ -3658,13 +3754,6 @@ export namespace clpp {
      * });
      */
     setDrmCustomDataModifier(modifier: Function): void;
-    /**
-     * On the Tizen platform the `http://tizen.org/privilege/tv.audio` privilege
-     * is required.
-     *
-     * @param muted The muted state
-     */
-    setMuted(muted: boolean): void;
     /**
      * Set the network engine.
      *
@@ -4554,7 +4643,7 @@ export namespace clpp {
        */
       CONTENT_UNSUPPORTED_BY_BROWSER = 4032,
       /**
-       * Microsoft smooth streaming invalid manifest XML
+       * Microsoft smooth streaming invalid manifest XML.
        * The {@link clpp.Error#data} property contains an object with the following
        * properties:
        * 
@@ -4581,7 +4670,7 @@ export namespace clpp {
        */
       SMOOTH_MEDIA_PROCESSING_ERROR = 4035,
       /**
-       * The smooth streaming manifest version is invalid
+       * The smooth streaming manifest version is invalid.
        * The {@link clpp.Error#data} property contains an object with the following
        * properties:
        * 
@@ -4845,16 +4934,31 @@ export namespace clpp {
        */
       INVALID_CONTAINER_ELEMENT = 7006,
       /**
-       * The provided {@link clpp.PlayerConfiguration} is invalid
+       * Error raised when a method is passed an invalid argument.
+       */
+      INVALID_ARGUMENT = 7007,
+      /**
+       * Error raised when two methods which depend on each other are called
+       * in the wrong order.
+       */
+      WRONG_ORDER_OF_OPERATIONS = 7008,
+      /**
+       * Error raised when calling a method which is not supported or passing
+       * arguments or a configuration of arguments that are not supported. This
+       * may also be platform dependent.
+       */
+      NOT_SUPPORTED = 7009,
+      /**
+       * The provided {@link clpp.PlayerConfiguration} is invalid.
        */
       INVALID_CONFIGURATION = 7100,
       /**
        * The provided {@link clpp.PlayerConfiguration#license} does not exist
-       * or is invalid
+       * or is invalid.
        */
       INVALID_LICENSE = 7101,
       /**
-       * No DOM element or element ID was provided when initializing the player
+       * No DOM element or element ID was provided when initializing the player.
        */
       NO_ELEMENT = 7102,
       /**
@@ -4933,7 +5037,7 @@ export namespace clpp {
        */
       GL_CONTEXT_ERROR = 9003,
       /**
-       * Error code that indicates that the player not able to compile a shader
+       * Error code that indicates that the player not able to compile a shader.
        */
       GL_SHADER_ERROR = 9004,
       /**
@@ -4989,7 +5093,7 @@ export namespace clpp {
        */
       AD_ERROR = 10003,
       /**
-       * Triggered when no container could be found to add a SIMID creative
+       * Triggered when no container could be found to add a SIMID creative.
        */
       SIMID_CONTAINER_MISSING = 10100,
       /**
@@ -6241,9 +6345,8 @@ export namespace clpp {
        */
       append(cues: Array<clpp.text.Cue>, styles: Array<string>): void;
       /**
-       * Request that this object be destroyed, releasing all resources.
-       * It also shuts down all active operations.
-       * Returns a Promise which is resolved when destruction
+       * Request that this object be destroyed, releasing all resources and shutting
+       * down all operations. Returns a Promise which is resolved when destruction
        * is complete. This Promise should never be rejected.
        */
       destroy(): Promise<void>;
@@ -6428,60 +6531,8 @@ export namespace clpp {
      */
     export class Player {
       /**
-       * Player that plays HLS interstitials.
-       * Fires events @see {@link clpp.interstitial.Event}.
-       * Support:
-       * 
-       * X-ASSET-LIST, X-ASSET-URI, X-RESUME-OFFSET, X-PLAYOUT-LIMIT
-       * 
-       * Limitations:
-       * 
-       * 
-       * Only supports VOD.
-       * 
-       * 
-       * Interstitials must not be too close to each other.
-       * 
-       * 
-       * Interstitials cannot overlap.
-       * 
-       * 
-       * No error handling (for when some asset/list fails to load).
-       * 
-       * 
-       * No support for #EXT-X-DATERANGE.CUE
-       * 
-       * 
-       * No support for X-RESTRICT
-       * 
-       * 
-       * No support for _HLS_start_offset query in live (because no support
-       * for live)
-       * 
-       * 
-       * No support for _HLS_primary_id
-       * 
-       * 
-       * TODO configurable re-play of interstitial
-       * 
-       * 
-       * TODO configurable skipping
-       * 
-       * 
-       * TODO support live primary asset (working with position)
-       * 
-       * 
-       * Idea: if MultiController does not release primary player and just stops
-       * it, we can save some network requests and context changes. Currently we
-       * release the primary player.
-       * 
-       * 
-       */
-      constructor(options: clpp.interstitial.Options);
-      /**
-       * Request that this object be destroyed, releasing all resources.
-       * It also shuts down all active operations.
-       * Returns a Promise which is resolved when destruction
+       * Request that this object be destroyed, releasing all resources and shutting
+       * down all operations. Returns a Promise which is resolved when destruction
        * is complete. This Promise should never be rejected.
        */
       destroy(): Promise<void>;
@@ -6710,6 +6761,86 @@ export namespace clpp {
     }
   }
   
+  namespace media {
+    export class Timeline {
+      /**
+       * Get the currently active window of the timeline.
+       *
+       * @example // Get the current timeline window.
+       *
+       * const timelineWindow = timeline.getCurrentWindow();
+       */
+      getCurrentWindow(): clpp.media.TimelineWindow|null;
+      /**
+       * Get the index of the currently active window of the timeline.
+       *
+       * @example // Get the index of the current timeline window.
+       *
+       * const index = timeline.getCurrentWindowIndex(); // 0
+       */
+      getCurrentWindowIndex(): number;
+      /**
+       * Get a window of the timeline at the given index.
+       *
+       * @example // Get timeline window at index.
+       *
+       * const timelineWindow = timeline.getWindow(0);
+       */
+      getWindow(index: number): clpp.media.TimelineWindow|null;
+      /**
+       * Get the number of windows in the timeline.
+       *
+       * @example // Get the number of timeline windows.
+       *
+       * const count = timeline.getWindowCount(); // 4
+       */
+      getWindowCount(): number;
+      /**
+       * Get all the windows of the timeline.
+       *
+       * @example // Get all timeline windows.
+       *
+       * const windows = timeline.getWindows(); // [...]
+       */
+      getWindows(): Array<clpp.media.TimelineWindow>;
+    }
+    
+    export class TimelineWindow {
+      /**
+       * Get the duration of the timeline window.
+       *
+       * @example // Get the duration.
+       *
+       * const duration = timelineWindow.getDuration(); // 600
+       */
+      getDuration(): number;
+      /**
+       * Get the ID of the timeline window.
+       *
+       * @example // Get the ID.
+       *
+       * const id = timelineWindow.getId(); // "asset1"
+       */
+      getId(): string;
+      /**
+       * Get the start time of the timeline window.
+       *
+       * @example // Get the start of the window.
+       *
+       * const startTime = timelineWindow.getStart(); // 400
+       */
+      getStart(): number;
+      /**
+       * Check whether the timeline window is static or dynamic.
+       *
+       * @example // Check if the window is dynamic.
+       *
+       * const dynamic = timelineWindow.isDynamic(); // false
+       */
+      isDynamic(): boolean;
+    }
+  }
+  
   namespace muxdata {
     export class MuxDataPlugin {
       static Id: string;
@@ -7417,6 +7548,15 @@ export namespace clpp {
        * for video elements created by this playlist.
        */
       anchorId: string;
+      /**
+       * If true, when one item finishes playback the next item is played
+       * automatically and so on until the end of the playlist.
+       */
+      autoplayNext?: boolean;
+      /**
+       * Default configuration for player instances.
+       */
+      config: clpp.PlayerConfiguration;
       /**
        * If true, preloaded items will have also their media segments preloaded
        * thus reducing the time to start playback to minimum. This option is
@@ -7477,9 +7617,8 @@ export namespace clpp {
        */
       constructor(options: clpp.plist.Options);
       /**
-       * Request that this object be destroyed, releasing all resources.
-       * It also shuts down all active operations.
-       * Returns a Promise which is resolved when destruction
+       * Request that this object be destroyed, releasing all resources and shutting
+       * down all operations. Returns a Promise which is resolved when destruction
        * is complete. This Promise should never be rejected.
        */
       destroy(): Promise<void>;
@@ -7543,6 +7682,164 @@ export namespace clpp {
        */
       setItems(configs: Array<clpp.PlayerConfiguration>): void;
     }
+    
+    /**
+     * The single-controller playlist is intended for smooth continuous
+     * back-to-back playback of multiple items. The playlist class inherits from
+     * {@link clpp.Player} so all methods defined there can also be called on
+     * the playlist instance (e.g. {@link clpp.Player#on|on()},
+     * {@link clpp.Player#off|off()}, {@link clpp.Player#getPosition|getPosition()},
+     * {@link clpp.Player#seek|seek()}, etc).
+     * Limitations: Plugins are disabled and the method. Encryption
+     * is supported only if all the items are encrypted with the same method
+     * and key.
+     */
+    export class ScPlaylist {
+      /**
+       * The single-controller playlist is intended for smooth continuous
+       * back-to-back playback of multiple items. The playlist class inherits from
+       * {@link clpp.Player} so all methods defined there can also be called on
+       * the playlist instance (e.g. {@link clpp.Player#on|on()},
+       * {@link clpp.Player#off|off()}, {@link clpp.Player#getPosition|getPosition()},
+       * {@link clpp.Player#seek|seek()}, etc).
+       * Limitations: Plugins are disabled and the method. Encryption
+       * is supported only if all the items are encrypted with the same method
+       * and key.
+       *
+       * @param element The media element or the ID
+       *   of the media element to use as the underlying player
+       * @param opt_configuration The global
+       *   player configuration
+       * @param opt_viewConfiguration The global player view configuration
+       */
+      constructor(element: HTMLMediaElement|string, opt_configuration?: clpp.PlayerConfiguration, opt_viewConfiguration?: clpp.PlayerSurfaceConfiguration);
+      /**
+       * Append an item to the end of the playlist.
+       * This method cannot be called before
+       * {@link clpp.plist.ScPlaylist#open|open()}.
+       *
+       * @param config an item which must contain
+       *   at least an `id` and a `source`.
+       *
+       * @example // Append an item to the playlist.
+       *
+       * await playlist.addItem({
+       *   id: 'ASSET3',
+       *   source: { url: '...' }
+       * });
+       */
+      addItem(config: clpp.PlayerConfiguration): Promise<void>;
+      /**
+       * Destroy this playlist instance.
+       * The instance will not be usable after it was destroyed.
+       *
+       * @example // Destroy the playlist.
+       *
+       * await playlist.destroy();
+       * // Do not call any methods on the playlist after this point
+       */
+      destroy(): Promise<void>;
+      /**
+       * Get the currently playing item.
+       *
+       * @example // Get the config of the current item.
+       *
+       * const item = playlist.getCurrentItem(); // { id: 'ASSET1', ... }
+       */
+      getCurrentItem(): clpp.PlayerConfiguration|null;
+      /**
+       * Get the index of the currently playing item.
+       *
+       * @example // Get the index of the current item.
+       *
+       * const index = playlist.getCurrentItemIndex(); // 0
+       */
+      getCurrentItemIndex(): number;
+      /**
+       * Get all the items of the playlist.
+       *
+       * @example // Get playlist items.
+       *
+       * const items = playlist.getPlaylist(); // [...]
+       */
+      getPlaylist(): Array<clpp.PlayerConfiguration>;
+      /**
+       * Get the number of items in the playlist.
+       *
+       * @example // Get the number of items in the playlist.
+       *
+       * const countItems = playlist.getSize(); // 4
+       */
+      getSize(): number;
+      /**
+       * Get the timeline of the playlist.
+       *
+       * @example // Get timeline windows.
+       *
+       * const timeline = playlist.getTimeline();
+       * const windows = timeline?.getWindows();
+       *
+       * @example // Get the current timeline window.
+       *
+       * const timeline = playlist.getTimeline();
+       * const timelineWindow = timeline?.getCurrentWindow();
+       */
+      getTimeline(): clpp.media.Timeline|null;
+      /**
+       * Load items to the playlist and start playing the first one.
+       *
+       * @param index the index of the item to start playback at.
+       *   Currently only 0 is supported.
+       * @param configs a list of items
+       *   where each config must contain at least an `id` and a `source`.
+       *
+       * @example // Open a playlist of two items, start from the position of 2 minutes and automatically start playback.
+       *
+       * await playlist.open(0, [
+       *   {
+       *     id: 'ASSET1',
+       *     source: { url: '...' },
+       *     autoplay: true,
+       *     playlist: {
+       *       startTime: 120,
+       *     }
+       *   },
+       *   {
+       *     id: 'ASSET2',
+       *     source: { url: '...' }
+       *   }
+       * ]);
+       */
+      open(index: number, configs: Array<clpp.PlayerConfiguration>): Promise<void>;
+      /**
+       * Release the playlist instance resources.
+       * The playlist can load another source after it was released.
+       *
+       * @example // Release and reset the playlist.
+       *
+       * await playlist.release();
+       */
+      release(): Promise<void>;
+      /**
+       * Seek to a position relative to the current position.
+       * This may result in seeking to one of the following/preceding items
+       * in the playlist.
+       *
+       * @param offset the offset in seconds relative to the current
+       *   position to seek by. A positive value seeks forward, a negative value
+       *   seeks backward.
+       *
+       * @example // Seek 2 minutes forward.
+       *
+       * await playlist.seekWith(120);
+       *
+       * @example // Seek 2 minutes backward.
+       *
+       * await playlist.seekWith(-120);
+       */
+      seekWith(offset: number): Promise<void>;
+      setCdnErrorCallback(): void;
+    }
   }
   
   namespace smooth {
@@ -8218,8 +8515,8 @@ export namespace clpp {
        * alternate encoding/alphabet also known as "base64url".
        *
        * @param data 
-       * @param opt_padding If true, pad the output with equals signs.
-       *   Defaults to true.
+       * @param opt_padding If true, pad the output with equals
+       *   signs. Defaults to true.
        */
       static toBase64Url(data: BufferSource, opt_padding?: boolean): string;
       /**