@gcorevideo/player 2.16.17 → 2.18.0

package/dist/player.d.ts

@@ -1,14 +1,13 @@
 /**
- * Video player for the GCore streaming platform
+ * Video player for the Gcore streaming platform
  *
  * @remarks
- * This package provides a video player for the GCore streaming platform.
+ * 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.
  *
  * @packageDocumentation
  */
 
-import EventLite from 'event-lite';
 import { Logger } from '@gcorevideo/utils';
 import { LogTracer } from '@gcorevideo/utils';
 import { reportError as reportError_2 } from '@gcorevideo/utils';
@@ -17,17 +16,30 @@ import { setTracer } from '@gcorevideo/utils';
 import { trace } from '@gcorevideo/utils';
 
 /**
+ * Dimensions of the player container DOM element.
+ * @beta
+ */
+export declare type ContainerSize = {
+    width: number;
+    height: number;
+};
+
+/**
+ * A plain JS object that must conform to the DASH.js settings schema.
  * @beta
  * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html | DASH.js settings}
  */
 export declare type DashSettings = Record<string, unknown>;
 
 /**
+ * Levels of severity of errors. Non-fatal errors usually can be ignored.
  * @beta
  */
 export declare type ErrorLevel = 'FATAL' | 'WARN' | 'INFO';
 
 /**
+ * An ISO 639-1 language code.
+ * @example `pt`
  * @beta
  */
 export declare type LangTag = string;
@@ -37,63 +49,67 @@ export { Logger }
 export { LogTracer }
 
 /**
+ * Media delivery protocol
  * @beta
  */
 export declare type MediaTransport = 'dash' | 'hls';
 
 /**
- * @internal
- */
-export declare class _MockPlayback extends EventLite {
-    protected options: any;
-    readonly i18n: any;
-    protected playerError?: any | undefined;
-    constructor(options: any, i18n: any, playerError?: any | undefined);
-    get name(): string;
-    consent(): void;
-    play(): void;
-    pause(): void;
-    stop(): void;
-    destroy(): void;
-    seek(): void;
-    seekPercentage(): void;
-    getDuration(): number;
-    enterPiP(): void;
-    exitPiP(): void;
-    getPlaybackType(): string;
-    getStartTimeOffset(): number;
-    getCurrentTime(): number;
-    isHighDefinitionInUse(): boolean;
-    mute(): void;
-    unmute(): void;
-    volume(): void;
-    configure(): void;
-    attemptAutoPlay(): boolean;
-    canAutoPlay(): boolean;
-    onResize(): boolean;
-    trigger(event: string, ...args: any[]): void;
-}
-
-/**
+ * An error occurred during the playback.
  * @beta
  */
 export declare interface PlaybackError {
+    /**
+     * Error code.
+     */
     code: PlaybackErrorCode;
+    /**
+     * Detailed description of the error.
+     */
     description: string;
+    /**
+     * Level of severity of the error.
+     */
     level: ErrorLevel;
+    /**
+     * Error message. Non-fatal usually can be ignored.
+     */
     message: string;
+    /**
+     * Exact component that originated the error.
+     * @example
+     * - 'core'
+     * - 'dash'
+     * - 'media_control'
+     */
+    origin: string;
+    /**
+     * Component subsystem of the error origin
+     */
+    scope: PlayerComponentType;
 }
 
 /**
+ * Codes of errors occurring within the playback component.
  * @beta
  */
 export declare enum PlaybackErrorCode {
+    /**
+     * An unknown or uncategorised error.
+     */
     Generic = 0,
+    /**
+     * The media source is not available. Typically a network error.
+     */
     MediaSourceUnavailable = 1,
-    QualityLevelUnavailable = 2
+    /**
+     * The media source is not accessible due to some protection policy.
+     */
+    MediaSourceAccessDenied = 3
 }
 
 /**
+ * Module to perform the playback.
  * @beta
  */
 export declare type PlaybackModule = 'dash' | 'hls' | 'html5_video';
