@gcorevideo/player 2.22.1 → 2.22.3

package/lib/plugins/subtitles/ClosedCaptions.d.ts

@@ -1,21 +1,21 @@
 import { UICorePlugin } from '@clappr/core';
 import '../../../assets/subtitles/style.scss';
+/**
+ * Configuration options for the {@link ClosedCaptions} plugin.
+ * @beta
+ */
 export type ClosedCaptionsPluginSettings = {
     /**
-     * Initially selected subtitles language
+     * Initially selected subtitles language.
      */
     language?: string;
 };
-/**
- * @deprecated Use {@link ClosedCaptionsPluginSettings} instead.
- */
-export type SubtitlesPluginSettings = ClosedCaptionsPluginSettings;
 /**
  * `PLUGIN` that provides a UI to select the subtitles when available.
  * @beta
  *
  * @remarks
- * The plugin is activated when closed captions tracks are provided with the media source.
+ * The plugin is activated when closed captions tracks are detected in the media source.
  * It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
  *
  * Depends on:
@@ -32,7 +32,7 @@ export type SubtitlesPluginSettings = ClosedCaptionsPluginSettings;
  * new Player({
  *   ...
  *   cc: {
- *     language: 'en',
+ *     language: 'pt-BR',
  *   },
  * })
  * ```

package/lib/plugins/subtitles/ClosedCaptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClosedCaptions.d.ts","sourceRoot":"","sources":["../../../src/plugins/subtitles/ClosedCaptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,YAAY,EAAwB,MAAM,cAAc,CAAA;AAOzE,OAAO,sCAAsC,CAAA;AAe7C,MAAM,MAAM,4BAA4B,GAAG;IACzC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,4BAA4B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,oBAAoB,CAAQ;IAEpC,OAAO,CAAC,SAAS,CAAQ;IAEzB,OAAO,CAAC,KAAK,CAA6B;IAE1C,OAAO,CAAC,MAAM,CAAsB;IAEpC,OAAO,CAAC,KAAK,CAA2B;IAExC;;OAEG;IACH,IAAI,IAAI,WAEP;IAED;;OAEG;IACH,IAAI,gBAAgB;;MAEnB;IAED;;OAEG;IACH,MAAM,KAAK,OAAO,WAEjB;IAED,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAEzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAuB;IAE7D;;OAEG;IACH,IAAa,UAAU;;MAItB;IAED;;OAEG;IACH,IAAa,MAAM;;;MAKlB;IAED,OAAO,KAAK,mBAAmB,GAE9B;IAED;;OAEG;IACM,UAAU;IAUnB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,YAAY;IAqBpB;;OAEG;IACH,IAAI;IAWJ;;OAEG;IACH,IAAI;IAiBJ,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACM,MAAM;IA0Bf,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,yBAAyB;IAgBjC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,yBAAyB;IAgBjC,OAAO,CAAC,UAAU;CAKnB"}
+{"version":3,"file":"ClosedCaptions.d.ts","sourceRoot":"","sources":["../../../src/plugins/subtitles/ClosedCaptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,YAAY,EAAwB,MAAM,cAAc,CAAA;AAOzE,OAAO,sCAAsC,CAAA;AAe7C;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,oBAAoB,CAAQ;IAEpC,OAAO,CAAC,SAAS,CAAQ;IAEzB,OAAO,CAAC,KAAK,CAA6B;IAE1C,OAAO,CAAC,MAAM,CAAsB;IAEpC,OAAO,CAAC,KAAK,CAA2B;IAExC;;OAEG;IACH,IAAI,IAAI,WAEP;IAED;;OAEG;IACH,IAAI,gBAAgB;;MAEnB;IAED;;OAEG;IACH,MAAM,KAAK,OAAO,WAEjB;IAED,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAEzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAuB;IAE7D;;OAEG;IACH,IAAa,UAAU;;MAItB;IAED;;OAEG;IACH,IAAa,MAAM;;;MAKlB;IAED,OAAO,KAAK,mBAAmB,GAE9B;IAED;;OAEG;IACM,UAAU;IAUnB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,YAAY;IAqBpB;;OAEG;IACH,IAAI;IAWJ;;OAEG;IACH,IAAI;IAiBJ,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACM,MAAM;IA0Bf,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,yBAAyB;IAgBjC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,yBAAyB;IAgBjC,OAAO,CAAC,UAAU;CAKnB"}

package/lib/plugins/subtitles/ClosedCaptions.js

@@ -16,7 +16,7 @@ const T = 'plugins.cc';
  * @beta
  *
  * @remarks
- * The plugin is activated when closed captions tracks are provided with the media source.
+ * The plugin is activated when closed captions tracks are detected in the media source.
  * It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
  *
  * Depends on:
@@ -33,7 +33,7 @@ const T = 'plugins.cc';
  * new Player({
  *   ...
  *   cc: {
- *     language: 'en',
+ *     language: 'pt-BR',
  *   },
  * })
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcorevideo/player",
-  "version": "2.22.1",
+  "version": "2.22.3",
   "description": "Gcore JavaScript video player",
   "main": "dist/index.js",
   "type": "module",

package/src/index.plugins.ts

@@ -24,6 +24,7 @@ export * from "./plugins/seek-time/SeekTime.js";
 export * from "./plugins/share/Share.js";
 export * from "./plugins/skip-time/SkipTime.js";
 export * from "./plugins/spinner-three-bounce/SpinnerThreeBounce.js";
+export { SpinnerThreeBounce as Spinner } from "./plugins/spinner-three-bounce/SpinnerThreeBounce.js";
 export * from "./plugins/source-controller/SourceController.js";
 export * from "./plugins/subtitles/ClosedCaptions.js";
 export { ClosedCaptions as Subtitles } from "./plugins/subtitles/ClosedCaptions.js"; // TODO remove in future versions

package/src/internal.types.ts

@@ -143,3 +143,9 @@ export type CoreOptions = {
   watermarkLink?: string
   width?: number
 }
+
+export interface TextTrackItem {
+  id: number
+  name: string
+  track: TextTrack
+}

package/src/playback.types.ts

@@ -131,8 +131,3 @@ export interface PlaybackError {
   }
 }
 
-export interface TextTrackItem {
-  id: number
-  name: string
-  track: TextTrack
-}

package/src/plugins/bottom-gear/BottomGear.ts

@@ -10,35 +10,30 @@ import '../../../assets/bottom-gear/gear-sub-menu.scss'
 import gearIcon from '../../../assets/icons/new/gear.svg'
 import gearHdIcon from '../../../assets/icons/new/gear-hd.svg'
 import { ZeptoResult } from '../../types.js'
-import { MediaControlEvents } from '../media-control/MediaControl'
 
 const VERSION = '2.19.12'
 
 const T = 'plugins.bottom_gear'
 
-export enum GearEvents {
-  RENDERED = 'rendered',
-}
-
 /**
- * An element inside the gear menu
+ * Events triggered by the plugin
  * @beta
- * @deprecated
- */
-export type GearOptionsItem = 'quality' | 'rate' | 'nerd'
-
-/**
- * @deprecated Use {@link GearOptionsItem} instead
  */
