feat: Create a new simple API for Video (#8454)

Co-authored-by: Wojciech Tyczyński <[email protected]>

Author: avelad

externs/shaka/player.js

@@ -540,6 +540,53 @@ shaka.extern.AudioTrack;
 shaka.extern.TextTrack;
 
 
+/**
+ * @typedef {{
+ *   active: boolean,
+ *   bandwidth: number,
+ *   width: ?number,
+ *   height: ?number,
+ *   frameRate: ?number,
+ *   pixelAspectRatio: ?string,
+ *   hdr: ?string,
+ *   colorGamut: ?string,
+ *   videoLayout: ?string,
+ *   mimeType: ?string,
+ *   codecs: ?string
+ * }}
+ *
+ * @description
+ * An object describing a video track.  This object should be treated as
+ * read-only as changing any values does not have any effect.
+ *
+ * @property {boolean} active
+ *   If true, this is the track being streamed (another track may be
+ *   visible/audible in the buffer).
+ * @property {number} bandwidth
+ *   The bandwidth required to play the track, in bits/sec.
+ * @property {?number} width
+ *   The video width provided in the manifest, if present.
+ * @property {?number} height
+ *   The video height provided in the manifest, if present.
+ * @property {?number} frameRate
+ *   The video framerate provided in the manifest, if present.
+ * @property {?string} pixelAspectRatio
+ *   The video pixel aspect ratio provided in the manifest, if present.
+ * @property {?string} hdr
+ *   The video HDR provided in the manifest, if present.
+ * @property {?string} colorGamut
+ *   The video color gamut provided in the manifest, if present.
+ * @property {?string} videoLayout
+ *   The video layout provided in the manifest, if present.
+ * @property {?string} mimeType
+ *   The video MIME type of the content provided in the manifest.
+ * @property {?string} codecs
+ *   The video codecs string provided in the manifest, if present.
+ * @exportDoc
+ */
+shaka.extern.VideoTrack;
+
+
 /**
  * @typedef {{
  *   id: number,

lib/cast/cast_utils.js

@@ -345,6 +345,7 @@ shaka.cast.CastUtils.LargePlayerGetterMethods = new Map()
     .set('getConfigurationForLowLatency', 4)
     .set('getStats', 5)
     .set('getAudioTracks', 2)
+    .set('getVideoTracks', 2)
     .set('getTextTracks', 2)
     .set('getVariantTracks', 2);
 
@@ -408,6 +409,7 @@ shaka.cast.CastUtils.PlayerVoidMethods = [
   'selectTextTrack',
   'selectVariantTrack',
   'selectVariantsByLabel',
+  'selectVideoTrack',
   'setTextTrackVisibility',
   'trickPlay',
   'updateStartTime',

lib/player.js

@@ -5758,6 +5758,101 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     return Array.from(audioTracksMap.values());
   }
 
+
+  /**
+   * Select a video track compatible with the current audio track.
+   * If the player has not loaded any content, this will be a no-op.
+   *
+   * @param {shaka.extern.VideoTrack} videoTrack
+   * @param {boolean=} clearBuffer
+   * @param {number=} safeMargin Optional amount of buffer (in seconds) to
+   *   retain when clearing the buffer. Useful for switching quickly
+   *   without causing a buffering event. Defaults to 0 if not provided. Can
+   *   cause hiccups on some browsers if chosen too small, e.g. The amount of
+   *   two segments is a fair minimum to consider as safeMargin value.
+   * @export
+   */
+  selectVideoTrack(videoTrack, clearBuffer = false, safeMargin = 0) {
+    const variants = this.getVariantTracks();
+    if (!variants.length) {
+      return;
+    }
+    const active = variants.find((t) => t.active);
+    if (!active) {
+      return;
+    }
+    const validVariant = variants.find((t) => {
+      return t.audioId === active.audioId &&
+          (t.videoBandwidth || t.bandwidth) == videoTrack.bandwidth &&
+          t.width == videoTrack.width &&
+          t.height == videoTrack.height &&
+          t.frameRate == videoTrack.frameRate &&
+          t.pixelAspectRatio == videoTrack.pixelAspectRatio &&
+          t.hdr == videoTrack.hdr &&
+          t.colorGamut == videoTrack.colorGamut &&
+          t.videoLayout == videoTrack.videoLayout &&
+          t.videoMimeType == videoTrack.mimeType &&
+          t.videoCodec == videoTrack.codecs;
+    });
+    if (validVariant && !validVariant.active) {
+      this.selectVariantTrack(validVariant, clearBuffer, safeMargin);
+    }
+  }
+
+
+  /**
+   * Return a list of video tracks compatible with the current audio track.
+   *
+   * @return {!Array<shaka.extern.VideoTrack>}
+   * @export
+   */
+  getVideoTracks() {
+    if (this.loadMode_ == shaka.Player.LoadMode.SRC_EQUALS) {
+      return [];
+    }
+    const variants = this.getVariantTracks();
+    if (!variants.length) {
+      return [];
+    }
+    const active = variants.find((t) => t.active);
+    if (!active) {
+      return [];
+    }
+    const filteredTracks = variants.filter((t) => {
+      return t.originalAudioId === active.originalAudioId &&
+          t.audioId === active.audioId &&
+          t.audioGroupId === active.audioGroupId &&
+          t.videoCodec;
+    });
+    if (!filteredTracks.length) {
+      return [];
+    }
+
+    /** @type {!Map<number, shaka.extern.VideoTrack>} */
+    const videoTracksMap = new Map();
+    for (const track of filteredTracks) {
+      if (track.videoId == null) {
+        continue;
+      }
+      /** @type {shaka.extern.VideoTrack} */
+      const videoTrack = {
+        active: track.active,
+        bandwidth: track.videoBandwidth || track.bandwidth,
+        width: track.width,
+        height: track.height,
+        frameRate: track.frameRate,
+        pixelAspectRatio: track.pixelAspectRatio,
+        hdr: track.hdr,
+        colorGamut: track.colorGamut,
+        videoLayout: track.videoLayout,
+        mimeType: track.videoMimeType,
+        codecs: track.videoCodec,
+      };
+      videoTracksMap.set(track.videoId, videoTrack);
+    }
+    return Array.from(videoTracksMap.values());
+  }
+
   /**
    * Return a list of audio language-role combinations available.  If the
    * player has not loaded any content, this will return an empty list.

test/player_unit.js

@@ -1523,6 +1523,8 @@ describe('Player', () => {
     let variantTracks;
     /** @type {!Array<shaka.extern.AudioTrack>} */
     let audioTracks;
+    /** @type {!Array<shaka.extern.VideoTrack>} */
+    let videoTracks;
     /** @type {!Array<shaka.extern.Track>} */
     let textTracks;
     /** @type {!Array<shaka.extern.Track>} */
@@ -2166,6 +2168,35 @@ describe('Player', () => {
         },
       ];
 
+      videoTracks = [
+        {
+          active: true,
+          bandwidth: 1000,
+          width: 100,
+          height: 200,
+          frameRate: 1000000 / 42000,
+          pixelAspectRatio: '59:54',
+          hdr: null,
+          colorGamut: null,
+          videoLayout: null,
+          mimeType: 'video/mp4',
+          codecs: 'avc1.4d401f',
+        },
+        {
+          active: false,
+          bandwidth: 2000,
+          width: 200,
+          height: 400,
+          frameRate: 24,
+          pixelAspectRatio: '59:54',
+          hdr: null,
+          colorGamut: null,
+          videoLayout: null,
+          mimeType: 'video/mp4',
+          codecs: 'avc1.4d401f',
+        },
+      ];
+
       textTracks = [
         {
           id: 50,
@@ -2252,6 +2283,7 @@ describe('Player', () => {
     it('returns the correct tracks', () => {
       expect(player.getVariantTracks()).toEqual(variantTracks);
       expect(player.getAudioTracks()).toEqual(audioTracks);
+      expect(player.getVideoTracks()).toEqual(videoTracks);
       expect(player.getTextTracks()).toEqual(textTracks);
       expect(player.getImageTracks()).toEqual(imageTracks);
     });
@@ -2263,6 +2295,7 @@ describe('Player', () => {
         // The player does not yet have a manifest.
         expect(player.getVariantTracks()).toEqual([]);
         expect(player.getAudioTracks()).toEqual([]);
+        expect(player.getVideoTracks()).toEqual([]);
         expect(player.getTextTracks()).toEqual([]);
         expect(player.getImageTracks()).toEqual([]);
 
@@ -2274,6 +2307,7 @@ describe('Player', () => {
 
       expect(player.getVariantTracks()).toEqual(variantTracks);
       expect(player.getAudioTracks()).toEqual(audioTracks);
+      expect(player.getVideoTracks()).toEqual(videoTracks);
       expect(player.getTextTracks()).toEqual(textTracks);
       expect(player.getImageTracks()).toEqual(imageTracks);
     });
@@ -2695,6 +2729,23 @@ describe('Player', () => {
         expect(variantChanged).not.toHaveBeenCalled();
       });
 
+      it('in selectVideoTrack', async () => {
+        // Any variant track we're not already streaming.
+        const newTrack = player.getVideoTracks().filter((t) => !t.active)[0];
+
+        // Call selectVariantTrack with a new track.  Expect an event to fire.
+        player.selectVideoTrack(newTrack);
+        await shaka.test.Util.shortDelay();
+        expect(variantChanged).toHaveBeenCalled();
+        variantChanged.calls.reset();
+
+        // Call again with the same track, and expect no event to fire, since
+        // nothing changed this time.
+        player.selectVideoTrack(newTrack);
+        await shaka.test.Util.shortDelay();
+        expect(variantChanged).not.toHaveBeenCalled();
+      });
+
       it('in selectTextLanguage', async () => {
         // The current text language.
         const currentLanguage = player.getTextTracks()
@@ -2737,7 +2788,7 @@ describe('Player', () => {
         expect(variantChanged).not.toHaveBeenCalled();
       });
 
-      it('in selectAudioLanguage', async () => {
+      it('in selectAudioTrack', async () => {
         // New audio track.
         const newAudioTrack = player.getAudioTracks().find((t) => !t.active);
         goog.asserts.assert(newAudioTrack, 'audio track must be non-null');

test/ui/ui_unit.js

@@ -589,19 +589,19 @@ describe('UI', () => {
         await player.load(
             /* uri= */ 'fake', /* startTime= */ 0, fakeMimeType);
 
-        const selectVariantTrack = spyOn(player, 'selectVariantTrack');
+        const selectVideoTrack = spyOn(player, 'selectVideoTrack');
 
         // There should be at least one explicit quality button.
         const qualityButton =
             videoContainer.querySelectorAll('button.explicit-resolution')[0];
         expect(qualityButton).toBeDefined();
 
         // Clicking this should select a track and clear the buffer.
-        expect(selectVariantTrack).not.toHaveBeenCalled();
+        expect(selectVideoTrack).not.toHaveBeenCalled();
         qualityButton.click();
 
         // The second argument is "clearBuffer", and should be true.
-        expect(selectVariantTrack).toHaveBeenCalledWith(
+        expect(selectVideoTrack).toHaveBeenCalledWith(
             jasmine.any(Object), true);
       });
 
@@ -745,7 +745,7 @@ describe('UI', () => {
           if (elem instanceof shaka.ui.OverflowMenu) {
             for (const child of elem.children_) {
               if (child instanceof shaka.ui.ResolutionSelection) {
-                child.updateResolutionSelection_();
+                child.updateSelection_();
                 found = true;
               }
             }