@gcorevideo/player 2.16.17 → 2.18.0

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() {

package/src/playback.types.ts

@@ -1,16 +1,21 @@
 /**
  * Playback time in seconds since the beginning of the stream (or a segment for the live streams)
- * For the plugin development
  * @beta
  */
 export type TimeValue = number
 
 /**
- * For the plugin development
+ * Current playback time and total duration of the media.
  * @beta
  */
-export type TimePosition = {
+export interface TimePosition {
+  /**
+   * Current playback time, 0..duration, seconds.
+   */
   current: TimeValue
+  /**
+   * Total duration of the media, seconds.
+   */
   total: TimeValue
 }
 
@@ -29,35 +34,90 @@ export type TimeUpdate = TimePosition & {
 }
 
 /**
+ * A level of quality within a media source.
  * @beta
  */
-export type QualityLevel = {
-  level: number // 0-based index
+export interface QualityLevel {
+  /**
+   * Zero-based index of the quality level.
+   */
+  level: number
+  /**
+   * Width of the video, pixels.
+   */
   width: number
+  /**
+   * Height of the video, pixels.
+   */
   height: number
+  /**
+   * Bitrate of the video, bps.
+   */
   bitrate: number
 }
 
 /**
+ * Codes of errors occurring within the playback component.
  * @beta
  */
 export enum PlaybackErrorCode {
+  /**
+   * An unknown or uncategorised error.
+   */
   Generic = 0,
+  /**
+   * The media source is not available. Typically a network error.
+   */
   MediaSourceUnavailable = 1,
+  /**
+   * The media source is not accessible due to some protection policy.
+   */
   MediaSourceAccessDenied = 3,
 }
 
 /**
+ * Levels of severity of errors. Non-fatal errors usually can be ignored.
  * @beta
  */
 export type ErrorLevel = 'FATAL' | 'WARN' | 'INFO'
 
 /**
+ * Subsystems of a player component.
+ * @beta
+ */
+export type PlayerComponentType = 'container' | 'core' | 'playback'
+
+/**
+ * An error occurred during the playback.
  * @beta
  */
 export interface PlaybackError {
+  /**
+   * Error code.
+   */
   code: PlaybackErrorCode
+  /**
+   * Detailed description of the error.
+   */
   description: string
+  /**
+   * Level of severity of the error.
+   */
   level: ErrorLevel
+  /**
+   * Error message. Non-fatal usually can be ignored.
+   */
   message: string
+  /**
+   * Exact component that originated the error.
+   * @example
+   * - 'core'
+   * - 'dash'
+   * - 'media_control'
+   */
+  origin: string
+  /**
+   * Component subsystem of the error origin
+   */
+  scope: PlayerComponentType
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-import { ContainerPlugin, CorePlugin } from "@clappr/core"
+import { ContainerPlugin, CorePlugin } from '@clappr/core'
 
 /**
  * Describes a media source with its MIME type and URL.
@@ -10,7 +10,8 @@ import { ContainerPlugin, CorePlugin } from "@clappr/core"
  */
 export interface PlayerMediaSourceDesc {
   /**
-   * The MIME type of the media source (e.g. "video/mp4", "application/x-mpegURL")
+   * The MIME type of the media source (e.g. `"video/mp4"`, `"application/x-mpegURL"`).
+   * Necessary if the type cannot be detected from file extension of the source URL.
    */
   mimeType?: string
 
@@ -27,12 +28,13 @@ export interface PlayerMediaSourceDesc {
 export type PlayerMediaSource = string | PlayerMediaSourceDesc
 
 /**
+ * Debug output category selector
  * @beta
  */
 export type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none'
 
 /**
- * @remarks true is equivalent to 'all', false is equivalent to 'none'
+ * @remarks `true` is equivalent to `'all'`, `false` is equivalent to `'none'`
  * @beta
  */
 export type PlayerDebugSettings = PlayerDebugTag | boolean
@@ -44,11 +46,13 @@ export type PlayerDebugSettings = PlayerDebugTag | boolean
 export type PlaybackType = 'live' | 'vod'
 
 /**
+ * Media delivery protocol
  * @beta
  */
 export type MediaTransport = 'dash' | 'hls'
 
 /**
+ * Preferred media delivery protocol
  * @beta
  */
 export type TransportPreference = MediaTransport
@@ -167,6 +171,8 @@ export interface PlayerConfig extends Record<string, unknown> {
 }
 
 /**
+ * An ISO 639-1 language code.
+ * @example `pt`
  * @beta
  */
 export type LangTag = string
@@ -177,13 +183,19 @@ export type LangTag = string
 export type TranslationKey = string
 
 /**
+ * A plain JS object that must conform to the DASH.js settings schema.
  * @beta
  * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html | DASH.js settings}
  */
 export type DashSettings = Record<string, unknown>
 
 /**
- * [language][key] =\> string
+ * Localization strings for the player UI.
+ * @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
  * ```
  * {
@@ -205,11 +217,34 @@ export type TranslationSettings = Partial<
   Record<LangTag, Record<TranslationKey, string>>
 >
 
+/**
+ * Dimensions of the player container DOM element.
+ * @beta
+ */
+export type ContainerSize = {
+  width: number
+  height: number
+}
+
 /**
  * A top-level event on the player object
  * @beta
  */
 export enum PlayerEvent {
+  /**
+   * Playback has reached the end of the media.
+   */
+  Ended = 'ended',
+  /**
+   * An error occurred.
+   * Parameters: {@link PlaybackError}
+   */
+  Error = 'error',
+  /**
+   * The player has switched to or from the fullscreen mode.
+   * Parameters:`boolean` isFullscreen
+   */
+  Fullscreen = 'fullscreen',
   /**
    * The player is ready to use.
    */
@@ -222,12 +257,27 @@ export enum PlayerEvent {
    * Playback has been paused.
    */
   Pause = 'pause',
+  /**
+   * The player's container has been resized.
+   * Parameters: {@link ContainerSize}
+   */
+  Resize = 'resize',
+  /**
+   * The player is seeking to a new position.
+   */
+  Seek = 'seek',
   /**
    * Playback has been stopped.
    */
   Stop = 'stop',
   /**
-   * Playback has reached the end of the media.
+   * The current playback time has changed.
+   * Parameters: {@link TimePosition}
    */
-  Ended = 'ended',
+  TimeUpdate = 'timeupdate',
+  /**
+   * The volume has changed.
+   * Parameters: `number` volume in the range 0..1
+   */
+  VolumeUpdate = 'volumeupdate',
 }

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'
         },