@gcorevideo/player 2.20.9 → 2.20.11

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) {

package/src/plugins/favicon/Favicon.ts

@@ -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/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

package/src/plugins/telemetry/Telemetry.ts

@@ -103,7 +103,7 @@ export enum TelemetryEvent {
 }
 
 /**
- * PLUGIN that collects and reports the performance statistics.
+ * `PLUGIN` that collects and reports the performance statistics.
  * @beta
  * @remarks
  * This plugin is experimental and its API is likely to change.

package/src/plugins/thumbnails/Thumbnails.ts

@@ -38,7 +38,7 @@ type Thumb = {
 const T = 'plugins.thumbnails'
 
 /**
- * Displays the thumbnails of the video when available.
+ * `PLUGIN` that displays the thumbnails of the video when available.
  * @beta
  * @example
  * ```ts

package/src/plugins/volume-fade/VolumeFade.ts

@@ -12,7 +12,7 @@ export enum VolumeFadeEvents {
 }
 
 /**
- * Applies fade effect to the player's volume change.
+ * `PLUGIN` that applies fade effect to the player's volume change.
  * @beta
  */
 export class VolumeFade extends UICorePlugin {

package/src/testUtils.ts

@@ -82,7 +82,10 @@ export class _MockPlayback extends Events {
   }
 }
 
-export function createMockCore(options: Record<string, unknown> = {}, container: any = createMockContainer()) {
+export function createMockCore(
+  options: Record<string, unknown> = {},
+  container: any = createMockContainer(),
+) {
   const el = document.createElement('div')
   const emitter = new Events()
   return Object.assign(emitter, {
@@ -90,10 +93,14 @@ export function createMockCore(options: Record<string, unknown> = {}, container:
     $el: $(el),
     activePlayback: container.playback,
     activeContainer: container,
+    i18n: {
+      t: vi.fn().mockImplementation((key: string) => key),
+    },
     options: {
       ...options,
     },
     configure: vi.fn(),
+    getPlaybackType: vi.fn(),
     getPlugin: vi.fn(),
     load: vi.fn(),
     trigger: emitter.emit,
@@ -165,20 +172,37 @@ export function createMockPlayback(name = 'mock') {
 
 export function createMockContainer(playback: any = createMockPlayback()) {
   const el = document.createElement('div')
-  return Object.assign(new Events(), {
-    $el: $(el),
+  const emitter = new Events()
+  return Object.assign(emitter, {
     el,
-    getPlugin: vi.fn(),
     playback,
+    $el: $(el),
+    getDuration: vi.fn().mockReturnValue(0),
+    getPlugin: vi.fn(),
+    isPlaying: vi.fn().mockReturnValue(false),
+    play: vi.fn(),
+    seek: vi.fn(),
+    trigger: emitter.emit,
   })
 }
 
 export function createMockMediaControl(core: any) {
   const mediaControl = new UICorePlugin(core)
+  mediaControl.$el.html(
+    `<div class="media-control-left-panel" data-media-control></div>
+    <div class="media-control-right-panel" data-media-control></div>
+    <div class="media-control-center-panel" data-media-control></div>`,
+  )
   const elements = {
     gear: $(document.createElement('div')),
   }
   // @ts-ignore
   mediaControl.getElement = vi.fn().mockImplementation((name) => elements[name])
+  // @ts-ignore
+  mediaControl.getLeftPanel = vi.fn().mockImplementation(() => mediaControl.$el.find('.media-control-left-panel'))
+  // @ts-ignore
+  mediaControl.getRightPanel = vi.fn().mockImplementation(() => mediaControl.$el.find('.media-control-right-panel'))
+  // @ts-ignore
+  mediaControl.getCenterPanel = vi.fn().mockImplementation(() => mediaControl.$el.find('.media-control-center-panel'))
   return mediaControl
 }

package/src/types.ts

@@ -6,7 +6,7 @@ import { $, Container, Core } from "@clappr/core";
  * @remarks
  * When the MIME type is provided, it helps the player determine the appropriate playback engine.
  * If omitted, the player will attempt to detect the type from the source URL extension.
- * @beta
+ * @public
  */
 export interface PlayerMediaSourceDesc {
   /**
@@ -23,42 +23,36 @@ export interface PlayerMediaSourceDesc {
 
 /**
  * A media source to fetch the media data from
- * @beta
+ * @public
  */
 export type PlayerMediaSource = string | PlayerMediaSourceDesc
 
 /**
  * Debug output category selector
- * @beta
+ * @public
  */
 export type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none'
 
 /**
  * @remarks `true` is equivalent to `'all'`, `false` is equivalent to `'none'`
- * @beta
+ * @public
  */
 export type PlayerDebugSettings = PlayerDebugTag | boolean
 
 /**
- * Type of a stream playback
- * @beta
+ * Type of a stream
+ * @public
  */
 export type PlaybackType = 'live' | 'vod'
 
 /**
- * Media delivery protocol
- * @beta
+ * Preferred streaming media delivery protocol
+ * @public
  */
-export type MediaTransport = 'dash' | 'hls'
+export type TransportPreference = 'dash' | 'hls'
 
 /**
- * Preferred media delivery protocol
- * @beta
- */
-export type TransportPreference = MediaTransport
-
-/**
- * @beta
+ * @public
  * @see {@link https://clappr.github.io/classes/UIContainerPlugin.html},
  * {@link https://clappr.github.io/classes/ContainerPlugin.html}
  */
@@ -67,12 +61,12 @@ export type PlayerPlugin = {
 }
 
 /**
- * @beta
+ * @public
  */
 export type PlayerPluginConstructor = CorePluginConstructor | ContainerPluginConstructor
 
 /**
- * @beta
+ * @public
  */
 export type CorePluginConstructor = {
   new (core: Core): PlayerPlugin
@@ -80,7 +74,7 @@ export type CorePluginConstructor = {
 }
 
 /**
- * @beta
+ * @public
  */
 export type ContainerPluginConstructor = {
   new (container: Container): PlayerPlugin
@@ -126,7 +120,7 @@ export type ContainerPluginConstructor = {
  *   },
  * }
  * ```
- * @beta
+ * @public
  */
 export interface PlayerConfig extends Record<string, unknown> {
   /**
@@ -194,18 +188,18 @@ export interface PlayerConfig extends Record<string, unknown> {
 /**
  * An ISO 639-1 language code.
  * @example `pt`
- * @beta
+ * @public
  */
 export type LangTag = string
 
 /**
- * @beta
+ * @public
  */
 export type TranslationKey = string
 
 /**
  * A plain JS object that must conform to the DASH.js settings schema.
- * @beta
+ * @public
  * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html | DASH.js settings}
  */
 export type DashSettings = Record<string, unknown>
@@ -232,7 +226,7 @@ export type DashSettings = Record<string, unknown>
  * }
  * ```
  *
- * @beta
+ * @public
  */
 export type TranslationSettings = Partial<
   Record<LangTag, Record<TranslationKey, string>>
@@ -240,7 +234,7 @@ export type TranslationSettings = Partial<
 
 /**
  * Dimensions of the player container DOM element.
- * @beta
+ * @public
  */
 export type ContainerSize = {
   width: number
@@ -249,7 +243,7 @@ export type ContainerSize = {
 
 /**
  * A top-level event on the player object
- * @beta
+ * @public
  */
 export enum PlayerEvent {
   /**