Source: lib/util/periods.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.PeriodCombiner');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.media.MetaSegmentIndex');
  12. goog.require('shaka.media.SegmentIndex');
  13. goog.require('shaka.util.DrmUtils');
  14. goog.require('shaka.util.Error');
  15. goog.require('shaka.util.IReleasable');
  16. goog.require('shaka.util.LanguageUtils');
  17. goog.require('shaka.util.ManifestParserUtils');
  18. goog.require('shaka.util.MimeUtils');
  20. /**
  21.  * A utility to combine streams across periods.
  22.  *
  23.  * @implements {shaka.util.IReleasable}
  24.  * @final
  25.  * @export
  26.  */
  27. shaka.util.PeriodCombiner = class {
  28.   /** */
  29.   constructor() {
  30.     /** @private {!Array.<shaka.extern.Variant>} */
  31.     this.variants_ = [];
  33.     /** @private {!Array.<shaka.extern.Stream>} */
  34.     this.audioStreams_ = [];
  36.     /** @private {!Array.<shaka.extern.Stream>} */
  37.     this.videoStreams_ = [];
  39.     /** @private {!Array.<shaka.extern.Stream>} */
  40.     this.textStreams_ = [];
  42.     /** @private {!Array.<shaka.extern.Stream>} */
  43.     this.imageStreams_ = [];
  45.     /** @private {boolean} */
  46.     this.multiTypeVariantsAllowed_ = false;
  48.     /** @private {boolean} */
  49.     this.useStreamOnce_ = false;
  51.     /**
  52.      * The IDs of the periods we have already used to generate streams.
  53.      * This helps us identify the periods which have been added when a live
  54.      * stream is updated.
  55.      *
  56.      * @private {!Set.<string>}
  57.      */
  58.     this.usedPeriodIds_ = new Set();
  59.   }
  61.   /** @override */
  62.   release() {
  63.     const allStreams =
  64.         this.audioStreams_.concat(this.videoStreams_, this.textStreams_,
  65.             this.imageStreams_);
  67.     for (const stream of allStreams) {
  68.       if (stream.segmentIndex) {
  69.         stream.segmentIndex.release();
  70.       }
  71.     }
  73.     this.audioStreams_ = [];
  74.     this.videoStreams_ = [];
  75.     this.textStreams_ = [];
  76.     this.imageStreams_ = [];
  77.     this.variants_ = [];
  78.   }
  80.   /**
  81.    * @return {!Array.<shaka.extern.Variant>}
  82.    *
  83.    * @export
  84.    */
  85.   getVariants() {
  86.     return this.variants_;
  87.   }
  89.   /**
  90.    * @return {!Array.<shaka.extern.Stream>}
  91.    *
  92.    * @export
  93.   */
  94.   getTextStreams() {
  95.     // Return a copy of the array because makeTextStreamsForClosedCaptions
  96.     // may make changes to the contents of the array. Those changes should not
  97.     // propagate back to the PeriodCombiner.
  98.     return this.textStreams_.slice();
  99.   }
  101.   /**
  102.    * @return {!Array.<shaka.extern.Stream>}
  103.    *
  104.    * @export
  105.    */
  106.   getImageStreams() {
  107.     return this.imageStreams_;
  108.   }
  110.   /**
  111.    * Deletes a stream from matchedStreams because it is no longer needed
  112.    *
  113.    * @param {?shaka.extern.Stream} stream
  114.    * @param {string} periodId
  115.    *
  116.    * @export
  117.    */
  118.   deleteStream(stream, periodId) {
  119.     if (!stream) {
  120.       return;
  121.     }
  122.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  123.     if (stream.type == ContentType.AUDIO) {
  124.       for (const audioStream of this.audioStreams_) {
  125.         audioStream.matchedStreams = audioStream.matchedStreams.filter((s) => {
  126.           return s !== stream;
  127.         });
  128.       }
  129.     } else if (stream.type == ContentType.VIDEO) {
  130.       for (const videoStream of this.videoStreams_) {
  131.         videoStream.matchedStreams = videoStream.matchedStreams.filter((s) => {
  132.           return s !== stream;
  133.         });
  134.         if (videoStream.trickModeVideo) {
  135.           videoStream.trickModeVideo.matchedStreams =
  136.             videoStream.trickModeVideo.matchedStreams.filter((s) => {
  137.               return s !== stream;
  138.             });
  139.         }
  140.       }
  141.     } else if (stream.type == ContentType.TEXT) {
  142.       for (const textStream of this.textStreams_) {
  143.         textStream.matchedStreams = textStream.matchedStreams.filter((s) => {
  144.           return s !== stream;
  145.         });
  146.       }
  147.     } else if (stream.type == ContentType.IMAGE) {
  148.       for (const imageStream of this.imageStreams_) {
  149.         imageStream.matchedStreams = imageStream.matchedStreams.filter((s) => {
  150.           return s !== stream;
  151.         });
  152.       }
  153.     }
  154.     if (stream.segmentIndex) {
  155.       stream.closeSegmentIndex();
  156.     }
  157.     this.usedPeriodIds_.delete(periodId);
  158.   }
  160.   /**
  161.    * Returns an object that contains arrays of streams by type
  162.    * @param {!Array<shaka.extern.Period>} periods
  163.    * @param {boolean} addDummy
  164.    * @return {{
  165.    *  audioStreamsPerPeriod: !Array<!Map<string, shaka.extern.Stream>>,
  166.    *  videoStreamsPerPeriod: !Array<!Map<string, shaka.extern.Stream>>,
  167.    *  textStreamsPerPeriod: !Array<!Map<string, shaka.extern.Stream>>,
  168.    *  imageStreamsPerPeriod: !Array<!Map<string, shaka.extern.Stream>>
  169.    * }}
  170.    * @private
  171.    */
  172.   getStreamsPerPeriod_(periods, addDummy) {
  173.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  174.     const PeriodCombiner = shaka.util.PeriodCombiner;
  176.     const audioStreamsPerPeriod = [];
  177.     const videoStreamsPerPeriod = [];
  178.     const textStreamsPerPeriod = [];
  179.     const imageStreamsPerPeriod = [];
  181.     for (const period of periods) {
  182.       const audioMap = new Map(period.audioStreams.map((s) =>
  183.         [PeriodCombiner.generateAudioKey_(s), s]));
  184.       const videoMap = new Map(period.videoStreams.map((s) =>
  185.         [PeriodCombiner.generateVideoKey_(s), s]));
  186.       const textMap = new Map(period.textStreams.map((s) =>
  187.         [PeriodCombiner.generateTextKey_(s), s]));
  188.       const imageMap = new Map(period.imageStreams.map((s) =>
  189.         [PeriodCombiner.generateImageKey_(s), s]));
  191.       // It's okay to have a period with no text or images, but our algorithm
  192.       // fails on any period without matching streams.  So we add dummy streams
  193.       // to each period.  Since we combine text streams by language and image
  194.       // streams by resolution, we might need a dummy even in periods with these
  195.       // streams already.
  196.       if (addDummy) {
  197.         const dummyText = PeriodCombiner.dummyStream_(ContentType.TEXT);
  198.         textMap.set(PeriodCombiner.generateTextKey_(dummyText), dummyText);
  199.         const dummyImage = PeriodCombiner.dummyStream_(ContentType.IMAGE);
  200.         imageMap.set(PeriodCombiner.generateImageKey_(dummyImage), dummyImage);
  201.       }
  203.       audioStreamsPerPeriod.push(audioMap);
  204.       videoStreamsPerPeriod.push(videoMap);
  205.       textStreamsPerPeriod.push(textMap);
  206.       imageStreamsPerPeriod.push(imageMap);
  207.     }
  208.     return {
  209.       audioStreamsPerPeriod,
  210.       videoStreamsPerPeriod,
  211.       textStreamsPerPeriod,
  212.       imageStreamsPerPeriod,
  213.     };
  214.   }
  216.   /**
  217.    * @param {!Array.<shaka.extern.Period>} periods
  218.    * @param {boolean} isDynamic
  219.    * @param {boolean=} isPatchUpdate
  220.    * @return {!Promise}
  221.    *
  222.    * @export
  223.    */
  224.   async combinePeriods(periods, isDynamic, isPatchUpdate = false) {
  225.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  227.     // Optimization: for single-period VOD, do nothing.  This makes sure
  228.     // single-period DASH content will be 100% accurately represented in the
  229.     // output.
  230.     if (!isDynamic && periods.length == 1) {
  231.       // We need to filter out duplicates, so call getStreamsPerPeriod()
  232.       // so it will do that by usage of Map.
  233.       const {
  234.         audioStreamsPerPeriod,
  235.         videoStreamsPerPeriod,
  236.         textStreamsPerPeriod,
  237.         imageStreamsPerPeriod,
  238.       } = this.getStreamsPerPeriod_(periods, /* addDummy= */ false);
  239.       this.audioStreams_ = Array.from(audioStreamsPerPeriod[0].values());
  240.       this.videoStreams_ = Array.from(videoStreamsPerPeriod[0].values());
  241.       this.textStreams_ = Array.from(textStreamsPerPeriod[0].values());
  242.       this.imageStreams_ = Array.from(imageStreamsPerPeriod[0].values());
  243.     } else {
  244.       // How many periods we've seen before which are not included in this call.
  245.       const periodsMissing = isPatchUpdate ? this.usedPeriodIds_.size : 0;
  246.       // Find the first period we haven't seen before.  Tag all the periods we
  247.       // see now as "used".
  248.       let firstNewPeriodIndex = -1;
  249.       for (let i = 0; i < periods.length; i++) {
  250.         const period = periods[i];
  251.         if (this.usedPeriodIds_.has(period.id)) {
  252.           // This isn't new.
  253.         } else {
  254.           // This one _is_ new.
  255.           this.usedPeriodIds_.add(period.id);
  257.           if (firstNewPeriodIndex == -1) {
  258.             // And it's the _first_ new one.
  259.             firstNewPeriodIndex = i;
  260.           }
  261.         }
  262.       }
  264.       if (firstNewPeriodIndex == -1) {
  265.         // Nothing new? Nothing to do.
  266.         return;
  267.       }
  269.       const {
  270.         audioStreamsPerPeriod,
  271.         videoStreamsPerPeriod,
  272.         textStreamsPerPeriod,
  273.         imageStreamsPerPeriod,
  274.       } = this.getStreamsPerPeriod_(periods, /* addDummy= */ true);
  276.       await Promise.all([
  277.         this.combine_(
  278.             this.audioStreams_,
  279.             audioStreamsPerPeriod,
  280.             firstNewPeriodIndex,
  281.             shaka.util.PeriodCombiner.cloneStream_,
  282.             shaka.util.PeriodCombiner.concatenateStreams_,
  283.             periodsMissing),
  284.         this.combine_(
  285.             this.videoStreams_,
  286.             videoStreamsPerPeriod,
  287.             firstNewPeriodIndex,
  288.             shaka.util.PeriodCombiner.cloneStream_,
  289.             shaka.util.PeriodCombiner.concatenateStreams_,
  290.             periodsMissing),
  291.         this.combine_(
  292.             this.textStreams_,
  293.             textStreamsPerPeriod,
  294.             firstNewPeriodIndex,
  295.             shaka.util.PeriodCombiner.cloneStream_,
  296.             shaka.util.PeriodCombiner.concatenateStreams_,
  297.             periodsMissing),
  298.         this.combine_(
  299.             this.imageStreams_,
  300.             imageStreamsPerPeriod,
  301.             firstNewPeriodIndex,
  302.             shaka.util.PeriodCombiner.cloneStream_,
  303.             shaka.util.PeriodCombiner.concatenateStreams_,
  304.             periodsMissing),
  305.       ]);
  306.     }
  308.     // Create variants for all audio/video combinations.
  309.     let nextVariantId = 0;
  310.     const variants = [];
  311.     if (!this.videoStreams_.length || !this.audioStreams_.length) {
  312.       // For audio-only or video-only content, just give each stream its own
  313.       // variant.
  314.       const streams = this.videoStreams_.length ? this.videoStreams_ :
  315.         this.audioStreams_;
  316.       for (const stream of streams) {
  317.         const id = nextVariantId++;
  318.         variants.push({
  319.           id,
  320.           language: stream.language,
  321.           disabledUntilTime: 0,
  322.           primary: stream.primary,
  323.           audio: stream.type == ContentType.AUDIO ? stream : null,
  324.           video: stream.type == ContentType.VIDEO ? stream : null,
  325.           bandwidth: stream.bandwidth || 0,
  326.           drmInfos: stream.drmInfos,
  327.           allowedByApplication: true,
  328.           allowedByKeySystem: true,
  329.           decodingInfos: [],
  330.         });
  331.       }
  332.     } else {
  333.       for (const audio of this.audioStreams_) {
  334.         for (const video of this.videoStreams_) {
  335.           const commonDrmInfos = shaka.util.DrmUtils.getCommonDrmInfos(
  336.               audio.drmInfos, video.drmInfos);
  338.           if (audio.drmInfos.length && video.drmInfos.length &&
  339.               !commonDrmInfos.length) {
  340.             shaka.log.warning(
  341.                 'Incompatible DRM in audio & video, skipping variant creation.',
  342.                 audio, video);
  343.             continue;
  344.           }
  346.           const id = nextVariantId++;
  347.           variants.push({
  348.             id,
  349.             language: audio.language,
  350.             disabledUntilTime: 0,
  351.             primary: audio.primary,
  352.             audio,
  353.             video,
  354.             bandwidth: (audio.bandwidth || 0) + (video.bandwidth || 0),
  355.             drmInfos: commonDrmInfos,
  356.             allowedByApplication: true,
  357.             allowedByKeySystem: true,
  358.             decodingInfos: [],
  359.           });
  360.         }
  361.       }
  362.     }
  364.     this.variants_ = variants;
  365.   }
  368.   /**
  369.    * Stitch together DB streams across periods, taking a mix of stream types.
  370.    * The offline database does not separate these by type.
  371.    *
  372.    * Unlike the DASH case, this does not need to maintain any state for manifest
  373.    * updates.
  374.    *
  375.    * @param {!Array.<!Array.<shaka.extern.StreamDB>>} streamDbsPerPeriod
  376.    * @return {!Promise.<!Array.<shaka.extern.StreamDB>>}
  377.    */
  378.   static async combineDbStreams(streamDbsPerPeriod) {
  379.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  380.     const PeriodCombiner = shaka.util.PeriodCombiner;
  382.     // Optimization: for single-period content, do nothing.  This makes sure
  383.     // single-period DASH or any HLS content stored offline will be 100%
  384.     // accurately represented in the output.
  385.     if (streamDbsPerPeriod.length == 1) {
  386.       return streamDbsPerPeriod[0];
  387.     }
  389.     const audioStreamDbsPerPeriod = streamDbsPerPeriod.map(
  390.         (streams) => new Map(streams
  391.             .filter((s) => s.type === ContentType.AUDIO)
  392.             .map((s) => [PeriodCombiner.generateAudioKey_(s), s])));
  393.     const videoStreamDbsPerPeriod = streamDbsPerPeriod.map(
  394.         (streams) => new Map(streams
  395.             .filter((s) => s.type === ContentType.VIDEO)
  396.             .map((s) => [PeriodCombiner.generateVideoKey_(s), s])));
  397.     const textStreamDbsPerPeriod = streamDbsPerPeriod.map(
  398.         (streams) => new Map(streams
  399.             .filter((s) => s.type === ContentType.TEXT)
  400.             .map((s) => [PeriodCombiner.generateTextKey_(s), s])));
  401.     const imageStreamDbsPerPeriod = streamDbsPerPeriod.map(
  402.         (streams) => new Map(streams
  403.             .filter((s) => s.type === ContentType.IMAGE)
  404.             .map((s) => [PeriodCombiner.generateImageKey_(s), s])));
  406.     // It's okay to have a period with no text or images, but our algorithm
  407.     // fails on any period without matching streams.  So we add dummy streams to
  408.     // each period.  Since we combine text streams by language and image streams
  409.     // by resolution, we might need a dummy even in periods with these streams
  410.     // already.
  411.     for (const textStreams of textStreamDbsPerPeriod) {
  412.       const dummy = PeriodCombiner.dummyStreamDB_(ContentType.TEXT);
  413.       textStreams.set(PeriodCombiner.generateTextKey_(dummy), dummy);
  414.     }
  415.     for (const imageStreams of imageStreamDbsPerPeriod) {
  416.       const dummy = PeriodCombiner.dummyStreamDB_(ContentType.IMAGE);
  417.       imageStreams.set(PeriodCombiner.generateImageKey_(dummy), dummy);
  418.     }
  420.     const periodCombiner = new shaka.util.PeriodCombiner();
  422.     const combinedAudioStreamDbs = await periodCombiner.combine_(
  423.         /* outputStreams= */ [],
  424.         audioStreamDbsPerPeriod,
  425.         /* firstNewPeriodIndex= */ 0,
  426.         shaka.util.PeriodCombiner.cloneStreamDB_,
  427.         shaka.util.PeriodCombiner.concatenateStreamDBs_,
  428.         /* periodsMissing= */ 0);
  430.     const combinedVideoStreamDbs = await periodCombiner.combine_(
  431.         /* outputStreams= */ [],
  432.         videoStreamDbsPerPeriod,
  433.         /* firstNewPeriodIndex= */ 0,
  434.         shaka.util.PeriodCombiner.cloneStreamDB_,
  435.         shaka.util.PeriodCombiner.concatenateStreamDBs_,
  436.         /* periodsMissing= */ 0);
  438.     const combinedTextStreamDbs = await periodCombiner.combine_(
  439.         /* outputStreams= */ [],
  440.         textStreamDbsPerPeriod,
  441.         /* firstNewPeriodIndex= */ 0,
  442.         shaka.util.PeriodCombiner.cloneStreamDB_,
  443.         shaka.util.PeriodCombiner.concatenateStreamDBs_,
  444.         /* periodsMissing= */ 0);
  446.     const combinedImageStreamDbs = await periodCombiner.combine_(
  447.         /* outputStreams= */ [],
  448.         imageStreamDbsPerPeriod,
  449.         /* firstNewPeriodIndex= */ 0,
  450.         shaka.util.PeriodCombiner.cloneStreamDB_,
  451.         shaka.util.PeriodCombiner.concatenateStreamDBs_,
  452.         /* periodsMissing= */ 0);
  454.     // Recreate variantIds from scratch in the output.
  455.     // HLS content is always single-period, so the early return at the top of
  456.     // this method would catch all HLS content.  DASH content stored with v3.0
  457.     // will already be flattened before storage.  Therefore the only content
  458.     // that reaches this point is multi-period DASH content stored before v3.0.
  459.     // Such content always had variants generated from all combinations of audio
  460.     // and video, so we can simply do that now without loss of correctness.
  461.     let nextVariantId = 0;
  462.     if (!combinedVideoStreamDbs.length || !combinedAudioStreamDbs.length) {
  463.       // For audio-only or video-only content, just give each stream its own
  464.       // variant ID.
  465.       const combinedStreamDbs =
  466.           combinedVideoStreamDbs.concat(combinedAudioStreamDbs);
  467.       for (const stream of combinedStreamDbs) {
  468.         stream.variantIds = [nextVariantId++];
  469.       }
  470.     } else {
  471.       for (const audio of combinedAudioStreamDbs) {
  472.         for (const video of combinedVideoStreamDbs) {
  473.           const id = nextVariantId++;
  474.           video.variantIds.push(id);
  475.           audio.variantIds.push(id);
  476.         }
  477.       }
  478.     }
  480.     return combinedVideoStreamDbs
  481.         .concat(combinedAudioStreamDbs)
  482.         .concat(combinedTextStreamDbs)
  483.         .concat(combinedImageStreamDbs);
  484.   }
  486.   /**
  487.    * Combine input Streams per period into flat output Streams.
  488.    * Templatized to handle both DASH Streams and offline StreamDBs.
  489.    *
  490.    * @param {!Array.<T>} outputStreams A list of existing output streams, to
  491.    *   facilitate updates for live DASH content.  Will be modified and returned.
  492.    * @param {!Array<!Map<string, T>>} streamsPerPeriod A list of maps of Streams
  493.    *   from each period.
  494.    * @param {number} firstNewPeriodIndex An index into streamsPerPeriod which
  495.    *   represents the first new period that hasn't been processed yet.
  496.    * @param {function(T):T} clone Make a clone of an input stream.
  497.    * @param {function(T, T)} concat Concatenate the second stream onto the end
  498.    *   of the first.
  499.    * @param {number} periodsMissing The number of periods missing
  500.    *
  501.    * @return {!Promise.<!Array.<T>>} The same array passed to outputStreams,
  502.    *   modified to include any newly-created streams.
  503.    *
  504.    * @template T
  505.    * Accepts either a StreamDB or Stream type.
  506.    *
  507.    * @private
  508.    */
  509.   async combine_(
  510.       outputStreams, streamsPerPeriod, firstNewPeriodIndex, clone, concat,
  511.       periodsMissing) {
  512.     const unusedStreamsPerPeriod = [];
  514.     for (let i = 0; i < streamsPerPeriod.length; i++) {
  515.       if (i >= firstNewPeriodIndex) {
  516.         // This periods streams are all new.
  517.         unusedStreamsPerPeriod.push(new Set(streamsPerPeriod[i].values()));
  518.       } else {
  519.         // This period's streams have all been used already.
  520.         unusedStreamsPerPeriod.push(new Set());
  521.       }
  522.     }
  524.     // First, extend all existing output Streams into the new periods.
  525.     for (const outputStream of outputStreams) {
  526.       // eslint-disable-next-line no-await-in-loop
  527.       const ok = await this.extendExistingOutputStream_(
  528.           outputStream, streamsPerPeriod, firstNewPeriodIndex, concat,
  529.           unusedStreamsPerPeriod, periodsMissing);
  530.       if (!ok) {
  531.         // This output Stream was not properly extended to include streams from
  532.         // the new period.  This is likely a bug in our algorithm, so throw an
  533.         // error.
  534.         throw new shaka.util.Error(
  535.             shaka.util.Error.Severity.CRITICAL,
  536.             shaka.util.Error.Category.MANIFEST,
  537.             shaka.util.Error.Code.PERIOD_FLATTENING_FAILED);
  538.       }
  540.       // This output stream is now complete with content from all known
  541.       // periods.
  542.     }  // for (const outputStream of outputStreams)
  544.     for (const unusedStreams of unusedStreamsPerPeriod) {
  545.       for (const stream of unusedStreams) {
  546.         // Create a new output stream which includes this input stream.
  547.         const outputStream = this.createNewOutputStream_(
  548.             stream, streamsPerPeriod, clone, concat,
  549.             unusedStreamsPerPeriod);
  550.         if (outputStream) {
  551.           outputStreams.push(outputStream);
  552.         } else {
  553.           // This is not a stream we can build output from, but it may become
  554.           // part of another output based on another period's stream.
  555.         }
  556.       }  // for (const stream of unusedStreams)
  557.     }  // for (const unusedStreams of unusedStreamsPerPeriod)
  559.     for (const unusedStreams of unusedStreamsPerPeriod) {
  560.       for (const stream of unusedStreams) {
  561.         if (shaka.util.PeriodCombiner.isDummy_(stream)) {
  562.           // This is one of our dummy streams, so ignore it.  We may not use
  563.           // them all, and that's fine.
  564.           continue;
  565.         }
  566.         // If this stream has a different codec/MIME than any other stream,
  567.         // then we can't play it.
  568.         const hasCodec = outputStreams.some((s) => {
  569.           return this.areAVStreamsCompatible_(stream, s);
  570.         });
  571.         if (!hasCodec) {
  572.           continue;
  573.         }
  575.         // Any other unused stream is likely a bug in our algorithm, so throw
  576.         // an error.
  577.         shaka.log.error('Unused stream in period-flattening!',
  578.             stream, outputStreams);
  579.         throw new shaka.util.Error(
  580.             shaka.util.Error.Severity.CRITICAL,
  581.             shaka.util.Error.Category.MANIFEST,
  582.             shaka.util.Error.Code.PERIOD_FLATTENING_FAILED);
  583.       }
  584.     }
  586.     return outputStreams;
  587.   }
  589.   /**
  590.    * @param {T} outputStream An existing output stream which needs to be
  591.    *   extended into new periods.
  592.    * @param {!Array<!Map<string, T>>} streamsPerPeriod A list of maps of Streams
  593.    *   from each period.
  594.    * @param {number} firstNewPeriodIndex An index into streamsPerPeriod which
  595.    *   represents the first new period that hasn't been processed yet.
  596.    * @param {function(T, T)} concat Concatenate the second stream onto the end
  597.    *   of the first.
  598.    * @param {!Array.<!Set.<T>>} unusedStreamsPerPeriod An array of sets of
  599.    *   unused streams from each period.
  600.    * @param {number} periodsMissing How many periods are missing in this update.
  601.    *
  602.    * @return {!Promise.<boolean>}
  603.    *
  604.    * @template T
  605.    * Should only be called with a Stream type in practice, but has call sites
  606.    * from other templated functions that also accept a StreamDB.
  607.    *
  608.    * @private
  609.    */
  610.   async extendExistingOutputStream_(
  611.       outputStream, streamsPerPeriod, firstNewPeriodIndex, concat,
  612.       unusedStreamsPerPeriod, periodsMissing) {
  613.     this.findMatchesInAllPeriods_(streamsPerPeriod,
  614.         outputStream, periodsMissing > 0);
  616.     // This only exists where T == Stream, and this should only ever be called
  617.     // on Stream types.  StreamDB should not have pre-existing output streams.
  618.     goog.asserts.assert(outputStream.createSegmentIndex,
  619.         'outputStream should be a Stream type!');
  621.     if (!outputStream.matchedStreams) {
  622.       // We were unable to extend this output stream.
  623.       shaka.log.error('No matches extending output stream!',
  624.           outputStream, streamsPerPeriod);
  625.       return false;
  626.     }
  627.     // We need to create all the per-period segment indexes and append them to
  628.     // the output's MetaSegmentIndex.
  629.     if (outputStream.segmentIndex) {
  630.       await shaka.util.PeriodCombiner.extendOutputSegmentIndex_(outputStream,
  631.           firstNewPeriodIndex + periodsMissing);
  632.     }
  634.     shaka.util.PeriodCombiner.extendOutputStream_(outputStream,
  635.         firstNewPeriodIndex, concat, unusedStreamsPerPeriod, periodsMissing);
  636.     return true;
  637.   }
  639.   /**
  640.    * Creates the segment indexes for an array of input streams, and append them
  641.    * to the output stream's segment index.
  642.    *
  643.    * @param {shaka.extern.Stream} outputStream
  644.    * @param {number} firstNewPeriodIndex An index into streamsPerPeriod which
  645.    *   represents the first new period that hasn't been processed yet.
  646.    * @private
  647.    */
  648.   static async extendOutputSegmentIndex_(outputStream, firstNewPeriodIndex) {
  649.     const operations = [];
  650.     const streams = outputStream.matchedStreams;
  651.     goog.asserts.assert(streams, 'matched streams should be valid');
  653.     for (let i = firstNewPeriodIndex; i < streams.length; i++) {
  654.       const stream = streams[i];
  655.       operations.push(stream.createSegmentIndex());
  656.       if (stream.trickModeVideo && !stream.trickModeVideo.segmentIndex) {
  657.         operations.push(stream.trickModeVideo.createSegmentIndex());
  658.       }
  659.     }
  660.     await Promise.all(operations);
  662.     // Concatenate the new matches onto the stream, starting at the first new
  663.     // period.
  664.     // Satisfy the compiler about the type.
  665.     // Also checks if the segmentIndex is still valid after the async
  666.     // operations, to make sure we stop if the active stream has changed.
  667.     if (outputStream.segmentIndex instanceof shaka.media.MetaSegmentIndex) {
  668.       for (let i = firstNewPeriodIndex; i < streams.length; i++) {
  669.         const match = streams[i];
  670.         goog.asserts.assert(match.segmentIndex,
  671.             'stream should have a segmentIndex.');
  672.         if (match.segmentIndex) {
  673.           outputStream.segmentIndex.appendSegmentIndex(match.segmentIndex);
  674.         }
  675.       }
  676.     }
  677.   }
  679.   /**
  680.    * Create a new output Stream based on a particular input Stream.  Locates
  681.    * matching Streams in all other periods and combines them into an output
  682.    * Stream.
  683.    * Templatized to handle both DASH Streams and offline StreamDBs.
  684.    *
  685.    * @param {T} stream An input stream on which to base the output stream.
  686.    * @param {!Array<!Map<string, T>>} streamsPerPeriod A list of maps of Streams
  687.    *   from each period.
  688.    * @param {function(T):T} clone Make a clone of an input stream.
  689.    * @param {function(T, T)} concat Concatenate the second stream onto the end
  690.    *   of the first.
  691.    * @param {!Array.<!Set.<T>>} unusedStreamsPerPeriod An array of sets of
  692.    *   unused streams from each period.
  693.    *
  694.    * @return {?T} A newly-created output Stream, or null if matches
  695.    *   could not be found.`
  696.    *
  697.    * @template T
  698.    * Accepts either a StreamDB or Stream type.
  699.    *
  700.    * @private
  701.    */
  702.   createNewOutputStream_(
  703.       stream, streamsPerPeriod, clone, concat, unusedStreamsPerPeriod) {
  704.     // Check do we want to create output stream from dummy stream
  705.     // and if so, return quickly.
  706.     if (shaka.util.PeriodCombiner.isDummy_(stream)) {
  707.       return null;
  708.     }
  709.     // Start by cloning the stream without segments, key IDs, etc.
  710.     const outputStream = clone(stream);
  712.     // Find best-matching streams in all periods.
  713.     this.findMatchesInAllPeriods_(streamsPerPeriod, outputStream);
  715.     // This only exists where T == Stream.
  716.     if (outputStream.createSegmentIndex) {
  717.       // Override the createSegmentIndex function of the outputStream.
  718.       outputStream.createSegmentIndex = async () => {
  719.         if (!outputStream.segmentIndex) {
  720.           outputStream.segmentIndex = new shaka.media.MetaSegmentIndex();
  721.           await shaka.util.PeriodCombiner.extendOutputSegmentIndex_(
  722.               outputStream, /* firstNewPeriodIndex= */ 0);
  723.         }
  724.       };
  725.       // For T == Stream, we need to create all the per-period segment indexes
  726.       // in advance.  concat() will add them to the output's MetaSegmentIndex.
  727.     }
  729.     if (!outputStream.matchedStreams || !outputStream.matchedStreams.length) {
  730.       // This is not a stream we can build output from, but it may become part
  731.       // of another output based on another period's stream.
  732.       return null;
  733.     }
  734.     shaka.util.PeriodCombiner.extendOutputStream_(outputStream,
  735.         /* firstNewPeriodIndex= */ 0, concat, unusedStreamsPerPeriod,
  736.         /* periodsMissing= */ 0);
  738.     return outputStream;
  739.   }
  741.   /**
  742.    * @param {T} outputStream An existing output stream which needs to be
  743.    *   extended into new periods.
  744.    * @param {number} firstNewPeriodIndex An index into streamsPerPeriod which
  745.    *   represents the first new period that hasn't been processed yet.
  746.    * @param {function(T, T)} concat Concatenate the second stream onto the end
  747.    *   of the first.
  748.    * @param {!Array.<!Set.<T>>} unusedStreamsPerPeriod An array of sets of
  749.    *   unused streams from each period.
  750.    * @param {number} periodsMissing How many periods are missing in this update
  751.    *
  752.    * @template T
  753.    * Accepts either a StreamDB or Stream type.
  754.    *
  755.    * @private
  756.    */
  757.   static extendOutputStream_(
  758.       outputStream, firstNewPeriodIndex, concat, unusedStreamsPerPeriod,
  759.       periodsMissing) {
  760.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  761.     const LanguageUtils = shaka.util.LanguageUtils;
  762.     const matches = outputStream.matchedStreams;
  764.     // Assure the compiler that matches didn't become null during the async
  765.     // operation before.
  766.     goog.asserts.assert(outputStream.matchedStreams,
  767.         'matchedStreams should be non-null');
  769.     // Concatenate the new matches onto the stream, starting at the first new
  770.     // period.
  771.     const start = firstNewPeriodIndex + periodsMissing;
  772.     for (let i = start; i < matches.length; i++) {
  773.       const match = matches[i];
  774.       concat(outputStream, match);
  776.       // We only consider an audio stream "used" if its language is related to
  777.       // the output language.  There are scenarios where we want to generate
  778.       // separate tracks for each language, even when we are forced to connect
  779.       // unrelated languages across periods.
  780.       let used = true;
  781.       if (outputStream.type == ContentType.AUDIO) {
  782.         const relatedness = LanguageUtils.relatedness(
  783.             outputStream.language, match.language);
  784.         if (relatedness == 0) {
  785.           used = false;
  786.         }
  787.       }
  789.       if (used) {
  790.         unusedStreamsPerPeriod[i - periodsMissing].delete(match);
  791.         // Add the full mimetypes to the stream.
  792.         if (match.fullMimeTypes) {
  793.           for (const fullMimeType of match.fullMimeTypes.values()) {
  794.             outputStream.fullMimeTypes.add(fullMimeType);
  795.           }
  796.         }
  797.       }
  798.     }
  799.   }
  801.   /**
  802.    * Clone a Stream to make an output Stream for combining others across
  803.    * periods.
  804.    *
  805.    * @param {shaka.extern.Stream} stream
  806.    * @return {shaka.extern.Stream}
  807.    * @private
  808.    */
  809.   static cloneStream_(stream) {
  810.     const clone = /** @type {shaka.extern.Stream} */(Object.assign({}, stream));
  812.     // These are wiped out now and rebuilt later from the various per-period
  813.     // streams that match this output.
  814.     clone.originalId = null;
  815.     clone.createSegmentIndex = () => Promise.resolve();
  816.     clone.closeSegmentIndex = () => {
  817.       if (clone.segmentIndex) {
  818.         clone.segmentIndex.release();
  819.         clone.segmentIndex = null;
  820.       }
  821.       // Close the segment index of the matched streams.
  822.       if (clone.matchedStreams) {
  823.         for (const match of clone.matchedStreams) {
  824.           if (match.segmentIndex) {
  825.             match.segmentIndex.release();
  826.             match.segmentIndex = null;
  827.           }
  828.         }
  829.       }
  830.     };
  832.     // Clone roles array so this output stream can own it.
  833.     clone.roles = clone.roles.slice();
  834.     clone.segmentIndex = null;
  835.     clone.emsgSchemeIdUris = [];
  836.     clone.keyIds = new Set();
  837.     clone.closedCaptions = stream.closedCaptions ?
  838.       new Map(stream.closedCaptions) : null;
  839.     clone.trickModeVideo = null;
  841.     return clone;
  842.   }
  844.   /**
  845.    * Clone a StreamDB to make an output stream for combining others across
  846.    * periods.
  847.    *
  848.    * @param {shaka.extern.StreamDB} streamDb
  849.    * @return {shaka.extern.StreamDB}
  850.    * @private
  851.    */
  852.   static cloneStreamDB_(streamDb) {
  853.     const clone = /** @type {shaka.extern.StreamDB} */(Object.assign(
  854.         {}, streamDb));
  856.     // Clone roles array so this output stream can own it.
  857.     clone.roles = clone.roles.slice();
  858.     // These are wiped out now and rebuilt later from the various per-period
  859.     // streams that match this output.
  860.     clone.keyIds = new Set();
  861.     clone.segments = [];
  862.     clone.variantIds = [];
  863.     clone.closedCaptions = streamDb.closedCaptions ?
  864.       new Map(streamDb.closedCaptions) : null;
  866.     return clone;
  867.   }
  869.   /**
  870.    * Combine the various fields of the input Stream into the output.
  871.    *
  872.    * @param {shaka.extern.Stream} output
  873.    * @param {shaka.extern.Stream} input
  874.    * @private
  875.    */
  876.   static concatenateStreams_(output, input) {
  877.     // We keep the original stream's resolution, frame rate,
  878.     // sample rate, and channel count to ensure that it's properly
  879.     // matched with similar content in other periods further down
  880.     // the line.
  882.     // Combine arrays, keeping only the unique elements
  883.     const combineArrays = (output, input) => {
  884.       if (!output) {
  885.         output = [];
  886.       }
  887.       for (const item of input) {
  888.         if (!output.includes(item)) {
  889.           output.push(item);
  890.         }
  891.       }
  892.       return output;
  893.     };
  894.     output.roles = combineArrays(output.roles, input.roles);
  896.     if (input.emsgSchemeIdUris) {
  897.       output.emsgSchemeIdUris = combineArrays(
  898.           output.emsgSchemeIdUris, input.emsgSchemeIdUris);
  899.     }
  901.     for (const keyId of input.keyIds) {
  902.       output.keyIds.add(keyId);
  903.     }
  905.     if (output.originalId == null) {
  906.       output.originalId = input.originalId;
  907.     } else {
  908.       const newOriginalId = (input.originalId || '');
  909.       if (newOriginalId && !output.originalId.endsWith(newOriginalId)) {
  910.         output.originalId += ',' + newOriginalId;
  911.       }
  912.     }
  914.     const commonDrmInfos = shaka.util.DrmUtils.getCommonDrmInfos(
  915.         output.drmInfos, input.drmInfos);
  916.     if (input.drmInfos.length && output.drmInfos.length &&
  917.         !commonDrmInfos.length) {
  918.       throw new shaka.util.Error(
  919.           shaka.util.Error.Severity.CRITICAL,
  920.           shaka.util.Error.Category.MANIFEST,
  921.           shaka.util.Error.Code.INCONSISTENT_DRM_ACROSS_PERIODS);
  922.     }
  923.     output.drmInfos = commonDrmInfos;
  925.     // The output is encrypted if any input was encrypted.
  926.     output.encrypted = output.encrypted || input.encrypted;
  928.     // Combine the closed captions maps.
  929.     if (input.closedCaptions) {
  930.       if (!output.closedCaptions) {
  931.         output.closedCaptions = new Map();
  932.       }
  933.       for (const [key, value] of input.closedCaptions) {
  934.         output.closedCaptions.set(key, value);
  935.       }
  936.     }
  938.     // Prioritize the highest bandwidth
  939.     if (output.bandwidth && input.bandwidth) {
  940.       output.bandwidth = Math.max(output.bandwidth, input.bandwidth);
  941.     }
  943.     // Combine trick-play video streams, if present.
  944.     if (input.trickModeVideo) {
  945.       if (!output.trickModeVideo) {
  946.         // Create a fresh output stream for trick-mode playback.
  947.         output.trickModeVideo = shaka.util.PeriodCombiner.cloneStream_(
  948.             input.trickModeVideo);
  949.         output.trickModeVideo.matchedStreams = [];
  950.         output.trickModeVideo.createSegmentIndex = () => {
  951.           if (output.trickModeVideo.segmentIndex) {
  952.             return Promise.resolve();
  953.           }
  954.           const segmentIndex = new shaka.media.MetaSegmentIndex();
  955.           goog.asserts.assert(output.trickModeVideo.matchedStreams,
  956.               'trickmode matched streams should exist');
  957.           for (const stream of output.trickModeVideo.matchedStreams) {
  958.             goog.asserts.assert(stream.segmentIndex,
  959.                 'trickmode segment index should exist');
  960.             segmentIndex.appendSegmentIndex(stream.segmentIndex);
  961.           }
  962.           output.trickModeVideo.segmentIndex = segmentIndex;
  964.           return Promise.resolve();
  965.         };
  966.       }
  968.       // Concatenate the trick mode input onto the trick mode output.
  969.       output.trickModeVideo.matchedStreams.push(input.trickModeVideo);
  970.       shaka.util.PeriodCombiner.concatenateStreams_(
  971.           output.trickModeVideo, input.trickModeVideo);
  972.     } else if (output.trickModeVideo) {
  973.       // We have a trick mode output, but no input from this Period.  Fill it in
  974.       // from the standard input Stream.
  975.       output.trickModeVideo.matchedStreams.push(input);
  976.       shaka.util.PeriodCombiner.concatenateStreams_(
  977.           output.trickModeVideo, input);
  978.     }
  979.   }
  981.   /**
  982.    * Combine the various fields of the input StreamDB into the output.
  983.    *
  984.    * @param {shaka.extern.StreamDB} output
  985.    * @param {shaka.extern.StreamDB} input
  986.    * @private
  987.    */
  988.   static concatenateStreamDBs_(output, input) {
  989.     // Combine arrays, keeping only the unique elements
  990.     const combineArrays = (output, input) => {
  991.       if (!output) {
  992.         output = [];
  993.       }
  994.       for (const item of input) {
  995.         if (!output.includes(item)) {
  996.           output.push(item);
  997.         }
  998.       }
  999.       return output;
  1000.     };
  1001.     output.roles = combineArrays(output.roles, input.roles);
  1003.     for (const keyId of input.keyIds) {
  1004.       output.keyIds.add(keyId);
  1005.     }
  1007.     // The output is encrypted if any input was encrypted.
  1008.     output.encrypted = output.encrypted && input.encrypted;
  1010.     // Concatenate segments without de-duping.
  1011.     output.segments.push(...input.segments);
  1013.     // Combine the closed captions maps.
  1014.     if (input.closedCaptions) {
  1015.       if (!output.closedCaptions) {
  1016.         output.closedCaptions = new Map();
  1017.       }
  1018.       for (const [key, value] of input.closedCaptions) {
  1019.         output.closedCaptions.set(key, value);
  1020.       }
  1021.     }
  1022.   }
  1024.   /**
  1025.    * Finds streams in all periods which match the output stream.
  1026.    *
  1027.    * @param {!Array<!Map<string, T>>} streamsPerPeriod
  1028.    * @param {T} outputStream
  1029.    * @param {boolean=} shouldAppend
  1030.    *
  1031.    * @template T
  1032.    * Accepts either a StreamDB or Stream type.
  1033.    *
  1034.    * @private
  1035.    */
  1036.   findMatchesInAllPeriods_(streamsPerPeriod, outputStream,
  1037.       shouldAppend = false) {
  1038.     const matches = shouldAppend ? outputStream.matchedStreams : [];
  1039.     for (const streams of streamsPerPeriod) {
  1040.       const match = this.findBestMatchInPeriod_(streams, outputStream);
  1041.       if (!match) {
  1042.         return;
  1043.       }
  1044.       matches.push(match);
  1045.     }
  1046.     outputStream.matchedStreams = matches;
  1047.   }
  1049.   /**
  1050.    * Find the best match for the output stream.
  1051.    *
  1052.    * @param {!Map<string, T>} streams
  1053.    * @param {T} outputStream
  1054.    * @return {?T}  Returns null if no match can be found.
  1055.    *
  1056.    * @template T
  1057.    * Accepts either a StreamDB or Stream type.
  1058.    *
  1059.    * @private
  1060.    */
  1061.   findBestMatchInPeriod_(streams, outputStream) {
  1062.     const getKey = {
  1063.       'audio': shaka.util.PeriodCombiner.generateAudioKey_,
  1064.       'video': shaka.util.PeriodCombiner.generateVideoKey_,
  1065.       'text': shaka.util.PeriodCombiner.generateTextKey_,
  1066.       'image': shaka.util.PeriodCombiner.generateImageKey_,
  1067.     }[outputStream.type];
  1069.     let best = null;
  1070.     const key = getKey(outputStream);
  1071.     if (streams.has(key)) {
  1072.       // We've found exact match by hashing.
  1073.       best = streams.get(key);
  1074.     } else {
  1075.       // We haven't found exact match, try to find the best one via
  1076.       // linear search.
  1077.       const areCompatible = {
  1078.         'audio': (os, s) => this.areAVStreamsCompatible_(os, s),
  1079.         'video': (os, s) => this.areAVStreamsCompatible_(os, s),
  1080.         'text': shaka.util.PeriodCombiner.areTextStreamsCompatible_,
  1081.         'image': shaka.util.PeriodCombiner.areImageStreamsCompatible_,
  1082.       }[outputStream.type];
  1083.       const isBetterMatch = {
  1084.         'audio': shaka.util.PeriodCombiner.isAudioStreamBetterMatch_,
  1085.         'video': shaka.util.PeriodCombiner.isVideoStreamBetterMatch_,
  1086.         'text': shaka.util.PeriodCombiner.isTextStreamBetterMatch_,
  1087.         'image': shaka.util.PeriodCombiner.isImageStreamBetterMatch_,
  1088.       }[outputStream.type];
  1090.       for (const stream of streams.values()) {
  1091.         if (!areCompatible(outputStream, stream)) {
  1092.           continue;
  1093.         }
  1095.         if (outputStream.fastSwitching != stream.fastSwitching) {
  1096.           continue;
  1097.         }
  1099.         if (!best || isBetterMatch(outputStream, best, stream)) {
  1100.           best = stream;
  1101.         }
  1102.       }
  1103.     }
  1105.     // Remove just found stream if configured to, so possible future linear
  1106.     // searches can be faster.
  1107.     if (this.useStreamOnce_ && !shaka.util.PeriodCombiner.isDummy_(best)) {
  1108.       streams.delete(getKey(best));
  1109.     }
  1111.     return best;
  1112.   }
  1114.   /**
  1115.    * @param {T} a
  1116.    * @param {T} b
  1117.    * @return {boolean}
  1118.    *
  1119.    * @template T
  1120.    * Accepts either a StreamDB or Stream type.
  1121.    *
  1122.    * @private
  1123.    */
  1124.   static areAVStreamsExactMatch_(a, b) {
  1125.     if (a.mimeType != b.mimeType) {
  1126.       return false;
  1127.     }
  1128.     return shaka.util.PeriodCombiner.getCodec_(a.codecs) ===
  1129.         shaka.util.PeriodCombiner.getCodec_(b.codecs);
  1130.   }
  1132.   /**
  1133.    * @param {boolean} allowed If set to true, multi-mimeType or multi-codec
  1134.    *   variants will be allowed.
  1135.    * @export
  1136.    */
  1137.   setAllowMultiTypeVariants(allowed) {
  1138.     this.multiTypeVariantsAllowed_ = allowed;
  1139.   }
  1141.   /**
  1142.    * @param {boolean} useOnce if true, stream will be used only once in period
  1143.    *   flattening algoritnm.
  1144.    * @export
  1145.    */
  1146.   setUseStreamOnce(useOnce) {
  1147.     this.useStreamOnce_ = useOnce;
  1148.   }
  1150.   /**
  1151.    * @param {T} outputStream An audio or video output stream
  1152.    * @param {T} candidate A candidate stream to be combined with the output
  1153.    * @return {boolean} True if the candidate could be combined with the
  1154.    *   output stream
  1155.    *
  1156.    * @template T
  1157.    * Accepts either a StreamDB or Stream type.
  1158.    *
  1159.    * @private
  1160.    */
  1161.   areAVStreamsCompatible_(outputStream, candidate) {
  1162.     // Check for an exact match.
  1163.     if (!shaka.util.PeriodCombiner.areAVStreamsExactMatch_(
  1164.         outputStream, candidate)) {
  1165.       // It's not an exact match. See if we can do multi-codec or multi-mimeType
  1166.       // stream instead, using SourceBuffer.changeType.
  1167.       if (!this.multiTypeVariantsAllowed_) {
  1168.         return false;
  1169.       }
  1170.     }
  1172.     // This field is only available on Stream, not StreamDB.
  1173.     if (outputStream.drmInfos) {
  1174.       // Check for compatible DRM systems.  Note that clear streams are
  1175.       // implicitly compatible with any DRM and with each other.
  1176.       if (!shaka.util.DrmUtils.areDrmCompatible(outputStream.drmInfos,
  1177.           candidate.drmInfos)) {
  1178.         return false;
  1179.       }
  1180.     }
  1182.     return true;
  1183.   }
  1185.   /**
  1186.    * @param {T} outputStream A text output stream
  1187.    * @param {T} candidate A candidate stream to be combined with the output
  1188.    * @return {boolean} True if the candidate could be combined with the
  1189.    *   output
  1190.    *
  1191.    * @template T
  1192.    * Accepts either a StreamDB or Stream type.
  1193.    *
  1194.    * @private
  1195.    */
  1196.   static areTextStreamsCompatible_(outputStream, candidate) {
  1197.     const LanguageUtils = shaka.util.LanguageUtils;
  1199.     // For text, we don't care about MIME type or codec.  We can always switch
  1200.     // between text types.
  1202.     // If the candidate is a dummy, then it is compatible, and we could use it
  1203.     // if nothing else matches.
  1204.     if (!candidate.language) {
  1205.       return true;
  1206.     }
  1208.     // Forced subtitles should be treated as unique streams
  1209.     if (outputStream.forced !== candidate.forced) {
  1210.       return false;
  1211.     }
  1213.     const languageRelatedness = LanguageUtils.relatedness(
  1214.         outputStream.language, candidate.language);
  1216.     // We will strictly avoid combining text across languages or "kinds"
  1217.     // (caption vs subtitle).
  1218.     if (languageRelatedness == 0 ||
  1219.         candidate.kind != outputStream.kind) {
  1220.       return false;
  1221.     }
  1223.     return true;
  1224.   }
  1226.   /**
  1227.    * @param {T} outputStream A image output stream
  1228.    * @param {T} candidate A candidate stream to be combined with the output
  1229.    * @return {boolean} True if the candidate could be combined with the
  1230.    *   output
  1231.    *
  1232.    * @template T
  1233.    * Accepts either a StreamDB or Stream type.
  1234.    *
  1235.    * @private
  1236.    */
  1237.   static areImageStreamsCompatible_(outputStream, candidate) {
  1238.     // For image, we don't care about MIME type.  We can always switch
  1239.     // between image types.
  1241.     return true;
  1242.   }
  1244.   /**
  1245.    * @param {T} outputStream An audio output stream
  1246.    * @param {T} best The best match so far for this period
  1247.    * @param {T} candidate A candidate stream which might be better
  1248.    * @return {boolean} True if the candidate is a better match
  1249.    *
  1250.    * @template T
  1251.    * Accepts either a StreamDB or Stream type.
  1252.    *
  1253.    * @private
  1254.    */
  1255.   static isAudioStreamBetterMatch_(outputStream, best, candidate) {
  1256.     const LanguageUtils = shaka.util.LanguageUtils;
  1257.     const {BETTER, EQUAL, WORSE} = shaka.util.PeriodCombiner.BetterOrWorse;
  1259.     // An exact match is better than a non-exact match.
  1260.     const bestIsExact = shaka.util.PeriodCombiner.areAVStreamsExactMatch_(
  1261.         outputStream, best);
  1262.     const candidateIsExact = shaka.util.PeriodCombiner.areAVStreamsExactMatch_(
  1263.         outputStream, candidate);
  1264.     if (bestIsExact && !candidateIsExact) {
  1265.       return false;
  1266.     }
  1267.     if (!bestIsExact && candidateIsExact) {
  1268.       return true;
  1269.     }
  1271.     // The most important thing is language.  In some cases, we will accept a
  1272.     // different language across periods when we must.
  1273.     const bestRelatedness = LanguageUtils.relatedness(
  1274.         outputStream.language, best.language);
  1275.     const candidateRelatedness = LanguageUtils.relatedness(
  1276.         outputStream.language, candidate.language);
  1278.     if (candidateRelatedness > bestRelatedness) {
  1279.       return true;
  1280.     }
  1281.     if (candidateRelatedness < bestRelatedness) {
  1282.       return false;
  1283.     }
  1285.     // If language-based differences haven't decided this, look at labels.
  1286.     // If available options differ, look does any matches with output stream.
  1287.     if (best.label !== candidate.label) {
  1288.       if (outputStream.label === best.label) {
  1289.         return false;
  1290.       }
  1291.       if (outputStream.label === candidate.label) {
  1292.         return true;
  1293.       }
  1294.     }
  1296.     // If label-based differences haven't decided this, look at roles.  If
  1297.     // the candidate has more roles in common with the output, upgrade to the
  1298.     // candidate.
  1299.     if (outputStream.roles.length) {
  1300.       const bestRoleMatches =
  1301.           best.roles.filter((role) => outputStream.roles.includes(role));
  1302.       const candidateRoleMatches =
  1303.           candidate.roles.filter((role) => outputStream.roles.includes(role));
  1304.       if (candidateRoleMatches.length > bestRoleMatches.length) {
  1305.         return true;
  1306.       } else if (candidateRoleMatches.length < bestRoleMatches.length) {
  1307.         return false;
  1308.       } else if (candidate.roles.length !== best.roles.length) {
  1309.         // Both streams have the same role overlap with the outputStream
  1310.         // If this is the case, choose the stream with the fewer roles overall.
  1311.         // Streams that match best together tend to be streams with the same
  1312.         // roles, e g stream1 with roles [r1, r2] is likely a better match
  1313.         // for stream2 with roles [r1, r2] vs stream3 with roles
  1314.         // [r1, r2, r3, r4].
  1315.         // If we match stream1 with stream3 due to the same role overlap,
  1316.         // stream2 is likely to be left unmatched and error out later.
  1317.         // See https://github.com/shaka-project/shaka-player/issues/2542 for
  1318.         // more details.
  1319.         return candidate.roles.length < best.roles.length;
  1320.       }
  1321.     } else if (!candidate.roles.length && best.roles.length) {
  1322.       // If outputStream has no roles, and only one of the streams has no roles,
  1323.       // choose the one with no roles.
  1324.       return true;
  1325.     } else if (candidate.roles.length && !best.roles.length) {
  1326.       return false;
  1327.     }
  1329.     // If the language doesn't match, but the candidate is the "primary"
  1330.     // language, then that should be preferred as a fallback.
  1331.     if (!best.primary && candidate.primary) {
  1332.       return true;
  1333.     }
  1334.     if (best.primary && !candidate.primary) {
  1335.       return false;
  1336.     }
  1338.     // If language-based and role-based features are equivalent, take the audio
  1339.     // with the closes channel count to the output.
  1340.     const channelsBetterOrWorse =
  1341.         shaka.util.PeriodCombiner.compareClosestPreferLower(
  1342.             outputStream.channelsCount,
  1343.             best.channelsCount,
  1344.             candidate.channelsCount);
  1345.     if (channelsBetterOrWorse == BETTER) {
  1346.       return true;
  1347.     } else if (channelsBetterOrWorse == WORSE) {
  1348.       return false;
  1349.     }
  1351.     // If channels are equal, take the closest sample rate to the output.
  1352.     const sampleRateBetterOrWorse =
  1353.         shaka.util.PeriodCombiner.compareClosestPreferLower(
  1354.             outputStream.audioSamplingRate,
  1355.             best.audioSamplingRate,
  1356.             candidate.audioSamplingRate);
  1357.     if (sampleRateBetterOrWorse == BETTER) {
  1358.       return true;
  1359.     } else if (sampleRateBetterOrWorse == WORSE) {
  1360.       return false;
  1361.     }
  1363.     if (outputStream.bandwidth) {
  1364.       // Take the audio with the closest bandwidth to the output.
  1365.       const bandwidthBetterOrWorse =
  1366.           shaka.util.PeriodCombiner.compareClosestPreferMinimalAbsDiff_(
  1367.               outputStream.bandwidth,
  1368.               best.bandwidth,
  1369.               candidate.bandwidth);
  1370.       if (bandwidthBetterOrWorse == BETTER) {
  1371.         return true;
  1372.       } else if (bandwidthBetterOrWorse == WORSE) {
  1373.         return false;
  1374.       }
  1375.     }
  1377.     // If the result of each comparison was inconclusive, default to false.
  1378.     return false;
  1379.   }
  1381.   /**
  1382.    * @param {T} outputStream A video output stream
  1383.    * @param {T} best The best match so far for this period
  1384.    * @param {T} candidate A candidate stream which might be better
  1385.    * @return {boolean} True if the candidate is a better match
  1386.    *
  1387.    * @template T
  1388.    * Accepts either a StreamDB or Stream type.
  1389.    *
  1390.    * @private
  1391.    */
  1392.   static isVideoStreamBetterMatch_(outputStream, best, candidate) {
  1393.     const {BETTER, EQUAL, WORSE} = shaka.util.PeriodCombiner.BetterOrWorse;
  1395.     // An exact match is better than a non-exact match.
  1396.     const bestIsExact = shaka.util.PeriodCombiner.areAVStreamsExactMatch_(
  1397.         outputStream, best);
  1398.     const candidateIsExact = shaka.util.PeriodCombiner.areAVStreamsExactMatch_(
  1399.         outputStream, candidate);
  1400.     if (bestIsExact && !candidateIsExact) {
  1401.       return false;
  1402.     }
  1403.     if (!bestIsExact && candidateIsExact) {
  1404.       return true;
  1405.     }
  1407.     // Take the video with the closest resolution to the output.
  1408.     const resolutionBetterOrWorse =
  1409.         shaka.util.PeriodCombiner.compareClosestPreferLower(
  1410.             outputStream.width * outputStream.height,
  1411.             best.width * best.height,
  1412.             candidate.width * candidate.height);
  1413.     if (resolutionBetterOrWorse == BETTER) {
  1414.       return true;
  1415.     } else if (resolutionBetterOrWorse == WORSE) {
  1416.       return false;
  1417.     }
  1419.     // We may not know the frame rate for the content, in which case this gets
  1420.     // skipped.
  1421.     if (outputStream.frameRate) {
  1422.       // Take the video with the closest frame rate to the output.
  1423.       const frameRateBetterOrWorse =
  1424.           shaka.util.PeriodCombiner.compareClosestPreferLower(
  1425.               outputStream.frameRate,
  1426.               best.frameRate,
  1427.               candidate.frameRate);
  1428.       if (frameRateBetterOrWorse == BETTER) {
  1429.         return true;
  1430.       } else if (frameRateBetterOrWorse == WORSE) {
  1431.         return false;
  1432.       }
  1433.     }
  1436.     if (outputStream.bandwidth) {
  1437.       // Take the video with the closest bandwidth to the output.
  1438.       const bandwidthBetterOrWorse =
  1439.           shaka.util.PeriodCombiner.compareClosestPreferMinimalAbsDiff_(
  1440.               outputStream.bandwidth,
  1441.               best.bandwidth,
  1442.               candidate.bandwidth);
  1443.       if (bandwidthBetterOrWorse == BETTER) {
  1444.         return true;
  1445.       } else if (bandwidthBetterOrWorse == WORSE) {
  1446.         return false;
  1447.       }
  1448.     }
  1450.     // If the result of each comparison was inconclusive, default to false.
  1451.     return false;
  1452.   }
  1454.   /**
  1455.    * @param {T} outputStream A text output stream
  1456.    * @param {T} best The best match so far for this period
  1457.    * @param {T} candidate A candidate stream which might be better
  1458.    * @return {boolean} True if the candidate is a better match
  1459.    *
  1460.    * @template T
  1461.    * Accepts either a StreamDB or Stream type.
  1462.    *
  1463.    * @private
  1464.    */
  1465.   static isTextStreamBetterMatch_(outputStream, best, candidate) {
  1466.     const LanguageUtils = shaka.util.LanguageUtils;
  1468.     // The most important thing is language.  In some cases, we will accept a
  1469.     // different language across periods when we must.
  1470.     const bestRelatedness = LanguageUtils.relatedness(
  1471.         outputStream.language, best.language);
  1472.     const candidateRelatedness = LanguageUtils.relatedness(
  1473.         outputStream.language, candidate.language);
  1475.     if (candidateRelatedness > bestRelatedness) {
  1476.       return true;
  1477.     }
  1478.     if (candidateRelatedness < bestRelatedness) {
  1479.       return false;
  1480.     }
  1482.     // If the language doesn't match, but the candidate is the "primary"
  1483.     // language, then that should be preferred as a fallback.
  1484.     if (!best.primary && candidate.primary) {
  1485.       return true;
  1486.     }
  1487.     if (best.primary && !candidate.primary) {
  1488.       return false;
  1489.     }
  1491.     // If language-based differences haven't decided this, look at labels.
  1492.     // If available options differ, look does any matches with output stream.
  1493.     if (best.label !== candidate.label) {
  1494.       if (outputStream.label === best.label) {
  1495.         return false;
  1496.       }
  1497.       if (outputStream.label === candidate.label) {
  1498.         return true;
  1499.       }
  1500.     }
  1502.     // If the candidate has more roles in common with the output, upgrade to the
  1503.     // candidate.
  1504.     if (outputStream.roles.length) {
  1505.       const bestRoleMatches =
  1506.           best.roles.filter((role) => outputStream.roles.includes(role));
  1507.       const candidateRoleMatches =
  1508.           candidate.roles.filter((role) => outputStream.roles.includes(role));
  1509.       if (candidateRoleMatches.length > bestRoleMatches.length) {
  1510.         return true;
  1511.       }
  1512.       if (candidateRoleMatches.length < bestRoleMatches.length) {
  1513.         return false;
  1514.       }
  1515.     } else if (!candidate.roles.length && best.roles.length) {
  1516.       // If outputStream has no roles, and only one of the streams has no roles,
  1517.       // choose the one with no roles.
  1518.       return true;
  1519.     } else if (candidate.roles.length && !best.roles.length) {
  1520.       return false;
  1521.     }
  1523.     // If the candidate has the same MIME type and codec, upgrade to the
  1524.     // candidate.  It's not required that text streams use the same format
  1525.     // across periods, but it's a helpful signal.  Some content in our demo app
  1526.     // contains the same languages repeated with two different text formats in
  1527.     // each period.  This condition ensures that all text streams are used.
  1528.     // Otherwise, we wind up with some one stream of each language left unused,
  1529.     // triggering a failure.
  1530.     if (candidate.mimeType == outputStream.mimeType &&
  1531.         candidate.codecs == outputStream.codecs &&
  1532.         (best.mimeType != outputStream.mimeType ||
  1533.          best.codecs != outputStream.codecs)) {
  1534.       return true;
  1535.     }
  1537.     // If the result of each comparison was inconclusive, default to false.
  1538.     return false;
  1539.   }
  1541.   /**
  1542.    * @param {T} outputStream A image output stream
  1543.    * @param {T} best The best match so far for this period
  1544.    * @param {T} candidate A candidate stream which might be better
  1545.    * @return {boolean} True if the candidate is a better match
  1546.    *
  1547.    * @template T
  1548.    * Accepts either a StreamDB or Stream type.
  1549.    *
  1550.    * @private
  1551.    */
  1552.   static isImageStreamBetterMatch_(outputStream, best, candidate) {
  1553.     const {BETTER, EQUAL, WORSE} = shaka.util.PeriodCombiner.BetterOrWorse;
  1555.     // Take the image with the closest resolution to the output.
  1556.     const resolutionBetterOrWorse =
  1557.         shaka.util.PeriodCombiner.compareClosestPreferLower(
  1558.             outputStream.width * outputStream.height,
  1559.             best.width * best.height,
  1560.             candidate.width * candidate.height);
  1561.     if (resolutionBetterOrWorse == BETTER) {
  1562.       return true;
  1563.     } else if (resolutionBetterOrWorse == WORSE) {
  1564.       return false;
  1565.     }
  1567.     // If the result of each comparison was inconclusive, default to false.
  1568.     return false;
  1569.   }
  1571.   /**
  1572.    * Create a dummy StreamDB to fill in periods that are missing a certain type,
  1573.    * to avoid failing the general flattening algorithm.  This won't be used for
  1574.    * audio or video, since those are strictly required in all periods if they
  1575.    * exist in any period.
  1576.    *
  1577.    * @param {shaka.util.ManifestParserUtils.ContentType} type
  1578.    * @return {shaka.extern.StreamDB}
  1579.    * @private
  1580.    */
  1581.   static dummyStreamDB_(type) {
  1582.     return {
  1583.       id: 0,
  1584.       originalId: '',
  1585.       groupId: null,
  1586.       primary: false,
  1587.       type,
  1588.       mimeType: '',
  1589.       codecs: '',
  1590.       language: '',
  1591.       originalLanguage: null,
  1592.       label: null,
  1593.       width: null,
  1594.       height: null,
  1595.       encrypted: false,
  1596.       keyIds: new Set(),
  1597.       segments: [],
  1598.       variantIds: [],
  1599.       roles: [],
  1600.       forced: false,
  1601.       channelsCount: null,
  1602.       audioSamplingRate: null,
  1603.       spatialAudio: false,
  1604.       closedCaptions: null,
  1605.       external: false,
  1606.       fastSwitching: false,
  1607.     };
  1608.   }
  1610.   /**
  1611.    * Create a dummy Stream to fill in periods that are missing a certain type,
  1612.    * to avoid failing the general flattening algorithm.  This won't be used for
  1613.    * audio or video, since those are strictly required in all periods if they
  1614.    * exist in any period.
  1615.    *
  1616.    * @param {shaka.util.ManifestParserUtils.ContentType} type
  1617.    * @return {shaka.extern.Stream}
  1618.    * @private
  1619.    */
  1620.   static dummyStream_(type) {
  1621.     return {
  1622.       id: 0,
  1623.       originalId: '',
  1624.       groupId: null,
  1625.       createSegmentIndex: () => Promise.resolve(),
  1626.       segmentIndex: new shaka.media.SegmentIndex([]),
  1627.       mimeType: '',
  1628.       codecs: '',
  1629.       encrypted: false,
  1630.       drmInfos: [],
  1631.       keyIds: new Set(),
  1632.       language: '',
  1633.       originalLanguage: null,
  1634.       label: null,
  1635.       type,
  1636.       primary: false,
  1637.       trickModeVideo: null,
  1638.       emsgSchemeIdUris: null,
  1639.       roles: [],
  1640.       forced: false,
  1641.       channelsCount: null,
  1642.       audioSamplingRate: null,
  1643.       spatialAudio: false,
  1644.       closedCaptions: null,
  1645.       accessibilityPurpose: null,
  1646.       external: false,
  1647.       fastSwitching: false,
  1648.       fullMimeTypes: new Set(),
  1649.     };
  1650.   }
  1652.   /**
  1653.    * Compare the best value so far with the candidate value and the output
  1654.    * value.  Decide if the candidate is better, equal, or worse than the best
  1655.    * so far.  Any value less than or equal to the output is preferred over a
  1656.    * larger value, and closer to the output is better than farther.
  1657.    *
  1658.    * This provides us a generic way to choose things that should match as
  1659.    * closely as possible, like resolution, frame rate, audio channels, or
  1660.    * sample rate.  If we have to go higher to make a match, we will.  But if
  1661.    * the user selects 480p, for example, we don't want to surprise them with
  1662.    * 720p and waste bandwidth if there's another choice available to us.
  1663.    *
  1664.    * @param {number} outputValue
  1665.    * @param {number} bestValue
  1666.    * @param {number} candidateValue
  1667.    * @return {shaka.util.PeriodCombiner.BetterOrWorse}
  1668.    */
  1669.   static compareClosestPreferLower(outputValue, bestValue, candidateValue) {
  1670.     const {BETTER, EQUAL, WORSE} = shaka.util.PeriodCombiner.BetterOrWorse;
  1672.     // If one is the exact match for the output value, and the other isn't,
  1673.     // prefer the one that is the exact match.
  1674.     if (bestValue == outputValue && outputValue != candidateValue) {
  1675.       return WORSE;
  1676.     } else if (candidateValue == outputValue && outputValue != bestValue) {
  1677.       return BETTER;
  1678.     }
  1680.     if (bestValue > outputValue) {
  1681.       if (candidateValue <= outputValue) {
  1682.         // Any smaller-or-equal-to-output value is preferable to a
  1683.         // bigger-than-output value.
  1684.         return BETTER;
  1685.       }
  1687.       // Both "best" and "candidate" are greater than the output.  Take
  1688.       // whichever is closer.
  1689.       if (candidateValue - outputValue < bestValue - outputValue) {
  1690.         return BETTER;
  1691.       } else if (candidateValue - outputValue > bestValue - outputValue) {
  1692.         return WORSE;
  1693.       }
  1694.     } else {
  1695.       // The "best" so far is less than or equal to the output.  If the
  1696.       // candidate is bigger than the output, we don't want it.
  1697.       if (candidateValue > outputValue) {
  1698.         return WORSE;
  1699.       }
  1701.       // Both "best" and "candidate" are less than or equal to the output.
  1702.       // Take whichever is closer.
  1703.       if (outputValue - candidateValue < outputValue - bestValue) {
  1704.         return BETTER;
  1705.       } else if (outputValue - candidateValue > outputValue - bestValue) {
  1706.         return WORSE;
  1707.       }
  1708.     }
  1710.     return EQUAL;
  1711.   }
  1713.   /**
  1714.    * @param {number} outputValue
  1715.    * @param {number} bestValue
  1716.    * @param {number} candidateValue
  1717.    * @return {shaka.util.PeriodCombiner.BetterOrWorse}
  1718.    * @private
  1719.    */
  1720.   static compareClosestPreferMinimalAbsDiff_(
  1721.       outputValue, bestValue, candidateValue) {
  1722.     const {BETTER, EQUAL, WORSE} = shaka.util.PeriodCombiner.BetterOrWorse;
  1724.     const absDiffBest = Math.abs(outputValue - bestValue);
  1725.     const absDiffCandidate = Math.abs(outputValue - candidateValue);
  1726.     if (absDiffCandidate < absDiffBest) {
  1727.       return BETTER;
  1728.     } else if (absDiffBest < absDiffCandidate) {
  1729.       return WORSE;
  1730.     }
  1732.     return EQUAL;
  1733.   }
  1735.   /**
  1736.    * @param {T} stream
  1737.    * @return {boolean}
  1738.    * @template T
  1739.    * Accepts either a StreamDB or Stream type.
  1740.    * @private
  1741.    */
  1742.   static isDummy_(stream) {
  1743.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  1744.     switch (stream.type) {
  1745.       case ContentType.TEXT:
  1746.         return !stream.language;
  1747.       case ContentType.IMAGE:
  1748.         return !stream.tilesLayout;
  1749.       default:
  1750.         return false;
  1751.     }
  1752.   }
  1754.   /**
  1755.    * @param {T} v
  1756.    * @return {string}
  1757.    * @template T
  1758.    * Accepts either a StreamDB or Stream type.
  1759.    * @private
  1760.    */
  1761.   static generateVideoKey_(v) {
  1762.     return shaka.util.PeriodCombiner.generateKey_([
  1763.       v.fastSwitching,
  1764.       v.width,
  1765.       v.frameRate,
  1766.       shaka.util.PeriodCombiner.getCodec_(v.codecs),
  1767.       v.mimeType,
  1768.       v.label,
  1769.       v.roles,
  1770.       v.closedCaptions ? Array.from(v.closedCaptions.entries()) : null,
  1771.       v.bandwidth,
  1772.     ]);
  1773.   }
  1775.   /**
  1776.    * @param {T} a
  1777.    * @return {string}
  1778.    * @template T
  1779.    * Accepts either a StreamDB or Stream type.
  1780.    * @private
  1781.    */
  1782.   static generateAudioKey_(a) {
  1783.     return shaka.util.PeriodCombiner.generateKey_([
  1784.       a.fastSwitching,
  1785.       a.channelsCount,
  1786.       a.language,
  1787.       a.bandwidth,
  1788.       a.label,
  1789.       shaka.util.PeriodCombiner.getCodec_(a.codecs),
  1790.       a.mimeType,
  1791.       a.roles,
  1792.       a.audioSamplingRate,
  1793.       a.primary,
  1794.     ]);
  1795.   }
  1797.   /**
  1798.    * @param {T} t
  1799.    * @return {string}
  1800.    * @template T
  1801.    * Accepts either a StreamDB or Stream type.
  1802.    * @private
  1803.    */
  1804.   static generateTextKey_(t) {
  1805.     return shaka.util.PeriodCombiner.generateKey_([
  1806.       t.language,
  1807.       t.label,
  1808.       t.codecs,
  1809.       t.mimeType,
  1810.       t.bandwidth,
  1811.       t.roles,
  1812.     ]);
  1813.   }
  1815.   /**
  1816.    * @param {T} i
  1817.    * @return {string}
  1818.    * @template T
  1819.    * Accepts either a StreamDB or Stream type.
  1820.    * @private
  1821.    */
  1822.   static generateImageKey_(i) {
  1823.     return shaka.util.PeriodCombiner.generateKey_([
  1824.       i.width,
  1825.       i.codecs,
  1826.       i.mimeType,
  1827.     ]);
  1828.   }
  1830.   /**
  1831.    * @param {!Array<*>} values
  1832.    * @return {string}
  1833.    * @private
  1834.    */
  1835.   static generateKey_(values) {
  1836.     return JSON.stringify(values);
  1837.   }
  1839.   /**
  1840.    * @param {string} codecs
  1841.    * @return {string}
  1842.    * @private
  1843.    */
  1844.   static getCodec_(codecs) {
  1845.     if (!shaka.util.PeriodCombiner.memoizedCodecs.has(codecs)) {
  1846.       const normalizedCodec = shaka.util.MimeUtils.getNormalizedCodec(codecs);
  1847.       shaka.util.PeriodCombiner.memoizedCodecs.set(codecs, normalizedCodec);
  1848.     }
  1849.     return shaka.util.PeriodCombiner.memoizedCodecs.get(codecs);
  1850.   }
  1851. };
  1853. /**
  1854.  * @enum {number}
  1855.  */
  1856. shaka.util.PeriodCombiner.BetterOrWorse = {
  1857.   BETTER: 1,
  1858.   EQUAL: 0,
  1859.   WORSE: -1,
  1860. };
  1862. /**
  1863.  * @private {Map<string, string>}
  1864.  */
  1865. shaka.util.PeriodCombiner.memoizedCodecs = new Map();