@gcorevideo/player 2.17.0 → 2.18.0

package/src/Player.ts

@@ -15,18 +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,
   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'
 
@@ -42,6 +57,7 @@ const DEFAULT_OPTIONS: PlayerConfig = {
 }
 
 /**
+ * Module to perform the playback.
  * @beta
  */
 export type PlaybackModule = 'dash' | 'hls' | 'html5_video'
@@ -50,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
@@ -80,19 +96,19 @@ 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 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)
   }
 
@@ -212,7 +228,16 @@ export class Player {
   }
 
   /**
-   * 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 {
+    return this.player?.isDvrInUse() ?? false
+  }
+
+  /**
+   * Indicates the playing state.
    */
   isPlaying(): boolean {
     return this.player?.isPlaying() ?? false
@@ -250,10 +275,10 @@ 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.
+   * 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)
   }
 
@@ -357,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`, {
@@ -418,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`, {
@@ -434,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)
     },
   }
 
@@ -496,6 +486,7 @@ export class Player {
         mute: this.config.mute,
         crossOrigin: 'anonymous', // TODO
         hlsjsConfig: {
+          // TODO
           debug: this.config.debug === 'all' || this.config.debug === 'hls',
         },
       },
@@ -504,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
@@ -523,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 {
@@ -536,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/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;

package/src/playback/dash-playback/DashPlayback.ts

@@ -2,7 +2,15 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-import { Events, HTML5Video, Log, Playback, PlayerError, Utils } from '@clappr/core'
+import {
+  Events,
+  HTML5Video,
+  Log,
+  Playback,
+  PlayerError,
+  Utils,
+  $,
+} from '@clappr/core'
 import { trace } from '@gcorevideo/utils'
 import assert from 'assert'
 import DASHJS, {
@@ -14,7 +22,15 @@ import DASHJS, {
   IManifestInfo,
 } from 'dashjs'
 
-import { PlaybackError, PlaybackErrorCode, QualityLevel, TimePosition, TimeUpdate, TimeValue } from '../../playback.types.js'
+import {
+  PlaybackError,
+  PlaybackErrorCode,
+  PlayerComponentType,
+  QualityLevel,
+  TimePosition,
+  TimeUpdate,
+  TimeValue,
+} from '../../playback.types.js'
 import { isDashSource } from '../../utils/mediaSources.js'
 
 const AUTO = -1
@@ -123,13 +139,15 @@ export default class DashPlayback extends HTML5Video {
     )
     const dash = this._dash
 
-    // TODO use $.extend
-    const settings = this.options.dash ? structuredClone(this.options.dash) : {}
-    settings.streaming = settings.streaming || {}
-    settings.streaming.abr = settings.streaming.abr || {}
-    settings.streaming.abr.autoSwitchBitrate =
-      settings.streaming.abr.autoSwitchBitrate || {}
-    settings.streaming.abr.autoSwitchBitrate.video = id === -1
+    const settings = $.extend(true, {}, this.options.dash, {
+      streaming: {
+        abr: {
+          autoSwitchBitrate: {
+            video: id === -1,
+          },
+        },
+      },
+    })
 
     dash.updateSettings(settings)
     if (id !== -1) {
@@ -222,16 +240,14 @@ export default class DashPlayback extends HTML5Video {
 
     if (this.options.dash) {
       // TODO use $.extend
-      const settings = structuredClone(this.options.dash)
-      if (!settings.streaming) {
-        settings.streaming = {}
-      }
-      if (!settings.streaming.text) {
-        settings.streaming.text = {
-          defaultEnabled: false,
-        }
-      }
-      this._dash.updateSettings(this.options.dash)
+      const settings = $.extend({}, this.options.dash, {
+        streaming: {
+          text: {
+            defaultEnabled: false,
+          },
+        },
+      })
+      this._dash.updateSettings(settings)
     }
 
     this._dash.attachView(this.el)
@@ -250,20 +266,18 @@ export default class DashPlayback extends HTML5Video {
 
       this._updatePlaybackType()
       this._fillLevels(bitrates)
+
       dash.on(DASHJS.MediaPlayer.events.QUALITY_CHANGE_REQUESTED, (evt) => {
-        // TODO
-        assert.ok(
-          this._levels,
-          'An array of levels is required to change quality',
-        )
-        const newLevel = this._levels.find(
-          (level) => level.level === evt.newQuality,
-        ) // TODO or simply this._levels[evt.newQuality]?
-        assert.ok(newLevel, 'A valid level is required to change quality')
+        const newLevel = this.getLevel(evt.newQuality)
         this.onLevelSwitch(newLevel)
       })
     })
 
+    this._dash.on(DASHJS.MediaPlayer.events.QUALITY_CHANGE_RENDERED, (evt: DASHJS.QualityChangeRenderedEvent) => {
+      const currentLevel = this.getLevel(evt.newQuality)
+      this.onLevelSwitchEnd(currentLevel)
+    })
+
     this._dash.on(
       DASHJS.MediaPlayer.events.METRIC_ADDED,
       (e: DashMetricEvent) => {
@@ -409,7 +423,6 @@ export default class DashPlayback extends HTML5Video {
     trace(`${T} _onDASHJSSError`, { event })
     this._stopTimeUpdateTimer()
 
-
     // Note that the other error types are deprecated
     const e = (event as MediaPlayerErrorEvent).error
     switch (e.code) {
@@ -419,7 +432,7 @@ export default class DashPlayback extends HTML5Video {
       case DASHJS.MediaPlayer.errors.DOWNLOAD_ERROR_ID_MANIFEST_CODE:
       case DASHJS.MediaPlayer.errors.DOWNLOAD_ERROR_ID_CONTENT_CODE:
       case DASHJS.MediaPlayer.errors.DOWNLOAD_ERROR_ID_INITIALIZATION_CODE:
-        // TODO these probably indicate a broken manifest and should be treated by removing the source
+      // TODO these probably indicate a broken manifest and should be treated by removing the source
       case DASHJS.MediaPlayer.errors.MANIFEST_ERROR_ID_NOSTREAMS_CODE:
       case DASHJS.MediaPlayer.errors.MANIFEST_ERROR_ID_PARSE_CODE:
       case DASHJS.MediaPlayer.errors.MANIFEST_ERROR_ID_MULTIPLEXED_CODE:
@@ -431,7 +444,7 @@ export default class DashPlayback extends HTML5Video {
           description: e.message,
           level: PlayerError.Levels.FATAL,
         })
-        break;
+        break
       // TODO more cases
       default:
         this.triggerError({
@@ -443,9 +456,15 @@ export default class DashPlayback extends HTML5Video {
     }
   }
 
-  private triggerError(error: PlaybackError) {
+  private triggerError(
+    error: Pick<PlaybackError, 'code' | 'message' | 'description' | 'level'>,
+  ) {
     trace(`${T} triggerError`, { error })
-    this.trigger(Events.PLAYBACK_ERROR, error)
+    this.trigger(Events.PLAYBACK_ERROR, {
+      ...error,
+      origin: this.name,
+      scope: DashPlayback.type as PlayerComponentType,
+    })
     // only reset the dash player in 10ms async, so that the rest of the
     // calling function finishes
     setTimeout(() => {
@@ -591,9 +610,13 @@ export default class DashPlayback extends HTML5Video {
   private onLevelSwitch(currentLevel: QualityLevel) {
     // TODO check the two below
     this.trigger(Events.PLAYBACK_LEVEL_SWITCH, currentLevel)
+  }
+
+  private onLevelSwitchEnd(currentLevel: QualityLevel) {
     this.trigger(Events.PLAYBACK_LEVEL_SWITCH_END)
-    const isHD = (currentLevel.height >= 720 || (currentLevel.bitrate / 1000) >= 2000);
-    this.trigger(Events.PLAYBACK_HIGHDEFINITIONUPDATE, isHD);
+    const isHD =
+      currentLevel.height >= 720 || currentLevel.bitrate / 1000 >= 2000
+    this.trigger(Events.PLAYBACK_HIGHDEFINITIONUPDATE, isHD)
     this.trigger(Events.PLAYBACK_BITRATE, currentLevel)
   }
 
@@ -604,6 +627,12 @@ export default class DashPlayback extends HTML5Video {
   isSeekEnabled() {
     return this._playbackType === Playback.VOD || this.dvrEnabled
   }
+
+  private getLevel(quality: number) {
+    const ret = this.levels.find((level) => level.level === quality)
+    assert.ok(ret, 'Invalid quality level')
+    return ret
+  }
 }
 
 DashPlayback.canPlay = function (resource, mimeType) {

package/src/playback/hls-playback/HlsPlayback.ts

@@ -28,6 +28,7 @@ import HLSJS, {
 import {
   PlaybackError,
   PlaybackErrorCode,
+  PlayerComponentType,
   QualityLevel,
   TimePosition,
   TimeUpdate,
@@ -426,6 +427,11 @@ export default class HlsPlayback extends HTML5Video {
       (evt: HlsEvents.LEVEL_SWITCHING, data: LevelSwitchingData) =>
         this._onLevelSwitch(evt, data),
     )
+    this._hls.on(
+      HLSJS.Events.LEVEL_SWITCHED,
+      (evt: HlsEvents.LEVEL_SWITCHED, data: { level: number }) =>
+        this._onLevelSwitched(evt, data),
+    )
     this._hls.on(
       HLSJS.Events.FRAG_CHANGED,
       (evt: HlsEvents.FRAG_CHANGED, data: FragChangedData) =>
@@ -511,7 +517,10 @@ export default class HlsPlayback extends HTML5Video {
       this._hls.recoverMediaError()
     } else {
       Log.error('hlsjs: failed to recover', { evt, data })
-      trace(`${T} _recover failed to recover`, { type: data.type, details: data.details })
+      trace(`${T} _recover failed to recover`, {
+        type: data.type,
+        details: data.details,
+      })
       error.level = PlayerError.Levels.FATAL
 
       this.triggerError(error)
@@ -614,12 +623,18 @@ export default class HlsPlayback extends HTML5Video {
   }
 
   _onHLSJSError(evt: HlsEvents.ERROR, data: HlsErrorData) {
-    trace(`${T} _onHLSJSError`, { fatal: data.fatal, type: data.type, details: data.details })
+    trace(`${T} _onHLSJSError`, {
+      fatal: data.fatal,
+      type: data.type,
+      details: data.details,
+    })
     const error: PlaybackError = {
       code: PlaybackErrorCode.Generic,
       description: `${this.name} error: type: ${data.type}, details: ${data.details} fatal: ${data.fatal}`,
       level: data.fatal ? PlayerError.Levels.FATAL : PlayerError.Levels.WARN,
       message: `${this.name} error: type: ${data.type}, details: ${data.details}`,
+      origin: this.name,
+      scope: HlsPlayback.type as PlayerComponentType,
     }
 
     if (data.response) {
@@ -657,9 +672,12 @@ export default class HlsPlayback extends HTML5Video {
                   evt,
                   data,
                 })
-                trace(`${T} _onHLSJSError trying to recover from network error`, {
-                  details: data.details,
-                })
+                trace(
+                  `${T} _onHLSJSError trying to recover from network error`,
+                  {
+                    details: data.details,
+                  },
+                )
                 error.level = PlayerError.Levels.WARN
                 this._hls?.startLoad()
                 break
@@ -705,7 +723,10 @@ export default class HlsPlayback extends HTML5Video {
       }
 
       Log.warn('hlsjs: non-fatal error occurred', { evt, data })
-      trace(`${T} _onHLSJSError non-fatal error occurred`, { type: data.type, details: data.details })
+      trace(`${T} _onHLSJSError non-fatal error occurred`, {
+        type: data.type,
+        details: data.details,
+      })
     }
   }
 
@@ -1035,23 +1056,26 @@ export default class HlsPlayback extends HTML5Video {
     if (!this.levels.length) {
       this._fillLevels()
     }
-    this.trigger(Events.PLAYBACK_LEVEL_SWITCH_END)
     this.trigger(Events.PLAYBACK_LEVEL_SWITCH, data)
-    assert(this._hls, 'Hls.js instance is not available')
-    const currentLevel = this._hls.levels[data.level]
-
-    if (currentLevel) {
-      // TODO should highDefinition be private and maybe have a read only accessor if it's used somewhere
-      this.highDefinition =
-        currentLevel.height >= 720 || currentLevel.bitrate / 1000 >= 2000
-      this.trigger(Events.PLAYBACK_HIGHDEFINITIONUPDATE, this.highDefinition)
-      this.trigger(Events.PLAYBACK_BITRATE, {
-        height: currentLevel.height,
-        width: currentLevel.width,
-        bitrate: currentLevel.bitrate,
-        level: data.level,
-      })
-    }
+  }
+
+  _onLevelSwitched(evt: HlsEvents.LEVEL_SWITCHED, data: { level: number }) {
+    // @ts-ignore
+    const currentLevel = this._hls.levels[data.level] // TODO or find by .id == level?
+    assert.ok(currentLevel, 'Invalid quality level')
+    this._currentLevel = data.level
+
+    // TODO should highDefinition be private and maybe have a read only accessor if it's used somewhere
+    this.highDefinition =
+      currentLevel.height >= 720 || currentLevel.bitrate / 1000 >= 2000
+    this.trigger(Events.PLAYBACK_HIGHDEFINITIONUPDATE, this.highDefinition)
+    this.trigger(Events.PLAYBACK_BITRATE, {
+      height: currentLevel.height,
+      width: currentLevel.width,
+      bitrate: currentLevel.bitrate,
+      level: data.level,
+    })
+    this.trigger(Events.PLAYBACK_LEVEL_SWITCH_END)
   }
 
   get dvrEnabled() {