@gcorevideo/player 2.20.9 → 2.20.12

package/dist/player.d.ts

@@ -3,9 +3,26 @@
  *
  * @remarks
  * This package provides a video player for the Gcore streaming platform.
- * It is built on top of the Clappr library and provides a framework for building custom integrations.
+ * It is built on top of the {@link https://github.com/clappr/clappr | Clappr} library and provides a framework for building custom integrations.
  * Start with {@link Player} for more information.
  *
+ * Various plugins (marked with `PLUGIN` keyword) are available to extend the player with additional features.
+ * @example
+ * ```ts
+ * import { Player, MediaControl, ErrorScreen } from '@gcorevideo/player'
+ *
+ * Player.registerPlugin(MediaControl)
+ * Player.registerPlugin(ErrorScreen)
+ *
+ * const player = new Player({
+ *   autoPlay: true,
+ *   mute: true,
+ *   sources: [{ source: 'https://example.com/a.mpd', mimeType: 'application/dash+xml' }],
+ * })
+ *
+ * player.attachTo(document.getElementById('container'))
+ * ```
+ *
  * @packageDocumentation
  */
 
@@ -28,7 +45,7 @@ import { UICorePlugin } from '@clappr/core';
 import { UIObject } from '@clappr/core';
 
 /**
- * Adds an audio track selector to the media control UI.
+ * `PLUGIN` that adds an audio track selector to the media control UI.
  * @beta
  */
 export declare class AudioSelector extends UICorePlugin {
@@ -98,7 +115,7 @@ export declare class AudioSelector extends UICorePlugin {
 }
 
 /**
- * Displays a big mute button over the video when it's muted.
+ * `PLUGIN` that displays a big mute button over the video when it's muted.
  * Once pressed, it unmutes the video.
  * @beta
  */
@@ -158,7 +175,7 @@ declare type BitrateTrackRecord = {
 };
 
 /**
- * Adds the gear button that triggers extra options menu on the right side of the {@link MediaControl | media control} UI
+ * `PLUGIN` that adds the gear button with an extra options menu on the right side of the {@link MediaControl | media control} UI
  * @beta
  * @remarks
  * The plugins provides a base for attaching custom settings UI in the gear menu
@@ -229,7 +246,7 @@ export declare class BottomGear extends UICorePlugin {
 }
 
 /**
- * PLUGIN that displays useful network-related statistics.
+ * `PLUGIN` that displays useful network-related statistics.
  * @beta
  *
  * @remarks
@@ -307,7 +324,7 @@ export declare class ClapprNerdStats extends UICorePlugin {
 }
 
 /**
- * PLIGIN that collects useful statistics about playback performance.
+ * `PLUGIN` that collects useful statistics about playback performance.
  * @beta
  * @remarks
  * This plugin does not render anything and is supposed to be extended or used together with other plugins that actually render something.
@@ -386,7 +403,7 @@ export declare class ClapprStats extends ContainerPlugin {
 }
 
 /**
- * Adds a behavior of toggling the playback state on click over the container
+ * `PLUGIN` that adds a behavior of toggling the playback state on click over the container
  * @beta
  */
 export declare class ClickToPause extends ContainerPlugin {
@@ -413,7 +430,7 @@ export declare class ClickToPause extends ContainerPlugin {
 }
 
 /**
- * PLUGIN that shows text over the seekbar to indicate the current clip.
+ * `PLUGIN` that shows text over the seekbar to indicate the current clip.
  * @beta
  * @remarks
  * Depends on:
@@ -471,15 +488,16 @@ export declare interface ClipsPluginSettings {
 }
 
 /**
- * @beta
+ * @public
  */
-export declare type ContainerPluginConstructor = ((container: unknown) => PlayerPlugin) & {
-    type: 'container';
+export declare type ContainerPluginConstructor = {
+    new (container: Container): PlayerPlugin;
+    type: string;
 };
 
 /**
  * Dimensions of the player container DOM element.
- * @beta
+ * @public
  */
 export declare type ContainerSize = {
     width: number;
@@ -487,7 +505,7 @@ export declare type ContainerSize = {
 };
 
 /**
- * Displays a small context menu when clicked on the player container.
+ * `PLUGIN` that displays a small context menu when clicked on the player container.
  * @beta
  * @remarks
  * Configuration options - {@link ContextMenuPluginSettings}
@@ -543,7 +561,7 @@ export declare class ContextMenu extends UIContainerPlugin {
 }
 
 /**
- * The plugin adds a context menu to the player.
+ * Context menu plugin settings
  * @beta
  */
 export declare interface ContextMenuPluginSettings {
@@ -553,21 +571,23 @@ export declare interface ContextMenuPluginSettings {
 }
 
 /**
- * @beta
+ * @public
  */
-export declare type CorePluginConstructor = ((core: unknown) => PlayerPlugin) & {
-    type: 'core';
+export declare type CorePluginConstructor = {
+    new (core: Core): PlayerPlugin;
+    type: string;
 };
 
 /**
  * A plain JS object that must conform to the DASH.js settings schema.
- * @beta
+ * @public
  * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html | DASH.js settings}
  */
 export declare type DashSettings = Record<string, unknown>;
 
 /**
- * Adds the DVR controls to the media control UI
+ * `PLUGIN` that adds the DVR controls to the media control UI
+ *
  * @beta
  *
  * @remarks
@@ -575,7 +595,9 @@ export declare type DashSettings = Record<string, unknown>;
  *
  * - {@link MediaControl}
  *
- * The plugin renders the live stream indicator and the DVR seek bar, if DVR is enabled, in the media control UI.
+ * The plugin renders live stream indicator.
+ * If DVR is enabled, the indicator shows whether the current position is at the live edge of the stream or not.
+ * In the latter case, the indicator can be clicked to seek to the live edge.
  */
 export declare class DvrControls extends UICorePlugin {
     private static readonly template;
@@ -602,11 +624,11 @@ export declare class DvrControls extends UICorePlugin {
         class: string;
         'data-dvr-controls': string;
     };
-    constructor(core: Core);
     /**
      * @internal
      */
     bindEvents(): void;
+    private onCoreReady;
     private bindContainerEvents;
     private onDvrChanged;
     private click;
@@ -618,32 +640,14 @@ export declare class DvrControls extends UICorePlugin {
     render(): this;
 }
 
-/**
- * An error fired in the player and plugins code to be handled in the UI
- * @beta
- */
-export declare type ErrorDesc = {
-    description: string;
-    level: string;
-    code: string;
-    origin: string;
-    scope: string;
-    raw?: string;
-    UI?: {
-        icon?: string;
-        title: string;
-        message: string;
-    };
-};
-
 /**
  * Levels of severity of errors. Non-fatal errors usually can be ignored.
- * @beta
+ * @public
  */
 export declare type ErrorLevel = 'FATAL' | 'WARN' | 'INFO';
 
 /**
- * PLUGIN that displays errors nicely in the overlay on top of the player.
+ * `PLUGIN` that displays errors nicely in the overlay on top of the player.
  * @beta
  */
 export declare class ErrorScreen extends UICorePlugin {
@@ -699,24 +703,42 @@ export declare type ErrorScreenPluginSettings = {
 };
 
 /**
- * The plugin adds custom favicon to the player's tab.
+ * `PLUGIN` that changes the favicon according to the player's state.
  * @beta
+ * @remarks
+ * There are three states: stopped, playing and paused.
  */
 export declare class Favicon extends CorePlugin {
-    private _container;
     private oldIcon;
     private playIcon;
     private pauseIcon;
     private stopIcon;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
+    /**
+     * @internal
+     */
     constructor(core: Core);
-    configure(): void;
+    /**
+     * @internal
+     */
     bindEvents(): void;
     private containerChanged;
+    /**
+     * @internal
+     */
     disable(): void;
+    /**
+     * @internal
+     */
     destroy(): void;
     private createIcon;
     private setPlayIcon;
@@ -725,6 +747,16 @@ export declare class Favicon extends CorePlugin {
     private changeIcon;
 }
 
+/**
+ * @beta
+ */
+export declare interface FaviconPluginSettings {
+    /**
+     * CSS color of the favicon.
+     */
+    faviconColor?: string;
+}
+
 /**
  * An element inside the gear menu
  * @beta
@@ -732,7 +764,7 @@ export declare class Favicon extends CorePlugin {
 export declare type GearItemElement = 'quality' | 'rate' | 'nerd';
 
 /**
- * An example Google Analytics integration plugin
+ * `PLUGIN` that integrates with Google Analytics
  * @beta
  */
 export declare class GoogleAnalytics extends ContainerPlugin {
@@ -775,12 +807,12 @@ export declare interface InitEventData {
 /**
  * An ISO 639-1 language code.
  * @example `pt`
- * @beta
+ * @public
  */
 export declare type LangTag = string;
 
 /**
- * PLUGIN that provides a UI to select the desired quality level of the playback.
+ * `PLUGIN` that provides a UI to select the desired quality level of the playback.
  * @beta
  *
  * @remarks
@@ -895,7 +927,7 @@ export declare interface LevelSelectorPluginSettings {
 export { Logger }
 
 /**
- * The plugin adds custom logo to the player.
+ * `PLUGIN` that adds custom logo to the player.
  * @beta
  */
 export declare class Logo extends UIContainerPlugin {
@@ -928,11 +960,11 @@ export declare class Logo extends UIContainerPlugin {
 export { LogTracer }
 
 /**
- * PLUGIN that provides a foundation for developing custom media controls UI.
+ * `PLUGIN` that provides a foundation for developing custom media controls UI.
  * @beta
  * @remarks
  * The methods exposed are to be used by the other plugins that extend the media control UI.
- * The plugin registration should be arranged so that MediaControl is initialized before every other plugin that depends on it.
+ * The plugin registration should be arranged so that MediaControl is initialized before every other `PLUGIN` that depends on it.
  * @example
  * ```ts
  * Player.registerPlugin(MediaControl) // <--- This must go first
@@ -1154,6 +1186,12 @@ export declare class MediaControl extends UICorePlugin {
      * @returns  ZeptoSelector of the right panel element
      */
     getRightPanel(): any;
+    /**
+     * Get the left panel area to append custom elements to
+     * @returns  ZeptoSelector of the left panel element
+     */
+    getLeftPanel(): any;
+    getCenterPanel(): any;
     private resetIndicators;
     private initializeIcons;
     private setSeekPercentage;
@@ -1206,12 +1244,6 @@ export declare enum MediaControlEvents {
     MEDIACONTROL_GEAR_RENDERED = "mediacontrol:gear:rendered"
 }
 
-/**
- * Media delivery protocol
- * @beta
- */
-export declare type MediaTransport = 'dash' | 'hls';
-
 /**
  * @beta
  */
@@ -1260,7 +1292,7 @@ declare type Metrics = {
 declare type MetricsUpdateFn = (metrics: Metrics) => void;
 
 /**
- * PLUGIN that adds support for loading multiple streams and switching between them using the media control UI.
+ * `PLUGIN` that adds support for loading multiple streams and switching between them using the media control UI.
  * @beta
  */
 export declare class MultiCamera extends UICorePlugin {
@@ -1313,7 +1345,7 @@ export declare class MultiCamera extends UICorePlugin {
 }
 
 /**
- * Enables picture in picture mode.
+ * `PLUGIN` that enables picture in picture mode.
  * @beta
  * @remarks
  * Depends on:
@@ -1360,7 +1392,7 @@ export declare class PictureInPicture extends UICorePlugin {
 
 /**
  * An error occurred during the playback.
- * @beta
+ * @public
  */
 export declare interface PlaybackError {
     /**
@@ -1397,12 +1429,13 @@ export declare interface PlaybackError {
     UI?: {
         title: string;
         message: string;
+        icon?: string;
     };
 }
 
 /**
  * Codes of errors occurring within the playback component.
- * @beta
+ * @public
  */
 export declare enum PlaybackErrorCode {
     /**
@@ -1421,12 +1454,12 @@ export declare enum PlaybackErrorCode {
 
 /**
  * Module to perform the playback.
- * @beta
+ * @public
  */
 export declare type PlaybackModule = 'dash' | 'hls' | 'html5_video';
 
 /**
- * PLUGIN that allows changing the playback speed of the video.
+ * `PLUGIN` that allows changing the playback speed of the video.
  * @beta
  *
  * @remarks
@@ -1501,14 +1534,14 @@ export declare class PlaybackRate extends UICorePlugin {
 }
 
 /**
- * Type of a stream playback
- * @beta
+ * Type of a stream
+ * @public
  */
 export declare type PlaybackType = 'live' | 'vod';
 
 /**
- * The main component to use in the application code.
- * @beta
+ * `MAIN` component to use in the application code.
+ * @public
  * @remarks
  * The Player object provides very basic API to control playback.
  * To build a sophisticated UI, use the plugins framework to tap into the Clappr core.
@@ -1674,13 +1707,22 @@ export declare class Player {
      * ```
      */
     static registerPlugin(plugin: PlayerPluginConstructor): void;
-    private static getRegisteredPlugins;
-    private static corePlugins;
     /**
      * Unregisters a plugin registered earlier with {@link Player.registerPlugin}.
-     * @param plugin - a plugin class
+     * @remarks
+     * It can be also used to unregister a built-in default plugin.
+     *
+     * Currently, the plugins that are always registered are:
+     *
+     * - {@link https://github.com/clappr/clappr-core/blob/3126c3a38a6eee9d5aba3918b194e6380fa1178c/src/plugins/strings/strings.js | 'strings'}, which supports internationalization of the player UI
+     *
+     * - {@link https://github.com/clappr/clappr-core/blob/3126c3a38a6eee9d5aba3918b194e6380fa1178c/src/plugins/sources/sources.js | 'sources'}, which lets to specify multiple media sources and selects the first suitable playback module
+     *
+     * @param name - name of the plugin
      */
-    static unregisterPlugin(plugin: PlayerPluginConstructor): void;
+    static unregisterPlugin(name: string): void;
+    private static getRegisteredPlugins;
+    private static corePlugins;
     private setConfig;
     private initPlayer;
     private tuneIn;
@@ -1696,7 +1738,7 @@ export declare class Player {
 
 /**
  * Subsystems of a player component.
- * @beta
+ * @public
  */
 export declare type PlayerComponentType = 'container' | 'core' | 'playback';
 
@@ -1739,7 +1781,7 @@ export declare type PlayerComponentType = 'container' | 'core' | 'playback';
  *   },
  * }
  * ```
- * @beta
+ * @public
  */
 export declare interface PlayerConfig extends Record<string, unknown> {
     /**
@@ -1797,19 +1839,19 @@ export declare interface PlayerConfig extends Record<string, unknown> {
 
 /**
  * @remarks `true` is equivalent to `'all'`, `false` is equivalent to `'none'`
- * @beta
+ * @public
  */
 export declare type PlayerDebugSettings = PlayerDebugTag | boolean;
 
 /**
  * Debug output category selector
- * @beta
+ * @public
  */
 export declare type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none';
 
 /**
  * A top-level event on the player object
- * @beta
+ * @public
  */
 export declare enum PlayerEvent {
     /**
@@ -1866,12 +1908,12 @@ export declare enum PlayerEvent {
 /**
  * Type of a listener callback function for a player event.
  * See the description of the event parameters in {@link PlayerEvent}.
- * @beta
+ * @public
  */
 export declare type PlayerEventHandler<E extends PlayerEvent> = (...args: PlayerEventParams<E>) => void;
 
 /**
- * @beta
+ * @public
  */
 export declare type PlayerEventParams<E extends PlayerEvent> = E extends PlayerEvent.Seek ? [number] : E extends PlayerEvent.VolumeUpdate ? [number] : E extends PlayerEvent.TimeUpdate ? [TimePosition] : E extends PlayerEvent.Resize ? [{
     width: number;
@@ -1880,7 +1922,7 @@ export declare type PlayerEventParams<E extends PlayerEvent> = E extends PlayerE
 
 /**
  * A media source to fetch the media data from
- * @beta
+ * @public
  */
 export declare type PlayerMediaSource = string | PlayerMediaSourceDesc;
 
@@ -1890,7 +1932,7 @@ export declare type PlayerMediaSource = string | PlayerMediaSourceDesc;
  * @remarks
  * When the MIME type is provided, it helps the player determine the appropriate playback engine.
  * If omitted, the player will attempt to detect the type from the source URL extension.
- * @beta
+ * @public
  */
 export declare interface PlayerMediaSourceDesc {
     /**
@@ -1905,22 +1947,21 @@ export declare interface PlayerMediaSourceDesc {
 }
 
 /**
- * @beta
+ * @public
  * @see {@link https://clappr.github.io/classes/UIContainerPlugin.html},
  * {@link https://clappr.github.io/classes/ContainerPlugin.html}
  */
 export declare type PlayerPlugin = {
-    new (...args: any[]): unknown;
     name: string;
 };
 
 /**
- * @beta
+ * @public
  */
 export declare type PlayerPluginConstructor = CorePluginConstructor | ContainerPluginConstructor;
 
 /**
- * Displays a poster image in the background and a big play button on top when playback is stopped
+ * `PLUGIN` that displays a poster image in the background and a big play button on top when playback is stopped
  * @beta
  * @remarks
  * When the playback is stopped, media control UI is disabled.
@@ -2015,7 +2056,7 @@ export declare class Poster extends UIContainerPlugin {
 
 /**
  * A level of quality within a media source.
- * @beta
+ * @public
  */
 export declare interface QualityLevel {
     /**
@@ -2039,7 +2080,7 @@ export declare interface QualityLevel {
 export { reportError_2 as reportError }
 
 /**
- * The plugin adds a seek time indicator to the media control UI.
+ * `PLUGIN` that adds a seek time indicator to the media control UI.
  * @beta
  */
 export declare class SeekTime extends UICorePlugin {
@@ -2083,7 +2124,7 @@ export { SentryTracer }
 export { setTracer }
 
 /**
- * PLUGIN that adds a share button to the media control UI.
+ * `PLUGIN` that adds a share button to the media control UI.
  * @beta
  */
 export declare class Share extends UICorePlugin {
@@ -2123,7 +2164,7 @@ export declare class Share extends UICorePlugin {
 }
 
 /**
- * PLUGIN that adds skip controls to the media control UI.
+ * `PLUGIN` that adds skip controls to the media control UI.
  * @beta
  */
 export declare class SkipTime extends UICorePlugin {
@@ -2153,7 +2194,7 @@ export declare class SkipTime extends UICorePlugin {
 }
 
 /**
- * This plugin is responsible for managing the automatic failover between sources.
+ * `PLUGIN` that is responsible for managing the automatic failover between sources.
  * @beta
  * @remarks
  * Have a look at the {@link https://miro.com/app/board/uXjVLiN15tY=/?share_link_id=390327585787 | source failover diagram} for the details
@@ -2216,7 +2257,7 @@ export declare enum SpinnerEvents {
 }
 
 /**
- * PLUGIN that shows a pending operation indicator when playback is buffering or in a similar state
+ * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state
  * @beta
  * @remarks
  * Events emitted- {@link SpinnerEvents}
@@ -2299,7 +2340,7 @@ export declare interface StartEventData {
 }
 
 /**
- * A {@link MediaControl | media control} plugin that provides a UI to select the subtitles when available.
+ * `PLUGIN` that provides a UI to select the subtitles when available.
  * @beta
  *
  * @remarks
@@ -2407,7 +2448,7 @@ export declare class Subtitles extends UICorePlugin {
 }
 
 /**
- * PLUGIN that collects and reports the performance statistics.
+ * `PLUGIN` that collects and reports the performance statistics.
  * @beta
  * @remarks
  * This plugin is experimental and its API is likely to change.
@@ -2522,7 +2563,7 @@ export declare type TelemetryRecord = {
 export declare type TelemetrySendFn = (data: TelemetryRecord) => void;
 
 /**
- * Displays the thumbnails of the video when available.
+ * `PLUGIN` that displays the thumbnails of the video when available.
  * @beta
  * @example
  * ```ts
@@ -2614,7 +2655,7 @@ export declare type ThumbnailsPluginSettings = {
 
 /**
  * Current playback time and total duration of the media.
- * @beta
+ * @public
  */
 export declare interface TimePosition {
     /**
@@ -2645,14 +2686,14 @@ export declare type TimeUpdate = TimePosition & {
 
 /**
  * Playback time in seconds since the beginning of the stream (or a segment for the live streams)
- * @beta
+ * @public
  */
 export declare type TimeValue = number;
 
 export { trace }
 
 /**
- * @beta
+ * @public
  */
 export declare type TranslationKey = string;
 
@@ -2678,15 +2719,15 @@ export declare type TranslationKey = string;
  * }
  * ```
  *
- * @beta
+ * @public
  */
 export declare type TranslationSettings = Partial<Record<LangTag, Record<TranslationKey, string>>>;
 
 /**
- * Preferred media delivery protocol
- * @beta
+ * Preferred streaming media delivery protocol
+ * @public
  */
-export declare type TransportPreference = MediaTransport;
+export declare type TransportPreference = 'dash' | 'hls';
 
 /**
  * Version information about the gplayer and its main dependencies
@@ -2701,7 +2742,7 @@ export declare function version(): {
 };
 
 /**
- * Applies fade effect to the player's volume change.
+ * `PLUGIN` that applies fade effect to the player's volume change.
  * @beta
  */
 export declare class VolumeFade extends UICorePlugin {