@@ -106,11 +122,11 @@ export declare type PlaybackType = 'live' | 'vod';
 
 /**
  * The main component to use in the application code.
+ * @beta
  * @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.
  * {@link https://github.com/clappr/clappr/wiki/Architecture}
- * @beta
  */
 export declare class Player {
     private config;
@@ -123,50 +139,95 @@ export declare class Player {
     constructor(config: PlayerConfig);
     /**
      * Adds a listener to a player event
-     * @param event - See {@link PlayerEvent}
-     * @param handler - See {@link PlayerEventHandler}
+     * @param event - event type, see {@link PlayerEvent}
+     * @param handler - a callback function to handle the event
      */
-    on<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>): void;
+    on<E extends PlayerEvent>(event: E, handler: PlayerEventHandler<E>): void;
     /**
-     * Removes a listener from a player event
+     * Removes a previously added event listener
      * @param event - See {@link PlayerEvent}
-     * @param handler - See {@link PlayerEventHandler}
+     * @param handler - a callback attached earlier to that event type
      */
-    off<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>): void;
+    off<E extends PlayerEvent>(event: E, handler: PlayerEventHandler<E>): void;
     /**
      * Configures the player.
      *
-     * Can be called multiple times. Each consequent call extends the previous configuration.
-     * After a reconfiguration, if something significant has changed, the must be reinitialized (i.e, a `.destroy()` followed by an `.init()` call).
-     *
      * @param config - complete or partial configuration
+     * @remarks
+     * Can be called multiple times.
+     * Each consequent call extends the previous configuration with only the new keys overridden.
+     *
+     * After a reconfiguration, if something significant has changed, it might make sense reinitialize the player (i.e, a `.destroy()` followed by an `.init()` call).
      */
     configure(config: Partial<PlayerConfig>): void;
     /**
      * Initializes the player at the given container element.
      * @param playerElement - DOM element to host the player
+     * @remarks
+     * The player will be initialized and attached to the given element.
+     *
+     * All the core plugins will be initialized at this point.
+     *
+     * If no sources were configured, it will trigger an error.
+     *
+     * The player container will be initialized and then all the registered UI plugins.
+     *
+     * If the `autoPlay` option is set, then it will trigger playback immediately.
+     *
+     * It is an error to call this method twice. If you need to attache player to another DOM element,
+     * first call {@link Player.destroy} and then {@link Player.attachTo}.
+     *
+     * @example
+     * ```ts
+     * const player = new Player({
+     *   sources: [{ source: 'https://example.com/a.mpd', mimeType: 'application/dash+xml' }],
+     * })
+     * document.addEventListener('DOMContentLoaded', () => {
+     *   player.attachTo(document.getElementById('video-container'))
+     * })
+     * ```
      */
     attachTo(playerElement: HTMLElement): void;
     /**
-     * Destroys the player, releasing all resources and removing any DOM elements added.
+     * Destroys the player, releasing all resources and unmounting its UI from the DOM.
      */
     destroy(): void;
     /**
-     * Current playback time in seconds, if appropriate.
-     * @returns For live streams, it returns the current time of the current segment.
+     * Current playback (time since the beginning of the stream), if appropriate.
+     *
+     * @returns Time in seconds
+     * @remarks
+     * For live streams, it returns the current time within the current segment.
      */
     getCurrentTime(): number;
     /**
      * Duration of the current media in seconds, if appropriate.
-     * @returns For live streams, it returns the duration of the current segment.
+     *
+     * @returns Time in seconds
+     * @remarks
+     * For live streams, it returns the duration of the current segment.
      */
     getDuration(): number;
     /**
-     * Mutes the player.
+     * Indicates whether DVR is enabled.
+     */
+    isDvrEnabled(): boolean;
+    /**
+     * Indicates whether DVR is in use.
+     * @remarks
+     * DVR mode, if it is enabled, is triggered we a user seeks behind the live edge.
+     */
+    isDvrInUse(): boolean;
+    /**
+     * Indicates the playing state.
+     */
+    isPlaying(): boolean;
+    /**
+     * Mutes the sound of the video.
      */
     mute(): void;
     /**
-     * Unmutes the player.
+     * Unmutes the video sound.
      */
     unmute(): void;
     /**
@@ -180,40 +241,71 @@ export declare class Player {
     /**
      * Resizes the player container element and everything within it.
      * @param newSize - new size of the player
+     * @remarks
+     * Use this method when the player itself does not detect properly the change in size of its container element.
+     * It can be a case for orientation change on some mobile devices.
      */
