feat: Simplicate Text and Chapters APIs (#8264)

Author: avelad

externs/shaka/player.js

@@ -464,6 +464,79 @@ shaka.extern.Track;
 shaka.extern.AudioTrack;
 
 
+/**
+ * @typedef {{
+ *   id: number,
+ *   active: boolean,
+ *   bandwidth: number,
+ *   language: string,
+ *   label: ?string,
+ *   kind: ?string,
+ *   mimeType: ?string,
+ *   codecs: ?string,
+ *   primary: boolean,
+ *   roles: !Array<string>,
+ *   accessibilityPurpose: ?shaka.media.ManifestParser.AccessibilityPurpose,
+ *   forced: boolean,
+ *   originalTextId: ?string,
+ *   originalLanguage: ?string
+ * }}
+ *
+ * @description
+ * An object describing a media track.  This object should be treated as
+ * read-only as changing any values does not have any effect.  This is the
+ * public view of an audio/video paring (variant type) or text track (text
+ * type) or image track (image type).
+ *
+ * @property {number} id
+ *   The unique ID of the track.
+ * @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 {string} language
+ *   The language of the track, or <code>'und'</code> if not given.  This value
+ *   is normalized as follows - language part is always lowercase and translated
+ *   to ISO-639-1 when possible, locale part is always uppercase,
+ *   i.e. <code>'en-US'</code>.
+ * @property {?string} label
+ *   The track label, which is unique text that should describe the track.
+ * @property {?string} kind
+ *   (only for text tracks) The kind of text track, either
+ *   <code>'caption'</code> or <code>'subtitle'</code>.
+ * @property {?string} mimeType
+ *   The MIME type of the content provided in the manifest.
+ * @property {?string} codecs
+ *   The audio/video codecs string provided in the manifest, if present.
+ * @property {boolean} primary
+ *   True indicates that this in the primary language for the content.
+ *   This flag is based on signals from the manifest.
+ *   This can be a useful hint about which language should be the default, and
+ *   indicates which track Shaka will use when the user's language preference
+ *   cannot be satisfied.
+ * @property {!Array<string>} roles
+ *   The roles of the track, e.g. <code>'main'</code>, <code>'caption'</code>,
+ *   or <code>'commentary'</code>.
+ * @property {?shaka.media.ManifestParser.AccessibilityPurpose
+ *           } accessibilityPurpose
+ *   The DASH accessibility descriptor, if one was provided for this track.
+ *   For text tracks, this describes the text; otherwise, this is for the audio.
+ * @property {boolean} forced
+ *   True indicates that this in the forced text language for the content.
+ *   This flag is based on signals from the manifest.
+ * @property {?string} originalTextId
+ *   (text tracks only) The original ID of the text track, if any, as it
+ *   appeared in the original manifest.
+ * @property {?string} originalLanguage
+ *   The original language of the track, if any, as it appeared in the original
+ *   manifest.  This is the exact value provided in the manifest; for normalized
+ *   value use <code>language</code> property.
+ * @exportDoc
+ */
+shaka.extern.TextTrack;
+
+
 /**
  * @typedef {!Array<!shaka.extern.Track>}
  */

lib/media/preload_manager.js

@@ -364,7 +364,7 @@ shaka.media.PreloadManager = class extends shaka.util.FakeEventTarget {
   /**
    * Gets the preloaded text track if it exists.
    *
-   * @return {?shaka.extern.Track}
+   * @return {?shaka.extern.TextTrack}
    * @export
    */
   getPrefetchedTextTrack() {

lib/player.js

@@ -5099,7 +5099,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * <p>
    * If the player has not loaded content, this will return an empty list.
    *
-   * @return {!Array<shaka.extern.Track>}
+   * @return {!Array<shaka.extern.TextTrack>}
    * @export
    */
   getTextTracks() {
@@ -5344,7 +5344,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * Note that <code>AdaptationEvents</code> are not fired for manual track
    * selections.
    *
-   * @param {shaka.extern.Track} track
+   * @param {shaka.extern.TextTrack} track
    * @export
    */
   selectTextTrack(track) {
@@ -5673,7 +5673,13 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * Return a list of text language-role combinations available.  If the player
    * has not loaded any content, this will be return an empty list.
    *
+   * <br>
+   *
+   * This API is deprecated and will be removed in version 5.0, please migrate
+   * to using `getTextTracks` and `selectTextTrack`.
+   *
    * @return {!Array<shaka.extern.LanguageRole>}
+   * @deprecated
    * @export
    */
   getTextLanguagesAndRoles() {
@@ -5701,7 +5707,13 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * Return a list of text languages available. If the player has not loaded
    * any content, this will return an empty list.
    *
+   * <br>
+   *
+   * This API is deprecated and will be removed in version 5.0, please migrate
+   * to using `getTextTracks` and `selectTextTrack`.
+   *
    * @return {!Array<string>}
+   * @deprecated
    * @export
    */
   getTextLanguages() {
@@ -5812,9 +5824,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * language and role, and chooses a new variant if need be. If the player has
    * not loaded any content, this will be a no-op.
    *
+   * <br>
+   *
+   * This API is deprecated and will be removed in version 5.0, please migrate
+   * to using `getTextTracks` and `selectTextTrack`.
+   *
    * @param {string} language
    * @param {string=} role
    * @param {boolean=} forced
+   * @deprecated
    * @export
    */
   selectTextLanguage(language, role, forced = false) {
@@ -5964,7 +5982,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   /**
    * Return a list of chapters tracks.
    *
-   * @return {!Array<shaka.extern.Track>}
+   * @return {!Array<shaka.extern.TextTrack>}
    * @export
    */
   getChaptersTracks() {
@@ -6376,7 +6394,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @param {string=} codec
    * @param {string=} label
    * @param {boolean=} forced
-   * @return {!Promise<shaka.extern.Track>}
+   * @return {!Promise<shaka.extern.TextTrack>}
    * @export
    */
   async addTextTrackAsync(uri, language, kind, mimeType, codec, label,
@@ -6689,7 +6707,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * @param {string} uri
    * @param {string} language
    * @param {string=} mimeType
-   * @return {!Promise<shaka.extern.Track>}
+   * @return {!Promise<shaka.extern.TextTrack>}
    * @export
    */
   async addChaptersTrack(uri, language, mimeType) {
@@ -8621,7 +8639,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   /**
    * Get the normalized languages for a group of tracks.
    *
-   * @param {!Array<?shaka.extern.Track>} tracks
+   * @param {!Array<?(shaka.extern.Track|shaka.extern.TextTrack)>} tracks
    * @return {!Set<string>}
    * @private
    */
@@ -8643,7 +8661,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * Get all permutations of normalized languages and role for a group of
    * tracks.
    *
-   * @param {!Array<?shaka.extern.Track>} tracks
+   * @param {!Array<?(shaka.extern.Track|shaka.extern.TextTrack)>} tracks
    * @return {!Array<shaka.extern.LanguageRole>}
    * @private
    */
@@ -8653,7 +8671,8 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     /** @type {!Map<string, !Map<string, string>>} */
     const languageRoleToLabel = new Map();
 
-    for (const track of tracks) {
+    for (let i = 0; i < tracks.length; i++) {
+      const track = /** @type {shaka.extern.Track} */(tracks[i]);
       let language = 'und';
       let roles = [];
 

lib/util/stream_utils.js

@@ -1458,51 +1458,24 @@ shaka.util.StreamUtils = class {
 
   /**
    * @param {shaka.extern.Stream} stream
-   * @return {shaka.extern.Track}
+   * @return {shaka.extern.TextTrack}
    */
   static textStreamToTrack(stream) {
-    const ContentType = shaka.util.ManifestParserUtils.ContentType;
-
-    /** @type {shaka.extern.Track} */
+    /** @type {shaka.extern.TextTrack} */
     const track = {
       id: stream.id,
       active: false,
-      type: ContentType.TEXT,
       bandwidth: 0,
       language: stream.language,
       label: stream.label,
       kind: stream.kind || null,
-      width: null,
-      height: null,
-      frameRate: null,
-      pixelAspectRatio: null,
-      hdr: null,
-      colorGamut: null,
-      videoLayout: null,
       mimeType: stream.mimeType,
-      audioMimeType: null,
-      videoMimeType: null,
       codecs: stream.codecs || null,
-      audioCodec: null,
-      videoCodec: null,
       primary: stream.primary,
       roles: stream.roles,
-      audioRoles: null,
+      accessibilityPurpose: stream.accessibilityPurpose,
       forced: stream.forced,
-      videoId: null,
-      audioId: null,
-      audioGroupId: null,
-      channelsCount: null,
-      audioSamplingRate: null,
-      spatialAudio: false,
-      tilesLayout: null,
-      audioBandwidth: null,
-      videoBandwidth: null,
-      originalVideoId: null,
-      originalAudioId: null,
       originalTextId: stream.originalId,
-      originalImageId: null,
-      accessibilityPurpose: stream.accessibilityPurpose,
       originalLanguage: stream.originalLanguage,
     };
 
@@ -1605,16 +1578,26 @@ shaka.util.StreamUtils = class {
 
   /**
    * @param {TextTrack} textTrack
-   * @return {shaka.extern.Track}
+   * @return {shaka.extern.TextTrack}
    */
   static html5TextTrackToTrack(textTrack) {
-    const StreamUtils = shaka.util.StreamUtils;
-
-    /** @type {shaka.extern.Track} */
-    const track = StreamUtils.html5TrackToGenericShakaTrack_(textTrack);
-    track.active = textTrack.mode != 'disabled';
-    track.type = 'text';
-    track.originalTextId = textTrack.id;
+    /** @type {shaka.extern.TextTrack} */
+    const track = {
+      id: shaka.util.StreamUtils.html5TrackId(textTrack),
+      active: textTrack.mode != 'disabled',
+      bandwidth: 0,
+      language: shaka.util.LanguageUtils.normalize(textTrack.language || 'und'),
+      label: textTrack.label,
+      kind: textTrack.kind,
+      mimeType: null,
+      codecs: null,
+      primary: false,
+      roles: [],
+      accessibilityPurpose: null,
+      forced: textTrack.kind == 'forced',
+      originalTextId: textTrack.id,
+      originalLanguage: textTrack.language,
+    };
     if (textTrack.kind == 'captions') {
       // See: https://github.com/shaka-project/shaka-player/issues/6233
       track.mimeType = 'unknown';
@@ -1625,9 +1608,6 @@ shaka.util.StreamUtils = class {
     if (textTrack.kind) {
       track.roles = [textTrack.kind];
     }
-    if (textTrack.kind == 'forced') {
-      track.forced = true;
-    }
 
     return track;
   }