npm - @gcorevideo/player - Versions diffs - 2.16.17 → 2.17.0 - Mend

@gcorevideo/player 2.16.17 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/README.md +68 -19
package/dist/index.js +93 -19
package/dist/player.d.ts +82 -51
package/docs/api/index.md +1 -1
package/docs/api/player.md +2 -2
package/docs/api/player.playbackerrorcode.md +4 -4
package/docs/api/player.player.attachto.md +26 -0
package/docs/api/player.player.configure.md +6 -2
package/docs/api/player.player.destroy.md +1 -1
package/docs/api/player.player.getcurrenttime.md +6 -2
package/docs/api/player.player.getduration.md +4 -0
package/docs/api/player.player.getvolume.md +22 -0
package/docs/api/player.player.isdvrenabled.md +20 -0
package/docs/api/player.player.isplaying.md +20 -0
package/docs/api/player.player.md +62 -8
package/docs/api/player.player.mute.md +1 -1
package/docs/api/player.player.off.md +1 -1
package/docs/api/player.player.registerplugin.md +14 -1
package/docs/api/player.player.resize.md +4 -0
package/docs/api/player.player.seek.md +1 -1
package/docs/api/player.player.setvolume.md +56 -0
package/docs/api/player.player.unmute.md +1 -1
package/docs/api/player.player.unregisterplugin.md +2 -2
package/lib/Player.d.ts +79 -14
package/lib/Player.d.ts.map +1 -1
package/lib/Player.js +91 -14
package/lib/index.d.ts +2 -3
package/lib/index.d.ts.map +1 -1
package/lib/index.js +2 -3
package/package.json +1 -1
package/rollup.config.js +1 -1
package/src/Player.ts +95 -15
package/src/__tests__/Player.test.ts +9 -3
package/src/index.ts +2 -3
package/src/utils/__tests__/mediaSources.test.ts +8 -2
package/temp/player.api.json +162 -21
package/tsconfig.tsbuildinfo +1 -1

package/README.md CHANGED Viewed

@@ -6,33 +6,82 @@
 npm install @gcorevideo/player
 ```
+Or use a script on the CDN directly in your HTML:
+```html
+<script src="https://player.gvideo.co/v2/assets/player/2.16.7/index.js"></script>
+```
+See also the [plugins package](../player-plugins/README.md) which almost always used with the player.
 ## Usage
-```ts
-import { Player } from '@gcorevideo/player'
+See the complete example app on Vercel: [https://github.com/dmitritz/gcore-videoplayer-js-nuxt](https://github.com/dmitritz/gcore-videoplayer-js-nuxt)
-import { MyFancyPlugin } from './plugins/my-fancy-plugin'
+### Plain HTML example
-Player.registerPlugin(MyFancyPlugin)
+```html
+<html>
+<head>
+    <link rel="stylesheet" href="https://player.gvideo.co/v2/assets/player-plugins/0.10.2/index.css" />
+    ...
+    <style>
+      #container {
+        width: 100%;
+        height: 0;
+        padding-bottom: 56.25%;
+        position: relative;
+        background-color:black;
+        color:#fff
+      }
+      #wrapper {
+        max-width: 400px;
+        margin: 1rem auto;
+      }
+    </style>
+</head>
+<body>
+<div id="wrapper">
+  <div id="container"></div>
+</div>
+<script type="module">
+  import {
+    Player,
+  } from 'https://player.gvideo.co/v2/assets/player/2.16.7/index.js'
+  import {
+    MediaControl,
+    SourceController,
+    Spinner,
+  } from 'https://player.gvideo.co/v2/assets/player-plugins/0.10.2/index.js'
-const player = new Player({
-  autoPlay: true,
-  mute: true,
-  sources: [{
-    source: 'https://example.com/myownair66.mpd',
-    mimeType: 'application/dash+xml',
-  }],
-  myFancyPlugin: {
-    color: 'rainbow',
-  }
-})
+  Player.registerPlugin(MediaControl)
+  Player.registerPlugin(SourceController)
+  Player.registerPlugin(Spinner)
-document.addEventListener('DOMContentLoaded', () => {
-    player.attachTo(document.getElementById('video-container'))
-})
+  const player = new Player({
+    autoPlay: true,
+    mute: true,
+    sources: [{
+      source: 'https://demo.gvideo.io/cmaf/2675_19146/index.mpd,
+      type: 'application/dash+xml',
+    }, {
+      source: 'https://demo.gvideo.io/cmaf/2675_19146/master.m3u8',
+      type: 'application/x-mpegURL',
+    }],
+    spinner: {
+      showOnError: true,
+      showOnStart: true,
+    }
+  })
+  document.addEventListener('DOMContentLoaded', () => {
+    player.attachTo(document.getElementById('container'))
+  })
+</script>
+</body>
+</html>
 ```
-See the complete example app on Vercel: [https://github.com/dmitritz/gcore-videoplayer-js-nuxt](https://github.com/dmitritz/gcore-videoplayer-js-nuxt)
+[Example codepen](https://codepen.io/dmitritz/pen/OPLdEab)
 ## Documentation

package/dist/index.js CHANGED Viewed

@@ -12273,9 +12273,6 @@ function buildMediaSourcesList(sources, priorityTransport = 'dash') {
     }, [[], []]);
     return preferred.concat(rest);
 }
-function unwrapSource(s) {
-    return typeof s === 'string' ? s : s.source;
-}
 function wrapSource(s) {
     return typeof s === 'string' ? { source: s, mimeType: guessMimeType(s) } : s;
 }
@@ -42290,7 +42287,7 @@ 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}
      */
