@gcorevideo/player 2.17.0 → 2.18.0

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