@gcorevideo/player 2.22.0 → 2.22.2

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,21 @@ 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}
+ * 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 +131,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',
  *   },
  * })
  * ```
@@ -338,7 +337,7 @@ export class ClosedCaptions extends UICorePlugin {
     this.resizeFont()
 
     this.core.activeContainer.$el.append(this.$line)
-    mediaControl.putElement('cc', this.el)
+    mediaControl.putElement('cc', this.$el)
 
     this.updateSelection()
 

package/src/plugins/subtitles/__tests__/ClosedCaptions.test.ts

@@ -52,7 +52,7 @@ describe('ClosedCaptions', () => {
     it('should render', () => {
       expect(cc.el.innerHTML).toMatchSnapshot()
       expect(cc.$el.find('[data-cc-button]').length).toEqual(1)
-      expect(mediaControl.putElement).toHaveBeenCalledWith('cc', cc.el)
+      expect(mediaControl.putElement).toHaveBeenCalledWith('cc', cc.$el)
     })
   })
 })

package/src/testUtils.ts

@@ -193,3 +193,17 @@ export function createMockMediaControl(core: any) {
   mediaControl.toggleElement = vi.fn()
   return mediaControl
 }
+
+export function createMockBottomGear(core: any) {
+  const plugin: any = new UICorePlugin(core)
+  plugin.getItem = vi.fn()
+  plugin.addItem = vi.fn().mockImplementation((name: string, $el: any) => {
+    const existing = plugin.$el.find(`[data-${name}]`)
+    if (existing.length) {
+      return existing
+    }
+    return $('<li></li>').attr(`data-${name}`, '').append($el).appendTo(plugin.$el)
+  })
+  plugin.refresh = vi.fn()
+  return plugin
+}

package/src/typings/vitest.d.ts

@@ -1,6 +1,7 @@
 import 'vitest'
 
 interface CustomMatchers<R = unknown> {
+  toMatchPlaybackRateOption: (expected: string) => R
   toMatchQualityLevelLabel: (expected: string) => R
   toMatchQualityLevelOption: (expected: string) => R
 }