@gcorevideo/player 2.8.2 → 2.10.0

package/lib/utils/mediaSources.js

@@ -71,12 +71,3 @@ export function buildSourcesPriorityList(sources, priorityTransport = 'auto') {
 export function unwrapSource(s) {
     return typeof s === 'string' ? s : s.source;
 }
-export function buildGcoreStreamSourcesList(ms, priorityTransport) {
-    const sources = {
-        dash: ms.sourceDash,
-        master: ms.source,
-        hls: ms.hlsCmafUrl,
-        mpegts: ms.hlsMpegtsUrl,
-    };
-    return buildSourcesPriorityList(sources, priorityTransport);
-}

package/lib/version.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Version information about the gplayer and its main dependencies
+ * @returns Version information about the gplayer and its main dependencies
+ * @beta
+ */
 export declare function version(): {
     gplayer: string;
     clappr: string;

package/lib/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA,wBAAgB,OAAO;;;;;EAOtB"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,OAAO;;;;;EAOtB"}

package/lib/version.js

@@ -1,5 +1,10 @@
 import * as pkg from '../package.json' with { "type": "json" };
 import * as lock from '../package-lock.json' with { "type": "json" };
+/**
+ * Version information about the gplayer and its main dependencies
+ * @returns Version information about the gplayer and its main dependencies
+ * @beta
+ */
 export function version() {
     return {
         gplayer: pkg.version,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcorevideo/player",
-  "version": "2.8.2",
+  "version": "2.10.0",
   "description": "Gcore JavaScript video player",
   "main": "dist/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
     "build:1": "npm run build:ts && npm run build:bundle && date",
     "build:ts": "tsc",
     "build:bundle": "rollup -c",
+    "dev": "nodemon --watch src -e ts --exec \"npm run build:ts && npm run docs\"",
     "docs": "npm run docs:extract && npm run docs:build",
     "docs:extract": "api-extractor run --local --verbose",
     "docs:build": "api-documenter markdown --input-folder=temp --output-folder=docs/api",
@@ -30,17 +31,21 @@
   },
   "homepage": "https://github.com/G-Core/gcore-videoplayer-js#readme",
   "devDependencies": {
+    "@microsoft/api-documenter": "^7.26.5",
+    "@microsoft/api-extractor": "^7.49.1",
     "@rollup/plugin-commonjs": "^28.0.1",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@types/node": "^22.10.1",
     "assert": "^2.1.0",
+    "nodemon": "^3.1.9",
     "rollup": "^4.27.4",
     "rollup-plugin-polyfill-node": "^0.13.0",
     "typescript": "^5.7.2"
   },
   "dependencies": {
     "@clappr/core": "^0.11.3",
+    "@gcorevideo/utils": "^0.0.1",
     "@sentry/types": "^8.47.0",
     "dashjs": "^4.7.4",
     "event-lite": "^1.0.0",

package/src/Player.ts

@@ -6,6 +6,7 @@ import {
   $,
   Loader,
 } from '@clappr/core'
+import { reportError, trace } from '@gcorevideo/utils'
 import assert from 'assert'
 import EventLite from 'event-lite'
 
@@ -13,12 +14,8 @@ import type {
   CorePlayerEvents,
   CoreOptions,
   CorePluginOptions,
-  PlayerMediaSource,
 } from './internal.types.js'
-import type {
-  PlayerPlugin,
-} from './types.js'
-import { reportError, trace } from './trace/index.js'
+import type { PlayerMediaSource, PlayerPlugin } from './types.js'
 import { PlayerConfig, PlayerEvent } from './types.js'
 import DashPlayback from './plugins/dash-playback/DashPlayback.js'
 import HlsPlayback from './plugins/hls-playback/HlsPlayback.js'
@@ -30,7 +27,10 @@ import {
 
 // TODO implement transport retry/failover and fallback logic
 
-type PlayerEventHandler<T extends PlayerEvent> = () => void
+/**
+ * @beta
+ */
+export type PlayerEventHandler<T extends PlayerEvent> = () => void
 
 const T = 'GPlayer'
 
@@ -40,18 +40,24 @@ const DEFAULT_OPTIONS: PlayerConfig = {
   loop: false,
   mute: false,
   playbackType: 'vod',
-  pluginSettings: {},
-  poster: '',
   priorityTransport: 'dash',
   sources: [],
   strings: {},
 }
 
+/**
+ * @beta
+ */
 export type PlaybackModule = 'dash' | 'hls' | 'native'
 
 type PluginOptions = Record<string, unknown>
 
 /**
+ * The main component to use in the application code.
+ * @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 {
@@ -73,23 +79,41 @@ export class Player {
     this.setConfig(config)
   }
 
+  /**
+   * Adds a listener to a player event
+   * @param event - See {@link PlayerEvent}
+   * @param handler - See {@link PlayerEventHandler}
+   */
   on<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>) {
     this.emitter.on(event, handler)
   }
 
+  /**
+   * Removes a listener from a player event
+   * @param event - See {@link PlayerEvent}
+   * @param handler - See {@link PlayerEventHandler}
+   */
   off<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>) {
     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
+   */
   configure(config: Partial<PlayerConfig>) {
     this.setConfig(config)
   }
 
-  private setConfig(config: Partial<PlayerConfig>) {
-    this.config = $.extend(true, this.config, config)
-  }
-
-  async init(playerElement: HTMLElement) {
+  /**
+   * Initializes the player at the given container element.
+   * @param playerElement - DOM element to host the player
+   */
+  attachTo(playerElement: HTMLElement): void {
     assert.ok(!this.player, 'Player already initialized')
     assert.ok(playerElement, 'Player container element is required')
     if (this.config.debug === 'all' || this.config.debug === 'clappr') {
@@ -114,6 +138,9 @@ export class Player {
     return this.initPlayer(coreOpts)
   }
 
+  /**
+   * Destroys the player, releasing all resources and removing any DOM elements added.
+   */
   destroy() {
     trace(`${T} destroy`, {
       player: !!this.player,
@@ -130,46 +157,100 @@ export class Player {
     }
   }
 
+  /**
+   * Current playback time in seconds, if appropriate.
+   * @returns For live streams, it returns the current time of the current segment.
+   */
+  getCurrentTime(): number {
+    if (!this.player) {
+      return 0
+    }
+    return this.player.getCurrentTime()
+  }
+
+  /**
+   * Duration of the current media in seconds, if appropriate.
+   * @returns For live streams, it returns the duration of the current segment.
+   */
+  getDuration(): number {
+    if (!this.player) {
+      return 0
+    }
+    return this.player.getDuration()
+  }
+
+  /**
+   * Mutes the player.
+   */
+  mute() {
+    this.player?.mute()
+  }
+
+  /**
+   * Unmutes the player.
+   */
+  unmute() {
+    this.player?.unmute()
+  }
+
+  /**
+   * Pauses playback.
+   */
   pause() {
-    assert.ok(this.player, 'Player not initialized')
-    this.player.pause()
+    this.player?.pause()
   }
 
+  /**
+   * Starts playback.
+   */
   play() {
-    assert.ok(this.player, 'Player not initialized')
-    this.player.play()
+    this.player?.play()
   }
 
+  /**
+   * Resizes the player container element and everything within it.
+   * @param newSize - new size of the player
+   */
   resize(newSize: { width: number; height: number }) {
-    if (!this.player) {
-      trace(`${T} resize not initialized`, { newSize })
-      return
-    }
-    trace(`${T} resize`, {
-      newSize,
-    })
-    this.player.resize(newSize)
+    this.player?.resize(newSize)
   }
 
-  seekTo(time: number) {
-    assert.ok(this.player, 'Player not initialized')
-    this.player.seek(time)
+  /**
+   * Seeks to the given time.
+   * @param time - time to seek to in seconds
+   */
+  seek(time: number) {
+    this.player?.seek(time)
   }
 
+  /**
+   * Stops playback.
+   */
   stop() {
-    assert.ok(this.player, 'Player not initialized')
-    this.player.stop()
+    this.player?.stop()
   }
 
+  /**
+   * Registers a plugin.
+   * @param plugin - plugin to register
+   */
   static registerPlugin(plugin: PlayerPlugin) {
     Loader.registerPlugin(plugin)
   }
 
+  /**
+   * Unregisters a plugin.
+   * @param plugin - plugin to unregister
+   */
   static unregisterPlugin(plugin: PlayerPlugin) {
     Loader.unregisterPlugin(plugin)
   }
 
-  private initPlayer(coreOptions: CoreOptions) {
+  private setConfig(config: Partial<PlayerConfig>) {
+    this.config = $.extend(true, this.config, config)
+  }
+
+  private initPlayer(coreOptions: CoreOptions): void {
     trace(`${T} initPlayer`, {
       // TODO selected options
     })
@@ -321,7 +402,7 @@ export class Player {
     this.rootNode = rootNode
 
     const coreOptions: CoreOptions & PluginOptions = {
-      ...this.config.pluginSettings,
+      ...this.config, // plugin settings
       allowUserInteraction: true,
       autoPlay: false,
       dash: this.config.dash,

package/src/index.ts

@@ -1,9 +1,15 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ */
+
+export { setTracer } from "@gcorevideo/utils";
 export * from "./Player.js"
 export * from "./playback.types.js";
-export * from "./trace/LogTracer.js";
-export * from "./trace/SentryTracer.js";
-export * from "./trace/index.js";
-export * from "./trace/types.js";
 export * from "./types.js";
-export * from "./utils/Logger.js";
 export * from "./version.js";

package/src/internal.types.ts

@@ -3,7 +3,8 @@ import type {
   ContainerPlugin,
   Playback as ClapprPlayback,
 } from "@clappr/core";
-import { PlaybackType, PlayerDebugTag, StreamMediaSource } from "./types";
+
+import { PlaybackType, PlayerDebugTag, PlayerMediaSource } from "./types";
 
 type ExternalTrack = {
   kind?: "subtitles" | "captions";
@@ -18,13 +19,10 @@ type MediacontrolStyles = {
   buttons?: string;
 }
 
-export type PlayerMediaSourceDesc = {
-  mimeType?: string;
-  source: string;
-}
-
-export type PlayerMediaSource = string | PlayerMediaSourceDesc;
-
+/**
+ * HLS.js configuration options to use with the HlsPlayback plugin.
+ * @beta
+ */
 type HlsjsConfig = {
   debug?: boolean;
   startLevel?: number;
@@ -32,7 +30,11 @@ type HlsjsConfig = {
 
 type ShakaConfig = Record<string, unknown>;
 
-type CorePlaybackConfig = {
+/**
+ * @see {@link https://github.com/clappr/clappr-core?tab=readme-ov-file#playback-configuration | the Clappr playback settings}
+ * @beta
+ */
+export interface CorePlaybackConfig {
   // audioOnly: boolean;
   disableContextMenu?: boolean;
   controls?: boolean;
@@ -56,6 +58,9 @@ type CorePlaybackConfig = {
 
 type ErrorLevel = "FATAL" | "WARN" | "INFO";
 
+/**
+ * @internal
+ */
 export type PlaybackError = {
   code?: number | string;
   description: string;
@@ -63,6 +68,9 @@ export type PlaybackError = {
   level?: ErrorLevel;
 }
 
+/**
+ * @internal
+ */
 export type CorePlayerEvents = {
   // TODO event arguments types
   onReady?: () => void;
@@ -78,13 +86,15 @@ export type CorePlayerEvents = {
   onSubtitleAvailable?: () => void;
 }
 
-export type ClapprVersionSpec = {
-  min: string;
-  // TODO
-}
-
+/**
+ * @internal
+ */
 export type PlaybackPluginFactory = typeof ClapprPlayback;
 
+/**
+ * For the plugin development
+ * @internal
+ */
 export type CorePluginOptions = {
   core?: CorePlugin[];
   container?: ContainerPlugin[];
@@ -93,6 +103,10 @@ export type CorePluginOptions = {
   loadExternalPlaybacksFirst?: boolean;
 }
 
+/**
+ * For the plugin development
+ * @internal
+ */
 export type CoreOptions = {
   actualLiveTime?: boolean;
   actualLiveServerTime?: string;
@@ -116,7 +130,6 @@ export type CoreOptions = {
   maxBufferLength?: number;
   mediacontrol?: MediacontrolStyles;
   mimeType?: string;
-  // multisources: StreamMediaSource[];
   mute?: boolean;
   persistConfig?: boolean;
   preload?: "auto" | "metadata" | "none";

package/src/playback.types.ts

@@ -1,22 +1,36 @@
+
+/**
+ * For the plugin development
+ * @internal
+ */
 export type TimeValue = number;
 
+/**
+ * For the plugin development
+ * @internal
+ */
 export type TimePosition = {
   current: TimeValue;
   total: TimeValue;
 }
 
+/**
+ * For the plugin development
+ * @internal
+ */
 export type TimeProgress = TimePosition & { start: number; };
 
+/**
+ * For the plugin development
+ * @internal
+ */
 export type TimeUpdate = TimePosition & {
   firstFragDateTime: number;
 };
 
-export type BitrateInfo = {
-  bitrate: number;
-  width: number;
-  height: number;
-}
-
+/**
+ * @beta
+ */
 export type QualityLevel = {
   level: number // index
   width: number

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

@@ -11,7 +11,7 @@ import DASHJS, {
   MetricEvent as DashMetricEvent,
   IManifestInfo,
 } from 'dashjs'
-import { trace } from '../../trace/index.js'
+import { trace } from '@gcorevideo/utils'
 
 import { QualityLevel, TimePosition, TimeValue } from '../../playback.types.js'
 

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

@@ -18,7 +18,7 @@ import HLSJS, {
 } from 'hls.js';
 
 import { QualityLevel, TimePosition } from '../../playback.types.js';
-import { trace } from '../../trace/index.js';
+import { trace } from '@gcorevideo/utils';
 import { PlaybackType } from '../../types';
 import { TimerId } from '../../utils/types';