@gcorevideo/player 2.16.17 → 2.18.0

package/docs/api/player.qualitylevel.md

@@ -2,19 +2,116 @@
 
 [Home](./index.md) > [@gcorevideo/player](./player.md) > [QualityLevel](./player.qualitylevel.md)
 
-## QualityLevel type
+## QualityLevel interface
 
 > 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 level of quality within a media source.
 
 **Signature:**
 
 ```typescript
-export type QualityLevel = {
-    level: number;
-    width: number;
-    height: number;
-    bitrate: number;
-};
+export interface QualityLevel 
 ```
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[bitrate](./player.qualitylevel.bitrate.md)
+
+
+</td><td>
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+**_(BETA)_** Bitrate of the video, bps.
+
+
+</td></tr>
+<tr><td>
+
+[height](./player.qualitylevel.height.md)
+
+
+</td><td>
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+**_(BETA)_** Height of the video, pixels.
+
+
+</td></tr>
+<tr><td>
+
+[level](./player.qualitylevel.level.md)
+
+
+</td><td>
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+**_(BETA)_** Zero-based index of the quality level.
+
+
+</td></tr>
+<tr><td>
+
+[width](./player.qualitylevel.width.md)
+
+
+</td><td>
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+**_(BETA)_** Width of the video, pixels.
+
+
+</td></tr>
+</tbody></table>

package/docs/api/player.qualitylevel.width.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [QualityLevel](./player.qualitylevel.md) &gt; [width](./player.qualitylevel.width.md)
+
+## QualityLevel.width property
+
+> 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.
+> 
+
+Width of the video, pixels.
+
+**Signature:**
+
+```typescript
+width: number;
+```

package/docs/api/player.timeposition.current.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [TimePosition](./player.timeposition.md) &gt; [current](./player.timeposition.current.md)
+
+## TimePosition.current property
+
+> 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.
+> 
+
+Current playback time, 0..duration, seconds.
+
+**Signature:**
+
+```typescript
+current: TimeValue;
+```

package/docs/api/player.timeposition.md

@@ -2,20 +2,78 @@
 
 [Home](./index.md) > [@gcorevideo/player](./player.md) > [TimePosition](./player.timeposition.md)
 
-## TimePosition type
+## TimePosition interface
 
 > 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.
 > 
 
-For the plugin development
+Current playback time and total duration of the media.
 
 **Signature:**
 
 ```typescript
-export type TimePosition = {
-    current: TimeValue;
-    total: TimeValue;
-};
+export interface TimePosition 
 ```
-**References:** [TimeValue](./player.timevalue.md)
 
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[current](./player.timeposition.current.md)
+
+
+</td><td>
+
+
+</td><td>
+
+[TimeValue](./player.timevalue.md)
+
+
+</td><td>
+
+**_(BETA)_** Current playback time, 0..duration, seconds.
+
+
+</td></tr>
+<tr><td>
+
+[total](./player.timeposition.total.md)
+
+
+</td><td>
+
+
+</td><td>
+
+[TimeValue](./player.timevalue.md)
+
+
+</td><td>
+
+**_(BETA)_** Total duration of the media, seconds.
+
+
+</td></tr>
+</tbody></table>

package/docs/api/player.timeposition.total.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [TimePosition](./player.timeposition.md) &gt; [total](./player.timeposition.total.md)
+
+## TimePosition.total property
+
+> 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.
+> 
+
+Total duration of the media, seconds.
+
+**Signature:**
+
+```typescript
+total: TimeValue;
+```

package/docs/api/player.timevalue.md

@@ -7,7 +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.
 > 
 
-Playback time in seconds since the beginning of the stream (or a segment for the live streams) For the plugin development
+Playback time in seconds since the beginning of the stream (or a segment for the live streams)
 
 **Signature:**
 

package/docs/api/player.translationsettings.md

@@ -7,7 +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.
 > 
 
-\[language\]\[key\] =<!-- -->&gt; string
+Localization strings for the player UI.
 
 **Signature:**
 
@@ -16,6 +16,12 @@ export type TranslationSettings = Partial<Record<LangTag, Record<TranslationKey,
 ```
 **References:** [LangTag](./player.langtag.md)<!-- -->, [TranslationKey](./player.translationkey.md)
 
+## 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
 
 

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

package/lib/Player.d.ts

@@ -1,20 +1,31 @@
-import type { PlayerPlugin } from './types.js';
+import type { ContainerSize, PlayerPlugin } from './types.js';
 import { PlayerConfig, PlayerEvent } from './types.js';
+import { PlaybackError, TimePosition } from './playback.types.js';
 /**
  * @beta
  */
-export type PlayerEventHandler<T extends PlayerEvent> = () => void;
+export 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] : [];
 /**
+ * Type of a listener callback function for a player event.
+ * See the description of the event parameters in {@link PlayerEvent}.
+ * @beta
+ */
+export type PlayerEventHandler<E extends PlayerEvent> = (...args: PlayerEventParams<E>) => void;
+/**
+ * Module to perform the playback.
  * @beta
  */
 export type PlaybackModule = 'dash' | 'hls' | 'html5_video';
 /**
  * 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;
@@ -27,50 +38,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;
     /**
@@ -84,37 +140,62 @@ 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;
 }
 //# sourceMappingURL=Player.d.ts.map

package/lib/Player.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Player.d.ts","sourceRoot":"","sources":["../src/Player.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAyB,YAAY,EAAE,MAAM,YAAY,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAQtD;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,WAAW,IAAI,MAAM,IAAI,CAAA;AAelE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,aAAa,CAAA;AAI3D;;;;;;;GAOG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAgC;IAE9C,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,MAAM,CAA4B;IAE1C,OAAO,CAAC,KAAK,CAAQ;IAErB,OAAO,CAAC,QAAQ,CAA2B;IAE3C,OAAO,CAAC,aAAa,CAA6C;IAElE,OAAO,CAAC,OAAO,CAAQ;gBAEX,MAAM,EAAE,YAAY;IAOhC;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAIlE;;;;OAIG;IACH,GAAG,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAInE;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC;IAIvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,WAAW,GAAG,IAAI;IAoB1C;;OAEG;IACH,OAAO;IAgBP;;;OAGG;IACH,cAAc,IAAI,MAAM;IAOxB;;;OAGG;IACH,WAAW,IAAI,MAAM;IAOrB;;OAEG;IACH,IAAI;IAIJ;;OAEG;IACH,MAAM;IAIN;;OAEG;IACH,KAAK;IAIL;;OAEG;IACH,IAAI;IAIJ;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAIjD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM;IAIjB;;OAEG;IACH,IAAI;IAIJ;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY;IAI1C;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,YAAY;IAI5C,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;YAqBJ,MAAM;IAwEpB,OAAO,CAAC,MAAM,CAiDb;IAED,OAAO,CAAC,gBAAgB;IAyCxB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,2BAA2B;CAcpC"}
+{"version":3,"file":"Player.d.ts","sourceRoot":"","sources":["../src/Player.ts"],"names":[],"mappings":"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"}