@gcorevideo/player 2.22.16 → 2.22.18

package/src/plugins/clappr-nerd-stats/NerdStats.ts

@@ -0,0 +1,503 @@
+import {
+  UICorePlugin,
+  Events,
+  template,
+  Core,
+  Container,
+  Playback,
+} from '@clappr/core'
+import { reportError, trace } from '@gcorevideo/utils'
+import Mousetrap from 'mousetrap'
+import assert from 'assert'
+
+import { CLAPPR_VERSION } from '../../build.js'
+import {
+  ClapprStatsEvents,
+  Metrics as PerfMetrics,
+} from '../clappr-stats/types.js'
+import { newMetrics as newBaseMetrics } from '../clappr-stats/utils.js'
+import Formatter from './formatter.js'
+import {
+  clearSpeedTestResults,
+  configureSpeedTest,
+  drawSpeedTestResults,
+  initSpeedTest,
+  startSpeedtest,
+  stopSpeedtest,
+} from './speedtest/index.js'
+import { SpeedtestMetrics } from './speedtest/types.js'
+import { PlaybackType } from '../../types.js'
+
+import '../../../assets/clappr-nerd-stats/clappr-nerd-stats.scss'
+import pluginHtml from '../../../assets/clappr-nerd-stats/clappr-nerd-stats.ejs'
+import buttonHtml from '../../../assets/clappr-nerd-stats/button.ejs'
+import statsIcon from '../../../assets/icons/new/stats.svg'
+import { BottomGear, GearEvents } from '../bottom-gear/BottomGear.js'
+import { drawSummary, getPingQuality } from './utils.js'
+import { getDownloadQuality } from './utils.js'
+
+const PLAYBACK_NAMES: Record<string, string> = {
+  dash: 'DASH.js',
+  hls: 'HLS.js',
+  html5_video: 'Native',
+}
+
+type IconPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+
+type Metrics = PerfMetrics & {
+  general: {
+    displayResolution?: string
+    resolution: {
+      width: number
+      height: number
+    }
+    volume: number
+  }
+  custom: SpeedtestMetrics & {
+    vodQuality?: string
+    liveQuality?: string
+  }
+}
+
+const T = 'plugins.nerd_stats'
+
+/**
+ * `PLUGIN` that displays useful network-related statistics.
+ * @beta
+ *
+ * @remarks
+ * Depends on:
+ *
+ * - {@link BottomGear}
+ *
+ * - {@link ClapprStats}
+ *
+ * The plugin is rendered as an item in the gear menu.
+ *
+ * When clicked, it shows an overlay window with the information about the network speed, latency, etc,
+ * and recommended quality level.
+ */
+export class NerdStats extends UICorePlugin {
+  private container: Container | null = null
+
+  private speedtestMetrics: SpeedtestMetrics = {
+    connectionSpeed: 0,
+    ping: 0,
+    jitter: 0,
+  }
+
+  private metrics: Metrics = newMetrics()
+
+  private open = false
+
+  private shortcut: string[]
+
+  private iconPosition: IconPosition
+
+  private static readonly buttonTemplate = template(buttonHtml)
+
+  /**
+   * @internal
+   */
+  get name() {
+    return 'nerd_stats'
+  }
+
+  /**
+   * @internal
+   */
+  get supportedVersion() {
+    return { min: CLAPPR_VERSION }
+  }
+
+  private static readonly template = template(pluginHtml)
+
+  /**
+   * @internal
+   */
+  override get attributes() {
+    return {
+      class: 'clappr-nerd-stats',
+    }
+  }
+
+  /**
+   * @internal
+   */
+  override get events() {
+    return {
+      click: 'clicked',
+      'click #nerd-stats-close': 'hide',
+      'click #nerd-stats-refresh': 'refreshSpeedTest',
+    }
+  }
+
+  private clicked(e: MouseEvent) {
+    e.stopPropagation()
+    e.preventDefault()
+  }
+
+  private get statsBoxElem() {
+    return this.$el.find('#nerd-stats-box')
+  }
+
+  private get statsBoxWidthThreshold() {
+    return 720
+  }
+
+  private get playerWidth() {
+    return this.core.$el.width()
+  }
+
+  private get playerHeight() {
+    return this.core.$el.height()
+  }
+
+  constructor(core: Core) {
+    super(core)
+    this.shortcut = core.options.clapprNerdStats?.shortcut ?? [
+      'command+shift+s',
+      'ctrl+shift+s',
+    ]
+    this.iconPosition =
+      core.options.clapprNerdStats?.iconPosition ?? 'bottom-right'
+    this.speedtestMetrics = {
+      connectionSpeed: 0,
+      ping: 0,
+      jitter: 0,
+    }
+    configureSpeedTest(core.options.clapprNerdStats?.speedTestServers ?? [])
+  }
+
+  /**
+   * @internal
+   */
+  override bindEvents() {
+    this.listenToOnce(this.core, Events.CORE_READY, this.onCoreReady)
+    this.listenTo(this.core, Events.CORE_RESIZE, this.onPlayerResize)
+    this.listenTo(
+      this.core,
+      Events.CORE_ACTIVE_CONTAINER_CHANGED,
+      this.onActiveContainerChanged,
+    )
+  }
+
+  private onCoreReady() {
+    const bottomGear = this.core.getPlugin('bottom_gear') as BottomGear
+    assert(bottomGear, 'bottom_gear plugin is required')
+    this.listenTo(bottomGear, GearEvents.RENDERED, this.attach)
+
+    Mousetrap.bind(this.shortcut, this.toggle)
+    this.updateResolution()
+  }
+
+  private onActiveContainerChanged() {
+    this.container = this.core.activeContainer
+    const clapprStats = this.container?.getPlugin('clappr_stats')
+    assert(
+      clapprStats,
+      'clappr-stats not available. Please, include it as a plugin of your Clappr instance.\n' +
+        'For more info, visit: https://github.com/clappr/clappr-stats.',
+    )
+    this.listenTo(clapprStats, ClapprStatsEvents.REPORT, this.updateMetrics)
+    this.listenTo(this.core.activeContainer, Events.CONTAINER_VOLUME, () => {
+      this.metrics.general.volume = this.container?.volume ?? 0
+      this.$el
+        .find('#nerd-stats-volume')
+        .text(Formatter.formatVolume(this.metrics.general.volume))
+    })
+    this.listenTo(
+      this.core.activePlayback,
+      Events.PLAYBACK_LOADEDMETADATA,
+      () => {
+        this.$el
+          .find('#nerd-stats-playback-type')
+          .text(
+            this.formatPlaybackName(this.core.activePlayback.getPlaybackType()),
+          )
+      },
+    )
+    this.updateMetrics(clapprStats.exportMetrics())
+    this.$el
+      .find('#nerd-stats-playback-name')
+      .text(PLAYBACK_NAMES[this.core.activePlayback.name] ?? '-')
+    this.core.activeContainer.$el.append(this.$el)
+  }
+
+  /**
+   * @internal
+   */
+  override destroy() {
+    Mousetrap.unbind(this.shortcut)
+    return super.destroy()
+  }
+
+  private toggle = () => {
+    if (this.open) {
+      this.hide()
+    } else {
+      this.show()
+    }
+  }
+
+  private show() {
+    this.$el.show()
+    this.statsBoxElem.scrollTop(this.statsBoxElem.scrollTop())
+    this.open = true
+
+    this.refreshSpeedTest()
+    initSpeedTest(this.speedtestMetrics)
+      .then(() => {
+        startSpeedtest()
+      })
+      .catch((e) => {
+        reportError(e)
+        this.disable()
+      })
+  }
+
+  private hide() {
+    this.$el.hide()
+    this.open = false
+    stopSpeedtest()
+  }
+
+  private onPlayerResize() {
+    this.setStatsBoxSize()
+    this.updateResolution()
+  }
+
+  private updateResolution() {
+    this.metrics.general.resolution = {
+      width: this.playerWidth,
+      height: this.playerHeight,
+    }
+    this.$el
+      .find('#nerd-stats-resolution-width')
+      .text(this.metrics.general.resolution.width)
+    this.$el
+      .find('#nerd-stats-resolution-height')
+      .text(this.metrics.general.resolution.height)
+  }
+
+  private estimateQuality() {
+    trace(`${T} estimateQuality`)
+    const videoQualityNames = [
+      'SD (480p)',
+      'HD (720p)',
+      'Full HD (1080p)',
+      '2K (1440p)',
+      '4K (2160p)',
+    ]
+    const { connectionSpeed, ping } = this.speedtestMetrics
+
+    if (!connectionSpeed || !ping) {
+      const calculatingText = this.core.i18n.t('stats.calculating')
+      this.metrics.custom.vodQuality = calculatingText
+      this.metrics.custom.liveQuality = calculatingText
+      return
+    }
+
+    const downloadQuality = getDownloadQuality(connectionSpeed)
+    const pingQuality = getPingQuality(ping)
+    const liveQuality = Math.min(downloadQuality, pingQuality)
+
+    const prefix = 'Optimal for '
+
+    this.metrics.custom.vodQuality =
+      prefix + videoQualityNames[downloadQuality - 1]
+    this.metrics.custom.liveQuality =
+      prefix + videoQualityNames[liveQuality - 1]
+  }
+
+  private updateMetrics(metrics: PerfMetrics) {
+    trace(`${T} updateMetrics`, { custom: this.speedtestMetrics })
+    Object.assign(this.metrics, metrics)
+    this.updateEstimatedQuality()
+
+    this.$el
+      .find('#nerd-stats-current-time')
+      .text(Formatter.formatTime(this.metrics.extra.currentTime))
+    this.$el
+      .find('#nerd-stats-video-duration')
+      .text(Formatter.formatTime(this.metrics.extra.duration))
+    this.$el
+      .find('#nerd-stats-buffer-size')
+      .text(Formatter.formatTime(this.metrics.extra.buffersize))
+
+    this.$el
+      .find('#nerd-stats-bitrate-weighted-mean')
+      .text(Formatter.formatBitrate(this.metrics.extra.bitrateWeightedMean))
+    this.$el
+      .find('#nerd-stats-bitrate-most-used')
+      .text(Formatter.formatBitrate(this.metrics.extra.bitrateMostUsed))
+    this.$el
+      .find('#nerd-stats-watched-percentage')
+      .text(Formatter.formatPercentage(this.metrics.extra.watchedPercentage))
+    this.$el
+      .find('#nerd-stats-buffering-percentage')
+      .text(Formatter.formatPercentage(this.metrics.extra.bufferingPercentage))
+
+    this.$el
+      .find('#nerd-stats-startup-time')
+      .text(Formatter.formatTime(this.metrics.chrono.startup))
+    this.$el
+      .find('#nerd-stats-watch-time')
+      .text(Formatter.formatTime(this.metrics.chrono.watch))
+    this.$el
+      .find('#nerd-stats-pause-time')
+      .text(Formatter.formatTime(this.metrics.chrono.pause))
+    this.$el
+      .find('#nerd-stats-buffering-time')
+      .text(Formatter.formatTime(this.metrics.chrono.buffering))
+    this.$el
+      .find('#nerd-stats-session-time')
+      .text(Formatter.formatTime(this.metrics.chrono.session))
+
+    this.$el.find('#nerd-stats-plays').text(this.metrics.counters.play)
+    this.$el.find('#nerd-stats-pauses').text(this.metrics.counters.pause)
+    this.$el.find('#nerd-stats-errors').text(this.metrics.counters.error)
+    this.$el
+      .find('#nerd-stats-bufferings')
+      .text(this.metrics.counters.buffering)
+    this.$el
+      .find('#nerd-stats-decoded-frames')
+      .text(this.metrics.counters.decodedFrames)
+    this.$el
+      .find('#nerd-stats-dropped-frames')
+      .text(this.metrics.counters.droppedFrames)
+
+    this.$el
+      .find('#nerd-stats-bitrate-changes')
+      .text(this.metrics.counters.changeLevel)
+    this.$el.find('#nerd-stats-seeks').text(this.metrics.counters.seek)
+    this.$el
+      .find('#nerd-stats-fullscreen')
+      .text(this.metrics.counters.fullscreen)
+    this.$el.find('#nerd-stats-dvr-usage').text(this.metrics.counters.dvrUsage)
+
+    this.$el
+      .find('#nerd-stats-fps')
+      .text(Formatter.formatFps(this.metrics.counters.fps))
+
+    this.setStatsBoxSize()
+    drawSpeedTestResults()
+    drawSummary(
+      this.speedtestMetrics,
+      this.$el.find('#nerd-stats-quality-vod'),
+      this.$el.find('#nerd-stats-quality-live'),
+    )
+
+    if (!this.open) {
+      this.hide()
+    }
+  }
+
+  private updateEstimatedQuality() {
+    this.estimateQuality()
+    this.$el
+      .find('#nerd-stats-quality-vod-text')
+      .html(this.metrics.custom.vodQuality)
+    this.$el
+      .find('#nerd-stats-quality-live-text')
+      .html(this.metrics.custom.liveQuality)
+  }
+
+  private setStatsBoxSize() {
+    if (this.playerWidth >= this.statsBoxWidthThreshold) {
+      this.statsBoxElem.addClass('wide')
+      this.statsBoxElem.removeClass('narrow')
+    } else {
+      this.statsBoxElem.removeClass('wide')
+      this.statsBoxElem.addClass('narrow')
+    }
+  }
+
+  /**
+   * @internal
+   */
+  override render() {
+    this.$el
+      .html(
+        NerdStats.template({
+          metrics: Formatter.format(this.metrics ?? newMetrics()),
+          iconPosition: this.iconPosition,
+          i18n: this.core.i18n,
+        }),
+      )
+      .hide()
+
+    return this
+  }
+
+  private attach() {
+    trace(`${T} attach`)
+    const gear = this.core.getPlugin('bottom_gear') as BottomGear
+    gear
+      .addItem('nerd_stats')
+      .html(
+        NerdStats.buttonTemplate({
+          icon: statsIcon,
+          i18n: this.core.i18n,
+        }),
+      )
+      .on('click', (e: MouseEvent) => {
+        e.stopPropagation()
+        this.toggle()
+      })
+  }
+
+  private clearSpeedtestMetrics() {
+    const clapprStats = this.container?.getPlugin('clappr_stats')
+
+    this.speedtestMetrics.connectionSpeed = 0
+    this.speedtestMetrics.ping = 0
+    this.speedtestMetrics.jitter = 0
+
+    if (clapprStats) {
+      this.updateMetrics(clapprStats.exportMetrics())
+    }
+  }
+
+  private refreshSpeedTest() {
+    stopSpeedtest()
+    setTimeout(() => {
+      this.clearSpeedtestMetrics()
+      clearSpeedTestResults()
+      drawSpeedTestResults()
+    }, 200)
+    setTimeout(() => {
+      startSpeedtest()
+    }, 800)
+  }
+
+  private formatPlaybackName(playbackType: PlaybackType): string {
+    switch (playbackType) {
+      case Playback.VOD:
+        return this.core.i18n.t('vod')
+      case Playback.LIVE:
+        return this.core.i18n.t('live')
+      default:
+        return '-'
+    }
+  }
+}
+
+function newMetrics(): Metrics {
+  return {
+    ...newBaseMetrics(),
+    general: {
+      displayResolution: '',
+      resolution: {
+        width: 0,
+        height: 0,
+      },
+      volume: 0,
+    },
+    custom: {
+      connectionSpeed: 0,
+      ping: 0,
+      jitter: 0,
+    },
+  }
+}

