@gcorevideo/player 2.19.14 → 2.20.1

package/src/plugins/picture-in-picture/PictureInPicture.ts

@@ -9,31 +9,56 @@ import '../../../assets/picture-in-picture/button.scss';
 
 const VERSION = '0.0.1';
 
-const T = `plugins.media_control_pip`;
-
+const T = `plugins.pip`;
+
+/**
+ * Enables picture in picture mode.
+ * @beta
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * It renders a button to toggle picture in picture mode in the media control UI.
+ */
 export class PictureInPicture extends UICorePlugin {
+  /**
+   * @internal
+   */
   get name() {
-    return 'media_control_pip';
+    return 'pip';
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION };
   }
 
+  /**
+   * @internal
+   */
   static get version() {
     return VERSION;
   }
 
+  /**
+   * @internal
+   */
   override get events() {
     return {
       'click button': 'togglePictureInPicture',
     };
   }
 
-  get videoElement() {
+  private get videoElement() {
     return this.core.activePlayback.el;
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
     this.listenTo(this.core.mediaControl, Events.MEDIACONTROL_RENDERED, this.render);
   }
@@ -47,6 +72,9 @@ export class PictureInPicture extends UICorePlugin {
     return document.pictureInPictureEnabled && !!HTMLVideoElement.prototype.requestPictureInPicture;
   }
 
+  /**
+   * @internal
+   */
   override render() {
     if (!this.isPiPSupported()) {
       return this;
@@ -64,7 +92,7 @@ export class PictureInPicture extends UICorePlugin {
     return this;
   }
 
-  togglePictureInPicture() {
+  private togglePictureInPicture() {
     trace(`${T} togglePictureInPicture`);
     if (this.videoElement !== document.pictureInPictureElement) {
       this.requestPictureInPicture();
@@ -73,14 +101,14 @@ export class PictureInPicture extends UICorePlugin {
     }
   }
 
-  requestPictureInPicture() {
+  private requestPictureInPicture() {
     trace(`${T} requestPictureInPicture`, {
       videoElement: !!this.videoElement,
     });
     this.videoElement.requestPictureInPicture();
   }
 
-  exitPictureInPicture() {
+  private exitPictureInPicture() {
     trace(`${T} exitPictureInPicture`);
     document.exitPictureInPicture();
   }

package/src/plugins/playback-rate/PlaybackRate.ts

@@ -31,6 +31,19 @@ const DEFAULT_PLAYBACK_RATE = '1.0';
 // TODO
 const MEDIACONTROL_PLAYBACKRATE = 'playbackRate';
 
+/**
+ * Allows changing the playback speed of the video.
+ * @beta
+ *
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl | media_control}
+ *
+ * - {@link BottomGear | bottom_gear}
+ *
+ * It renders a button in the gear menu, which opens a dropdown with the available playback rates.
+ */
 export class PlaybackRate extends UICorePlugin {
   private currentPlayback: Playback | null = null;
 
@@ -40,18 +53,29 @@ export class PlaybackRate extends UICorePlugin {
 
   private selectedRate: string = DEFAULT_PLAYBACK_RATE;
 
+  /**
+   * @internal
+   */
   get name() {
-    return 'media_control_playback_rate';
+    return 'playback_rate';
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION };
   }
 
-  get template() {
-    return template(pluginHtml);
-  }
+  private static readonly template = template(pluginHtml);
+
+  private static readonly buttonTemplate = template(buttonHtml);
+
+  private static readonly listTemplate = template(listHtml);
 
+  /**
+   * @internal
+   */
   override get attributes() {
     return {
       'class': this.name,
@@ -59,6 +83,9 @@ export class PlaybackRate extends UICorePlugin {
     };
   }
 
+  /**
+   * @internal
+   */
   override get events() {
     return {
       'click .gear-sub-menu_btn': 'onRateSelect',
@@ -67,8 +94,12 @@ export class PlaybackRate extends UICorePlugin {
     };
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
     this.listenTo(this.core, 'gear:rendered', this.render);
+    // TODO this.core.getPlugin('media_control'), bottom_gear
     this.listenTo(this.core.mediaControl, Events.MEDIACONTROL_CONTAINERCHANGED, this.reload);
     this.listenTo(this.core.mediaControl, MEDIACONTROL_PLAYBACKRATE, this.updatePlaybackRate);
 
@@ -87,7 +118,7 @@ export class PlaybackRate extends UICorePlugin {
     }
   }
 
-  unBindEvents() {
+  private unBindEvents() {
     this.stopListening(this.core, 'gear:rendered', this.render);
     this.stopListening(this.core.mediaControl, Events.MEDIACONTROL_CONTAINERCHANGED, this.reload);
     this.stopListening(this.core, 'core:advertisement:start', this.onStartAd);
@@ -121,7 +152,7 @@ export class PlaybackRate extends UICorePlugin {
     }
   }
 
-  reload() {
+  private reload() {
     this.unBindEvents();
     this.bindEvents();
   }
@@ -136,6 +167,9 @@ export class PlaybackRate extends UICorePlugin {
     return !(this.currentPlayback?.tagName !== 'video' && this.currentPlayback?.tagName !== 'audio');
   }
 
+  /**
+   * @internal
+   */
   override render() {
     const container = this.core.activeContainer;
 
@@ -153,9 +187,7 @@ export class PlaybackRate extends UICorePlugin {
     }
 
     if (this.shouldRender()) {
-      const t = template(buttonHtml);
-      // const html = t({ playbackRates: this.playbackRates, title: this.getTitle() });
-      const button = t({
+      const button = PlaybackRate.buttonTemplate({
         title: this.getTitle(),
         speedIcon,
         arrowRightIcon,
@@ -177,19 +209,19 @@ export class PlaybackRate extends UICorePlugin {
     return this;
   }
 
-  onStartAd() {
+  private onStartAd() {
     this.prevSelectedRate = this.selectedRate;
     this.setSelectedRate('1.0');
     this.listenToOnce(this.currentPlayback, Events.PLAYBACK_PLAY, this.onFinishAd);
   }
 
-  onFinishAd() {
+  private onFinishAd() {
     if (this.prevSelectedRate) {
       this.setSelectedRate(this.prevSelectedRate);
     }
   }
 
-  onPlay() {
+  private onPlay() {
     if (!this.core.mediaControl.$el.hasClass('dvr')) {
       if (this.core.getPlaybackType() === Playback.LIVE) {
         this.updatePlaybackRate(DEFAULT_PLAYBACK_RATE);
@@ -200,11 +232,10 @@ export class PlaybackRate extends UICorePlugin {
     }
   }
 
-  onStop() {
-
+  private onStop() {
   }
 
-  onRateSelect(event: MouseEvent) {
+  private onRateSelect(event: MouseEvent) {
     event.stopPropagation();
     const rate = (event.currentTarget as HTMLElement).dataset.rate;
     if (rate) {
@@ -215,10 +246,8 @@ export class PlaybackRate extends UICorePlugin {
     return false;
   }
 
-  onShowMenu() {
-    const t = template(listHtml);
-
-    this.$el.html(t({
+  private onShowMenu() {
+    this.$el.html(PlaybackRate.listTemplate({
       playbackRates: this.playbackRates,
       arrowLeftIcon,
       checkIcon,
@@ -228,15 +257,15 @@ export class PlaybackRate extends UICorePlugin {
     this.highlightCurrentRate();
   }
 
-  goBack() {
+  private goBack() {
     this.core.trigger('gear:refresh');
   }
 
-  updatePlaybackRate(rate: string) {
+  private updatePlaybackRate(rate: string) {
     this.setSelectedRate(rate);
   }
 
-  setSelectedRate(rate: string) {
+  private setSelectedRate(rate: string) {
     // Set <video playbackRate="..."
     this.core.$el.find('video,audio').get(0).playbackRate = rate;
     this.selectedRate = rate;
@@ -244,7 +273,7 @@ export class PlaybackRate extends UICorePlugin {
     // Player.player.trigger('playbackRateChanged', rate);
   }
 
-  getTitle() {
+  private getTitle() {
     let title = this.selectedRate;
 
     this.playbackRates.forEach((r) => {
@@ -256,7 +285,7 @@ export class PlaybackRate extends UICorePlugin {
     return title;
   }
 
-  highlightCurrentRate() {
+  private highlightCurrentRate() {
     this.allRateElements().removeClass('current');
     this.allRateElements().find('a').removeClass('gcore-skin-active');
 

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

@@ -11,6 +11,7 @@ import {
   type PlayerMediaSourceDesc,
 } from '../../types.js'
 import { trace } from '@gcorevideo/utils'
+import { SpinnerEvents } from '../spinner-three-bounce/SpinnerThreeBounce.js'
 
 import { CLAPPR_VERSION } from '../../build.js'
 
@@ -96,10 +97,16 @@ export class SourceController extends CorePlugin {
 
   private sync: SyncFn = noSync
 
+  /**
+   * @internal
+   */
   get name() {
     return 'source_controller'
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION }
   }
@@ -132,7 +139,7 @@ export class SourceController extends CorePlugin {
     const spinner = this.core.activeContainer?.getPlugin('spinner')
     if (spinner) {
       this.sync = (cb: () => void) => {
-        spinner.once('spinner:sync', cb)
+        spinner.once(SpinnerEvents.SYNC, cb)
       }
     } else {
       this.sync = noSync
@@ -228,6 +235,9 @@ export class SourceController extends CorePlugin {
     })
   }
 
+  /**
+   * @internal
+   */
   static get version() {
     return VERSION
   }

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

@@ -146,7 +146,7 @@ describe('SourceController', () => {
       it('should sync with the spinner before reloading the source', async () => {
         await clock.tickAsync(1000)
         expect(core.load).not.toHaveBeenCalled()
-        spinner.emit('spinner:sync')
+        spinner.emit('plugins:spinner:sync')
         expect(core.load).toHaveBeenCalled()
       })
     })

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

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-import { Container, Events, UIContainerPlugin, template } from '@clappr/core';
+import { Container, Events as ClapprEvents, UIContainerPlugin, template } from '@clappr/core';
 import { PlaybackError, PlaybackErrorCode } from '../../playback.types.js';
 import { trace } from '@gcorevideo/utils';
 
@@ -13,15 +13,41 @@ import { CLAPPR_VERSION } from '../../build.js';
 
 const T = 'plugins.spinner'
 
+/**
+ * Custom events emitted by the plugin
+ */
+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
+   */
+  SYNC = 'plugins:spinner:sync',
+}
+
+/**
+ * Shows a pending operation indicator when playback is buffering or in other appropriate cases
+ * @beta
+ * @remarks
+ * The plugin emits 
+ */
 export class SpinnerThreeBounce extends UIContainerPlugin {
+  /**
+   * @internal
+   */
   get name() {
     return 'spinner';
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION };
   }
 
+  /**
+   * @internal
+   */
   override get attributes() {
     return {
       'data-spinner':'',
@@ -39,13 +65,13 @@ export class SpinnerThreeBounce extends UIContainerPlugin {
 
   constructor(container: Container) {
     super(container);
-    this.listenTo(this.container, Events.CONTAINER_STATE_BUFFERING, this.onBuffering);
-    this.listenTo(this.container, Events.CONTAINER_STATE_BUFFERFULL, this.onBufferFull);
-    this.listenTo(this.container, Events.CONTAINER_PLAY, this.onPlay);
-    this.listenTo(this.container, Events.CONTAINER_STOP, this.onStop);
-    this.listenTo(this.container, Events.CONTAINER_ENDED, this.onStop);
-    this.listenTo(this.container, Events.CONTAINER_ERROR, this.onError);
-    this.listenTo(this.container, Events.CONTAINER_READY, this.render);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_STATE_BUFFERING, this.onBuffering);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_STATE_BUFFERFULL, this.onBufferFull);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_PLAY, this.onPlay);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_STOP, this.onStop);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_ENDED, this.onStop);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_ERROR, this.onError);
+    this.listenTo(this.container, ClapprEvents.CONTAINER_READY, this.render);
   }
 
   private onBuffering() {
@@ -90,21 +116,16 @@ export class SpinnerThreeBounce extends UIContainerPlugin {
     }
   }
 
-  show(immediate = false) {
-    trace(`${T} show`, {
-      immediate,
-    })
-    if (immediate) {
-      if (this.showTimeout !== null) {
-        clearTimeout(this.showTimeout);
-        this.showTimeout = null;
-      }
-      this.$el.show();
-    } else if (this.showTimeout === null) {
-      this.showTimeout = setTimeout(() => this.$el.show(), 300);
-    }
+  /**
+   * Shows the spinner
+   */
+  show() {
+    this.showTimeout = setTimeout(() => this.$el.show(), 300);
   }
 
+  /**
+   * Hides the spinner
+   */
   hide() {
     if (this.showTimeout !== null) {
       clearTimeout(this.showTimeout);
@@ -113,6 +134,9 @@ export class SpinnerThreeBounce extends UIContainerPlugin {
     this.$el.hide();
   }
 
+  /**
+   * @internal
+   */
   override render() {
     const showOnStart = this.options.spinner?.showOnStart;
     trace(`${T} render`, {
@@ -121,7 +145,7 @@ export class SpinnerThreeBounce extends UIContainerPlugin {
     })
     this.$el.html(this.template());
     this.el.firstElementChild?.addEventListener('animationiteration', () => {
-      this.trigger('spinner:sync')
+      this.trigger(SpinnerEvents.SYNC)
     })
     this.container.$el.append(this.$el[0]);
     if (showOnStart || this.container.buffering) {