-    resize(newSize: {
-        width: number;
-        height: number;
-    }): void;
+    resize(newSize: ContainerSize): void;
     /**
      * Seeks to the given time.
-     * @param time - time to seek to in seconds
+     * @param time - time to seek to in seconds (since the beginning of the stream)
      */
     seek(time: number): void;
+    /**
+     * Gets the current volume of the media content being played.
+     * @returns a number between 0 and 1
+     */
+    getVolume(): number;
+    /**
+     * Sets the current volume of the media content being played.
+     * @param volume - a number between 0 and 1
+     */
+    setVolume(volume: number): void;
     /**
      * Stops playback.
      */
     stop(): void;
     /**
      * Registers a plugin.
-     * @param plugin - plugin to register
+     * @param plugin - a plugin class
+     * @remarks
+     * Use this method to extend the player with custom behavior.
+     * The plugin class must inherit from one of the Clappr UIPlugin, UIContainerPlugin or CorePlugin classes.
+     * A core plugin will be initialized and attached to the player when the player is initialized.
+     * A UI plugin will be initialized and attached to the player container is initialized.
+     *
+     * @see {@link https://github.com/clappr/clappr/wiki/Architecture}
+     * @example
+     * ```ts
+     * import MyPlugin from './MyPlugin.js'
+     *
+     * Player.registerPlugin(MyPlugin)
+     * ```
      */
     static registerPlugin(plugin: PlayerPlugin): void;
     /**
-     * Unregisters a plugin.
-     * @param plugin - plugin to unregister
+     * Unregisters a plugin registered earlier with {@link Player.registerPlugin}.
+     * @param plugin - a plugin class
      */
     static unregisterPlugin(plugin: PlayerPlugin): void;
     private setConfig;
     private initPlayer;
     private tuneIn;
+    private safeTriggerEvent;
     private events;
     private buildCoreOptions;
     private configurePlaybacks;
     private buildMediaSourcesList;
     private bindContainerEventListeners;
+    private bindSizeManagementListeners;
 }
 
+/**
+ * Subsystems of a player component.
+ * @beta
+ */
+export declare type PlayerComponentType = 'container' | 'core' | 'playback';
+
 /**
  * Configuration options for the player
  *
@@ -310,12 +402,13 @@ export declare interface PlayerConfig extends Record<string, unknown> {
 }
 
 /**
- * @remarks true is equivalent to 'all', false is equivalent to 'none'
+ * @remarks `true` is equivalent to `'all'`, `false` is equivalent to `'none'`
  * @beta
  */
 export declare type PlayerDebugSettings = PlayerDebugTag | boolean;
 
 /**
+ * Debug output category selector
  * @beta
  */
 export declare type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none';
