@gcorevideo/player 2.16.17 → 2.18.0

package/src/Player.ts

@@ -15,19 +15,33 @@ import type {
   CoreOptions,
   CorePluginOptions,
 } from './internal.types.js'
-import type { PlayerMediaSourceDesc, PlayerPlugin } from './types.js'
+import type { ContainerSize, 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'
+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
 
 const T = 'GPlayer'
 
@@ -43,6 +57,7 @@ const DEFAULT_OPTIONS: PlayerConfig = {
 }
 
 /**
+ * Module to perform the playback.
  * @beta
  */
 export type PlaybackModule = 'dash' | 'hls' | 'html5_video'
@@ -51,11 +66,11 @@ type PluginOptions = Record<string, unknown>
 
 /**
  * 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 class Player {
   private config: PlayerConfig = DEFAULT_OPTIONS
@@ -81,29 +96,31 @@ export class Player {
 
   /**
    * 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>) {
+  on<E extends PlayerEvent>(event: E, handler: PlayerEventHandler<E>) {
     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}
+   * @param handler - a callback attached earlier to that event type
    */
-  off<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>) {
+  off<E extends PlayerEvent>(event: E, handler: PlayerEventHandler<E>) {
     this.emitter.off(event, handler)
   }
 
   /**
    * 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 +129,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 +174,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 +193,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 +208,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 +221,37 @@ export class Player {
   }
 
   /**
-   * Mutes the player.
+   * Indicates whether DVR is enabled.
+   */
+  isDvrEnabled(): boolean {
+    return this.player?.isDvrEnabled() ?? false
+  }
+
+  /**
+   * 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 {
+    return this.player?.isDvrInUse() ?? false
+  }
+
+  /**
+   * Indicates the playing state.
+   */
+  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,19 +274,42 @@ 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 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 }) {
+  resize(newSize: ContainerSize) {
     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: 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 +319,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)
@@ -277,50 +382,15 @@ export class Player {
     }
     this.tunedIn = true
     const player = this.player
+    
     this.bindContainerEventListeners(player)
     player.core.on(
       ClapprEvents.CORE_ACTIVE_CONTAINER_CHANGED,
       () => this.bindContainerEventListeners(player),
       null,
     )
-    player.core.on(
-      ClapprEvents.CORE_SCREEN_ORIENTATION_CHANGED,
-      ({ orientation }: { orientation: 'landscape' | 'portrait' }) => {
-        trace(`${T} CORE_SCREEN_ORIENTATION_CHANGED`, {
-          orientation,
-          rootNode: {
-            width: this.rootNode?.clientWidth,
-            height: this.rootNode?.clientHeight,
-          },
-        })
-        if (Browser.isiOS && this.rootNode) {
-          player.core.resize({
-            width: this.rootNode.clientWidth,
-            height: this.rootNode.clientHeight,
-          })
-        }
-      },
-      null,
-    )
-    player.core.on(
-      ClapprEvents.CORE_RESIZE,
-      ({ width, height }: { width: number; height: number }) => {
-        trace(`${T} CORE_RESIZE`, {
-          width,
-          height,
-        })
-      },
-      null,
-    )
-    player.core.on(
-      ClapprEvents.CORE_FULLSCREEN,
-      (isFullscreen: boolean) => {
-        trace(`${T} CORE_FULLSCREEN`, {
-          isFullscreen,
-        })
-      },
-      null,
-    )
+    this.bindSizeManagementListeners(player)
+
     if (this.config.autoPlay) {
       setTimeout(() => {
         trace(`${T} autoPlay`, {
@@ -338,6 +408,15 @@ export class Player {
     }
   }
 
+  private safeTriggerEvent<E extends PlayerEvent>(event: E, ...args: PlayerEventParams<E>) {
+    try {
+      this.emitter.emit(event, ...args)
+    } catch (e) {
+      reportError(e)
+    }
+  }
+
+  // TODO test
   private events: CorePlayerEvents = {
     onReady: () => {
       trace(`${T} onReady`, {
@@ -354,38 +433,29 @@ export class Player {
       // TODO ensure that CORE_ACTIVE_CONTAINER_CHANGED does not get caught before onReady
       setTimeout(() => this.tuneIn(), 0)
     },
-    onResize: (newSize: { width: number; height: number }) => {
-      trace(`${T} onResize`, {
-        newSize,
-      })
-    },
     onPlay: () => {
-      try {
-        this.emitter.emit(PlayerEvent.Play)
-      } catch (e) {
-        reportError(e)
-      }
+      this.safeTriggerEvent(PlayerEvent.Play)
     },
     onPause: () => {
-      try {
-        this.emitter.emit(PlayerEvent.Pause)
-      } catch (e) {
-        reportError(e)
-      }
+      this.safeTriggerEvent(PlayerEvent.Pause)
     },
     onEnded: () => {
-      try {
-        this.emitter.emit(PlayerEvent.Ended)
-      } catch (e) {
-        reportError(e)
-      }
+      this.safeTriggerEvent(PlayerEvent.Ended)
+    },
+    onSeek: (time: number) => {
+      this.safeTriggerEvent(PlayerEvent.Seek, time)
     },
     onStop: () => {
-      try {
-        this.emitter.emit(PlayerEvent.Stop)
-      } catch (e) {
-        reportError(e)
-      }
+      this.safeTriggerEvent(PlayerEvent.Stop)
+    },
+    onVolumeUpdate: (volume: number) => {
+      this.safeTriggerEvent(PlayerEvent.VolumeUpdate, volume)
+    },
+    onTimeUpdate: (time: TimePosition) => {
+      this.safeTriggerEvent(PlayerEvent.TimeUpdate, time)
+    },
+    onError: (error: PlaybackError) => {
+      this.safeTriggerEvent(PlayerEvent.Error, error)
     },
   }
 
@@ -416,6 +486,7 @@ export class Player {
         mute: this.config.mute,
         crossOrigin: 'anonymous', // TODO
         hlsjsConfig: {
+          // TODO
           debug: this.config.debug === 'all' || this.config.debug === 'hls',
         },
       },
@@ -424,7 +495,7 @@ export class Player {
       width: rootNode.clientWidth,
       source: source ? source.source : undefined,
       mimeType: source ? source.mimeType : undefined,
-      sources, // prevent Clappr from loading all sources simultaneously
+      sources,
       strings: this.config.strings,
     }
     return coreOptions
@@ -443,9 +514,6 @@ export class Player {
   }
 
   private bindContainerEventListeners(player: PlayerClappr) {
-    trace(`${T} bindContainerEventListeners`, {
-      activePlayback: player.core.activePlayback?.name,
-    })
     if (Browser.isiOS && player.core.activePlayback) {
       player.core.activePlayback.$el.on('webkitendfullscreen', () => {
         try {
@@ -456,4 +524,47 @@ export class Player {
       })
     }
   }
+
+  private bindSizeManagementListeners(player: PlayerClappr) {
+    player.core.on(
+      ClapprEvents.CORE_SCREEN_ORIENTATION_CHANGED,
+      ({ orientation }: { orientation: 'landscape' | 'portrait' }) => {
+        trace(`${T} on CORE_SCREEN_ORIENTATION_CHANGED`, {
+          orientation,
+          rootNode: {
+            width: this.rootNode?.clientWidth,
+            height: this.rootNode?.clientHeight,
+          },
+        })
+        if (Browser.isiOS && this.rootNode) {
+          player.core.resize({
+            width: this.rootNode.clientWidth,
+            height: this.rootNode.clientHeight,
+          })
+        }
+      },
+      null,
+    )
+    player.core.on(
+      ClapprEvents.CORE_RESIZE,
+      ({ width, height }: { width: number; height: number }) => {
+        trace(`${T} on CORE_RESIZE`, {
+          width,
+          height,
+        })
+        this.safeTriggerEvent(PlayerEvent.Resize, { width, height })
+      },
+      null,
+    )
+    player.core.on(
+      ClapprEvents.CORE_FULLSCREEN,
+      (isFullscreen: boolean) => {
+        trace(`${T} CORE_FULLSCREEN`, {
+          isFullscreen,
+        })
+        this.safeTriggerEvent(PlayerEvent.Fullscreen, isFullscreen)
+      },
+      null,
+    )
+  }
 }

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/internal.types.ts

@@ -4,7 +4,7 @@ import type {
   Playback as ClapprPlayback,
 } from "@clappr/core";
 
-import { PlaybackType, PlayerDebugTag, PlayerMediaSource } from "./types";
+import { ContainerSize, PlaybackType, PlayerDebugTag, PlayerMediaSource } from "./types";
 import { PlaybackError } from "./playback.types";
 
 type ExternalTrack = {
@@ -54,6 +54,7 @@ export interface CorePlaybackConfig {
   playInline: boolean;
   preload?: 'metadata' | 'auto' | 'none';
   // preferredAudioLanguage?: string;
+  recycleVideo?: boolean;
   shakaConfiguration?: ShakaConfig;
 }
 
@@ -63,7 +64,7 @@ export interface CorePlaybackConfig {
 export type CorePlayerEvents = {
   // TODO event arguments types
   onReady?: () => void;
-  onResize?: (data: { width: number; height: number }) => void;
+  onResize?: (data: ContainerSize) => void;
   onPlay?: (metadata: unknown) => void;
   onPause?: (metadata: unknown) => void;
   onStop?: (metadata: unknown) => void;