@gcorevideo/player 2.16.17 → 2.17.0

package/lib/Player.js

@@ -47,7 +47,7 @@ export class Player {
         this.emitter.on(event, handler);
     }
     /**
-     * Removes a listener from a player event
+     * Removes a previously added event listener
      * @param event - See {@link PlayerEvent}
      * @param handler - See {@link PlayerEventHandler}
      */
@@ -57,10 +57,12 @@ export class Player {
     /**
      * 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) {
         this.setConfig(config);
@@ -68,6 +70,29 @@ export class Player {
     /**
      * 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) {
         assert.ok(!this.player, 'Player already initialized');
@@ -88,7 +113,7 @@ export class Player {
         return this.initPlayer(coreOpts);
     }
     /**
-     * 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() {
         trace(`${T} destroy`, {
@@ -106,8 +131,11 @@ export class Player {
         }
     }
     /**
-     * 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() {
         if (!this.player) {
@@ -117,7 +145,10 @@ export class Player {
     }
     /**
      * 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() {
         if (!this.player) {
@@ -126,13 +157,25 @@ export class Player {
         return this.player.getDuration();
     }
     /**
-     * Mutes the player.
+     * Indicates whether DVR is enabled.
+     */
+    isDvrEnabled() {
+        return this.player?.isDvrEnabled() ?? false;
+    }
+    /**
+     * Indicates the playing state of the player.
+     */
+    isPlaying() {
+        return this.player?.isPlaying() ?? false;
+    }
+    /**
+     * Mutes the sound of the video.
      */
     mute() {
         this.player?.mute();
     }
     /**
-     * Unmutes the player.
+     * Unmutes the video sound.
      */
     unmute() {
         this.player?.unmute();
@@ -152,17 +195,38 @@ export 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.
+     * It can be a case for orientation change on some mobile devices.
      */
     resize(newSize) {
         this.player?.resize(newSize);
     }
     /**
      * 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) {
         this.player?.seek(time);
     }
+    /**
+     * Gets the current volume of the media content being played.
+     * @returns a number between 0 and 1
+     */
+    getVolume() {
+        // This method is provided by the MediaControl plugin
+        // @ts-ignore
+        return this.player?.getVolume?.() || 0;
+    }
+    /**
+     * Sets the current volume of the media content being played.
+     * @param volume - a number between 0 and 1
+     */
+    setVolume(volume) {
+        // This method is provided by the MediaControl plugin
+        // @ts-ignore
+        this.player?.setVolume?.(volume);
+    }
     /**
      * Stops playback.
      */
@@ -171,14 +235,27 @@ export class Player {
     }
     /**
      * 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) {
         Loader.registerPlugin(plugin);
     }
     /**
-     * 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) {
         Loader.unregisterPlugin(plugin);

package/lib/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * 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
@@ -11,6 +11,5 @@ export { LogTracer, Logger, SentryTracer, reportError, setTracer, trace } from '
 export * from './Player.js';
 export * from './playback.types.js';
 export * from './types.js';
-export * from './utils/mediaSources.js';
 export * from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAClG,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAClG,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}

package/lib/index.js

@@ -1,8 +1,8 @@
 /**
- * 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
@@ -11,5 +11,4 @@ export { LogTracer, Logger, SentryTracer, reportError, setTracer, trace } from '
 export * from './Player.js';
 export * from './playback.types.js';
 export * from './types.js';
-export * from './utils/mediaSources.js';
 export * from './version.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcorevideo/player",
-  "version": "2.16.17",
+  "version": "2.17.0",
   "description": "Gcore JavaScript video player",
   "main": "dist/index.js",
   "type": "module",

package/rollup.config.js

@@ -8,7 +8,7 @@ export default [
   {
     input: 'lib/index.js',
     plugins: [
-      resolve(),
+      resolve(), // TODO check which aren't inlined in the bundle and put them here
       commonjs(),
       json(),
       polyfillNode(),

package/src/Player.ts

@@ -19,7 +19,6 @@ import type { PlayerMediaSourceDesc, PlayerPlugin } from './types.js'
 import { PlayerConfig, PlayerEvent } from './types.js'
 import {
   buildMediaSourcesList,
-  unwrapSource,
   wrapSource,
 } from './utils/mediaSources.js'
 import { registerPlaybacks } from './playback/index.js'
@@ -89,7 +88,7 @@ export class Player {
   }
 
   /**
-   * Removes a listener from a player event
+   * Removes a previously added event listener
    * @param event - See {@link PlayerEvent}
    * @param handler - See {@link PlayerEventHandler}
    */
@@ -100,10 +99,12 @@ export class Player {
   /**
    * 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>) {
     this.setConfig(config)
@@ -112,6 +113,29 @@ export class Player {
   /**
    * 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 {
     assert.ok(!this.player, 'Player already initialized')
@@ -134,7 +158,7 @@ export class Player {
   }
 
   /**
-   * 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() {
     trace(`${T} destroy`, {
@@ -153,8 +177,11 @@ export class Player {
   }
 
   /**
-   * 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 {
     if (!this.player) {
@@ -165,7 +192,10 @@ export class Player {
 
   /**
    * 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 {
     if (!this.player) {
@@ -175,14 +205,28 @@ export class Player {
   }
 
   /**
-   * Mutes the player.
+   * Indicates whether DVR is enabled.
+   */
+  isDvrEnabled(): boolean {
+    return this.player?.isDvrEnabled() ?? false
+  }
+
+  /**
+   * Indicates the playing state of the player.
+   */
+  isPlaying(): boolean {
+    return this.player?.isPlaying() ?? false
+  }
+
+  /**
+   * Mutes the sound of the video.
    */
   mute() {
     this.player?.mute()
   }
 
   /**
-   * Unmutes the player.
+   * Unmutes the video sound.
    */
   unmute() {
     this.player?.unmute()
@@ -205,6 +249,9 @@ export 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.
+   * It can be a case for orientation change on some mobile devices.
    */
   resize(newSize: { width: number; height: number }) {
     this.player?.resize(newSize)
@@ -212,12 +259,32 @@ export class Player {
 
   /**
    * 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) {
     this.player?.seek(time)
   }
 
+  /**
+   * Gets the current volume of the media content being played.
+   * @returns a number between 0 and 1
+   */
+  getVolume(): number {
+    // This method is provided by the MediaControl plugin
+    // @ts-ignore
+    return this.player?.getVolume?.() || 0
+  }
+
+  /**
+   * Sets the current volume of the media content being played.
+   * @param volume - a number between 0 and 1
+   */
+  setVolume(volume: number) {
+    // This method is provided by the MediaControl plugin
+    // @ts-ignore
+    this.player?.setVolume?.(volume)
+  }
+
   /**
    * Stops playback.
    */
@@ -227,15 +294,28 @@ export class Player {
 
   /**
    * 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) {
     Loader.registerPlugin(plugin)
   }
 
   /**
-   * 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) {
     Loader.unregisterPlugin(plugin)

package/src/__tests__/Player.test.ts

@@ -34,21 +34,27 @@ vi.mock('@clappr/core', async () => {
   const imported = await import('@clappr/core')
   const MockDashPlayback = {
     _supported: true,
-    name: 'dash',
+    prototype: {
+      name: 'dash',
+    },
     canPlay(source, mimeType) {
       return this._supported && (mimeType === 'application/dash+xml' || source.endsWith('.mpd'))
     },
   }
   const MockHlsPlayback = {
     _supported: true,
-    name: 'hls',
+    prototype: {
+      name: 'hls',
+    },
     canPlay(source, mimeType) {
       return this._supported && (['application/vnd.apple.mpegurl', 'application/x-mpegurl'].includes(mimeType) || source.endsWith('.m3u8'))
     },
   }
   const MockHTML5VideoPlayback = {
     _supported: true,
-    name: 'html5_video',
+    prototype: {
+      name: 'html5_video',
+    },
     canPlay(source, mimeType) {
       return this._supported && ['video/mp4', 'application/vnd.apple.mpegurl'].includes(mimeType)
     },

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * 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
@@ -12,5 +12,4 @@ export { LogTracer, Logger, SentryTracer, reportError, setTracer, trace } from '
 export * from './Player.js'
 export * from './playback.types.js'
 export * from './types.js'
-export * from './utils/mediaSources.js'
 export * from './version.js'

package/src/utils/__tests__/mediaSources.test.ts

@@ -10,21 +10,27 @@ vi.mock('@clappr/core', () => ({
     registeredPlaybacks: [
       {
         _supported: true,
+        prototype: {
         name: 'dash',
+        },
         canPlay(source, mimeType) {
           return this._supported && (mimeType === 'application/dash+xml' || source.endsWith('.mpd'))
         },
       },
       {
         _supported: true,
-        name: 'hls',
+        prototype: {
+          name: 'hls',
+        },
         canPlay(source, mimeType) {
           return this._supported && (['application/vnd.apple.mpegurl', 'application/x-mpegurl'].includes(mimeType) || source.endsWith('.m3u8'))
         },
       },
       {
         _supported: true,
-        name: 'html5_video',
+        prototype: {
+          name: 'html5_video',
+        },
         canPlay: function (source, mimeType) {
           return this._supported && mimeType === 'video/mp4'
         },