@gcorevideo/player 2.20.8 → 2.20.11

package/src/plugins/context-menu/ContextMenu.ts

@@ -1,9 +1,7 @@
 import {
-  UICorePlugin,
   Events,
   template,
   $,
-  Core,
   Container,
   UIContainerPlugin,
 } from '@clappr/core'
@@ -30,7 +28,7 @@ export interface ContextMenuPluginSettings {
 }
 
 /**
- * Displays a small context menu when clicked on the player container.
+ * `PLUGIN` that displays a small context menu when clicked on the player container.
  * @beta
  * @remarks
  * Configuration options - {@link ContextMenuPluginSettings}

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

@@ -6,11 +6,13 @@ 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'
 
 /**
- * Adds the DVR controls to the media control UI
+ * `PLUGIN` that adds the DVR controls to the media control UI
+ *
  * @beta
  *
  * @remarks
@@ -18,7 +20,9 @@ const T = 'plugins.dvr_controls'
  *
  * - {@link MediaControl}
  *
- * The plugin renders the 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)
@@ -56,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(
@@ -72,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() {
@@ -93,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
   }
 
@@ -153,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
@@ -163,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,21 +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'
-
-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
@@ -29,14 +15,21 @@ type ErrorScreenDesc = {
   icon?: string
 }
 
+/**
+ * Configuration options for the {@link ErrorScreen | error screen} plugin.
+ * @beta
+ */
 export type ErrorScreenPluginSettings = {
+  /**
+   * Whether to hide the reload button.
+   */
   noReload?: boolean
 }
 
 const T = 'plugins.error_screen'
 
 /**
- * Displays an error 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 {
@@ -131,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) {

package/src/plugins/favicon/Favicon.ts

@@ -1,7 +1,7 @@
 import { CorePlugin, Events, $, Core, Container } from '@clappr/core';
 
 import { CLAPPR_VERSION } from '../../build.js';
-import { ZeptoResult } from '../../utils/types.js';
+import { ZeptoResult } from '../../types.js';
 
 import playIcon from '../../../assets/icons/new/play.svg';
 import pauseIcon from '../../../assets/icons/new/pause.svg';
@@ -13,7 +13,7 @@ const FAVICON_SELECTOR = 'link[rel="shortcut icon"]';
 // const oldIcon = $(FAVICON_SELECTOR);
 
 /**
- * The plugin adds custom favicon to the player's tab.
+ * `PLUGIN` that adds custom favicon to the player's tab.
  * @beta
  */
 export class Favicon extends CorePlugin {

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/index.ts

@@ -19,7 +19,6 @@ export * from "./error-screen/ErrorScreen.js";
 export * from "./favicon/Favicon.js";
 // _ ga-events
 export * from "./google-analytics/GoogleAnalytics.js";
-export * from "./kibo/index.js";
 export * from "./level-selector/LevelSelector.js";
 export * from "./logo/Logo.js";
 export * from "./media-control/MediaControl.js";

package/src/plugins/kibo/index.ts

@@ -11,9 +11,6 @@ type KeyboardEventBindings = {
 
 type UpDown = 'up' | 'down';
 
-/**
- * @internal
- */
 export class Kibo {
   private lastKeyCode = -1;
 

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

@@ -4,7 +4,7 @@ import assert from 'assert'
 
 import { type QualityLevel } from '../../playback.types.js'
 import { CLAPPR_VERSION } from '../../build.js'
-import { ZeptoResult } from '../../utils/types.js'
+import { ZeptoResult } from '../../types.js'
 import { TemplateFunction } from '../types.js'
 import { BottomGear } from '../bottom-gear/BottomGear.js'
 
@@ -20,6 +20,10 @@ import { MediaControl, MediaControlEvents } from '../media-control/MediaControl.
 const T = 'plugins.level_selector'
 const VERSION = '2.19.4'
 
+/**
+ * Configuration options for the {@link LevelSelector | level selector} plugin.
+ * @beta
+ */
 export interface LevelSelectorPluginSettings {
   /**
    * The maximum resolution to allow in the level selector.
@@ -36,7 +40,7 @@ export interface LevelSelectorPluginSettings {
 }
 
 /**
- * A {@link MediaControl | media control} plugin that provides a UI to control the quality level of the playback.
+ * `PLUGIN` that provides a UI to select the desired quality level of the playback.
  * @beta
  *
  * @remarks
@@ -46,9 +50,7 @@ export interface LevelSelectorPluginSettings {
  *
  * - {@link BottomGear}
  *
- * The plugin is rendered as an item in the gear menu.
- *
- * When clicked, it shows a list of quality levels to choose from.
+ * The plugin is rendered as an item in the gear menu, which, when clicked, shows a list of quality levels to choose from.
  *
  * Configuration options - {@link LevelSelectorPluginSettings}
  *

package/src/plugins/logo/Logo.ts

@@ -2,7 +2,7 @@ import { UIContainerPlugin, Events, template as t, Container } from '@clappr/cor
 
 import { CLAPPR_VERSION } from '../../build.js';
 import { calculateSize } from './utils/index.js';
-import { ZeptoResult } from '../../utils/types.js';
+import { ZeptoResult } from '../../types.js';
 
 import logoHTML from '../../../assets/logo/templates/logo.ejs';
 import '../../../assets/logo/styles/logo.scss';
@@ -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 {
@@ -20,7 +22,7 @@ import { type TimeProgress } from '../../playback.types.js'
 import { Kibo } from '../kibo/index.js'
 
 import { CLAPPR_VERSION } from '../../build.js'
-import { ZeptoResult } from '../../utils/types.js'
+import { ZeptoResult } from '../../types.js'
 import { getPageX, isFullscreen } from '../utils.js'
 
 import '../../../assets/media-control/media-control.scss'
@@ -88,11 +90,11 @@ type DisabledClickable = {
 }
 
 /**
- * The MediaControl 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
@@ -218,7 +220,7 @@ export class MediaControl extends UICorePlugin {
 
   /**
    * @internal
-   * @deprecated
+   * @deprecated Use core.activeContainer directly
    */
   get container() {
     return this.core.activeContainer
@@ -226,7 +228,7 @@ export class MediaControl extends UICorePlugin {
 
   /**
    * @internal
-   * @deprecated
+   * @deprecated Use core.activePlayback directly
    */
   get playback() {
     return this.core.activePlayback
@@ -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

@@ -9,7 +9,7 @@ import '../../../assets/multi-camera/style.scss';
 import streamsIcon from '../../../assets/icons/old/streams.svg';
 import streamsMomentoIcon from '../../../assets/icons/old/language.svg';
 import streamsWhiteNightsIcon from '../../../assets/icons/old/wn.svg';
-import { ZeptoResult } from '../../utils/types.js';
+import { ZeptoResult } from '../../types.js';
 
 type MultisourcesMode = 'one_first' | 'only_live' | 'show_all';
 
@@ -26,7 +26,7 @@ const VERSION = '0.0.1';
 const T = 'plugins.multicamera';
 
 /**
- * The plugin 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 {
@@ -381,11 +381,11 @@ export class MultiCamera extends UICorePlugin {
     this.toggleContextMenu();
   }
 
-  getCamerasList() {
+  private getCamerasList() {
     return this.multicamera;
   }
 
-  getCurrentCamera() {
+  private getCurrentCamera() {
     return this.currentCamera;
   }
 

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

@@ -3,7 +3,7 @@ import { trace } from '@gcorevideo/utils';
 import assert from 'assert';
 
 import { CLAPPR_VERSION } from '../../build.js';
-import type { ZeptoResult } from '../../utils/types.js';
+import type { ZeptoResult } from '../../types.js';
 
 import buttonHtml from '../../../assets/playback-rate/button.ejs';
 import listHtml from '../../../assets/playback-rate/list.ejs';
@@ -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

@@ -14,17 +14,17 @@ import {
 import { trace } from '@gcorevideo/utils'
 
 import { CLAPPR_VERSION } from '../../build.js'
-import type { ZeptoResult } from '../../utils/types.js'
+import type { ZeptoResult } from '../../types.js'
 
 import '../../../assets/poster/poster.scss'
 import posterHTML from '../../../assets/poster/poster.ejs'
 import playIcon from '../../../assets/icons/new/play.svg'
 import { PlaybackError } from '../../playback.types.js'
 
-const T = 'plugins.poster_custom'
+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.
@@ -65,7 +65,7 @@ export class Poster extends UIContainerPlugin {
    * @internal
    */
   get name() {
-    return 'poster_custom'
+    return 'poster'
   }
 
   /**

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

@@ -9,12 +9,12 @@ import { CLAPPR_VERSION } from '../../build.js';
 
 import seekTimeHTML from '../../../assets/seek-time/seek-time.html';
 import '../../../assets/seek-time/seek-time.scss';
-import { ZeptoResult } from '../../utils/types.js';
+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,8 @@ import fbIcon from '../../../assets/icons/old/fb.svg';
 import twIcon from '../../../assets/icons/old/twitter.svg';
 
 /**
- * The plugin 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 {
   private hide = false;