package/src/plugins/clappr-nerd-stats/formatter.ts

@@ -1,109 +1,153 @@
-import humanFormat, { ScaleLike } from 'human-format';
-import type { MetricsKind, MetricsType } from './types';
+import humanFormat, { ScaleLike } from 'human-format'
+import type { MetricName, MetricsKind, MetricsType } from './types'
 
 const timeScale = new humanFormat.Scale({
   ms: 1,
   sec: 1000,
   min: 60000,
-  hours: 3600000
-});
+  hours: 3600000,
+})
 
 const percentScale = new humanFormat.Scale({
-  '%': 1
-});
+  '%': 1,
+})
 
 type FormatParams = {
-  scale?: ScaleLike;
-  unit?: 'bps';
-  decimals?: number;
+  scale?: ScaleLike
+  unit?: 'bps'
+  decimals?: number
 }
 
-const formattingTemplate: Record<MetricsKind, Partial<Record<MetricsType, FormatParams>>> = {
+const metricTemplates: Partial<Record<MetricName, FormatParams>> = {
+  fps: {
+    scale: 'SI',
+    decimals: 0,
+  },
+  volume: {
+    scale: percentScale,
+  },
+}
+
+const formattingTemplate: Record<
+  MetricsKind,
+  Partial<Record<MetricsType, FormatParams>>
+> = {
   general: {
     volume: {
-      scale: percentScale
-    }
+      scale: percentScale,
+    },
   },
   timers: {
     startup: {
-      scale: timeScale
+      scale: timeScale,
     },
     watch: {
-      scale: timeScale
+      scale: timeScale,
     },
     pause: {
-      scale: timeScale
+      scale: timeScale,
     },
     buffering: {
-      scale: timeScale
+      scale: timeScale,
     },
     session: {
-      scale: timeScale
+      scale: timeScale,
     },
     latency: {
-      scale: timeScale
-    }
+      scale: timeScale,
+    },
   },
   extra: {
     buffersize: {
-      scale: timeScale
+      scale: timeScale,
     },
     duration: {
-      scale: timeScale
+      scale: timeScale,
     },
     currentTime: {
-      scale: timeScale
+      scale: timeScale,
     },
     bitrateWeightedMean: {
-      unit: 'bps'
+      unit: 'bps',
     },
     bitrateMostUsed: {
-      unit: 'bps'
+      unit: 'bps',
     },
     bandwidth: {
-      unit: 'bps'
+      unit: 'bps',
     },
     watchedPercentage: {
-      scale: percentScale
+      scale: percentScale,
     },
     bufferingPercentage: {
-      scale: percentScale
-    }
-  }
-};
+      scale: percentScale,
+    },
+  },
+}
 
