@gcorevideo/player 2.20.9 → 2.20.12

package/src/plugins/dvr-controls/DvrControls.ts

@@ -6,11 +6,12 @@ import { CLAPPR_VERSION } from '../../build.js'
 import dvrHTML from '../../../assets/dvr-controls/index.ejs'
 import '../../../assets/dvr-controls/dvr_controls.scss'
 import { trace } from '@gcorevideo/utils'
+import { MediaControl } from '../media-control/MediaControl.js'
 
 const T = 'plugins.dvr_controls'
 
 /**
- * PLUGIN that adds the DVR controls to the media control UI
+ * `PLUGIN` that adds the DVR controls to the media control UI
  *
  * @beta
  *
@@ -19,7 +20,9 @@ const T = 'plugins.dvr_controls'
  *
  * - {@link MediaControl}
  *
- * The plugin renders live stream indicator and the DVR seek bar, if DVR is enabled, in the media control UI.
+ * The plugin renders live stream indicator.
+ * If DVR is enabled, the indicator shows whether the current position is at the live edge of the stream or not.
+ * In the latter case, the indicator can be clicked to seek to the live edge.
  */
 export class DvrControls extends UICorePlugin {
   private static readonly template = template(dvrHTML)
@@ -57,15 +60,20 @@ export class DvrControls extends UICorePlugin {
     }
   }
 
