@gcorevideo/player 2.22.1 → 2.22.3

package/dist/player.d.ts

@@ -173,14 +173,72 @@ declare type BitrateTrackRecord = {
 };
 
 /**
- * `PLUGIN` that adds the gear button with an extra options menu on the right side of the {@link MediaControl | media control} UI
+ * `PLUGIN` that adds a button to extend the media controls UI with extra options.
  * @beta
  * @remarks
- * The plugins provides a base for attaching custom settings UI in the gear menu
+ * The plugin renders small gear icon to the right of the media controls.
+ * It provides a base for attaching custom settings UI in the gear menu
  *
  * Depends on:
  *
  * - {@link MediaControl}
+ *
+ * @example
+ * You can use bottom gear to add custom settings UI to the gear menu.
+ *
+ * ```ts
+ * import { BottomGear } from '@gcorevideo/player/plugins/bottom-gear';
+ *
+ * class CustomOptionsPlugin extends UICorePlugin {
+ *   // ...
+ *
+ *   override get events() {
+ *     return {
+ *       'click #my-button': 'doMyAction',
+ *     }
+ *   }
+ *
+ *   private doMyAction() {
+ *     // ...
+ *   }
+ *
+ *   override render() {
+ *     const bottomGear = this.core.getPlugin('bottom_gear');
+ *     if (!bottomGear) {
+ *       return this;
+ *     }
+ *     this.$el.html('<button class="custom-option">Custom option</button>');
+ *     // Put rendered element into the gear menu
+ *     bottomGear.addItem('custom').html(this.$el)
+ *     return this;
+ *   }
+ *
+ *   // alternatively, add an option with a submenu
+ *   override render() {
+ *     this.$el.html(template(templateHtml)({
+ *       // ...
+ *     })));
+ *     return this;
+ *   }
+ *
+ *   private addGearOption() {
+ *     this.core.getPlugin('bottom_gear')
+ *       .addItem('custom', this.$el)
+ *       .html($('<button class="custom-option">Custom option</button>'))
+ *   }
+ *
+ *   override bindEvents() {
+ *     this.listenToOnce(this.core, ClapprEvents.CORE_READY, () => {
+ *       const bottomGear = this.core.getPlugin('bottom_gear');
+ *       assert(bottomGear, 'bottom_gear plugin is required');
+ *       // simple case
+ *       this.listenTo(bottomGear, GearEvents.RENDERED, this.render);
+ *       // or with a submenu
+ *       this.listenTo(bottomGear, GearEvents.RENDERED, this.addGearOption);
+ *      });
+ *   }
+ * }
+ * ```
  */
 export declare class BottomGear extends UICorePlugin {
     private isHd;
@@ -209,22 +267,35 @@ export declare class BottomGear extends UICorePlugin {
      * @internal
      */
     get events(): {
-        'click .button-gear': string;
+        'click #gear-button': string;
     };
     /**
      * @internal
      */
     bindEvents(): void;
     /**
-     * @param name - Name of a gear menu placeholder item to attach custom UI
-     * @returns Zepto result of the element
-     */
-    getElement(name: GearOptionsItem): ZeptoResult | null;
-    /**
-     * Replaces the content of the gear menu
-     * @param content - Zepto result of the element
+     * Adds a custom option to the gear menu
+     * @param name - A unique name of the option
+     * @param $subMenu - The submenu to attach to the option
+     * @returns The added item placeholder to attach custom markup
+     * @remarks
+     * When called with $submenu param, a click on the added item will toggle the submenu visibility.
+     *
+     * When added without submenu, it's responsibility of the caller to handle the click event however needed.
+     * @example
+     * ```ts
+     * class MyPlugin extends UICorePlugin {
+     *   override render() {
+     *     this.$el.html('<div class="my-awesome-settings">...</div>')
+     *     this.core.getPlugin('bottom_gear')
+     *       ?.addItem('custom', this.$el)
+     *       .html($('<button>Custom settings</button>'))
+     *     return this
+     *   }
+     * }
+     * ```
      */
-    setContent(content: ZeptoResult): void;
+    addItem(name: string, $subMenu?: ZeptoResult): ZeptoResult;
     private onActiveContainerChanged;
     private bindContainerEvents;
     private highDefinitionUpdate;
@@ -233,14 +304,15 @@ export declare class BottomGear extends UICorePlugin {
      */
     render(): this;
     /**
-     * Re-renders the gear menu.
-     * It fires the {@link MediaControlEvents.MEDIACONTROL_GEAR_RENDERED | MEDIACONTROL_GEAR_RENDERED} event,
-     * which the plugins that attach to the gear menu can listen to to re-render themselves.
+     * Collapses any submenu open back to the gear menu.
+     * @remarks
+     * Should be called by the UI plugin that added a gear item with a submenu when the latter is closed (e.g., when a "back" button is clicked).
      */
     refresh(): void;
     private toggleGearMenu;
     private hide;
     private onCoreReady;
+    private onMediaControlRendered;
 }
 
 /**
@@ -250,8 +322,6 @@ export declare class BottomGear extends UICorePlugin {
  * @remarks
  * Depends on:
  *
- * - {@link MediaControl}
- *
  * - {@link BottomGear}
  *
  * - {@link ClapprStats}
@@ -268,6 +338,7 @@ export declare class ClapprNerdStats extends UICorePlugin {
     private showing;
     private shortcut;
     private iconPosition;
+    private static readonly buttonTemplate;
     /**
      * @internal
      */
@@ -303,7 +374,7 @@ export declare class ClapprNerdStats extends UICorePlugin {
      * @internal
      */
     bindEvents(): void;
-    private init;
+    private onCoreReady;
     private toggle;
     private show;
     private hide;
@@ -401,7 +472,7 @@ export declare class ClapprStats extends ContainerPlugin {
 }
 
 /**
- * `PLUGIN` that adds a behavior of toggling the playback state on click over the container
+ * A small `PLUGIN` that toggles the playback state on click over the video container
  * @beta
  */
 export declare class ClickToPause extends ContainerPlugin {
@@ -490,7 +561,7 @@ export declare interface ClipsPluginSettings {
  * @beta
  *
  * @remarks
- * The plugin is activated when closed captions tracks are provided with the media source.
+ * The plugin is activated when closed captions tracks are detected in the media source.
  * It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
  *
  * Depends on:
@@ -507,7 +578,7 @@ export declare interface ClipsPluginSettings {
  * new Player({
  *   ...
  *   cc: {
- *     language: 'en',
+ *     language: 'pt-BR',
  *   },
  * })
  * ```
@@ -593,9 +664,13 @@ declare class ClosedCaptions extends UICorePlugin {
 export { ClosedCaptions }
 export { ClosedCaptions as Subtitles }
 
+/**
+ * Configuration options for the {@link ClosedCaptions} plugin.
+ * @beta
+ */
 export declare type ClosedCaptionsPluginSettings = {
     /**
-     * Initially selected subtitles language
+     * Initially selected subtitles language.
      */
     language?: string;
 };
@@ -757,8 +832,23 @@ export declare class DvrControls extends UICorePlugin {
 export declare type ErrorLevel = 'FATAL' | 'WARN' | 'INFO';
 
 /**
- * `PLUGIN` that displays errors nicely in the overlay on top of the player.
- * @beta
+ * `PLUGIN` that displays fatal errors nicely in the overlay on top of the player.
+ * @public
+ * @remarks
+ * A fatal error is an error that prevents the player from playing the content.
+ * It's usually a network error that persists after multiple retries.
+ *
+ * The error screen should not be confused with the content stub that is shown when no media sources are available.
+ * This can happen due to the lack of the support of the given sources type or because the sources are misconfigured (e.g., omitted).
+ *
+ * Configuration options - {@link ErrorScreenPluginSettings}
+ *
+ * @example
+ * ```ts
+ * import { ErrorScreen, Player } from '@gcorevideo/player'
+ *
+ * Player.registerPlugin(ErrorScreen)
+ * ```
  */
 export declare class ErrorScreen extends UICorePlugin {
     private err;
@@ -802,8 +892,8 @@ export declare class ErrorScreen extends UICorePlugin {
 }
 
 /**
- * Configuration options for the {@link ErrorScreen | error screen} plugin.
- * @beta
+ * Configuration options for the {@link ErrorScreen} plugin.
+ * @public
  */
 export declare type ErrorScreenPluginSettings = {
     /**
@@ -812,6 +902,17 @@ export declare type ErrorScreenPluginSettings = {
     noReload?: boolean;
 };
 
+/**
+ * Settings for the {@link ErrorScreen} plugin.
+ * @public
+ */
+export declare type ErrorScreenSettings = {
+    /**
+     * Whether to hide the reload button. The reload button triggers reload of the current source.
+     */
+    noReload?: boolean;
+};
+
 /**
  * `PLUGIN` that changes the favicon according to the player's state.
  * @beta
@@ -868,15 +969,15 @@ export declare interface FaviconPluginSettings {
 }
 
 /**
- * @deprecated Use {@link GearOptionsItem} instead
- */
-export declare type GearItemElement = GearOptionsItem;
-
-/**
- * An element inside the gear menu
+ * Events triggered by the plugin
  * @beta
  */
-export declare type GearOptionsItem = 'quality' | 'rate' | 'nerd';
+export declare enum GearEvents {
+    /**
+     * Use this event to accurately attach an item to the gear menu
+     */
+    RENDERED = "rendered"
+}
 
 /**
  * `PLUGIN` that integrates with Google Analytics
@@ -956,7 +1057,8 @@ export declare class LevelSelector extends UICorePlugin {
     private levelLabels;
     private removeAuto;
     private isHd;
-    private isOpen;
+    private currentText;
+    private selectedLevelId;
     private static readonly buttonTemplate;
     private static readonly listTemplate;
     /**
@@ -980,11 +1082,8 @@ export declare class LevelSelector extends UICorePlugin {
         class: string;
         'data-level-selector': string;
     };
-    private currentText;
-    private selectedLevelId;
     get events(): {
         'click .gear-sub-menu_btn': string;
-        'click .gear-option': string;
         'click .go-back': string;
     };
     /**
@@ -993,31 +1092,30 @@ export declare class LevelSelector extends UICorePlugin {
     bindEvents(): void;
     private onCoreReady;
     private onGearRendered;
-    private bindPlaybackEvents;
+    private onActiveContainerChange;
+    private updateHd;
     private onStop;
     private shouldRender;
     /**
      * @internal
      */
     render(): this;
-    private renderButton;
     private renderDropdown;
+    private updateButton;
     private get maxLevel();
-    private fillLevels;
+    private onLevelsAvailable;
     private makeLevelsLabels;
-    private onLevelSelect;
+    private onSelect;
     private goBack;
     private setLevel;
-    private onShowLevelSelectMenu;
     private allLevelElements;
     private levelElement;
     private onLevelSwitchStart;
     private onLevelSwitchEnd;
     private updateText;
     private getLevelLabel;
-    private updateCurrentLevel;
+    private onBitrate;
     private highlightCurrentLevel;
-    private deferRender;
 }
 
 /**
@@ -1081,6 +1179,8 @@ export { LogTracer }
  * The methods exposed are to be used by the other plugins that extend the media control UI.
  */
 export declare class MediaControl extends UICorePlugin {
+    private customAreaElements;
+    private customAreaHandler?;
     private buttonsColor;
     private currentDurationValue;
     private currentPositionValue;
@@ -1105,13 +1205,11 @@ export declare class MediaControl extends UICorePlugin {
     private userDisabled;
     private userKeepVisible;
     private verticalVolume;
-    private $audioTracksSelector;
     private $clipText;
     private $clipTextContainer;
     private $duration;
     private $fullscreenToggle;
     private $multiCameraSelector;
-    private $pip;
     private $playPauseToggle;
     private $playStopToggle;
     private $playbackRate;
@@ -1284,13 +1382,14 @@ export declare class MediaControl extends UICorePlugin {
      * ```
      */
     getElement(name: MediaControlElement): ZeptoResult | null;
-    putElement(name: MediaControlElement, element: HTMLElement): void;
+    putElement(name: MediaControlElement, element: ZeptoResult): void;
+    handleCustomArea(handler: (name: string, content: HTMLElement) => void): void;
     /**
      * Toggle the visibility of a media control element
      * @param name - The name of the media control element
      * @param show - Whether to show or hide the element
      */
-    toggleElement(name: MediaControlElement, show: boolean): void;
+    toggleElement(area: MediaControlElement, show: boolean): void;
     private getRightPanel;
     private getLeftPanel;
     private getCenterPanel;
@@ -1335,18 +1434,7 @@ export declare class MediaControl extends UICorePlugin {
  * Media control elements, mount points for additional plugins
  * @beta
  */
-export declare type MediaControlElement = 'audiotracks' | 'cc' | 'clipText' | 'dvr' | 'duration' | 'gear' | 'pip' | 'playbackRate' | 'position' | 'seekBarContainer';
-
-/**
- * Custom events emitted by the plugins to communicate with one another
- * @beta
- */
-export declare enum MediaControlEvents {
-    /**
-     * Emitted when the gear menu is rendered
-     */
-    MEDIACONTROL_GEAR_RENDERED = "mediacontrol:gear:rendered"
-}
+export declare type MediaControlElement = 'audiotracks' | 'cc' | 'clipText' | 'dvr' | 'duration' | 'fullscreen' | 'gear' | 'multicamera' | 'pip' | 'playbackRate' | 'position' | 'seekBarContainer' | 'vr' | 'volume';
 
 /**
  * @beta
@@ -1573,17 +1661,32 @@ export declare type PlaybackModule = 'dash' | 'hls' | 'html5_video';
  * @remarks
  * Depends on:
  *
- * - {@link MediaControl | media_control}
+ * - {@link MediaControl}
  *
- * - {@link BottomGear | bottom_gear}
+ * - {@link BottomGear}
+ *
+ * It renders an option in the gear menu, which opens a dropdown with the options to change the playback rate.
+ * Note that the playback rate change is supported only for VOD or DVR-enabled live streams.
  *
- * It renders a button in the gear menu, which opens a dropdown with the options to change the playback rate.
- * Note that the playback rate change is supported only for VOD or DVR enabled live streams.
+ * Plugin settings - {@link PlaybackRateSettings}
+ *
+ * @example
+ * ```ts
+ * import { Player, PlaybackRateSettings } from '@gcorevideo/player'
+ * Player.registerPlugin(PlaybackRate)
+ * const player = new Player({
+ *   playbackRate: {
+ *     options: [
+ *       { value: 0.5, label: '0.5x' },
+ *       { value: 1, label: '1x' },
+ *     ],
+ *     defaultValue: 1,
+ *   } as PlaybackRateSettings,
+ * })
+ * ```
  */
 export declare class PlaybackRate extends UICorePlugin {
     private playbackRates;
-    private prevSelectedRate;
-    private rendered;
     private selectedRate;
     /**
      * @internal
@@ -1608,9 +1711,8 @@ export declare class PlaybackRate extends UICorePlugin {
      * @internal
      */
     get events(): {
-        'click .gear-sub-menu_btn': string;
-        'click .gear-option': string;
-        'click .go-back': string;
+        'click [data-rate]': string;
+        'click #playback-rate-back-button': string;
     };
     /**
      * @internal
@@ -1618,8 +1720,10 @@ export declare class PlaybackRate extends UICorePlugin {
     bindEvents(): void;
     private onCoreReady;
     private onActiveContainerChange;
+    private onMediaControlRendered;
     private onGearRendered;
-    private onDvrStateChanged;
+    private addGearItem;
+    private onMetaDataLoaded;
     private allRateElements;
     private rateElement;
     private onPlaybackRateChange;
@@ -1628,19 +1732,33 @@ export declare class PlaybackRate extends UICorePlugin {
      * @internal
      */
     render(): this;
-    private onStartAd;
-    private onFinishAd;
     private onPlay;
     private resetPlaybackRate;
     private onStop;
-    private onRateSelect;
-    private onShowMenu;
+    private onSelect;
     private goBack;
     private setSelectedRate;
     private getTitle;
     private highlightCurrentRate;
+    private updateGearOptionLabel;
 }
 
+/**
+ * @beta
+ */
+export declare type PlaybackRateOption = {
+    value: number;
+    label: string;
+};
+
+/**
+ * @beta
+ */
+export declare type PlaybackRateSettings = {
+    options?: PlaybackRateOption[];
+    defaultValue?: number;
+};
+
 /**
  * Type of a stream
  * @public
@@ -2304,11 +2422,47 @@ export declare class SkipTime extends UICorePlugin {
 }
 
 /**
- * `PLUGIN` that is responsible for managing the automatic failover between sources.
- * @beta
+ * `PLUGIN` that is managing the automatic failover between media sources.
+ * @public
  * @remarks
  * Have a look at the {@link https://miro.com/app/board/uXjVLiN15tY=/?share_link_id=390327585787 | source failover diagram} for the details
- * on how sources ordering and selection works.
+ * on how sources ordering and selection works. Below is a simplified diagram:
+ *
+ * ```markdown
+ * sources_list:
+ *       - a.mpd  |    +--------------------+
+ *       - b.m3u8 |--->|         init       |
+ *       - ...    |    |--------------------|
+ *                     | current_source = 0 |
+ *                     +--------------------+
+ *                            |
+ *                            |  source = a.mpd
+ *                            |  playback = dash.js
+ *                            v
+ *                      +------------------+
+ *                  +-->|   load source    |
+ *                  |   +---------|--------+
+ *                  |             v
+ *                  |   +------------------+
+ *                  |   |       play       |
+ *                  |   +---------|--------+
+ *                  |             |
+ *                  |             v
+ *                  |   +-----------------------+
+ *                  |   |  on playback_error    |
+ *                  |   |-----------------------|
+ *                  |   | current_source =      |
+ *                  |   |  (current_source + 1) |
+ *                  |   |  % len sources_list   |
+ *                  |   |                       |
+ *                  |   | delay 1..3s           |
+ *                  |   +---------------|-------+
+ *                  |                   |
+ *                  |   source=b.m3u8   |
+ *                  |   playback=hls.js |
+ *                  +-------------------+
+ *
+ * ```
  *
  * This plugin does not expose any public methods apart from required by the Clappr plugin interface.
  * It is supposed to work autonomously.
@@ -2338,7 +2492,7 @@ export declare class SourceController extends CorePlugin {
         min: string;
     };
     /**
-     * @internal
+     * @param core - The Clappr core instance.
      */
     constructor(core: Core);
     /**
@@ -2359,25 +2513,26 @@ export declare class SourceController extends CorePlugin {
 
 /**
  * Custom events emitted by the plugin
- * @beta
+ * @public
  */
 export declare enum SpinnerEvents {
     /**
      * Emitted at the end of the spinner animation cycle to facilitate smooth UI updates,
-     * e.g. {@link SourceController} listens to this event to reload the source when the spinner is hidden
+     * for instance, {@link SourceController} listens to this event to reload the source when the spinner is hidden
      */
     SYNC = "plugins:spinner:sync"
 }
 
 /**
- * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state
- * @beta
+ * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state.
+ * @public
  * @remarks
- * Events emitted- {@link SpinnerEvents}
+ * It is aliased as `Spinner` for convenience.
+ * Events emitted - {@link SpinnerEvents}
  * Other plugins can use {@link SpinnerThreeBounce.show | show} and {@link SpinnerThreeBounce.hide | hide} methods to
  * implement custom pending/progress indication scenarios.
  */
-export declare class SpinnerThreeBounce extends UIContainerPlugin {
+declare class SpinnerThreeBounce extends UIContainerPlugin {
     private userShown;
     /**
      * @internal
@@ -2409,7 +2564,9 @@ export declare class SpinnerThreeBounce extends UIContainerPlugin {
     /**
      * Shows the spinner.
      *
-     * When called, the spinner will not hide (due to its built-in logic) until {@link SpinnerThreeBounce.hide} is called
+     * The method call prevents spinner's built-in logic from automatically hiding it until {@link SpinnerThreeBounce.hide} is called
+     *
+     * @param delay - The delay in milliseconds before the spinner is shown.
      */
     show(delay?: number): void;
     /**
@@ -2423,6 +2580,8 @@ export declare class SpinnerThreeBounce extends UIContainerPlugin {
      */
     render(): this;
 }
+export { SpinnerThreeBounce as Spinner }
+export { SpinnerThreeBounce }
 
 /**
  * Playback stall event data
@@ -2452,11 +2611,6 @@ export declare interface StartEventData {
     event: TelemetryEvent.Start;
 }
 
-/**
- * @deprecated Use {@link ClosedCaptionsPluginSettings} instead.
- */
-export declare type SubtitlesPluginSettings = ClosedCaptionsPluginSettings;
-
 /**
  * `PLUGIN` that collects and reports the performance statistics.
  * @beta
@@ -2572,12 +2726,6 @@ export declare type TelemetryRecord = {
  */
 export declare type TelemetrySendFn = (data: TelemetryRecord) => void;
 
-export declare interface TextTrackItem {
-    id: number;
-    name: string;
-    track: TextTrack;
-}
-
 /**
  * `PLUGIN` that displays the thumbnails of the video when available.
  * @beta