@castlabs/prestoplay 6.14.1 → 6.16.0

package/typings.d.ts

@@ -892,6 +892,22 @@ export namespace clpp {
     xlinkFailGracefully: boolean;
   }
   
+  /**
+   * Media source configuration.
+   */
+  export type MediaSourceConfiguration = {
+    /**
+     * The switching
+     * strategy determines how to handle codec changes during playback. The `SMOOTH`
+     * strategy uses `SourceBuffer.changeType()` - if it’s available and reliably
+     * supported on a device - to dynamically switch between streams encoded with
+     * different codecs. The `PREVENT` strategy, which is the default, actively
+     * tries to prevent scenarios where different codecs are available for
+     * switching, whether through ABR or user selection.
+     */
+    codecSwitchingStrategy: clpp.CodecSwitchingStrategy;
+  }
+  
   /**
    * Mux Data plugin configuration.
    */
@@ -1161,6 +1177,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.
      */
@@ -1186,6 +1209,10 @@ export namespace clpp {
      * Manifest configuration and settings.
      */
     manifest?: Partial<clpp.ManifestConfiguration>;
+    /**
+     * Media source configuration and settings.
+     */
+    mediaSource?: Partial<clpp.MediaSourceConfiguration>;
     /**
      * Defaults to undefined. 
      * 
@@ -1204,6 +1231,10 @@ export namespace clpp {
      * back into foreground.
      */
     pauseWhenInBackground?: boolean;
+    /**
+     * Playlist-related configuration.
+     */
+    playlist?: Partial<clpp.PlaylistConfiguration>;
     /**
      * Defaults to `false`. 
      * 
@@ -1290,8 +1321,7 @@ export namespace clpp {
      */
     safari?: Partial<clpp.SafariConfiguration>;
     /**
-     * SIMID plugin
-     * configuration
+     * SIMID plugin configuration
      */
     simid?: Partial<clpp.SimidConfiguration>;
     /**
@@ -1391,6 +1421,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 +2313,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 +2339,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;
     /**
@@ -2785,6 +2871,32 @@ export namespace clpp {
     severity: clpp.Error.Severity;
   }
   
+  /**
+   * Codec switching strategy.
+   */
+  export enum CodecSwitchingStrategy {
+    /**
+     * Prevent codec switching. This strategy actively tries to prevent a
+     * situation where different codecs are available for switching, whether by
+     * ABR or user selection. It select only the codecs that are possible to adapt
+     * within the period and between periods.
+     */
+    PREVENT = "prevent",
+    /**
+     * Enable codec switching using `SourceBuffer.changeType()`. This checks if
+     * `SourceBuffer.changeType()` is available and reliably supported on a
+     * device, and if so, uses it.
+     * Note: Some devices expose the `MediaSource.changeType()` API but are
+     * known to have unreliable support, which can lead to issues like playback
+     * hanging after the `changeType()` request. Currently, we explicitly include
+     * Tizen 6.0 and 6.5 in the list of devices with problematic `changeType()`
+     * support and disable the use of the `SMOOTH` strategy to prevent potential
+     * issues. We are also aware that some Chromecast devices and Edge on Windows
+     * have similar problems, so these may be added to the list in the future.
+     */
+    SMOOTH = "smooth",
+  }
+  
   /**
    * Speed-up mode to use during trick play.
    */
@@ -3124,6 +3236,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.
      */
@@ -4845,6 +4979,21 @@ export namespace clpp {
        * E.g. it is not a direct parent of the video element.
        */
       INVALID_CONTAINER_ELEMENT = 7006,
+      /**
+       * 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.
        */
@@ -6427,57 +6576,6 @@ 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 and shutting
        * down all operations. Returns a Promise which is resolved when destruction
@@ -6709,6 +6807,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;
@@ -7550,6 +7728,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 {
@@ -8225,8 +8561,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;
       /**