@gcorevideo/player 2.17.0 → 2.18.0

package/dist/player.d.ts

@@ -16,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;
@@ -36,30 +49,67 @@ export { Logger }
 export { LogTracer }
 
 /**
+ * Media delivery protocol
  * @beta
  */
 export declare type MediaTransport = 'dash' | 'hls';
 
 /**
+ * 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,
+    /**
+     * 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';
@@ -72,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;
@@ -89,16 +139,16 @@ 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 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.
      *
@@ -163,7 +213,13 @@ export declare class Player {
      */
     isDvrEnabled(): boolean;
     /**
-     * Indicates the playing state of the player.
+     * 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;
     /**
@@ -186,13 +242,10 @@ 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 the change in size of its container element.
+     * 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 (since the beginning of the stream)
@@ -238,13 +291,21 @@ export declare class Player {
     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
  *
@@ -341,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';
@@ -356,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.
      */
@@ -368,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
@@ -399,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;
     /**
@@ -418,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 }
 
@@ -434,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
@@ -460,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;
@@ -473,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
  * ```
  * {
@@ -494,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/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`
+

package/docs/api/player.md

@@ -56,7 +56,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Codes of errors occurring within the playback component.
 
 
 </td></tr>
@@ -119,7 +119,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** An error occurred during the playback.
 
 
 </td></tr>
@@ -144,6 +144,28 @@ Description
 **_(BETA)_** Describes a media source with its MIME type and URL.
 
 
+</td></tr>
+<tr><td>
+
+[QualityLevel](./player.qualitylevel.md)
+
+
+</td><td>
+
+**_(BETA)_** A level of quality within a media source.
+
+
+</td></tr>
+<tr><td>
+
+[TimePosition](./player.timeposition.md)
+
+
+</td><td>
+
+**_(BETA)_** Current playback time and total duration of the media.
+
+
 </td></tr>
 </tbody></table>
 
@@ -162,12 +184,25 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[ContainerSize](./player.containersize.md)
+
+
+</td><td>
+
+**_(BETA)_** Dimensions of the player container DOM element.
+
+
+</td></tr>
+<tr><td>
+
 [DashSettings](./player.dashsettings.md)
 
 
 </td><td>
 
-**_(BETA)_** [DASH.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html)
+**_(BETA)_** 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)
 
 
 </td></tr>
@@ -178,7 +213,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Levels of severity of errors. Non-fatal errors usually can be ignored.
 
 
 </td></tr>
@@ -189,7 +224,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** An ISO 639-1 language code.
 
 
 </td></tr>
@@ -200,7 +235,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Media delivery protocol
 
 
 </td></tr>
@@ -211,7 +246,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Module to perform the playback.
 
 
 </td></tr>
@@ -228,18 +263,18 @@ Description
 </td></tr>
 <tr><td>
 
-[PlayerDebugSettings](./player.playerdebugsettings.md)
+[PlayerComponentType](./player.playercomponenttype.md)
 
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Subsystems of a player component.
 
 
 </td></tr>
 <tr><td>
 
-[PlayerDebugTag](./player.playerdebugtag.md)
+[PlayerDebugSettings](./player.playerdebugsettings.md)
 
 
 </td><td>
@@ -250,29 +285,29 @@ Description
 </td></tr>
 <tr><td>
 
-[PlayerEventHandler](./player.playereventhandler.md)
+[PlayerDebugTag](./player.playerdebugtag.md)
 
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Debug output category selector
 
 
 </td></tr>
 <tr><td>
 
-[PlayerMediaSource](./player.playermediasource.md)
+[PlayerEventHandler](./player.playereventhandler.md)
 
 
 </td><td>
 
-**_(BETA)_** A media source to fetch the media data from
+**_(BETA)_** Type of a listener callback function for a player event. See the description of the event parameters in [PlayerEvent](./player.playerevent.md)<!-- -->.
 
 
 </td></tr>
 <tr><td>
 
-[PlayerPlugin](./player.playerplugin.md)
+[PlayerEventParams](./player.playereventparams.md)
 
 
 </td><td>
@@ -283,23 +318,23 @@ Description
 </td></tr>
 <tr><td>
 
-[QualityLevel](./player.qualitylevel.md)
+[PlayerMediaSource](./player.playermediasource.md)
 
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** A media source to fetch the media data from
 
 
 </td></tr>
 <tr><td>
 
-[TimePosition](./player.timeposition.md)
+[PlayerPlugin](./player.playerplugin.md)
 
 
 </td><td>
 
-**_(BETA)_** For the plugin development
+**_(BETA)_**
 
 
 </td></tr>
@@ -332,7 +367,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** Playback time in seconds since the beginning of the stream (or a segment for the live streams) For the plugin development
+**_(BETA)_** Playback time in seconds since the beginning of the stream (or a segment for the live streams)
 
 
 </td></tr>
@@ -354,7 +389,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** \[language\]\[key\] =<!-- -->&gt; string
+**_(BETA)_** Localization strings for the player UI.
 
 
 </td></tr>
@@ -365,7 +400,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Preferred media delivery protocol
 
 
 </td></tr>

package/docs/api/player.mediatransport.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.
 > 
 
+Media delivery protocol
 
 **Signature:**
 

package/docs/api/player.playbackerror.code.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.
 > 
 
+Error code.
+
 **Signature:**
 
 ```typescript

package/docs/api/player.playbackerror.description.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.
 > 
 
+Detailed description of the error.
+
 **Signature:**
 
 ```typescript

package/docs/api/player.playbackerror.level.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.
 > 
 
+Level of severity of the error.
+
 **Signature:**
 
 ```typescript