@gumlet/insights-js-core 1.0.3 → 1.1.0

package/js/adapters/HTML5Adapter.js

@@ -0,0 +1,774 @@
+import Events from '../enums/Events';
+import {getMIMETypeFromFileExtension} from '../enums/MIMETypes';
+import {getStreamTypeFromMIMEType} from '../enums/StreamTypes';
+import {Players} from '../enums/Players';
+
+const BUFFERING_TIMECHANGED_TIMEOUT = 1000;
+
+/**
+ * @typedef QualityLevelInfo
+ * @type {Object}
+ * @prop {bitrate} number
+ * @prop {width} number
+ * @prop {height} number
+ */
+
+/**
+ * Base-class for all HTML5 media based playback engines
+ * @class
+ * @constructor
+ */
+export class HTML5Adapter {
+
+  /**
+   * @constructs
+   * @param {HTMLMediaElement} mediaElement
+   * @param {function} eventCallback
+   * @param {AnalyticsStateMachine} stateMachine
+   */
+  constructor(mediaElement, eventCallback, stateMachine, playerName = null) {
+    /**
+     * @public
+     * @member {AnalyticsEventCallback}
+     */
+    this.eventCallback = eventCallback;
+
+    if (playerName) {
+      this.playerSoftwareName = playerName;
+    }else {
+      this.playerSoftwareName = Players.HTML;
+    }
+
+    /**
+     * @member {AnalyticsStateMachine}
+     */
+    this.stateMachine = stateMachine;
+
+    /**
+     * @public
+     * @member {HTMLMediaElement}
+     */
+    this.mediaEl = mediaElement;
+
+    /**
+     * @public
+     * @member {function[]}
+     */
+    this.mediaElEventHandlers = [];
+
+    /**
+     * @private
+     * @member {number}
+     */
+    this.analyticsBitrate_ = -1;
+
+    /**
+     * @private
+     * @member {string}
+     */
+     this.audioCodec_ = "";
+    
+    /**
+     * @private
+     * @member {string}
+     */
+    this.videoCodec_ = "";
+
+    /**
+     * @private
+     * @member {number}
+     */
+    this.bufferingTimeout_ = null;
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.isBuffering_ = false;
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.isLive_ = false;
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.isPaused_ = false;
+
+    /**
+     * @private
+     * @member {number}
+     */
+    this.previousMediaTime_ = null;
+
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.needsReadyEvent_ = true;
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.needsFirstPlayIntent_ = true;
+
+    /**
+     * @private
+     * @member {boolean}
+     */
+    this.mediaElementSet_ = false;
+    this.playbackReadySet_ = false;
+
+    if (mediaElement) {
+      this.setMediaElement();
+    }
+
+
+  }
+
+  /**
+   * Used to setup against the media element.
+   * We need this method to desynchronize construction of this class
+   * and the actual initialization against the media element.
+   * That is because at construction some media engine
+   * may not already have the media element attached, for example
+   * when passing in the DOM element is happening at once with passing the source URL
+   * and can not be decoupled.
+   * We are then awaiting an event from the engine and calling this with the media element
+   * as argument from our sub-class.
+   *
+   * This method can also be called without arguments and then it will perform
+   * initialization against the existing media element (should only be called once, will throw an error otherwise)
+   *
+   * It can also be used to replace the element.
+   *
+   *
+   * @param {HTMLMediaElement} mediaElement
+   */
+  setMediaElement(mediaElement = null) {
+    // replace previously existing, if calld with args
+    if (mediaElement && this.mediaEl) {
+      this.unregisterMediaElement();
+      this.mediaElementSet_ = false;
+    }
+
+    // if called without args we assume it's already there
+    // we can also be called with args but without any being there before
+    if (mediaElement) {
+      this.mediaEl = mediaElement;
+    }
+
+    if (!this.mediaEl) {
+      throw new Error('No media element owned');
+    }
+
+    if (this.mediaElementSet_) {
+      throw new Error('Media element already set (only call this once)');
+    }
+    this.mediaElementSet_ = true;
+
+    this.registerMediaElement();
+    this.onMaybeReady();
+  }
+
+  /**
+   * Implemented by sub-class to deliver current quality-level info
+   * specific to media-engine.
+   * @returns {QualityLevelInfo}
+   * @abstract
+   */
+  getCurrentQualityLevelInfo() {
+    return null;
+  }
+
+  /**
+   * @abstract
+   * @returns {boolean}
+   */
+  isLive() {
+    return false;
+  }
+
+  /**
+   * Can be overriden by sub-classes
+   * @returns {string}
+   */
+  getMIMEType() {
+    const mediaEl = this.mediaEl;
+    let streamURL = "";
+    if (!mediaEl) {
+      streamURL = null;
+    }
+    if (mediaEl && mediaEl.src) {
+      streamURL = mediaEl.src
+    }else if(mediaEl && mediaEl.querySelector('source') && mediaEl.querySelector('source').src){
+      streamURL = mediaEl.querySelector('source').src;
+    }else{
+      streamURL = null;
+    }
+    return getMIMETypeFromFileExtension(streamURL);
+  }
+
+  /**
+   * Can be overriden by sub-classes
+   * @returns {string}
+   */
+  getStreamType() {
+    return getStreamTypeFromMIMEType(this.getMIMEType());
+  }
+
+  /**
+   * @abstract
+   * @returns {string}
+   */
+  getPlayerVersion() {
+    return null;
+  }
+
+  /**
+   * Can be overriden by subclasses.
+   * @returns {string}
+   */
+  getStreamURL() {
+    const mediaEl = this.mediaEl;
+    
+    if (!mediaEl) {
+      return null;
+    }
+    if (mediaEl && mediaEl.src) {
+      return mediaEl.src
+    }else if(mediaEl && mediaEl.querySelector('source') && mediaEl.querySelector('source').src){
+      return mediaEl.querySelector('source').src;
+    }else{
+      return null;
+    }
+  }
+
+  resetMedia() {
+    this.mediaEl = null;
+    this.mediaElEventHandlers = [];
+  }
+
+  registerMediaElement() {
+
+    const mediaEl = this.mediaEl;
+    if (!mediaEl) {
+      return;
+    }
+
+    this.listenToMediaElementEvent('loadedmetadata', () => {
+
+      // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState
+      // HAVE_NOTHING 0 No information is available about the media resource.
+      // HAVE_METADATA 1 Enough of the media resource has been retrieved that
+      // the metadata attributes are initialized. Seeking will no longer raise an exception.
+      // HAVE_CURRENT_DATA 2 Data is available for the current playback position,
+      // but not enough to actually play more than one frame.
+      // HAVE_FUTURE_DATA  3 Data for the current playback position as well as for
+      //  at least a little bit of time into the future is available
+      // (in other words, at least two frames of video, for example).
+      // HAVE_ENOUGH_DATA  4 Enough data is available—and the download rate is high
+      // enough—that the media can be played through to the end without interruption.
+      if (mediaEl.readyState !== 1) {
+        // we can't really gather any more information at this point
+        return;
+      }
+
+      // silent
+      this.checkQualityLevelAttributes(true);
+
+      const {
+        duration,
+        autoplay,
+        videoWidth,
+        videoHeight,
+        muted
+      } = mediaEl;
+
+      const width = mediaEl.clientWidth;
+      const height = mediaEl.clientHeight;
+
+      // This is redundant with what we give to updateMetadata method.
+      // Not sure if there are good reasons to keep that so or if we should better centralize.
+      const info       = {
+        type       : 'html5',
+        isLive     : this.isLive(),
+        version    : this.getPlayerVersion() || 'html5',
+        streamType : this.getStreamType(),
+        streamUrl  : this.getStreamURL(),
+        duration,
+        autoplay,
+        // HTMLVideoElement.width and HTMLVideoElement.height
+        // is a DOMString that reflects the height HTML attribute,
+        // which specifies the height of the display area, in CSS pixels.
+        // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement
+        currentVideoData:{
+          height     : videoHeight,
+          width      : videoWidth,
+          bitrate    : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        // Returns an unsigned long containing the intrinsic
+        // height of the resource in CSS pixels,
+        // taking into account the dimensions, aspect ratio,
+        // clean aperture, resolution, and so forth,
+        // as defined for the format used by the resource.
+        // If the element's ready state is HAVE_NOTHING, the value is 0.
+        // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement
+        videoWindowWidth : parseInt(width),
+        videoWindowHeight: parseInt(height),
+        muted
+      };
+
+      // silence events if we have not yet intended play
+      if (this.needsFirstPlayIntent_) {
+        return;
+      }
+
+      this.eventCallback(Events.METADATA_LOADED, info);
+    });
+
+    // For DashJS this is written in DashjsAdapter.js as it overrides
+    this.listenToMediaElementEvent('canplay', () => {
+
+      if (this.playbackReadySet_) {
+        return;
+      }else {
+        this.playbackReadySet_ = true;
+      }
+
+      const {
+        duration,
+        autoplay,
+        videoWidth,
+        videoHeight,
+        muted
+      } = mediaEl;
+
+      const width = mediaEl.clientWidth;
+      const height = mediaEl.clientHeight;
+
+      const info       = {
+        type            : 'html5',
+        isLive          : this.isLive(),
+        version         : this.getPlayerVersion() || 'html5',
+        streamType      : this.getStreamType(),
+        streamUrl       : this.getStreamURL(),
+        duration        : duration,
+        autoplay        : autoplay,
+        playerSoftware  : this.playerSoftwareName,
+        videoWindowWidth : parseInt(width),
+        videoWindowHeight: parseInt(height),
+        currentVideoData:{
+          height     : videoHeight,
+          width      : videoWidth,
+          bitrate    : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        muted
+      };
+
+      this.eventCallback(Events.SOURCE_LOADED, info);
+    });
+
+    // We need the PLAY event to indicate the intent to play
+    // NOTE: use TIMECHANGED event on 'playing' and trigger PLAY as intended in states.dot graph
+
+    this.listenToMediaElementEvent('play', () => {
+      const { currentTime, videoWidth, videoHeight,} = mediaEl;
+
+      this.needsFirstPlayIntent_ = false;
+
+      this.eventCallback(Events.PLAY, {
+        currentVideoData:{
+          height  : videoHeight,
+          width   : videoWidth,
+          bitrate : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        currentTime
+      });
+    });
+
+    this.listenToMediaElementEvent('pause', () => {
+      this.onPaused();
+    });
+
+    this.listenToMediaElementEvent('playing', () => {
+      const {currentTime, videoWidth, videoHeight} = mediaEl;
+
+      this.isPaused_ = false;
+
+      // silence events if we have not yet intended play
+      if (this.needsFirstPlayIntent_) {
+        return;
+      }
+
+      this.eventCallback(Events.TIMECHANGED, {
+        currentVideoData:{
+          height  : videoHeight,
+          width   : videoWidth,
+          bitrate : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        currentTime
+      });
+    });
+
+    this.listenToMediaElementEvent('error', () => {
+      const {currentTime, error} = mediaEl;
+
+      this.eventCallback(Events.ERROR, {
+        currentTime,
+        // See https://developer.mozilla.org/en-US/docs/Web/API/MediaError
+        code       : error.code,
+        message    : error.message
+      });
+    });
+
+    this.listenToMediaElementEvent('volumechange', () => {
+      const {muted, currentTime} = mediaEl;
+
+      if (muted) {
+        this.eventCallback(Events.MUTE, {
+          currentTime
+        });
+      } else {
+        this.eventCallback(Events.UN_MUTE, {
+          currentTime
+        });
+      }
+    });
+
+    this.listenToMediaElementEvent('seeking', () => {
+      const {currentTime, videoWidth, videoHeight} = mediaEl;
+
+      this.eventCallback(Events.SEEK, {
+        currentVideoData:{
+          height  : videoHeight,
+          width   : videoWidth,
+          bitrate : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        currentTime,
+        droppedFrames: 0
+      });
+    });
+
+    this.listenToMediaElementEvent('seeked', () => {
+      const {currentTime, videoWidth, videoHeight} = mediaEl;
+
+      if (this.bufferingTimeout_) {
+        clearTimeout(this.bufferingTimeout_);
+      }
+
+      this.eventCallback(Events.SEEKED, {
+        currentVideoData:{
+          height  : videoHeight,
+          width   : videoWidth,
+          bitrate : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        currentTime,
+        droppedFrames: 0
+      });
+    });
+
+    this.listenToMediaElementEvent('ended', () => {
+      const {currentTime, videoWidth, videoHeight} = mediaEl;
+
+      this.eventCallback(Events.END, {
+        currentVideoData:{
+          height  : videoHeight,
+          width   : videoWidth,
+          bitrate : this.analyticsBitrate_,
+          audioCodec : this.audioCodec_,
+          videoCodec : this.videoCodec_,
+        },
+        currentTime
+      });
+    });
+
+    this.listenToMediaElementEvent('timeupdate', () => {
+
+      const {currentTime, videoHeight, videoWidth} = mediaEl;
+
+      this.isBuffering_ = false;
+
+      // silence events if we have not yet intended play
+      if (this.needsFirstPlayIntent_) {
+        return;
+      }
+
+      if (!this.isPaused_) {
+        this.eventCallback(Events.TIMECHANGED, {
+          currentVideoData:{
+            height  : videoHeight,
+            width   : videoWidth,
+            bitrate : this.analyticsBitrate_,
+            audioCodec : this.audioCodec_,
+            videoCodec : this.videoCodec_,
+          },
+          currentTime
+        });
+      }
+
+      this.checkQualityLevelAttributes();
+
+      // We are doing this in case we can not rely
+      // on the "stalled" or "waiting" events in a specific browser
+      // and to detect intrinsinc paused states (when we do not get a paused event)
+      // but the player is paused already before attach or is paused from initialization on.
+      this.checkPlayheadProgress();
+
+      this.previousMediaTime_ = currentTime;
+    });
+
+    // The stalled event is fired when the user agent is trying to fetch media data,
+    // but data is unexpectedly not forthcoming.
+    // https://developer.mozilla.org/en-US/docs/Web/Events/stalled
+    this.listenToMediaElementEvent('stalled', () => {
+
+      // this event doesn't indicate buffering by definition (interupted playback),
+      // only that data throughput to playout buffers is not as high as expected
+      // It happens on Chrome every once in a while as SourceBuffer's are not fed
+      // as fast as the underlying native player may prefer (but it does not lead to
+      // interuption).
+    });
+
+    // The waiting event is fired when playback has stopped because of a temporary lack of data.
+    // See https://developer.mozilla.org/en-US/docs/Web/Events/waiting
+    this.listenToMediaElementEvent('waiting', () => {
+
+      this.onBuffering();
+    });
+
+  }
+
+  /**
+   * Should only be calld when a mediaEl is attached
+   */
+  listenToMediaElementEvent(event, handler) {
+    if (!this.mediaEl) {
+      throw new Error('No media attached');
+    }
+    const boundHandler = handler.bind(this);
+
+    this.mediaElEventHandlers.push(boundHandler);
+    this.mediaEl.addEventListener(event, boundHandler, false);
+  }
+
+  onMaybeReady() {
+
+    if (!this.needsReadyEvent_ || !this.mediaEl) {
+      return;
+    }
+
+    this.needsReadyEvent_ = false;
+
+    let playerPreload = false;
+    const {
+      duration,
+      autoplay,
+      videoWidth,
+      videoHeight,
+      muted,
+      preload
+    } = this.mediaEl;
+    
+    let streamURL = "";
+
+    if (this.mediaEl && this.mediaEl.src) {
+      streamURL = this.mediaEl.src
+    }else if(this.mediaEl && this.mediaEl.querySelector('source') && this.mediaEl.querySelector('source').src){
+      streamURL = this.mediaEl.querySelector('source').src;
+    }else{
+      streamURL = null;
+    }
+    const width = this.mediaEl.clientWidth;
+    const height = this.mediaEl.clientHeight;
+
+    if (preload !== 'none') {
+      playerPreload = true;
+    }
+
+    const info       = {
+      type            : 'html5',
+      isLive          : this.isLive(),
+      version         : this.getPlayerVersion() || 'html5',
+      streamType      : this.getStreamType(),
+      streamUrl       : this.getStreamURL(),
+      duration        : duration,
+      autoplay        : autoplay,
+      preload         : playerPreload,
+      playerSoftware  : this.playerSoftwareName,
+      currentVideoData:{
+        height        : videoHeight,
+        width         : videoWidth,
+        bitrate       : this.analyticsBitrate_,
+        audioCodec    : this.audioCodec_,
+        videoCodec    : this.videoCodec_,
+      },
+      // HTMLVideoElement.width and HTMLVideoElement.height
+      // is a DOMString that reflects the height HTML attribute,
+      // which specifies the height of the display area, in CSS pixels.
+      // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement
+      // width      : parseInt(width),
+      // height     : parseInt(height),
+
+
+      // Returns an unsigned long containing the intrinsic
+      // height of the resource in CSS pixels,
+      // taking into account the dimensions, aspect ratio,
+      // clean aperture, resolution, and so forth,
+      // as defined for the format used by the resource.
+      // If the element's ready state is HAVE_NOTHING, the value is 0.
+      // See https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement
+      videoWindowWidth : parseInt(width),
+      videoWindowHeight: parseInt(height),
+      muted
+    };
+
+    this.stateMachine.updateMetadata(info);
+    this.eventCallback(Events.READY, info);
+  }
+
+  /**
+   * Should only be calld when a mediaEl is attached
+   */
+  unregisterMediaElement() {
+    if (!this.mediaEl) {
+      throw new Error('No media attached');
+    }
+
+    this.mediaElEventHandlers.forEach((handler) => {
+      this.mediaEl.removeEventListener(handler);
+    });
+
+    this.resetMedia();
+  }
+
+  onBuffering() {
+    const {currentTime} = this.mediaEl;
+
+    // this handler may be called multiple times
+    // for one actual buffering-event occuring so lets guard from
+    // triggering this event redundantly.
+    if (this.isBuffering_ || this.isPaused_) {
+      return;
+    }
+
+    this.eventCallback(Events.START_BUFFERING, {
+      currentTime
+    });
+
+    this.isBuffering_ = true;
+  }
+
+  onPaused() {
+    if (this.isPaused_) {
+      return;
+    }
+
+    const {currentTime, videoHeight, videoWidth} = this.mediaEl;
+
+    this.eventCallback(Events.PAUSE, {
+      currentVideoData:{
+        height     : videoHeight,
+        width      : videoWidth,
+        bitrate    : this.analyticsBitrate_,
+        audioCodec : this.audioCodec_,
+        videoCodec : this.videoCodec_,
+      },
+      currentTime
+    });
+
+    this.isPaused_ = true;
+  }
+
+  checkPlayheadProgress() {
+    const mediaEl = this.mediaEl;
+
+    if (mediaEl.paused) {
+      this.onPaused();
+    }
+
+    if (this.bufferingTimeout_) {
+      clearTimeout(this.bufferingTimeout_);
+    }
+
+    this.bufferingTimeout_ = setTimeout(() => {
+
+      if (mediaEl.paused || mediaEl.ended && !this.isBuffering_) {
+        return;
+      }
+
+      const timeDelta = mediaEl.currentTime - this.previousMediaTime_;
+
+      if (timeDelta < BUFFERING_TIMECHANGED_TIMEOUT) {
+        this.onBuffering();
+      }
+
+    }, BUFFERING_TIMECHANGED_TIMEOUT);
+  }
+
+  /**
+   * @param {boolean} silent
+   */
+  checkQualityLevelAttributes(silent = false) {
+
+    const mediaEl = this.mediaEl;
+
+    const qualityLevelInfo = this.getCurrentQualityLevelInfo();
+    if (!qualityLevelInfo) {
+      return;
+    }
+
+    const {bitrate, width, height, videoCodec, audioCodec} = qualityLevelInfo;
+
+    const isLive = this.isLive();
+
+    if (isLive !== this.isLive_) {
+      this.isLive_ = isLive;
+
+      if (!silent) {
+        this.stateMachine.updateMetadata({
+          isLive
+        });
+      }
+
+    }
+
+    this.audioCodec_ = audioCodec;
+    this.videoCodec_ = videoCodec;
+
+    if (this.analyticsBitrate_ !== bitrate) {
+      const eventData = {
+        width,
+        height,
+        bitrate,
+        videoCodec,
+        audioCodec,
+        currentTime: mediaEl.currentTime
+      };
+
+      if (!silent) {
+        this.eventCallback(Events.VIDEO_CHANGE, eventData);
+      }
+
+      this.analyticsBitrate_ = bitrate;
+    }
+
+  }
+}