feat: Add getChaptersAsync method (#8541)

This allows the segmentIndex to be created if it is not already created
and also allows operation with CastProxy.

Author: avelad

docs/tutorials/upgrade.md

@@ -131,3 +131,4 @@ application:
     - The `TimelineRegionInfo.eventElement` has been replaced with `TimelineRegionInfo.eventNode` property, the new property type is `shaka.externs.xml.Node` instead of `Element`
     - New API for audio: `getAudioTracks` and `selectAudioTrack`, we also deprecated in v4.14 `getAudioLanguages`, `getAudioLanguagesAndRoles` and `selectAudioLanguage`.
     - `shaka.util.FairPlayUtils` is moved to `shaka.drm.FairPlay` (Deprecated in v4.14)
+    - `getChapters` is replaced by `getChaptersAsync` (Deprecated in v4.15)

lib/cast/cast_utils.js

@@ -346,7 +346,6 @@ shaka.cast.CastUtils.LargePlayerGetterMethods = new Map()
     .set('getImageTracks', 2)
     .set('getVideoTracks', 2)
     .set('getTextTracks', 2)
-    .set('getThumbnails', 2)
     .set('getVariantTracks', 2);
 
 
@@ -393,9 +392,6 @@ shaka.cast.CastUtils.PlayerInitAfterLoadState = [
  * @const {!Array<string>}
  */
 shaka.cast.CastUtils.PlayerVoidMethods = [
-  'addChaptersTrack',
-  'addTextTrackAsync',
-  'addThumbnailsTrack',
   'cancelTrickPlay',
   'configure',
   'configurationForLowLatency',
@@ -422,6 +418,12 @@ shaka.cast.CastUtils.PlayerVoidMethods = [
  * @const {!Array<string>}
  */
 shaka.cast.CastUtils.PlayerPromiseMethods = [
+  'addChaptersTrack',
+  'addTextTrackAsync',
+  'addThumbnailsTrack',
+  'getAllThumbnails',
+  'getChaptersAsync',
+  'getThumbnails',
   'attach',
   'attachCanvas',
   'detach',

lib/player.js

@@ -6238,6 +6238,9 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @export
    */
   getChapters(language) {
+    shaka.Deprecate.deprecateFeature(5,
+        'getChapters',
+        'Please use an getChaptersAsync.');
     if (!this.externalChaptersStreams_.length) {
       return [];
     }
@@ -6272,6 +6275,50 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     return chapters;
   }
 
+  /**
+   * This returns the list of chapters.
+   *
+   * @param {string} language
+   * @return {!Promise<!Array<shaka.extern.Chapter>>}
+   * @export
+   */
+  async getChaptersAsync(language) {
+    if (!this.externalChaptersStreams_.length) {
+      return [];
+    }
+    const LanguageUtils = shaka.util.LanguageUtils;
+    const inputLanguage = LanguageUtils.normalize(language);
+    const chapterStreams = this.externalChaptersStreams_
+        .filter((c) => LanguageUtils.normalize(c.language) == inputLanguage);
+    if (!chapterStreams.length) {
+      return [];
+    }
+    const chapters = [];
+    const uniqueChapters = new Set();
+    for (const chapterStream of chapterStreams) {
+      if (!chapterStream.segmentIndex) {
+        // eslint-disable-next-line no-await-in-loop
+        await chapterStream.createSegmentIndex();
+      }
+      chapterStream.segmentIndex.forEachTopLevelReference((ref) => {
+        const title = ref.getUris()[0];
+        const id = ref.startTime + '-' + ref.endTime + '-' + title;
+        /** @type {shaka.extern.Chapter} */
+        const chapter = {
+          id,
+          title,
+          startTime: ref.startTime,
+          endTime: ref.endTime,
+        };
+        if (!uniqueChapters.has(id)) {
+          chapters.push(chapter);
+          uniqueChapters.add(id);
+        }
+      });
+    }
+    return chapters;
+  }
+
   /**
    * Ignore the TextTracks with the 'metadata' or 'chapters' kind, or the one
    * generated by the SimpleTextDisplayer.

test/cast/cast_utils_unit.js

@@ -21,7 +21,6 @@ describe('CastUtils', () => {
       'getMediaElement',  // Handled specially
       'setMaxHardwareResolution',
       'destroy',  // Should use CastProxy.destroy instead
-      'getAllThumbnails', // Too large to proxy.
       'drmInfo',  // Too large to proxy
       'getManifest', // Too large to proxy
       'getManifestParserFactory',  // Would not serialize.

test/player_integration.js

@@ -1290,7 +1290,7 @@ describe('Player', () => {
 
       // Data should be available as soon as addChaptersTrack resolves.
       // See https://github.com/shaka-project/shaka-player/issues/4186
-      const chapters = player.getChapters('en');
+      const chapters = await player.getChaptersAsync('en');
       expect(chapters.length).toBe(3);
       const chapter1 = chapters[0];
       expect(chapter1.title).toBe('Chapter 1');
@@ -1309,7 +1309,7 @@ describe('Player', () => {
       const absoluteUri2 = locationUri.resolve(partialUri2);
       await player.addChaptersTrack(absoluteUri2.toString(), 'en');
 
-      const chaptersUpdated = player.getChapters('en');
+      const chaptersUpdated = await player.getChaptersAsync('en');
       expect(chaptersUpdated.length).toBe(6);
       const chapterUpdated1 = chaptersUpdated[0];
       expect(chapterUpdated1.title).toBe('Chapter 1');
@@ -1344,7 +1344,7 @@ describe('Player', () => {
       const absoluteUri = locationUri.resolve(partialUri);
       await player.addChaptersTrack(absoluteUri.toString(), 'es');
 
-      const chapters = player.getChapters('es');
+      const chapters = await player.getChaptersAsync('es');
       expect(chapters.length).toBe(3);
       const chapter1 = chapters[0];
       expect(chapter1.title).toBe('Chapter 1');

test/player_src_equals_integration.js

@@ -354,7 +354,7 @@ describe('Player Src Equals', () => {
 
       // Data should be available as soon as addChaptersTrack resolves.
       // See https://github.com/shaka-project/shaka-player/issues/4186
-      const chapters = player.getChapters('en');
+      const chapters = await player.getChaptersAsync('en');
       expect(chapters.length).toBe(3);
       const chapter1 = chapters[0];
       expect(chapter1.title).toBe('Chapter 1');
@@ -373,7 +373,7 @@ describe('Player Src Equals', () => {
       const absoluteUri2 = locationUri.resolve(partialUri2);
       await player.addChaptersTrack(absoluteUri2.toString(), 'en');
 
-      const chaptersUpdated = player.getChapters('en');
+      const chaptersUpdated = await player.getChaptersAsync('en');
       expect(chaptersUpdated.length).toBe(6);
       const chapterUpdated1 = chaptersUpdated[0];
       expect(chapterUpdated1.title).toBe('Chapter 1');
@@ -409,7 +409,7 @@ describe('Player Src Equals', () => {
       const absoluteUri = locationUri.resolve(partialUri);
       await player.addChaptersTrack(absoluteUri.toString(), 'es');
 
-      const chapters = player.getChapters('es');
+      const chapters = await player.getChaptersAsync('es');
       expect(chapters.length).toBe(3);
       const chapter1 = chapters[0];
       expect(chapter1.title).toBe('Chapter 1');

ui/chapter_selection.js

@@ -100,7 +100,7 @@ shaka.ui.ChapterSelection = class extends shaka.ui.SettingsMenu {
   /**
    * @private
    */
-  updateChapters_() {
+  async updateChapters_() {
     /**
      * Does a value compare on chapters.
      * @param {shaka.extern.Chapter} a
@@ -121,16 +121,21 @@ shaka.ui.ChapterSelection = class extends shaka.ui.SettingsMenu {
       nextLanguage = locale;
       // If player is a proxy, and the cast receiver doesn't support this
       // method, you get back undefined.
-      nextChapters = this.player.getChapters(nextLanguage) || [];
+      if (this.player) {
+        // eslint-disable-next-line no-await-in-loop
+        nextChapters = (await this.player.getChaptersAsync(nextLanguage)) || [];
+      }
       if (nextChapters.length) {
         break;
       }
     }
     if (!nextChapters.length) {
       nextLanguage = 'und';
-      // If player is a proxy, and the cast receiver doesn't support this
-      // method, you get back undefined.
-      nextChapters = this.player.getChapters(nextLanguage) || [];
+      if (this.player) {
+        // If player is a proxy, and the cast receiver doesn't support this
+        // method, you get back undefined.
+        nextChapters = (await this.player.getChaptersAsync(nextLanguage)) || [];
+      }
     }
 
     const languageChanged = nextLanguage !== this.chaptersLanguage_;