@gcorevideo/player 2.19.15 → 2.20.3

package/src/plugins/clappr-stats/ClapprStats.ts

@@ -23,7 +23,10 @@ type UriToMeasureBandwidth = {
 const updateMetrics = () => {};
 
 /**
+ * Collects useful statistics about playback performance.
  * @beta
+ * @remarks
+ * This plugin does not render anything and is supposed to be extended or used together with other plugins that actually render something.
  */
 export class ClapprStats extends ContainerPlugin {
   private bwMeasureCount = 0;
@@ -60,19 +63,25 @@ export class ClapprStats extends ContainerPlugin {
 
   private uriToMeasureLatency: string | undefined;
 
+  /**
+   * @internal
+   */
   get name() {
     return 'clappr_stats';
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION };
   }
 
-  get _playbackName() {
+  private get _playbackName() {
     return String(this.container.playback.name || '');
   }
 
-  get _playbackType() {
+  private get _playbackType() {
     return this.container.getPlaybackType();
   }
 
@@ -100,11 +109,15 @@ export class ClapprStats extends ContainerPlugin {
     this.metrics.timers[timer] += this._now() - this.timers[timer];
   }
 
+  /**
+   * Registers a callback to receive the metrics.
+   * @param updateMetricsFn
+   */
   setUpdateMetrics(updateMetricsFn: MetricsUpdateFn) {
     this.updateFn = updateMetricsFn;
   }
 
-  _defaultReport(metrics: Metrics) {
+  private _defaultReport(metrics: Metrics) {
     this.updateFn(metrics);
   }
 
@@ -122,6 +135,9 @@ export class ClapprStats extends ContainerPlugin {
     };
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
     this.listenTo(this.container, CoreEvents.CONTAINER_BITRATE, this.onBitrate);
     this.listenTo(this.container, CoreEvents.CONTAINER_STOP, this.stopReporting);
@@ -141,11 +157,18 @@ export class ClapprStats extends ContainerPlugin {
     this.listenTo(this.container.playback, CoreEvents.PLAYBACK_TIMEUPDATE, this.onTimeUpdate);
   }
 
+  /**
+   * @internal
+   */
   override destroy() {
     this.stopReporting();
     super.destroy();
   }
 
+  /**
+   * Returns the collected metrics.
+   * @returns The collected metrics
+   */
   exportMetrics() {
     return structuredClone(this.metrics);
   }
@@ -166,7 +189,7 @@ export class ClapprStats extends ContainerPlugin {
     this._inc('changeLevel');
   }
 
-  stopReporting() {
+  private stopReporting() {
     this._buildReport();
 
     if (this.intervalId !== null) {
@@ -175,25 +198,26 @@ export class ClapprStats extends ContainerPlugin {
     }
     this._newMetrics();
 
+    // TODO
     // @ts-ignore
     this.stopListening();
     this.bindEvents();
   }
 
-  startTimers() {
+  private startTimers() {
     this.intervalId = setInterval(this._buildReport.bind(this), this.runEach);
     this.start('session');
     this.start('startup');
   }
 
-  onFirstPlaying() {
+  private onFirstPlaying() {
     this.listenTo(this.container, CoreEvents.CONTAINER_TIMEUPDATE, this.onContainerUpdateWhilePlaying);
 
     this.start('watch');
     this._stop('startup');
   }
 
-  playAfterPause() {
+  private playAfterPause() {
     this.listenTo(this.container, CoreEvents.CONTAINER_TIMEUPDATE, this.onContainerUpdateWhilePlaying);
     this._stop('pause');
     this.start('watch');
@@ -280,7 +304,7 @@ export class ClapprStats extends ContainerPlugin {
     }
   }
 
-  _buildReport() {
+  private _buildReport() {
     this._stop('session');
     this.start('session');
 

package/src/plugins/clappr-stats/types.ts

@@ -1,3 +1,7 @@
+
+/**
+ * @beta
+ */
 export type Metrics = {
   counters: {
     play: number;
@@ -37,6 +41,9 @@ export type Metrics = {
   custom: Record<string, unknown>;
 };
 
+/**
+ * @beta
+ */
 export type BitrateTrackRecord = {
   start: number;
   end?: number;
@@ -44,8 +51,14 @@ export type BitrateTrackRecord = {
   bitrate: number;
 }
 
+/**
+ * @beta
+ */
 export type MetricsUpdateFn = (metrics: Metrics) => void;
 
+/**
+ * @beta
+ */
 export enum ClapprStatsEvents {
   REPORT_EVENT = 'clappr:stats:report',
   PERCENTAGE_EVENT = 'clappr:stats:percentage',

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

@@ -1,63 +1,74 @@
 //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.
+// license that can be found at https://github.com/clappr/clappr-plugins/blob/master/LICENSE.
 
-import { ContainerPlugin, Events, Playback } from '@clappr/core';
-import { trace } from '@gcorevideo/utils';
+import { ContainerPlugin, Events, Playback } from '@clappr/core'
+import { trace } from '@gcorevideo/utils'
 
-import { CLAPPR_VERSION } from '../../build.js';
+import { CLAPPR_VERSION } from '../../build.js'
 
-// const VERSION = '0.0.1';
+type Timer = ReturnType<typeof setTimeout>
 
-type Timer = ReturnType<typeof setTimeout>;
-
-const T = 'plugins.click_to_pause_custom';
+const T = 'plugins.click_to_pause_custom'
 
+/**
+ * Adds a behavior of toggling the playback state on click over the container
+ * @beta
+ */
 export class ClickToPause extends ContainerPlugin {
-  private pointerEnabled = false;
+  private pointerEnabled = false
 
-  private timer: Timer | null = null;
+  private timer: Timer | null = null
 
+  /**
+   * @internal
+   */
   get name() {
-    return 'click_to_pause_custom';
+    return 'click_to_pause_custom'
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
-    return { min: CLAPPR_VERSION };
-  }
-
-  get config() {
-    return this.container.options.clickToPauseConfig || {};
+    return { min: CLAPPR_VERSION }
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
-    this.listenTo(this.container, Events.CONTAINER_CLICK, this.click);
-    this.listenTo(this.container, Events.CONTAINER_SETTINGSUPDATE, this.settingsUpdate);
+    this.listenTo(this.container, Events.CONTAINER_CLICK, this.click)
+    this.listenTo(
+      this.container,
+      Events.CONTAINER_SETTINGSUPDATE,
+      this.settingsUpdate,
+    )
   }
 
   private click() {
-    const isLivePlayback = this.container.getPlaybackType() === Playback.LIVE;
-    const isDvrEnabled = this.container.isDvrEnabled();
+    const isLivePlayback = this.container.getPlaybackType() === Playback.LIVE
+    const isDvrEnabled = this.container.isDvrEnabled()
 
     trace(`${T} click`, {
       isLivePlayback,
       isDvrEnabled,
-    });
+    })
 
     if (isLivePlayback && !isDvrEnabled) {
-      this.togglePlay(true);
+      this.togglePlay(true)
     } else if (!isLivePlayback || isDvrEnabled) {
-      this.clearTimer();
+      this.clearTimer()
       this.timer = setTimeout(() => {
         this.timer = null
-        this.togglePlay(false);
-      }, 300);
+        this.togglePlay(false)
+      }, 300)
     }
   }
 
   private settingsUpdate() {
-    const isLivePlayback = this.container.getPlaybackType() === Playback.LIVE;
-    const pointerEnabled = !isLivePlayback || this.container.isDvrEnabled();
+    const isLivePlayback = this.container.getPlaybackType() === Playback.LIVE
+    const pointerEnabled = !isLivePlayback || this.container.isDvrEnabled()
 
     trace(`${T} settingsUpdate`, {
       isLivePlayback,
@@ -65,29 +76,29 @@ export class ClickToPause extends ContainerPlugin {
     })
 
     if (pointerEnabled === this.pointerEnabled) {
-      return;
+      return
     }
 
-    const method = pointerEnabled ? 'addClass' : 'removeClass';
+    const method = pointerEnabled ? 'addClass' : 'removeClass'
 
-    this.container.$el[method]('pointer-enabled');
-    this.pointerEnabled = pointerEnabled;
+    this.container.$el[method]('pointer-enabled')
+    this.pointerEnabled = pointerEnabled
   }
 
   private togglePlay(useStop: boolean) {
-    const isPlaying = this.container && this.container.isPlaying();
+    const isPlaying = this.container && this.container.isPlaying()
 
     if (isPlaying) {
-      useStop ? this.container.stop() : this.container.pause();
+      useStop ? this.container.stop() : this.container.pause()
     } else {
-      this.container.play();
+      this.container.play()
     }
   }
 
   private clearTimer() {
     if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
+      clearTimeout(this.timer)
+      this.timer = null
     }
   }
 }

package/src/plugins/clips/Clips.ts

@@ -1,115 +1,158 @@
-import { Container, Events, UICorePlugin, $ } from '@clappr/core';
+import { Container, Events, UICorePlugin, $ } from '@clappr/core'
 
-import { TimeProgress } from '../../playback.types.js';
-import type { ZeptoResult } from '../../utils/types.js';
-import { strtimeToMiliseconds } from '../utils.js';
-import '../../../assets/clips/clips.scss';
+import { TimeProgress } from '../../playback.types.js'
+import type { ZeptoResult } from '../../utils/types.js'
+import { strtimeToMiliseconds } from '../utils.js'
+import '../../../assets/clips/clips.scss'
+import assert from 'assert'
 
 type ClipDesc = {
-  start: number;
-  text: string;
-  end: number;
-  index: number;
+  start: number
+  text: string
+  end: number
+  index: number
 }
 
 type ClipItem = {
-  start: number;
-  text: string;
+  start: number
+  text: string
 }
 
+/**
+ * Configuration options
+ */
+export interface ClipsPluginSettings {
+  /**
+   * The text to display over the seekbar.
+   */
+  text: string
+}
+
+/**
+ * Adds a behavior of showing a text over the seekbar to indicate the current clip.
+ * @beta
+ * @remarks
+ * Depends on:
+ *
+ * - {@link MediaControl}
+ *
+ * Configuration options - {@link ClipsPluginSettings}
+ */
 export class ClipsPlugin extends UICorePlugin {
   private clips: Map<number, ClipDesc> = new Map()
 
-  private duration: number = 0;
+  private duration: number = 0
 
-  private durationGetting = false;
+  private durationGetting = false
 
-  private _oldContainer: Container | undefined;
+  private _oldContainer: Container | undefined
 
-  private svgMask: ZeptoResult | null = null;
+  private svgMask: ZeptoResult | null = null
 
+  /**
+   * @internal
+   */
   get name() {
-    return 'media_control_clips';
+    return 'clips'
   }
 
+  /**
+   * @internal
+   */
   override get attributes() {
     return {
-      'class': this.name
-    };
+      class: this.name,
+    }
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
-    this.listenToOnce(this.core, Events.CORE_READY, this._onCoreReady);
-    this.listenTo(this.core.mediaControl, Events.MEDIACONTROL_CONTAINERCHANGED, this._onMediaControlContainerChanged);
-    this.listenTo(this.core, Events.CORE_RESIZE, this.playerResize);
+    const mediaControl = this.core.getPlugin('media_control')
+    assert(mediaControl, 'media_control plugin is required')
+    this.listenToOnce(this.core, Events.CORE_READY, this._onCoreReady)
+    // TODO listen to CORE_ACTIVE_CONTAINER_CHANGED
+    this.listenTo(
+      mediaControl,
+      Events.MEDIACONTROL_CONTAINERCHANGED,
+      this._onMediaControlContainerChanged,
+    )
+    this.listenTo(this.core, Events.CORE_RESIZE, this.playerResize)
   }
 
   private _onCoreReady() {
     if (!this.options.clips) {
-      this.destroy();
+      this.destroy()
 
-      return;
+      return
     }
 
-    this.parseClips();
-  }
-
-  unbindEvents() {
-    // @ts-ignore
-    this.stopListening(this.core, Events.CORE_READY);
-    // @ts-ignore
-    this.stopListening(this.core.mediaControl, Events.MEDIACONTROL_CONTAINERCHANGED);
+    this.parseClips()
   }
 
   private _onMediaControlContainerChanged() {
-    this._bindContainerEvents();
+    this._bindContainerEvents()
   }
 
   private playerResize() {
-    this.durationGetting = false;
+    this.durationGetting = false
     if (this.durationGetting) {
-      this.makeSvg(this.duration);
+      this.makeSvg(this.duration)
     }
   }
 
   private _bindContainerEvents() {
     if (this._oldContainer) {
-      this.stopListening(this._oldContainer, Events.CONTAINER_TIMEUPDATE, this.onTimeUpdate);
+      this.stopListening(
+        this._oldContainer,
+        Events.CONTAINER_TIMEUPDATE,
+        this.onTimeUpdate,
+      )
     }
 
-    this._oldContainer = this.core.mediaControl.container;
-    this.durationGetting = false;
-    this.listenTo(this.core.mediaControl.container, Events.CONTAINER_TIMEUPDATE, this.onTimeUpdate);
+    const mediaControl = this.core.getPlugin('media_control')
+    this._oldContainer = mediaControl.container
+    this.durationGetting = false
+    this.listenTo(
+      mediaControl.container,
+      Events.CONTAINER_TIMEUPDATE,
+      this.onTimeUpdate,
+    )
   }
 
   private onTimeUpdate(event: TimeProgress) {
     if (!this.durationGetting) {
-      this.duration = event.total;
-      this.makeSvg(event.total);
-      this.durationGetting = true;
+      this.duration = event.total
+      this.makeSvg(event.total)
+      this.durationGetting = true
     }
 
     for (const value of this.clips.values()) {
       if (event.current >= value.start && event.current < value.end) {
-        this.setClipText(value.text);
-        break;
+        this.setClipText(value.text)
+        break
       }
     }
   }
 
   private parseClips() {
-    const textArr = this.options.clips.text.split('\n');
+    const textArr = this.options.clips.text.split('\n')
 
-    const clipsArr = textArr.map((val: string) => {
-      const matchRes = val.match(/(\d+:\d+|:\d+) (.+)/i);
+    const clipsArr = textArr
+      .map((val: string) => {
+        const matchRes = val.match(/(\d+:\d+|:\d+) (.+)/i)
 
-      return matchRes ? {
-        start: strtimeToMiliseconds(matchRes[1]),
-        text: matchRes[2],
-      } : null;
-    }).filter((clip: ClipItem | null) => clip !== null);
+        return matchRes
+          ? {
+              start: strtimeToMiliseconds(matchRes[1]),
+              text: matchRes[2],
+            }
+          : null
+      })
+      .filter((clip: ClipItem | null) => clip !== null)
 
-    clipsArr.sort((a: ClipDesc, b: ClipDesc) => a.start - b.start);
+    clipsArr.sort((a: ClipDesc, b: ClipDesc) => a.start - b.start)
 
     clipsArr.forEach((clip: ClipDesc, index: number) => {
       this.clips.set(clip.start, {
@@ -117,39 +160,49 @@ export class ClipsPlugin extends UICorePlugin {
         start: clip.start,
         text: clip.text,
         end: clipsArr[index + 1] ? clipsArr[index + 1].start : null,
-      });
-    });
+      })
+    })
   }
 
+  /**
+   * Returns the text of the current clip.
+   * @param time - The current time of the player.
+   * @returns The text of the current clip.
+   */
   getText(time: number) {
     for (const [key, value] of this.clips.entries()) {
       if (time >= value.start && time < value.end) {
-        return value.text;
+        return value.text
       }
     }
-    return '';
+    return ''
   }
 
-  makeSvg(duration: number) {
-    let svg = '<svg width="0" height="0">\n' + '<defs>\n' + '<clipPath id="myClip">\n';
-    const widthOfSeek = this.core.mediaControl.container.$el.width();
-    let finishValue = 0;
+  private makeSvg(duration: number) {
+    let svg =
+      '<svg width="0" height="0">\n' + '<defs>\n' + '<clipPath id="myClip">\n'
+    const widthOfSeek = this.core.activeContainer.$el.width()
+    let finishValue = 0
 
-    this.clips.forEach(val => {
-      let end = val.end;
+    this.clips.forEach((val) => {
+      let end = val.end
 
       if (!end) {
-        end = val.end = duration;
+        end = val.end = duration
       }
 
-      const widthChunk = (end - val.start) * widthOfSeek / duration;
+      const widthChunk = ((end - val.start) * widthOfSeek) / duration
 
-      svg += `<rect x="${finishValue}" y="0" width="${widthChunk - 2}" height="30"/>\n`;
-      finishValue += widthChunk;
-    });
+      svg += `<rect x="${finishValue}" y="0" width="${
+        widthChunk - 2
+      }" height="30"/>\n`
+      finishValue += widthChunk
+    })
 
-    svg += `<rect x="${finishValue}" y="0" width="${widthOfSeek - finishValue}" height="30"/>\n`;
-    svg += '</clipPath>' + '</defs>' + '</svg>';
+    svg += `<rect x="${finishValue}" y="0" width="${
+      widthOfSeek - finishValue
+    }" height="30"/>\n`
+    svg += '</clipPath>' + '</defs>' + '</svg>'
     this.setSVGMask(svg)
   }
 
@@ -159,7 +212,9 @@ export class ClipsPlugin extends UICorePlugin {
       this.svgMask.remove()
     }
 
-    const $seekBarContainer = this.core.mediaControl.getElement('seekBarContainer')
+    const mediaControl = this.core.getPlugin('media_control')
+    const $seekBarContainer =
+      mediaControl.getElement('seekBarContainer')
     if ($seekBarContainer?.get(0)) {
       $seekBarContainer.addClass('clips')
     }
@@ -169,7 +224,8 @@ export class ClipsPlugin extends UICorePlugin {
   }
 
   private setClipText(text: string) {
-    const $clipText = this.core.mediaControl.getElement('clipText')
+    const mediaControl = this.core.getPlugin('media_control')
+    const $clipText = mediaControl.getElement('clipText')
     if ($clipText && text) {
       $clipText.show()
       $clipText.text(`${text}`)