@gcorevideo/player 2.19.14 → 2.20.1

package/dist/player.d.ts

@@ -121,6 +121,10 @@ declare type BitrateTrackRecord = {
  * @beta
  * @remarks
  * The plugins provides a base for attaching custom settings UI in the gear menu
+ *
+ * Depends on:
+ *
+ * - {@link MediaControl | media_control}
  */
 export declare class BottomGear extends UICorePlugin {
     private isHd;
@@ -156,6 +160,16 @@ export declare class BottomGear extends UICorePlugin {
      * @internal
      */
     bindEvents(): void;
+    /**
+     * @param name - Name of a gear menu placeholder item to attach custom UI
+     * @returns Zepto result of the element
+     */
+    getElement(name: GearItemElement): ZeptoResult | null;
+    /**
+     * Replaces the content of the gear menu
+     * @param content - Zepto result of the element
+     */
+    setContent(content: ZeptoResult): void;
     private onActiveContainerChanged;
     private bindContainerEvents;
     private highDefinitionUpdate;
@@ -169,7 +183,22 @@ export declare class BottomGear extends UICorePlugin {
 }
 
 /**
+ * Displays useful network-related statistics.
  * @beta
+ *
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * - {@link BottomGear}
+ *
+ * - {@link ClapprStats}
+ *
+ * The plugin is rendered as an item in the gear menu.
+ *
+ * When clicked, it shows an overlay window with the information about the network speed, latency, etc,
+ * and recommended quality level.
  */
 export declare class ClapprNerdStats extends UICorePlugin {
     private container;
@@ -178,28 +207,43 @@ export declare class ClapprNerdStats extends UICorePlugin {
     private showing;
     private shortcut;
     private iconPosition;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
-    get template(): any;
+    private static readonly template;
+    /**
+     * @internal
+     */
     get attributes(): {
         'data-clappr-nerd-stats': string;
         class: string;
     };
+    /**
+     * @internal
+     */
     get events(): {
         'click [data-show-stats-button]': string;
         'click [data-close-button]': string;
         'click [data-refresh-button]': string;
     };
-    get statsBoxElem(): string;
-    get statsBoxWidthThreshold(): number;
-    get playerWidth(): any;
-    get playerHeight(): any;
+    private get statsBoxElem();
+    private get statsBoxWidthThreshold();
+    private get playerWidth();
+    private get playerHeight();
     constructor(core: Core);
+    /**
+     * @internal
+     */
     bindEvents(): void;
     private init;
-    private showOrHide;
+    private toggle;
     private show;
     private hide;
     private onPlayerResize;
@@ -207,6 +251,9 @@ export declare class ClapprNerdStats extends UICorePlugin {
     private addCustomMetrics;
     private updateMetrics;
     private setStatsBoxSize;
+    /**
+     * @internal
+     */
     render(): this;
     private addToBottomGear;
     private clearCustomMetrics;
@@ -377,8 +424,11 @@ export declare class DisableControls extends UICorePlugin {
  * @beta
  *
  * @remarks
- * The plugin is rendered in the {@link MediaControl | media control} UI.
- * It renders the live stream indicator and the DVR seek bar if DVR is enabled.
+ * Depends on:
+ *
+ * - {@link MediaControl | media_control}
+ *
+ * The plugin renders the live stream indicator and the DVR seek bar, if DVR is enabled, in the media control UI.
  */
 export declare class DvrControls extends UICorePlugin {
     private static readonly template;
@@ -429,6 +479,11 @@ export declare class DvrControls extends UICorePlugin {
  */
 export declare type ErrorLevel = 'FATAL' | 'WARN' | 'INFO';
 
+/**
+ * Displays a descriptive error in the overlay on top of the player.
+ * @beta
+ * TODO
+ */
 export declare class ErrorScreen extends UICorePlugin {
     private _retry;
     private err;
@@ -486,6 +541,22 @@ export declare class Favicon extends CorePlugin {
     private changeIcon;
 }
 
+/**
+ * Custom events emitted by the plugin
+ */
+export declare enum GearEvents {
+    /**
+     * Emitted when the gear menu is rendered
+     */
+    MEDIACONTROL_GEAR_RENDERED = "mediacontrol:gear:rendered"
+}
+
+/**
+ * An element inside the gear menu
+ * @beta
+ */
+export declare type GearItemElement = 'quality' | 'rate' | 'nerd';
+
 export declare class GoogleAnalytics extends ContainerPlugin {
     private account;
     private trackerName;
@@ -515,6 +586,10 @@ export declare class GoogleAnalytics extends ContainerPlugin {
     push(array: string[]): void;
 }
 
+export declare interface InitEventData {
+    event: TelemetryEvent.Init;
+}
+
 declare type KeyboardEventHandler = (e: KeyboardEvent) => boolean | undefined;
 
 /**
@@ -552,7 +627,14 @@ export declare type LangTag = string;
  * @beta
  *
  * @remarks
- * The plugin is rendered as a button in the {@link BottomGear | gear menu}.
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * - {@link BottomGear}
+ *
+ * The plugin is rendered as an item in the gear menu.
+ *
  * When clicked, it shows a list of quality levels to choose from.
  *
  * Configuration options:
@@ -577,8 +659,8 @@ export declare class LevelSelector extends UICorePlugin {
     private removeAuto;
     private isHd;
     private isOpen;
-    private buttonTemplate;
-    private listTemplate;
+    private static readonly buttonTemplate;
+    private static readonly listTemplate;
     /**
      * @internal
      */
@@ -869,7 +951,6 @@ export declare class MediaControl extends UICorePlugin {
     private hide;
     private updateCursorStyle;
     private settingsUpdate;
-    private getSettings;
     private highDefinitionUpdate;
     private createCachedElements;
     /**
@@ -891,6 +972,11 @@ export declare class MediaControl extends UICorePlugin {
      * ```
      */
     getElement(name: MediaControlElement): ZeptoResult | null;
+    /**
+     * Get the right panel area to append custom elements to
+     * @returns  ZeptoSelector of the right panel element
+     */
+    getRightPanel(): any;
     private resetIndicators;
     private initializeIcons;
     private setSeekPercentage;
@@ -930,7 +1016,7 @@ export declare class MediaControl extends UICorePlugin {
  * Media control elements, mount points for additional plugins
  * @beta
  */
-export declare type MediaControlElement = 'bottomGear' | 'clipText' | 'pip' | 'playbackRate' | 'seekBarContainer';
+export declare type MediaControlElement = 'bottomGear' | 'clipText' | 'gear' | 'pip' | 'playbackRate' | 'seekBarContainer' | 'subtitlesSelector';
 
 declare type MediaSourceInfo = {
     live: boolean;
@@ -1036,22 +1122,50 @@ export declare class MultiCamera extends UICorePlugin {
     private highlightCurrentLevel;
 }
 
+/**
+ * Enables picture in picture mode.
+ * @beta
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * It renders a button to toggle picture in picture mode in the media control UI.
+ */
 export declare class PictureInPicture extends UICorePlugin {
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
+    /**
+     * @internal
+     */
     static get version(): string;
+    /**
+     * @internal
+     */
     get events(): {
         'click button': string;
     };
-    get videoElement(): any;
+    private get videoElement();
+    /**
+     * @internal
+     */
     bindEvents(): void;
     private isPiPSupported;
+    /**
+     * @internal
+     */
     render(): this;
-    togglePictureInPicture(): void;
-    requestPictureInPicture(): void;
-    exitPictureInPicture(): void;
+    private togglePictureInPicture;
+    private requestPictureInPicture;
+    private exitPictureInPicture;
 }
 
 /**
@@ -1114,45 +1228,78 @@ export declare enum PlaybackErrorCode {
  */
 export declare type PlaybackModule = 'dash' | 'hls' | 'html5_video';
 
+/**
+ * Allows changing the playback speed of the video.
+ * @beta
+ *
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl | media_control}
+ *
+ * - {@link BottomGear | bottom_gear}
+ *
+ * It renders a button in the gear menu, which opens a dropdown with the available playback rates.
+ */
 export declare class PlaybackRate extends UICorePlugin {
     private currentPlayback;
     private playbackRates;
     private prevSelectedRate;
     private selectedRate;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
-    get template(): any;
+    private static readonly template;
+    private static readonly buttonTemplate;
+    private static readonly listTemplate;
+    /**
+     * @internal
+     */
     get attributes(): {
         class: string;
         'data-playback-rate-select': string;
     };
+    /**
+     * @internal
+     */
     get events(): {
         'click .gear-sub-menu_btn': string;
         'click .gear-option': string;
         'click .go-back': string;
     };
+    /**
+     * @internal
+     */
     bindEvents(): void;
-    unBindEvents(): void;
+    private unBindEvents;
     private allRateElements;
     private rateElement;
     private onDashRateChange;
     private updateLiveStatus;
-    reload(): void;
+    private reload;
     private shouldRender;
+    /**
+     * @internal
+     */
     render(): this;
-    onStartAd(): void;
-    onFinishAd(): void;
-    onPlay(): void;
-    onStop(): void;
-    onRateSelect(event: MouseEvent): boolean;
-    onShowMenu(): void;
-    goBack(): void;
-    updatePlaybackRate(rate: string): void;
-    setSelectedRate(rate: string): void;
-    getTitle(): string;
-    highlightCurrentRate(): void;
+    private onStartAd;
+    private onFinishAd;
+    private onPlay;
+    private onStop;
+    private onRateSelect;
+    private onShowMenu;
+    private goBack;
+    private updatePlaybackRate;
+    private setSelectedRate;
+    private getTitle;
+    private highlightCurrentRate;
 }
 
 /**
@@ -1566,15 +1713,6 @@ export declare type PlayerPlugin = {
     name: string;
 };
 
-export declare type PluginSettings = {
-    /**
-     * Sends the statistics record to the storage.
-     * The actual delivery is presumably async and batched.
-     * @param data - The statistics record to send.
-     */
-    send: (data: StatisticsRecord) => void;
-};
-
 /**
  * Displays a poster image in the background and a big play button on top when playback is stopped
  * @beta
@@ -1827,7 +1965,13 @@ export declare class SourceController extends CorePlugin {
     private sourcesDelay;
     private active;
     private sync;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
@@ -1841,14 +1985,43 @@ export declare class SourceController extends CorePlugin {
     private reset;
     private retryPlayback;
     private getNextMediaSource;
+    /**
+     * @internal
+     */
     static get version(): string;
 }
 
+/**
+ * Custom events emitted by the plugin
+ */
+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
+     */
+    SYNC = "plugins:spinner:sync"
+}
+
+/**
+ * Shows a pending operation indicator when playback is buffering or in other appropriate cases
+ * @beta
+ * @remarks
+ * The plugin emits
+ */
 export declare class SpinnerThreeBounce extends UIContainerPlugin {
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
+    /**
+     * @internal
+     */
     get attributes(): {
         'data-spinner': string;
         class: string;
@@ -1863,94 +2036,132 @@ export declare class SpinnerThreeBounce extends UIContainerPlugin {
     private onPlay;
     private onStop;
     private onError;
-    show(immediate?: boolean): void;
+    /**
+     * Shows the spinner
+     */
+    show(): void;
+    /**
+     * Hides the spinner
+     */
     hide(): void;
+    /**
+     * @internal
+     */
     render(): this;
 }
 
-export declare class Statistics extends ContainerPlugin {
-    get name(): string;
-    get supportedVersion(): {
-        min: string;
-    };
-    private started;
-    private timeStart;
-    private heatmapSent;
-    private heatmapLastTime;
-    private watchSent;
-    private bufTracking;
-    private lags;
+/**
+ * Playback stall event data
+ */
+export declare interface StallEventData {
+    event: TelemetryEvent.Stall;
     /**
-     * The time when buffering last started.
+     * Accumulated buffering duration over the measurement interval, ms
      */
-    private bufLastStarted;
+    total_ms: number;
     /**
-     * The accumulated buffering duration.
+     * Number of stalls
      */
-    private bufAccDuration;
-    constructor(container: Container);
-    bindEvents(): void;
-    private startLevelSwitch;
-    private stopLevelSwitch;
-    private onBuffering;
-    private onBufferFull;
-    private onReady;
-    private initEvent;
-    private sendMessage;
-    private send;
-    private sendHeatmap;
-    private onTimeUpdateLive;
-    private onStart;
+    count: number;
+    /**
+     * Playback time when the stall is reported at the end of a stall measurement interval, s
+     */
+    time: number;
 }
 
-declare type StatisticsEvent = 'init' | 'start' | 'watch' | 'heatmap';
-
-declare type StatisticsEventData = Record<string, string | number | boolean>;
-
-declare type StatisticsRecord = {
-    event: StatisticsEvent;
-    type: PlaybackType;
-} & StatisticsEventData;
+export declare interface StartEventData {
+    event: TelemetryEvent.Start;
+}
 
+/**
+ * A {@link MediaControl | media control} plugin that provides a UI to select the subtitles when available.
+ * @beta
+ *
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * Configuration options:
+ *
+ * - subtitles.language - The language of the subtitles to select by default.
+ *
+ * @example
+ * ```ts
+ * import { Subtitles } from '@gcorevideo/player'
+ *
+ * Player.registerPlugin(Subtitles)
+ *
+ * new Player({
+ *   ...
+ *   subtitles: {
+ *     language: 'en',
+ *   },
+ * })
+ * ```
+ */
 export declare class Subtitles extends UICorePlugin {
-    private currentContainer;
     private currentLevel;
-    private currentPlayback;
+    private isPreselectedApplied;
     private isShowing;
+    private track;
     private tracks;
     private $string;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     get supportedVersion(): {
         min: string;
     };
+    /**
+     * @internal
+     */
     static get version(): string;
-    get template(): any;
-    get templateString(): any;
+    private static readonly template;
+    private static readonly templateString;
+    /**
+     * @internal
+     */
     get attributes(): {
         class: string;
         'data-subtitles': string;
     };
+    /**
+     * @internal
+     */
     get events(): {
         'click [data-subtitles-select]': string;
         'click [data-subtitles-button]': string;
     };
-    private isPreselectedApplied;
-    private track;
-    get preselectedLanguage(): string;
+    private get preselectedLanguage();
+    /**
+     * @internal
+     */
     bindEvents(): void;
-    unBindEvents(): void;
     private bindPlaybackEvents;
     private getTracks;
     private onStartAd;
     private onFinishAd;
-    reload(): void;
     private playerResize;
+    /**
+     * Hides the subtitles menu and the subtitles.
+     */
     hide(): void;
+    /**
+     * Shows the subtitles menu and the subtitles.
+     */
     show(): void;
     private shouldRender;
     private resizeFont;
+    /**
+     * @internal
+     */
     render(): this;
-    private fillLevels;
+    private setTracks;
     private findLevelBy;
     private selectLevel;
     private onLevelSelect;
@@ -1958,11 +2169,11 @@ export declare class Subtitles extends UICorePlugin {
     private onShowLevelSelectMenu;
     private hideSelectLevelMenu;
     private toggleContextMenu;
-    buttonElement(): ZeptoResult;
-    levelElement(id?: string): ZeptoResult;
-    startLevelSwitch(): void;
-    stopLevelSwitch(): void;
-    selectSubtitles(): void;
+    private buttonElement;
+    private levelElement;
+    private startLevelSwitch;
+    private stopLevelSwitch;
+    private selectSubtitles;
     private setSubtitleText;
     private clearSubtitleText;
     private updateCurrentLevel;
@@ -1970,6 +2181,116 @@ export declare class Subtitles extends UICorePlugin {
     private renderIcon;
 }
 
+/**
+ * Collects and reports the performance statistics.
+ * @beta
+ * @remarks
+ * This plugin is experimental and its API is likely to change.
+ *
+ * Configuration options {@link TelemetryPluginSettings}
+ *
+ * @example
+ * ```ts
+ * import { Statistics } from '@gcorevideo/player'
+ *
+ * Player.registerPlugin(Statistics)
+ *
+ * const player = new Player({
+ *   statistics: {
+ *     send: (data) => {
+ *        fetch('/stats', {
+ *          method: 'POST',
+ *          body: JSON.stringify(data),
+ *          headers: { 'content-type': 'application/json' },
+ *        })
+ *     },
+ *   },
+ *   ...
+ * })
+ * ```
+ */
+export declare class Telemetry extends ContainerPlugin {
+    /**
+     * The name of the plugin.
+     */
+    get name(): string;
+    /**
+     * The supported version of the plugin.
+     */
+    get supportedVersion(): {
+        min: string;
+    };
+    private started;
+    private timeStart;
+    private stallSent;
+    private stallLastTime;
+    private watchSent;
+    private bufTracking;
+    private numStalls;
+    /**
+     * The time when buffering last started.
+     */
+    private bufLastStarted;
+    /**
+     * The accumulated buffering duration.
+     */
+    private stallAcc;
+    constructor(container: Container);
+    /**
+     * @internal
+     */
+    bindEvents(): void;
+    private startLevelSwitch;
+    private endLevelSwitch;
+    private onBuffering;
+    private onBufferFull;
+    private onReady;
+    private sendInit;
+    private send;
+    private sendStall;
+    private onTimeUpdate;
+    private onStart;
+}
+
+/**
+ * Telemetry event type
+ */
+export declare enum TelemetryEvent {
+    Init = 1,
+    Start = 2,
+    Watch = 3,
+    Stall = 4
+}
+
+/**
+ * Telemetry event data
+ */
+export declare type TelemetryEventData = StallEventData | InitEventData | StartEventData | WatchEventData;
+
+/**
+ * Plugin settings
+ */
+export declare interface TelemetryPluginSettings {
+    /**
+     * Sends the statistics record to the storage.
+     * The actual delivery is presumably async and batched.
+     */
+    send: TelemetrySendFn;
+}
+
+/**
+ * Telemetry record
+ */
+export declare type TelemetryRecord = {
+    type: PlaybackType;
+} & TelemetryEventData;
+
+/**
+ * Callback to send the telemetry record to the storage.
+ * @param data - The telemetry record to send.
+ */
+declare type TelemetrySendFn = (data: TelemetryRecord) => void;
+
 export declare class Thumbnails extends UICorePlugin {
     private _$spotlight;
     private _$backdrop;
@@ -2117,9 +2438,15 @@ export declare class VolumeFade extends UICorePlugin {
     private container;
     private delay;
     private interval;
+    /**
+     * @internal
+     */
     get name(): string;
+    /**
+     * @internal
+     */
     bindEvents(): void;
-    unBindEvents(): void;
+    private unBindEvents;
     private _onUserChangeVolume;
     private _onVolumeConfig;
     private onCoreReady;
@@ -2133,6 +2460,10 @@ export declare enum VolumeFadeEvents {
     FADE = "core:volume:fade"
 }
 
+export declare interface WatchEventData {
+    event: TelemetryEvent.Watch;
+}
+
 /**
  * @beta
  */