@gcorevideo/player 2.22.1 → 2.22.2

package/dist/index.js

@@ -43299,7 +43299,7 @@ class Player {
     }
 }
 
-var version$1 = "2.22.1";
+var version$1 = "2.22.2";
 
 var packages = {
 	"node_modules/@clappr/core": {
@@ -43665,16 +43665,24 @@ const gearHdIcon = "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\
 
 const VERSION$5 = '2.19.12';
 const T$f = 'plugins.bottom_gear';
+/**
+ * Events triggered by the plugin
+ * @beta
+ */
 var GearEvents;
 (function (GearEvents) {
+    /**
+     * Use this event to accurately attach an item to the gear menu
+     */
     GearEvents["RENDERED"] = "rendered";
 })(GearEvents || (GearEvents = {}));
 // 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:
  *
@@ -43781,6 +43789,28 @@ class BottomGear extends UICorePlugin {
         this.listenToOnce(this.core, Events$1.CORE_READY, this.onCoreReady);
         this.listenTo(this.core, Events$1.CORE_ACTIVE_CONTAINER_CHANGED, this.onActiveContainerChanged);
     }
+    /**
+     * 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, $subMenu) {
         const $existingItem = this.$el.find(`#gear-options li[data-${name}`);
         if ($existingItem.length) {
@@ -43840,7 +43870,9 @@ class BottomGear extends UICorePlugin {
         return this;
     }
     /**
-     * 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();
@@ -46624,12 +46656,13 @@ class ClapprStats extends ContainerPlugin {
 // ClapprStats.REPORT_EVENT = 'clappr:stats:report';
 // ClapprStats.PERCENTAGE_EVENT = 'clappr:stats:percentage';
 
-//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.
 const T$d = '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
  */
 class ClickToPause extends ContainerPlugin {
@@ -47133,8 +47166,23 @@ const templateHtml = "<div class=\"player-error-screen__content\" data-error-scr
 
 const T$b = '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)
+ * ```
  */
 class ErrorScreen extends UICorePlugin {
     err = null;
@@ -48178,18 +48226,6 @@ const DEFAULT_SETTINGS = {
     default: [],
     seekEnabled: true,
 };
-/**
- * Custom events emitted by the plugins to communicate with one another
- * @beta
- * @deprecated
- */
-var MediaControlEvents;
-(function (MediaControlEvents) {
-    /**
-     * Emitted when the gear menu is rendered
-     */
-    MediaControlEvents["MEDIACONTROL_GEAR_RENDERED"] = "mediacontrol:gear:rendered";
-})(MediaControlEvents || (MediaControlEvents = {}));
 const T$9 = 'plugins.media_control';
 const LEFT_ORDER = [
     'playpause',
@@ -50686,27 +50722,29 @@ class SkipTime extends UICorePlugin {
 
 const spinnerHTML = "<div data-bounce1></div>\n<div data-bounce2></div>\n<div data-bounce3></div>\n";
 
+// 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
 const T$4 = 'plugins.spinner';
 /**
  * Custom events emitted by the plugin
- * @beta
+ * @public
  */
 var SpinnerEvents;
 (function (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
      */
     SpinnerEvents["SYNC"] = "plugins:spinner:sync";
 })(SpinnerEvents || (SpinnerEvents = {}));
 /**
- * `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}
+ * 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.
  */
@@ -50779,7 +50817,9 @@ 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$4} show`);
@@ -50846,11 +50886,47 @@ function noSync(cb) {
     queueMicrotask(cb);
 }
 /**
- * `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.
@@ -50900,6 +50976,7 @@ 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.
      */
     sourcesList = [];
     currentSourceIndex = 0;
@@ -50920,7 +50997,7 @@ class SourceController extends CorePlugin {
         return { min: CLAPPR_VERSION };
     }
     /**
-     * @internal
+     * @param core - The Clappr core instance.
      */
     constructor(core) {
         super(core);
@@ -51064,7 +51141,7 @@ const T$2 = '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:
@@ -51081,7 +51158,7 @@ const T$2 = 'plugins.cc';
  * new Player({
  *   ...
  *   cc: {
- *     language: 'en',
+ *     language: 'pt-BR',
  *   },
  * })
  * ```
@@ -52234,4 +52311,4 @@ class VolumeFade extends UICorePlugin {
     }
 }
 
-export { AudioSelector, BigMuteButton, BottomGear, ClapprNerdStats, ClapprStats, ClickToPause, ClipsPlugin, ClosedCaptions, ContextMenu, DvrControls, ErrorScreen, Favicon, GearEvents, GoogleAnalytics, LevelSelector, LogTracer, Logger, Logo, MediaControl, MediaControlEvents, MultiCamera, PictureInPicture, PlaybackErrorCode, PlaybackRate, Player, PlayerEvent, Poster, SeekTime, SentryTracer, Share, SkipTime, SourceController, SpinnerEvents, SpinnerThreeBounce, ClosedCaptions as Subtitles, Telemetry, TelemetryEvent, Thumbnails, VolumeFade, VolumeFadeEvents, reportError, setTracer, trace, version };
+export { AudioSelector, BigMuteButton, BottomGear, ClapprNerdStats, ClapprStats, ClickToPause, ClipsPlugin, ClosedCaptions, ContextMenu, DvrControls, ErrorScreen, Favicon, GearEvents, GoogleAnalytics, LevelSelector, LogTracer, Logger, Logo, MediaControl, MultiCamera, PictureInPicture, PlaybackErrorCode, PlaybackRate, Player, PlayerEvent, Poster, SeekTime, SentryTracer, Share, SkipTime, SourceController, SpinnerEvents, SpinnerThreeBounce, ClosedCaptions as Subtitles, Telemetry, TelemetryEvent, Thumbnails, VolumeFade, VolumeFadeEvents, reportError, setTracer, trace, version };