-export type GearItemElement = GearOptionsItem
+export enum GearEvents {
+  /**
+   * Use this event to accurately attach an item to the gear menu
+   */
+  RENDERED = 'rendered',
+}
 
 // TODO disabled if no items added
 
 /**
- * `PLUGIN` that adds the gear button with an extra options menu on the right side of the {@link MediaControl | media control} UI
+ * `PLUGIN` that adds a button to extend the media controls UI with extra options.
  * @beta
  * @remarks
- * The plugins provides a base for attaching custom settings UI in the gear menu
+ * The plugin renders small gear icon to the right of the media controls.
+ * It provides a base for attaching custom settings UI in the gear menu
  *
  * Depends on:
  *
@@ -157,6 +152,28 @@ export class BottomGear extends UICorePlugin {
     )
   }
 
+  /**
+   * Adds a custom option to the gear menu
+   * @param name - A unique name of the option
+   * @param $subMenu - The submenu to attach to the option
+   * @returns The added item placeholder to attach custom markup
+   * @remarks
+   * When called with $submenu param, a click on the added item will toggle the submenu visibility.
+   *
+   * When added without submenu, it's responsibility of the caller to handle the click event however needed.
+   * @example
+   * ```ts
+   * class MyPlugin extends UICorePlugin {
+   *   override render() {
+   *     this.$el.html('<div class="my-awesome-settings">...</div>')
+   *     this.core.getPlugin('bottom_gear')
+   *       ?.addItem('custom', this.$el)
+   *       .html($('<button>Custom settings</button>'))
+   *     return this
+   *   }
+   * }
+   * ```
+   */
   addItem(name: string, $subMenu?: ZeptoResult): ZeptoResult {
     const $existingItem = this.$el.find(`#gear-options li[data-${name}`)
     if ($existingItem.length) {
@@ -228,7 +245,9 @@ export class BottomGear extends UICorePlugin {
   }
 
   /**
-   * Collapses any submenu open back to the gear menu
+   * Collapses any submenu open back to the gear menu.
+   * @remarks
+   * Should be called by the UI plugin that added a gear item with a submenu when the latter is closed (e.g., when a "back" button is clicked).
    */
   refresh() {
     this.$el.find('.gear-sub-menu-wrapper').hide()

package/src/plugins/click-to-pause/ClickToPause.ts

@@ -1,4 +1,5 @@
-//Copyright 2014 Globo.com Player authors. All rights reserved.
+// This work is based on the original work of the following authors:
+// Copyright 2014 Globo.com Player authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found at https://github.com/clappr/clappr-plugins/blob/master/LICENSE.
 
@@ -12,7 +13,7 @@ type Timer = ReturnType<typeof setTimeout>
 const T = 'plugins.click_to_pause_custom'
 
 /**
- * `PLUGIN` that adds a behavior of toggling the playback state on click over the container
+ * A small `PLUGIN` that toggles the playback state on click over the video container
  * @beta
  */
 export class ClickToPause extends ContainerPlugin {

package/src/plugins/error-screen/ErrorScreen.ts

@@ -16,8 +16,19 @@ type ErrorScreenDesc = {
 }
 
 /**
- * Configuration options for the {@link ErrorScreen | error screen} plugin.
- * @beta
+ * Settings for the {@link ErrorScreen} plugin.
+ * @public
+ */
+export type ErrorScreenSettings = {
+  /**
+   * Whether to hide the reload button. The reload button triggers reload of the current source.
+   */
+  noReload?: boolean
+}
+
+/**
+ * Configuration options for the {@link ErrorScreen} plugin.
+ * @public
  */
 export type ErrorScreenPluginSettings = {
   /**
@@ -29,8 +40,23 @@ export type ErrorScreenPluginSettings = {
 const T = 'plugins.error_screen'
 
 /**
- * `PLUGIN` that displays errors nicely in the overlay on top of the player.
- * @beta
+ * `PLUGIN` that displays fatal errors nicely in the overlay on top of the player.
+ * @public
+ * @remarks
+ * A fatal error is an error that prevents the player from playing the content.
+ * It's usually a network error that persists after multiple retries.
+ *
+ * The error screen should not be confused with the content stub that is shown when no media sources are available.
+ * This can happen due to the lack of the support of the given sources type or because the sources are misconfigured (e.g., omitted).
+ *
+ * Configuration options - {@link ErrorScreenPluginSettings}
+ *
+ * @example
+ * ```ts
+ * import { ErrorScreen, Player } from '@gcorevideo/player'
+ *
+ * Player.registerPlugin(ErrorScreen)
+ * ```
  */
 export class ErrorScreen extends UICorePlugin {
   private err: ErrorScreenDesc | null = null

package/src/plugins/media-control/MediaControl.ts

@@ -80,18 +80,6 @@ const DEFAULT_SETTINGS: MediaControlSettings = {
   seekEnabled: true,
 }
 
-/**
- * Custom events emitted by the plugins to communicate with one another
- * @beta
- * @deprecated
- */
-export enum MediaControlEvents {
-  /**
-   * Emitted when the gear menu is rendered
-   */
-  MEDIACONTROL_GEAR_RENDERED = 'mediacontrol:gear:rendered',
-}
-
 const T = 'plugins.media_control'
 
 const LEFT_ORDER = [

package/src/plugins/source-controller/SourceController.ts

@@ -27,11 +27,47 @@ function noSync(cb: () => void) {
 }
 
 /**
- * `PLUGIN` that is responsible for managing the automatic failover between sources.
- * @beta
+ * `PLUGIN` that is managing the automatic failover between media sources.
+ * @public
  * @remarks
  * Have a look at the {@link https://miro.com/app/board/uXjVLiN15tY=/?share_link_id=390327585787 | source failover diagram} for the details
- * on how sources ordering and selection works.
+ * on how sources ordering and selection works. Below is a simplified diagram:
+ *
+ * ```markdown
+ * sources_list:
+ *       - a.mpd  |    +--------------------+
+ *       - b.m3u8 |--->|         init       |
+ *       - ...    |    |--------------------|
+ *                     | current_source = 0 |
+ *                     +--------------------+
+ *                            |
+ *                            |  source = a.mpd
+ *                            |  playback = dash.js
+ *                            v
+ *                      +------------------+
+ *                  +-->|   load source    |
+ *                  |   +---------|--------+
+ *                  |             v
+ *                  |   +------------------+
+ *                  |   |       play       |
+ *                  |   +---------|--------+
+ *                  |             |
+ *                  |             v
+ *                  |   +-----------------------+
+ *                  |   |  on playback_error    |
+ *                  |   |-----------------------|
+ *                  |   | current_source =      |
+ *                  |   |  (current_source + 1) |
+ *                  |   |  % len sources_list   |
+ *                  |   |                       |
+ *                  |   | delay 1..3s           |
+ *                  |   +---------------|-------+
+ *                  |                   |
+ *                  |   source=b.m3u8   |
+ *                  |   playback=hls.js |
+ *                  +-------------------+
+ *
+ * ```
  *
  * This plugin does not expose any public methods apart from required by the Clappr plugin interface.
  * It is supposed to work autonomously.
@@ -81,6 +117,7 @@ export class SourceController extends CorePlugin {
    *                  |   playback=hls.js |
    *                  +-------------------+
    *
+   * As can be seen from the diagram, the plugin will endless try to load the next sources rotating between them in round-robin manner.
    */
   private sourcesList: PlayerMediaSourceDesc[] = []
 
@@ -109,7 +146,7 @@ export class SourceController extends CorePlugin {
   }
 
   /**
-   * @internal
+   * @param core - The Clappr core instance.
    */
   constructor(core: ClapprCore) {
     super(core)

package/src/plugins/spinner-three-bounce/SpinnerThreeBounce.ts

@@ -1,6 +1,8 @@
+// This work is based on the original work of Globo.com
 // Copyright 2014 Globo.com Player authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
+// https://github.com/clappr/clappr-plugins/blob/ffaa9d27005fa5a8a7c243ffc47eb5655b84b371/LICENSE
 
 import {
   Container,
@@ -20,21 +22,22 @@ const T = 'plugins.spinner'
 
 /**
  * Custom events emitted by the plugin
- * @beta
+ * @public
  */
 export enum SpinnerEvents {
   /**
    * Emitted at the end of the spinner animation cycle to facilitate smooth UI updates,
-   * e.g. {@link SourceController} listens to this event to reload the source when the spinner is hidden
+   * for instance, {@link SourceController} listens to this event to reload the source when the spinner is hidden
    */
   SYNC = 'plugins:spinner:sync',
 }
 
 /**
- * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state
- * @beta
+ * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state.
+ * @public
  * @remarks
- * Events emitted- {@link SpinnerEvents}
+ * It is aliased as `Spinner` for convenience.
+ * Events emitted - {@link SpinnerEvents}
  * Other plugins can use {@link SpinnerThreeBounce.show | show} and {@link SpinnerThreeBounce.hide | hide} methods to
  * implement custom pending/progress indication scenarios.
  */
@@ -129,7 +132,9 @@ export class SpinnerThreeBounce extends UIContainerPlugin {
   /**
    * Shows the spinner.
    *
-   * When called, the spinner will not hide (due to its built-in logic) until {@link SpinnerThreeBounce.hide} is called
+   * The method call prevents spinner's built-in logic from automatically hiding it until {@link SpinnerThreeBounce.hide} is called
+   *
+   * @param delay - The delay in milliseconds before the spinner is shown.
    */
   show(delay = 300) {
     trace(`${T} show`)

package/src/plugins/subtitles/ClosedCaptions.ts

@@ -3,7 +3,7 @@ import { reportError, trace } from '@gcorevideo/utils'
 import assert from 'assert'
 
 import { CLAPPR_VERSION } from '../../build.js'
-import type { TextTrackItem } from '../../playback.types.js'
+import type { TextTrackItem } from '../../internal.types.js'
 
 import '../../../assets/subtitles/style.scss'
 import subtitlesOffIcon from '../../../assets/icons/new/subtitles-off.svg'
@@ -20,24 +20,23 @@ const LOCAL_STORAGE_CC_ID = 'gplayer.plugins.cc.selected'
 
 const T = 'plugins.cc'
 
+/**
+ * Configuration options for the {@link ClosedCaptions} plugin.
+ * @beta
+ */
 export type ClosedCaptionsPluginSettings = {
   /**
-   * Initially selected subtitles language
+   * Initially selected subtitles language.
    */
   language?: string
 }
 
-/**
- * @deprecated Use {@link ClosedCaptionsPluginSettings} instead.
- */
-export type SubtitlesPluginSettings = ClosedCaptionsPluginSettings;
-
 /**
  * `PLUGIN` that provides a UI to select the subtitles when available.
  * @beta
  *
  * @remarks
- * The plugin is activated when closed captions tracks are provided with the media source.
+ * The plugin is activated when closed captions tracks are detected in the media source.
  * It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
  *
  * Depends on:
@@ -54,7 +53,7 @@ export type SubtitlesPluginSettings = ClosedCaptionsPluginSettings;
  * new Player({
  *   ...
  *   cc: {
- *     language: 'en',
+ *     language: 'pt-BR',
  *   },
  * })
  * ```