feat(FEC-11632): expose stream timed metadata (#618)

add a new api `getTextTracks` to get the native video text tracks
add a new type `TextTrackCue`
add a new class `CuePoint`  
and `CuePoint.TYPE` - `EMSG` for emsg and `CUSTOM` for custom cue points
add a new function `createTextTrackCue` to create `TextTrackCue` for a `CuePoint` 

Related to kaltura/kaltura-player-js#509, kaltura/playkit-js-dash#172
Solves FEC-11632

flow-typed/interfaces/engine.js

@@ -47,6 +47,7 @@ declare interface IEngine extends FakeEventTarget {
   getThumbnail(time: number): ?ThumbnailInfo;
   isOnLiveEdge(): boolean;
   addTextTrack(kind: string, label?: string, language): ?TextTrack;
+  getTextTracks(): Array<TextTrack>;
   +id: string;
   currentTime: number;
   +duration: number;

flow-typed/types/text-track-cue.js

@@ -0,0 +1,6 @@
+declare type TextTrackCue = window.TextTrackCue & {
+  value: {
+    key: string,
+    data: string | Object
+  }
+};

src/engines/html5/html5.js

@@ -325,6 +325,7 @@ export default class Html5 extends FakeEventTarget implements IEngine {
       this._eventManager.listen(mediaSourceAdapter, Html5EventType.PLAYING, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(mediaSourceAdapter, Html5EventType.WAITING, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(mediaSourceAdapter, CustomEventType.MEDIA_RECOVERED, (event: FakeEvent) => this.dispatchEvent(event));
+      this._eventManager.listen(mediaSourceAdapter, CustomEventType.TIMED_METADATA_ADDED, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(mediaSourceAdapter, 'hlsFragParsingMetadata', (event: FakeEvent) => this.dispatchEvent(event));
       if (this._droppedFramesWatcher) {
         this._eventManager.listen(this._droppedFramesWatcher, CustomEventType.FPS_DROP, (event: FakeEvent) => this.dispatchEvent(event));
@@ -1211,4 +1212,14 @@ export default class Html5 extends FakeEventTarget implements IEngine {
   addTextTrack(kind: string, label?: string, language?: string): ?TextTrack {
     return this._el.addTextTrack(kind, label, language);
   }
+
+  /**
+   * get text tracks
+   * @function getTextTracks
+   * @returns {Array<TextTrack>} - The TextTracks array.
+   * @public
+   */
+  getTextTracks(): Array<TextTrack> {
+    return Array.from(this._el.textTracks);
+  }
 }

src/player.js

@@ -1364,6 +1364,19 @@ export default class Player extends FakeEventTarget {
     }
   }
 
+  /**
+   * get text tracks
+   * @function getTextTracks
+   * @returns {Array<TextTrack>} - The TextTracks array.
+   * @public
+   */
+  getTextTracks(): Array<TextTrack> {
+    if (this._engine && typeof this._engine.getTextTracks === 'function') {
+      return this._engine.getTextTracks();
+    }
+    return [];
+  }
+
   /**
    * Enables adaptive bitrate switching.
    * @function enableAdaptiveBitrate
@@ -1908,6 +1921,7 @@ export default class Player extends FakeEventTarget {
       this._eventManager.listen(this._engine, CustomEventType.TEXT_CUE_CHANGED, (event: FakeEvent) => this._onCueChange(event));
       this._eventManager.listen(this._engine, CustomEventType.ABR_MODE_CHANGED, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(this._engine, CustomEventType.TIMED_METADATA, (event: FakeEvent) => this.dispatchEvent(event));
+      this._eventManager.listen(this._engine, CustomEventType.TIMED_METADATA_ADDED, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(this._engine, CustomEventType.PLAY_FAILED, (event: FakeEvent) => {
         this._onPlayFailed(event);
         this.dispatchEvent(event);
@@ -1916,6 +1930,7 @@ export default class Player extends FakeEventTarget {
       this._eventManager.listen(this._engine, CustomEventType.FRAG_LOADED, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(this._engine, CustomEventType.DRM_LICENSE_LOADED, (event: FakeEvent) => this.dispatchEvent(event));
       this._eventManager.listen(this._engine, CustomEventType.MANIFEST_LOADED, (event: FakeEvent) => this.dispatchEvent(event));
+      this._eventManager.listen(this._engine, CustomEventType.MEDIA_RECOVERED, () => this._handleRecovered());
       this._eventManager.listen(this, Html5EventType.PLAY, this._onPlay.bind(this));
       this._eventManager.listen(this, Html5EventType.PAUSE, this._onPause.bind(this));
       this._eventManager.listen(this, Html5EventType.PLAYING, this._onPlaying.bind(this));
@@ -1935,7 +1950,6 @@ export default class Player extends FakeEventTarget {
         this._resetTextCuesAndReposition();
         this.dispatchEvent(event);
       });
-      this._eventManager.listen(this._engine, CustomEventType.MEDIA_RECOVERED, () => this._handleRecovered());
       this._eventManager.listen(this._externalCaptionsHandler, CustomEventType.TEXT_CUE_CHANGED, (event: FakeEvent) => this._onCueChange(event));
       this._eventManager.listen(this._externalCaptionsHandler, CustomEventType.TEXT_TRACK_CHANGED, (event: FakeEvent) =>
         this._onTextTrackChanged(event)

src/playkit.js

@@ -11,6 +11,7 @@ import ImageTrack from './track/image-track';
 import VideoTrack from './track/video-track';
 import AudioTrack from './track/audio-track';
 import TextTrack from './track/text-track';
+import {CuePoint, createTextTrackCue} from './track/cue-point';
 import TextStyle from './track/text-style';
 import {Cue} from './track/vtt-cue';
 import Env from './utils/env';
@@ -62,6 +63,9 @@ export {BaseMiddleware};
 // Export the tracks classes
 export {Track, VideoTrack, AudioTrack, TextTrack, ImageTrack, TextStyle, Cue};
 
+// Export the cue point class and function
+export {CuePoint, createTextTrackCue};
+
 // Export utils library
 export {Utils};
 

src/track/cue-point.js

@@ -0,0 +1,53 @@
+//@flow
+class CuePoint {
+  static TYPE: {[type: string]: string};
+
+  startTime: number;
+  endTime: number;
+  id: string;
+  type: string;
+  metadata: string | Object;
+  /**
+   * @constructor
+   * @param {number} startTime - start time.
+   * @param {number} endTime - end time.
+   * @param {string} id - id.
+   * @param {string} type - type.
+   * @param {string|Object} metadata - metadata.
+   */
+  constructor(startTime: number, endTime: number, id: string, type: string, metadata: string | Object) {
+    this.startTime = startTime;
+    this.endTime = endTime;
+    this.id = id;
+    this.type = type;
+    this.metadata = metadata;
+  }
+}
+
+CuePoint.TYPE = {
+  EMSG: 'emsg',
+  CUSTOM: 'custom'
+};
+
+/**
+ * Create a standard TextTrackCue.
+ * @param {CuePoint} cuePoint - cue point.
+ * @returns {TextTrackCue} - the created text track cue
+ * @private
+ */
+function createTextTrackCue(cuePoint: CuePoint): TextTrackCue {
+  const {startTime, endTime, id, type, metadata} = cuePoint;
+  let cue = {};
+  if (window.VTTCue) {
+    cue = new window.VTTCue(startTime, endTime, '');
+  } else if (window.TextTrackCue) {
+    // IE11 support
+    cue = new window.TextTrackCue(startTime, endTime, '');
+  }
+  const cueValue = {key: type, data: metadata};
+  cue.id = id;
+  cue.value = cueValue;
+  return cue;
+}
+
+export {CuePoint, createTextTrackCue};

src/track/external-captions-handler.js

@@ -548,7 +548,7 @@ class ExternalCaptionsHandler extends FakeEventTarget {
    * @returns {Array<TextTrackCue>} the converted cues
    */
   _convertCues(cues: Array<Cue>): Array<TextTrackCue> {
-    return cues.map(cue => new TextTrackCue(cue.startTime, cue.endTime, cue.text));
+    return cues.map(cue => new window.TextTrackCue(cue.startTime, cue.endTime, cue.text));
   }
 
   /**