-type MetricsValue = number | string;
-type Metrics = Partial<Record<MetricsKind, Partial<Record<MetricsType, MetricsValue>>>>;
+type MetricsValue = number | string
+type Metrics = Partial<
+  Record<MetricsKind, Partial<Record<MetricsType, MetricsValue>>>
+>
 
 export default class Formatter {
   static format(metrics: Metrics): Metrics {
-    const formattedMetrics: Metrics = {};
+    const formattedMetrics: Metrics = {}
 
     Object.entries(metrics).forEach(([type, mm]) => {
-      const fmt: Partial<Record<MetricsType, MetricsValue>> = {};
-      formattedMetrics[type as MetricsKind] = fmt;
-      const typeTemplate = formattingTemplate[type as MetricsKind];
+      const fmt: Partial<Record<MetricsType, MetricsValue>> = {}
+      formattedMetrics[type as MetricsKind] = fmt
+      const typeTemplate = formattingTemplate[type as MetricsKind]
 
       Object.entries(mm).forEach(([name, value]) => {
-        // const value = mm[name];
-
-        if (typeTemplate && typeTemplate[name as MetricsType] && (typeof value === 'number') && !isNaN(value)) {
+        if (
+          typeTemplate &&
+          typeTemplate[name as MetricsType] &&
+          typeof value === 'number' &&
+          !isNaN(value)
+        ) {
           // @ts-ignore
-          const templateScale = typeTemplate[name as MetricsType].scale || 'SI';
+          const templateScale = typeTemplate[name as MetricsType].scale || 'SI'
           // @ts-ignore
-          const templateUnit = typeTemplate[name as MetricsType].unit || '';
+          const templateUnit = typeTemplate[name as MetricsType].unit || ''
 
           fmt[name as MetricsType] = humanFormat(value, {
             scale: templateScale,
             unit: templateUnit,
-            decimals: 2
-          });
+            decimals: 2,
+          })
         } else {
-          fmt[name as MetricsType] = value;
+          fmt[name as MetricsType] = value
         }
-      });
-    });
+      })
+    })
+
+    return formattedMetrics
+  }
+
+  static formatVolume(volume: number): string {
+    return humanFormat(volume, metricTemplates.volume)
+  }
+
+  static formatTime(time: number): string {
+    return humanFormat(time, {
+      scale: timeScale,
+    })
+  }
+
+  static formatFps(fps: number): string {
+    return humanFormat(fps, metricTemplates.fps)
+  }
+
+  static formatPercentage(percentage: number): string {
+    return humanFormat(percentage, {
+      scale: percentScale,
+    })
+  }
 
-    return formattedMetrics;
+  static formatBitrate(bitrate: number): string {
+    return humanFormat(bitrate, {
+      unit: 'bps',
+    })
   }
 }

package/src/plugins/clappr-nerd-stats/speedtest/index.ts

@@ -1,5 +1,5 @@
 import { type Server, type TestStatusInfo, Speedtest } from './Speedtest.js';
-import { CustomMetrics } from './types.js';
+import { SpeedtestMetrics } from './types.js';
 
 const DIGITS_THRESHOLD = 99999;
 const DEFAULT_DOWNLOAD_SPEED = '0.00';
@@ -59,7 +59,7 @@ export function drawSpeedTestResults() {
 
 let inited: Promise<void> | null = null;
 
-export const initSpeedTest = (customMetrics: CustomMetrics): Promise<void> => {
+export const initSpeedTest = (customMetrics: SpeedtestMetrics): Promise<void> => {
   if (inited !== null) {
     return inited;
   }