@@ -42300,10 +42297,12 @@ 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);
@@ -42311,6 +42310,29 @@ 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');
@@ -42331,7 +42353,7 @@ 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`, {
@@ -42349,8 +42371,11 @@ 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) {
@@ -42360,7 +42385,10 @@ 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) {
@@ -42369,13 +42397,25 @@ 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();
@@ -42395,17 +42435,38 @@ 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.
      */
@@ -42414,14 +42475,27 @@ 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);
@@ -42619,7 +42693,7 @@ class Player {
     }
 }
-var version$1 = "2.16.17";
+var version$1 = "2.17.0";
 var packages = {
 	"node_modules/@clappr/core": {
@@ -42643,4 +42717,4 @@ function version() {
     };
 }
-export { LogTracer, Logger, PlaybackErrorCode, Player, PlayerEvent, SentryTracer, buildMediaSourcesList, isDashSource, isHlsSource, reportError, setTracer, trace, unwrapSource, version, wrapSource };
+export { LogTracer, Logger, PlaybackErrorCode, Player, PlayerEvent, SentryTracer, reportError, setTracer, trace, version };

package/dist/player.d.ts CHANGED Viewed

@@ -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';
@@ -41,39 +40,6 @@ export { LogTracer }
  */
 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;
-}
 /**
  * @beta
  */
@@ -90,7 +56,7 @@ export declare interface PlaybackError {
 export declare enum PlaybackErrorCode {
     Generic = 0,
     MediaSourceUnavailable = 1,
-    QualityLevelUnavailable = 2
+    MediaSourceAccessDenied = 3
 }
 /**
@@ -128,7 +94,7 @@ export declare class Player {
      */
     on<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>): void;
     /**
-     * Removes a listener from a player event
+     * Removes a previously added event listener
      * @param event - See {@link PlayerEvent}
      * @param handler - See {@link PlayerEventHandler}
      */
@@ -136,37 +102,76 @@ export declare 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>): 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 the playing state of the player.
+     */
+    isPlaying(): boolean;
+    /**
+     * Mutes the sound of the video.
      */
     mute(): void;
     /**
-     * Unmutes the player.
+     * Unmutes the video sound.
      */
     unmute(): void;
     /**
@@ -180,6 +185,9 @@ 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.
+     * It can be a case for orientation change on some mobile devices.
      */
     resize(newSize: {
         width: number;
@@ -187,21 +195,44 @@ export declare class Player {
     }): 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;

package/docs/api/index.md CHANGED Viewed

@@ -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.md CHANGED Viewed

@@ -4,11 +4,11 @@
 ## player package
-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. It is built on top of the Clappr library and provides a framework for building custom integrations.
+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.
 ## Classes

package/docs/api/player.playbackerrorcode.md CHANGED Viewed

@@ -50,12 +50,12 @@ Generic
 </td></tr>
 <tr><td>
-MediaSourceUnavailable
+MediaSourceAccessDenied
 </td><td>
-`1`
+`3`
 </td><td>
@@ -66,12 +66,12 @@ MediaSourceUnavailable
 </td></tr>
 <tr><td>
-QualityLevelUnavailable
+MediaSourceUnavailable
 </td><td>
-`2`
+`1`
 </td><td>

package/docs/api/player.player.attachto.md CHANGED Viewed

@@ -54,3 +54,29 @@ DOM element to host the player
 void
+## 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 [Player.destroy()](./player.player.destroy.md) and then [Player.attachTo()](./player.player.attachto.md)<!-- -->.
+## 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'))
+})
+```

package/docs/api/player.player.configure.md CHANGED Viewed

@@ -9,8 +9,6 @@
 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).
 **Signature:**
 ```typescript
@@ -56,3 +54,9 @@ complete or partial configuration
 void
+## 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).

package/docs/api/player.player.destroy.md CHANGED Viewed

@@ -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.
 >
-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.
 **Signature:**

package/docs/api/player.player.getcurrenttime.md CHANGED Viewed

@@ -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.
 >
-Current playback time in seconds, if appropriate.
+Current playback (time since the beginning of the stream), if appropriate.
 **Signature:**
@@ -18,5 +18,9 @@ getCurrentTime(): number;
 number
-For live streams, it returns the current time of the current segment.
+Time in seconds
+## Remarks
+For live streams, it returns the current time within the current segment.

package/docs/api/player.player.getduration.md CHANGED Viewed

@@ -18,5 +18,9 @@ getDuration(): number;
 number
+Time in seconds
+## Remarks
 For live streams, it returns the duration of the current segment.