-  constructor(core: Core) {
-    super(core)
-    this.settingsUpdate()
-  }
-
   /**
    * @internal
    */
   override bindEvents() {
+    this.listenTo(this.core, Events.CORE_READY, this.onCoreReady)
+    this.listenTo(this.core, Events.CORE_OPTIONS_CHANGE, this.render)
+    this.listenTo(
+      this.core,
+      Events.CORE_ACTIVE_CONTAINER_CHANGED,
+      this.bindContainerEvents,
+    )
+  }
+
+  private onCoreReady() {
     const mediaControl = this.core.getPlugin('media_control')
     assert(mediaControl, 'media_control plugin is required')
     this.listenTo(
@@ -73,12 +81,7 @@ export class DvrControls extends UICorePlugin {
       Events.MEDIACONTROL_RENDERED,
       this.settingsUpdate,
     )
-    this.listenTo(this.core, Events.CORE_OPTIONS_CHANGE, this.render)
-    this.listenTo(
-      this.core,
-      Events.CORE_ACTIVE_CONTAINER_CHANGED,
-      this.bindContainerEvents,
-    )
+    this.settingsUpdate()
   }
 
   private bindContainerEvents() {
@@ -94,57 +97,45 @@ export class DvrControls extends UICorePlugin {
     )
   }
 
-  private onDvrChanged(dvrEnabled: boolean) {
+  private onDvrChanged(dvrInUse: boolean) {
     trace(`${T} onDvrChanged`, {
-      dvrEnabled,
+      dvrInUse,
     })
     if (this.core.getPlaybackType() !== Playback.LIVE) {
       return
     }
-    this.settingsUpdate()
-    this.core.mediaControl.$el.addClass('live')
-    if (dvrEnabled) {
-      // TODO
-      this.core.mediaControl.$el
+    this.render()
+    const mediaControl = this.core.getPlugin('media_control')
+    mediaControl.$el.addClass('live')
+    if (dvrInUse) {
+      mediaControl.$el
         .addClass('dvr')
         .find(
+          // TODO add API, test
           '.media-control-indicator[data-position], .media-control-indicator[data-duration]',
         )
         .hide()
     } else {
-      this.core.mediaControl.$el.removeClass('dvr')
+      mediaControl.$el.removeClass('dvr')
     }
   }
 
   private click() {
-    const mediaControl = this.core.getPlugin('media_control')
     const container = this.core.activeContainer
-
     if (!container.isPlaying()) {
       container.play()
     }
-
-    if (mediaControl.$el.hasClass('dvr')) {
-      container.seek(container.getDuration())
-    }
+    container.seek(container.getDuration())
   }
 
   private settingsUpdate() {
-    // @ts-ignore
-    this.stopListening() // TODO sort out
-    this.core.getPlugin('media_control').$el.removeClass('live') // TODO don't access directly
-    if (this.shouldRender()) {
-      this.render()
-      this.$el.click(() => this.click())
-    }
-    this.bindEvents()
+    trace(`${T} settingsUpdate`)
+    this.core.getPlugin('media_control').$el.removeClass('live')
+    this.render()
   }
 
   private shouldRender() {
-    const useDvrControls =
-      this.core.options.useDvrControls === undefined ||
-      !!this.core.options.useDvrControls
-
+    const useDvrControls = this.core.options.useDvrControls !== false
     return useDvrControls && this.core.getPlaybackType() === Playback.LIVE
   }
 
@@ -154,6 +145,7 @@ export class DvrControls extends UICorePlugin {
   override render() {
     trace(`${T} render`, {
       dvrEnabled: this.core.activePlayback?.dvrEnabled,
+      playbackType: this.core.getPlaybackType(),
     })
     if (!this.shouldRender()) {
       return this
@@ -164,13 +156,9 @@ export class DvrControls extends UICorePlugin {
         backToLive: this.core.i18n.t('back_to_live'),
       }),
     )
-    const mediaControl = this.core.getPlugin('media_control')
-    assert(mediaControl, 'media_control plugin is required')
-    // TODO don't tap into the $el directly
+    const mediaControl = this.core.getPlugin('media_control') as MediaControl
     mediaControl.$el.addClass('live')
-    mediaControl
-      .$('.media-control-left-panel[data-media-control]')
-      .append(this.$el)
+    mediaControl.getLeftPanel().append(this.$el)
 
     return this
   }

package/src/plugins/dvr-controls/__tests__/DvrControls.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DvrControls } from '../DvrControls.js'
+import { createMockCore, createMockMediaControl } from '../../../testUtils.js'
+// import { LogTracer, Logger, setTracer } from '@gcorevideo/utils'
+
+// setTracer(new LogTracer('DvrControls.test'))
+// Logger.enable('*')
+
+describe('DvrControls', () => {
+  let core: any
+  let mediaControl: any
+  let plugins: Record<string, any> = {}
+  let dvrControls: DvrControls
+  beforeEach(() => {
+    core = createMockCore()
+    mediaControl = createMockMediaControl(core)
+    plugins = {
+      media_control: mediaControl,
+    }
+    core.getPlugin.mockImplementation((name: string) => plugins[name])
+    dvrControls = new DvrControls(core)
+    plugins.dvr_controls = dvrControls
+  })
+  describe('live stream', () => {
+    beforeEach(() => {
+      core.getPlaybackType.mockReturnValue('live')
+    })
+    describe.each([
+      ['no DVR', false, false, false],
+      ['DVR at live edge', true, false, false],
+      ['DVR behind live edge', true, true, true],
+    ])('%s', (_, dvrEnabled, dvrInUse, indicateDvr) => {
+      beforeEach(() => {
+        core.activePlayback.dvrEnabled = dvrEnabled
+        core.trigger('core:ready')
+        core.trigger('core:active:container:changed')
+        if (dvrInUse) {
+          core.activeContainer.trigger('container:dvr', true)
+        }
+      })
+      it('should render', () => {
+        expect(dvrControls.el.textContent).toBeTruthy()
+        expect(dvrControls.el.innerHTML).toMatchSnapshot()
+      })
+      it('should render to the media control left panel', () => {
+        expect(mediaControl.$el.find('.media-control-left-panel').text()).toContain('live')
+        expect(mediaControl.el.innerHTML).toMatchSnapshot()
+      })
+      it('should indicate live streaming mode', () => {
+        expect(mediaControl.$el.hasClass('live')).toBe(true)
+      })
+      if (indicateDvr) {
+        it('should indicate DVR mode', () => {
+          expect(mediaControl.$el.hasClass('dvr')).toBe(true)
+        })
+      } else {
+        it('should not indicate DVR mode', () => {
+          expect(mediaControl.$el.hasClass('dvr')).toBe(false)
+        })
+      }
+    })
+    describe('when back_to_live button is clicked', () => {
+      beforeEach(() => {
+        core.activePlayback.dvrEnabled = true
+        core.trigger('core:ready')
+        core.trigger('core:active:container:changed')
+        core.activeContainer.getDuration.mockReturnValue(180)
+        core.activeContainer.trigger('container:dvr', true)
+        dvrControls.$el.find('.live-button').click()
+      })
+      it('should call active container play', () => {
+        expect(core.activeContainer.play).toHaveBeenCalled()
+      })
+      it('should seek to live edge', () => {
+        expect(core.activeContainer.seek).toHaveBeenCalledWith(180)
+      })
+    })
+  })
+  describe('VOD stream', () => {
+    beforeEach(() => {
+      core.getPlaybackType.mockReturnValue('vod')
+    })
+    beforeEach(() => {
+      core.trigger('core:ready')
+      core.trigger('core:active:container:changed')
+    })
+    it('should not render', () => {
+      expect(dvrControls.el.textContent).toBeFalsy()
+    })
+  })
+})

package/src/plugins/dvr-controls/__tests__/__snapshots__/DvrControls.test.ts.snap

@@ -0,0 +1,43 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`DvrControls > live stream > DVR at live edge > should render 1`] = `
+"<div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+"
+`;
+
+exports[`DvrControls > live stream > DVR at live edge > should render to the media control left panel 1`] = `
+"<div class="media-control-left-panel" data-media-control=""><div class="dvr-controls" data-dvr-controls=""><div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+</div></div>
+    <div class="media-control-right-panel" data-media-control=""></div>
+    <div class="media-control-center-panel" data-media-control=""></div>"
+`;
+
+exports[`DvrControls > live stream > DVR behind live edge > should render 1`] = `
+"<div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+"
+`;
+
+exports[`DvrControls > live stream > DVR behind live edge > should render to the media control left panel 1`] = `
+"<div class="media-control-left-panel" data-media-control=""><div class="dvr-controls" data-dvr-controls=""><div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+</div></div>
+    <div class="media-control-right-panel" data-media-control=""></div>
+    <div class="media-control-center-panel" data-media-control=""></div>"
+`;
+
+exports[`DvrControls > live stream > no DVR > should render 1`] = `
+"<div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+"
+`;
+
+exports[`DvrControls > live stream > no DVR > should render to the media control left panel 1`] = `
+"<div class="media-control-left-panel" data-media-control=""><div class="dvr-controls" data-dvr-controls=""><div class="live-info">live</div>
+<button type="button" class="live-button" aria-label="back_to_live">back_to_live</button>
+</div></div>
+    <div class="media-control-right-panel" data-media-control=""></div>
+    <div class="media-control-center-panel" data-media-control=""></div>"
+`;

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

@@ -6,25 +6,7 @@ import { CLAPPR_VERSION } from '../../build.js'
 import reloadIcon from '../../../assets/icons/old/reload.svg'
 import templateHtml from '../../../assets/error-screen/error_screen.ejs'
 import '../../../assets/error-screen/error_screen.scss'
-import { PlaybackErrorCode } from '../../playback.types.js'
-
-/**
- * An error fired in the player and plugins code to be handled in the UI
- * @beta
- */
-export type ErrorDesc = {
-  description: string
-  level: string
-  code: string
-  origin: string
-  scope: string
-  raw?: string
-  UI?: {
-    icon?: string
-    title: string
-    message: string
-  }
-}
+import { PlaybackError } from '../../playback.types.js'
 
 type ErrorScreenDesc = {
   title: string
@@ -47,7 +29,7 @@ export type ErrorScreenPluginSettings = {
 const T = 'plugins.error_screen'
 
 /**
- * PLUGIN that displays errors nicely in the overlay on top of the player.
+ * `PLUGIN` that displays errors nicely in the overlay on top of the player.
  * @beta
  */
 export class ErrorScreen extends UICorePlugin {
@@ -142,7 +124,7 @@ export class ErrorScreen extends UICorePlugin {
     }
   }
 
-  private onError(err: ErrorDesc) {
+  private onError(err: PlaybackError) {
     trace(`${T} onError`, { err })
     if (err.UI) {
       if (this.err) {
@@ -172,7 +154,6 @@ export class ErrorScreen extends UICorePlugin {
       }),
     )
 
-    // TODO append to container instead of core?
     if (!this.el.parentElement) {
       this.core.$el.append(this.el)
     }

package/src/plugins/favicon/Favicon.ts

@@ -10,15 +10,23 @@ import stopIcon from '../../../assets/icons/new/stop.svg';
 const FAVICON_COLOR = '#567';
 const FAVICON_SELECTOR = 'link[rel="shortcut icon"]';
 
-// const oldIcon = $(FAVICON_SELECTOR);
+/**
+ * @beta
+ */
+export interface FaviconPluginSettings {
+  /**
+   * CSS color of the favicon.
+   */
+  faviconColor?: string;
+}
 
 /**
- * The plugin adds custom favicon to the player's tab.
+ * `PLUGIN` that changes the favicon according to the player's state.
  * @beta
+ * @remarks
+ * There are three states: stopped, playing and paused.
  */
 export class Favicon extends CorePlugin {
-  private _container: Container | null = null;
-
   private oldIcon: ZeptoResult;
 
   private playIcon: ZeptoResult | null = null;
@@ -27,18 +35,23 @@ export class Favicon extends CorePlugin {
 
   private stopIcon: ZeptoResult | null = null;
 
+  /**
+   * @internal
+   */
   get name() {
     return 'favicon';
   }
 
+  /**
+   * @internal
+   */
   get supportedVersion() {
     return { min: CLAPPR_VERSION };
   }
 
-  //   get oldIcon() {
-  //     return oldIcon;
-  //   }
-
+  /**
+   * @internal
+   */
   constructor(core: Core) {
     super(core);
     this.oldIcon = $(FAVICON_SELECTOR);
@@ -46,45 +59,35 @@ export class Favicon extends CorePlugin {
       this.stopIcon = this.createIcon(stopIcon);
       this.changeIcon(this.stopIcon);
     }
-    this.configure();
-  }
-
-  configure() {
-    if (this.core.options.changeFavicon) {
-      if (!this.enabled) {
-        // @ts-ignore
-        this.stopListening(this.core, Events.CORE_OPTIONS_CHANGE);
-        this.enable();
-      }
-    } else if (this.enabled) {
-      this.disable();
-      this.listenTo(this.core, Events.CORE_OPTIONS_CHANGE, this.configure);
-    }
   }
 
+  /**
+   * @internal
+   */
   override bindEvents() {
-    this.listenTo(this.core, Events.CORE_OPTIONS_CHANGE, this.configure);
     this.listenTo(this.core, Events.CORE_ACTIVE_CONTAINER_CHANGED, this.containerChanged);
-    this.core.activeContainer && this.containerChanged();
   }
 
   private containerChanged() {
-    // @ts-ignore
-    this._container && this.stopListening(this._container);
-    this._container = this.core.activeContainer;
-    this.listenTo(this._container, Events.CONTAINER_PLAY, this.setPlayIcon);
-    this.listenTo(this._container, Events.CONTAINER_PAUSE, this.setPauseIcon);
-    this.listenTo(this._container, Events.CONTAINER_STOP, this.resetIcon);
-    this.listenTo(this._container, Events.CONTAINER_ENDED, this.resetIcon);
-    this.listenTo(this._container, Events.CONTAINER_ERROR, this.resetIcon);
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_PLAY, this.setPlayIcon);
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_PAUSE, this.setPauseIcon);
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_STOP, this.resetIcon);
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_ENDED, this.resetIcon);
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_ERROR, this.resetIcon);
     this.resetIcon();
   }
 
+  /**
+   * @internal
+   */
   override disable() {
     super.disable();
     this.resetIcon();
   }
 
+  /**
+   * @internal
+   */
   override destroy() {
     super.destroy();
     this.resetIcon();
@@ -113,7 +116,6 @@ export class Favicon extends CorePlugin {
     if (!this.playIcon) {
       this.playIcon = this.createIcon(playIcon);
     }
-
     this.changeIcon(this.playIcon);
   }
 
@@ -121,21 +123,16 @@ export class Favicon extends CorePlugin {
     if (!this.pauseIcon) {
       this.pauseIcon = this.createIcon(pauseIcon);
     }
-
     this.changeIcon(this.pauseIcon);
   }
 
   private resetIcon() {
-    $(FAVICON_SELECTOR).remove();
     const icon = this.oldIcon.length > 0 ? this.oldIcon : this.stopIcon;
-
     this.changeIcon(icon);
   }
 
-  private changeIcon(icon: ZeptoResult | null) {
-    if (icon) {
-      $('link[rel="shortcut icon"]').remove();
-      $('head').append(icon);
-    }
+  private changeIcon(icon: ZeptoResult) {
+    $('link[rel="shortcut icon"]').remove();
+    $('head').append(icon);
   }
 }

package/src/plugins/google-analytics/GoogleAnalytics.ts

@@ -11,7 +11,7 @@ declare const _gaq: {
 };
 
 /**
- * An example Google Analytics integration plugin
+ * `PLUGIN` that integrates with Google Analytics
  * @beta
  */
 export class GoogleAnalytics extends ContainerPlugin {

package/src/plugins/level-selector/LevelSelector.ts

@@ -40,7 +40,7 @@ export interface LevelSelectorPluginSettings {
 }
 
 /**
- * PLUGIN that provides a UI to select the desired quality level of the playback.
+ * `PLUGIN` that provides a UI to select the desired quality level of the playback.
  * @beta
  *
  * @remarks

package/src/plugins/logo/Logo.ts

@@ -21,7 +21,7 @@ type LogoOptions = {
 };
 
 /**
- * The plugin adds custom logo to the player.
+ * `PLUGIN` that adds custom logo to the player.
  * @beta
  */
 export class Logo extends UIContainerPlugin {

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

@@ -1,6 +1,8 @@
+// This is a derived work from the {@link https://github.com/clappr/clappr-plugins/tree/ffaa9d27005fa5a8a7c243ffc47eb5655b84b371/src/plugins/media_control | Clappr MediaControl plugin}
+// It is redistributed under the terms of the {@link ../../../../../LICENSE | Apache 2.0} license.
 // 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 in the {@link https://github.com/clappr/clappr-plugins/blob/master/LICENSE | LICENSE}.
 
 import assert from 'assert'
 import {
@@ -88,11 +90,11 @@ type DisabledClickable = {
 }
 
 /**
- * PLUGIN that provides a foundation for developing custom media controls UI.
+ * `PLUGIN` that provides a foundation for developing custom media controls UI.
  * @beta
  * @remarks
  * The methods exposed are to be used by the other plugins that extend the media control UI.
- * The plugin registration should be arranged so that MediaControl is initialized before every other plugin that depends on it.
+ * The plugin registration should be arranged so that MediaControl is initialized before every other `PLUGIN` that depends on it.
  * @example
  * ```ts
  * Player.registerPlugin(MediaControl) // <--- This must go first
@@ -1132,6 +1134,18 @@ export class MediaControl extends UICorePlugin {
     return this.$el.find('.media-control-right-panel')
   }
 
+  /**
+   * Get the left panel area to append custom elements to
+   * @returns  ZeptoSelector of the left panel element
+   */
+  getLeftPanel() {
+    return this.$el.find('.media-control-left-panel')
+  }
+
+  getCenterPanel() {
+    return this.$el.find('.media-control-center-panel')
+  }
+
   private resetIndicators() {
     assert.ok(
       this.$duration && this.$position,

package/src/plugins/multi-camera/MultiCamera.ts

@@ -26,7 +26,7 @@ const VERSION = '0.0.1';
 const T = 'plugins.multicamera';
 
 /**
- * PLUGIN that adds support for loading multiple streams and switching between them using the media control UI.
+ * `PLUGIN` that adds support for loading multiple streams and switching between them using the media control UI.
  * @beta
  */
 export class MultiCamera extends UICorePlugin {

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

@@ -12,7 +12,7 @@ const VERSION = '0.0.1';
 const T = `plugins.pip`;
 
 /**
- * Enables picture in picture mode.
+ * `PLUGIN` that enables picture in picture mode.
  * @beta
  * @remarks
  * Depends on:

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

@@ -35,7 +35,7 @@ const DEFAULT_PLAYBACK_RATE = '1.0';
 const T = 'plugins.playback_rate';
 
 /**
- * PLUGIN that allows changing the playback speed of the video.
+ * `PLUGIN` that allows changing the playback speed of the video.
  * @beta
  *
  * @remarks

package/src/plugins/poster/Poster.ts

@@ -24,7 +24,7 @@ import { PlaybackError } from '../../playback.types.js'
 const T = 'plugins.poster'
 
 /**
- * Displays a poster image in the background and a big play button on top when playback is stopped
+ * `PLUGIN` that displays a poster image in the background and a big play button on top when playback is stopped
  * @beta
  * @remarks
  * When the playback is stopped, media control UI is disabled.

package/src/plugins/seek-time/SeekTime.ts

@@ -14,7 +14,7 @@ import { ZeptoResult } from '../../types.js';
 const { formatTime } = Utils;
 
 /**
- * The plugin adds a seek time indicator to the media control UI.
+ * `PLUGIN` that adds a seek time indicator to the media control UI.
  * @beta
  */
 export class SeekTime extends UICorePlugin {

package/src/plugins/share/Share.ts

@@ -10,7 +10,7 @@ import fbIcon from '../../../assets/icons/old/fb.svg';
 import twIcon from '../../../assets/icons/old/twitter.svg';
 
 /**
- * PLUGIN that adds a share button to the media control UI.
+ * `PLUGIN` that adds a share button to the media control UI.
  * @beta
  */
 export class Share extends UICorePlugin {

package/src/plugins/skip-time/SkipTime.ts

@@ -8,7 +8,7 @@ import '../../../assets/skip-time/style.scss';
 type Position = 'mid' | 'left' | 'right';
 
 /**
- * PLUGIN that adds skip controls to the media control UI.
+ * `PLUGIN` that adds skip controls to the media control UI.
  * @beta
  */
 export class SkipTime extends UICorePluginOriginal {

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

@@ -27,7 +27,7 @@ function noSync(cb: () => void) {
 }
 
 /**
- * This plugin is responsible for managing the automatic failover between sources.
+ * `PLUGIN` that is responsible for managing the automatic failover between sources.
  * @beta
  * @remarks
  * Have a look at the {@link https://miro.com/app/board/uXjVLiN15tY=/?share_link_id=390327585787 | source failover diagram} for the details

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

@@ -31,7 +31,7 @@ export enum SpinnerEvents {
 }
 
 /**
- * PLUGIN that shows a pending operation indicator when playback is buffering or in a similar state
+ * `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state
  * @beta
  * @remarks
  * Events emitted- {@link SpinnerEvents}

package/src/plugins/subtitles/Subtitles.ts

@@ -34,7 +34,7 @@ type TextTrackInfo = {
 const NO_TRACK = { language: 'off' }
 
 /**
- * A {@link MediaControl | media control} plugin that provides a UI to select the subtitles when available.
+ * `PLUGIN` that provides a UI to select the subtitles when available.
  * @beta
  *
  * @remarks