@gcorevideo/player 2.19.15 → 2.20.1

package/dist/player.d.ts

@@ -183,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;
@@ -192,25 +207,40 @@ 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 toggle;
@@ -221,6 +251,9 @@ export declare class ClapprNerdStats extends UICorePlugin {
     private addCustomMetrics;
     private updateMetrics;
     private setStatsBoxSize;
+    /**
+     * @internal
+     */
     render(): this;
     private addToBottomGear;
     private clearCustomMetrics;
@@ -391,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;
@@ -443,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;
@@ -545,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;
 
 /**
@@ -1077,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;
 }
 
 /**
@@ -1155,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;
 }
 
 /**
@@ -1607,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
@@ -1953,49 +2050,28 @@ export declare class SpinnerThreeBounce extends UIContainerPlugin {
     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.
@@ -2105,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;
@@ -2252,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;
@@ -2268,6 +2460,10 @@ export declare enum VolumeFadeEvents {
     FADE = "core:volume:fade"
 }
 
+export declare interface WatchEventData {
+    event: TelemetryEvent.Watch;
+}
+
 /**
  * @beta
  */