@@ -325,6 +418,20 @@ export declare type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none';
  * @beta
  */
 export declare enum PlayerEvent {
+    /**
+     * Playback has reached the end of the media.
+     */
+    Ended = "ended",
+    /**
+     * An error occurred.
+     * Parameters: {@link PlaybackError}
+     */
+    Error = "error",
+    /**
+     * The player has switched to or from the fullscreen mode.
+     * Parameters:`boolean` isFullscreen
+     */
+    Fullscreen = "fullscreen",
     /**
      * The player is ready to use.
      */
@@ -337,20 +444,45 @@ export declare enum PlayerEvent {
      * Playback has been paused.
      */
     Pause = "pause",
+    /**
+     * The player's container has been resized.
+     * Parameters: {@link ContainerSize}
+     */
+    Resize = "resize",
+    /**
+     * The player is seeking to a new position.
+     */
+    Seek = "seek",
     /**
      * Playback has been stopped.
      */
     Stop = "stop",
     /**
-     * Playback has reached the end of the media.
+     * The current playback time has changed.
+     * Parameters: {@link TimePosition}
      */
-    Ended = "ended"
+    TimeUpdate = "timeupdate",
+    /**
+     * The volume has changed.
+     * Parameters: `number` volume in the range 0..1
+     */
+    VolumeUpdate = "volumeupdate"
 }
 
 /**
+ * Type of a listener callback function for a player event.
+ * See the description of the event parameters in {@link PlayerEvent}.
  * @beta
  */
-export declare type PlayerEventHandler<T extends PlayerEvent> = () => void;
+export declare type PlayerEventHandler<E extends PlayerEvent> = (...args: PlayerEventParams<E>) => void;
+
+/**
+ * @beta
+ */
+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;
+    height: number;
+}] : E extends PlayerEvent.Fullscreen ? [boolean] : E extends PlayerEvent.Error ? [PlaybackError] : [];
 
 /**
  * A media source to fetch the media data from
@@ -368,7 +500,8 @@ export declare type PlayerMediaSource = string | PlayerMediaSourceDesc;
  */
 export declare interface PlayerMediaSourceDesc {
     /**
-     * The MIME type of the media source (e.g. "video/mp4", "application/x-mpegURL")
+     * The MIME type of the media source (e.g. `"video/mp4"`, `"application/x-mpegURL"`).
+     * Necessary if the type cannot be detected from file extension of the source URL.
      */
     mimeType?: string;
     /**
@@ -387,14 +520,27 @@ export declare type PlayerPlugin = {
 };
 
 /**
+ * A level of quality within a media source.
  * @beta
  */
-export declare type QualityLevel = {
+export declare interface QualityLevel {
+    /**
+     * Zero-based index of the quality level.
+     */
     level: number;
+    /**
+     * Width of the video, pixels.
+     */
     width: number;
+    /**
+     * Height of the video, pixels.
+     */
     height: number;
+    /**
+     * Bitrate of the video, bps.
+     */
     bitrate: number;
-};
+}
 
 export { reportError_2 as reportError }
 
@@ -403,13 +549,19 @@ export { SentryTracer }
 export { setTracer }
 
 /**
- * For the plugin development
+ * Current playback time and total duration of the media.
  * @beta
  */
-export declare type TimePosition = {
+export declare interface TimePosition {
+    /**
+     * Current playback time, 0..duration, seconds.
+     */
     current: TimeValue;
+    /**
+     * Total duration of the media, seconds.
+     */
     total: TimeValue;
-};
+}
 
 /**
  * For the plugin development
@@ -429,7 +581,6 @@ export declare type TimeUpdate = TimePosition & {
 
 /**
  * Playback time in seconds since the beginning of the stream (or a segment for the live streams)
- * For the plugin development
  * @beta
  */
 export declare type TimeValue = number;
@@ -442,7 +593,12 @@ export { trace }
 export declare type TranslationKey = string;
 
 /**
- * [language][key] =\> string
+ * Localization strings for the player UI.
+ * @remarks
+ * The keys are language codes, and the values are objects with keys being the translation keys and values being the translations.
+ *
+ * This dictionary is used to localize the player UI, including the error messages and is shared across all the player components (including the plugins).
+ *
  * @example
  * ```
  * {
@@ -463,6 +619,7 @@ export declare type TranslationKey = string;
 export declare type TranslationSettings = Partial<Record<LangTag, Record<TranslationKey, string>>>;
 
 /**
+ * Preferred media delivery protocol
  * @beta
  */
 export declare type TransportPreference = MediaTransport;

package/docs/api/index.md

@@ -24,7 +24,7 @@ Description
 
 </td><td>
 
-Video player for the GCore streaming platform
+Video player for the Gcore streaming platform
 
 
 </td></tr>

package/docs/api/player.containersize.md

@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [ContainerSize](./player.containersize.md)
+
+## ContainerSize type
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Dimensions of the player container DOM element.
+
+**Signature:**
+
+```typescript
+export type ContainerSize = {
+    width: number;
+    height: number;
+};
+```

package/docs/api/player.dashsettings.md

@@ -7,6 +7,8 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
+A plain JS object that must conform to the DASH.js settings schema.
+
 [DASH.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html)
 
 **Signature:**

package/docs/api/player.errorlevel.md

@@ -7,6 +7,7 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
+Levels of severity of errors. Non-fatal errors usually can be ignored.
 
 **Signature:**
 

package/docs/api/player.langtag.md

@@ -7,9 +7,15 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
+An ISO 639-1 language code.
 
 **Signature:**
 
 ```typescript
 export type LangTag = string;
 ```
+
+## Example
+
+`pt`
+