Source: lib/dash/segment_template.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.dash.SegmentTemplate');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.dash.MpdUtils');
  11. goog.require('shaka.dash.SegmentBase');
  12. goog.require('shaka.log');
  13. goog.require('shaka.media.InitSegmentReference');
  14. goog.require('shaka.media.SegmentIndex');
  15. goog.require('shaka.media.SegmentReference');
  16. goog.require('shaka.util.Error');
  17. goog.require('shaka.util.IReleasable');
  18. goog.require('shaka.util.ManifestParserUtils');
  19. goog.require('shaka.util.ObjectUtils');
  20. goog.requireType('shaka.dash.DashParser');
  21. goog.requireType('shaka.media.PresentationTimeline');
  24. /**
  25.  * @summary A set of functions for parsing SegmentTemplate elements.
  26.  */
  27. shaka.dash.SegmentTemplate = class {
  28.   /**
  29.    * Creates a new StreamInfo object.
  30.    * Updates the existing SegmentIndex, if any.
  31.    *
  32.    * @param {shaka.dash.DashParser.Context} context
  33.    * @param {shaka.dash.DashParser.RequestSegmentCallback} requestSegment
  34.    * @param {!Object.<string, !shaka.extern.Stream>} streamMap
  35.    * @param {boolean} isUpdate True if the manifest is being updated.
  36.    * @param {number} segmentLimit The maximum number of segments to generate for
  37.    *   a SegmentTemplate with fixed duration.
  38.    * @param {!Object.<string, number>} periodDurationMap
  39.    * @param {shaka.extern.aes128Key|undefined} aes128Key
  40.    * @return {shaka.dash.DashParser.StreamInfo}
  41.    */
  42.   static createStreamInfo(
  43.       context, requestSegment, streamMap, isUpdate, segmentLimit,
  44.       periodDurationMap, aes128Key) {
  45.     goog.asserts.assert(context.representation.segmentTemplate,
  46.         'Should only be called with SegmentTemplate');
  47.     const SegmentTemplate = shaka.dash.SegmentTemplate;
  48.     const TimelineSegmentIndex = shaka.dash.TimelineSegmentIndex;
  50.     const initSegmentReference =
  51.         SegmentTemplate.createInitSegment_(context, aes128Key);
  53.     /** @type {shaka.dash.SegmentTemplate.SegmentTemplateInfo} */
  54.     const info = SegmentTemplate.parseSegmentTemplateInfo_(context);
  56.     SegmentTemplate.checkSegmentTemplateInfo_(context, info);
  58.     // Direct fields of context will be reassigned by the parser before
  59.     // generateSegmentIndex is called.  So we must make a shallow copy first,
  60.     // and use that in the generateSegmentIndex callbacks.
  61.     const shallowCopyOfContext =
  62.         shaka.util.ObjectUtils.shallowCloneObject(context);
  64.     if (info.indexTemplate) {
  65.       shaka.dash.SegmentBase.checkSegmentIndexSupport(
  66.           context, initSegmentReference);
  68.       return {
  69.         generateSegmentIndex: () => {
  70.           return SegmentTemplate.generateSegmentIndexFromIndexTemplate_(
  71.               shallowCopyOfContext, requestSegment, initSegmentReference,
  72.               info);
  73.         },
  74.       };
  75.     } else if (info.segmentDuration) {
  76.       if (!isUpdate && context.adaptationSet.contentType !== 'image') {
  77.         context.presentationTimeline.notifyMaxSegmentDuration(
  78.             info.segmentDuration);
  79.         context.presentationTimeline.notifyMinSegmentStartTime(
  80.             context.periodInfo.start);
  81.       }
  83.       return {
  84.         generateSegmentIndex: () => {
  85.           return SegmentTemplate.generateSegmentIndexFromDuration_(
  86.               shallowCopyOfContext, info, segmentLimit, initSegmentReference,
  87.               periodDurationMap, aes128Key);
  88.         },
  89.       };
  90.     } else {
  91.       /** @type {shaka.media.SegmentIndex} */
  92.       let segmentIndex = null;
  93.       let id = null;
  94.       let stream = null;
  95.       if (context.period.id && context.representation.id) {
  96.         // Only check/store the index if period and representation IDs are set.
  97.         id = context.period.id + ',' + context.representation.id;
  98.         stream = streamMap[id];
  99.         if (stream) {
  100.           segmentIndex = stream.segmentIndex;
  101.         }
  102.       }
  104.       const periodStart = context.periodInfo.start;
  105.       const periodEnd = context.periodInfo.duration ? periodStart +
  106.         context.periodInfo.duration : Infinity;
  108.       shaka.log.debug(`New manifest ${periodStart} - ${periodEnd}`);
  110.       /* When to fit segments.  All refactors should honor/update this table:
  111.        *
  112.        * | dynamic | infinite | last   | should | notes                     |
  113.        * |         | period   | period | fit    |                           |
  114.        * | ------- | -------- | ------ | ------ | ------------------------- |
  115.        * |     F   |     F    |    X   |    T   | typical VOD               |
  116.        * |     F   |     T    |    X   |    X   | impossible: infinite VOD  |
  117.        * |     T   |     F    |    F   |    T   | typical live, old period  |
  118.        * |     T   |     F    |    T   |    F   | typical IPR               |
  119.        * |     T   |     T    |    F   |    X   | impossible: old, infinite |
  120.        * |     T   |     T    |    T   |    F   | typical live, new period  |
  121.        */
  123.       // We never fit the final period of dynamic content, which could be
  124.       // infinite live (with no limit to fit to) or IPR (which would expand the
  125.       // most recent segment to the end of the presentation).
  126.       const shouldFit = !(context.dynamic && context.periodInfo.isLastPeriod);
  128.       if (!segmentIndex) {
  129.         shaka.log.debug(`Creating TSI with end ${periodEnd}`);
  130.         segmentIndex = new TimelineSegmentIndex(
  131.             info,
  132.             context.representation.id,
  133.             context.bandwidth,
  134.             context.representation.getBaseUris,
  135.             periodStart,
  136.             periodEnd,
  137.             initSegmentReference,
  138.             shouldFit,
  139.             aes128Key,
  140.             context.representation.segmentSequenceCadence,
  141.         );
  142.       } else {
  143.         const tsi = /** @type {!TimelineSegmentIndex} */(segmentIndex);
  144.         tsi.appendTemplateInfo(info, periodStart, periodEnd, shouldFit);
  146.         const availabilityStart =
  147.           context.presentationTimeline.getSegmentAvailabilityStart();
  148.         tsi.evict(availabilityStart);
  149.       }
  151.       if (info.timeline && context.adaptationSet.contentType !== 'image') {
  152.         const timeline = info.timeline;
  153.         context.presentationTimeline.notifyTimeRange(
  154.             timeline,
  155.             periodStart);
  156.       }
  158.       if (stream && context.dynamic) {
  159.         stream.segmentIndex = segmentIndex;
  160.       }
  162.       return {
  163.         generateSegmentIndex: () => {
  164.           // If segmentIndex is deleted, or segmentIndex's references are
  165.           // released by closeSegmentIndex(), we should set the value of
  166.           // segmentIndex again.
  167.           if (segmentIndex instanceof shaka.dash.TimelineSegmentIndex &&
  168.               segmentIndex.isEmpty()) {
  169.             segmentIndex.appendTemplateInfo(info, periodStart,
  170.                 periodEnd, shouldFit);
  171.           }
  172.           return Promise.resolve(segmentIndex);
  173.         },
  174.       };
  175.     }
  176.   }
  178.   /**
  179.    * @param {?shaka.dash.DashParser.InheritanceFrame} frame
  180.    * @return {Element}
  181.    * @private
  182.    */
  183.   static fromInheritance_(frame) {
  184.     return frame.segmentTemplate;
  185.   }
  187.   /**
  188.    * Parses a SegmentTemplate element into an info object.
  189.    *
  190.    * @param {shaka.dash.DashParser.Context} context
  191.    * @return {shaka.dash.SegmentTemplate.SegmentTemplateInfo}
  192.    * @private
  193.    */
  194.   static parseSegmentTemplateInfo_(context) {
  195.     const SegmentTemplate = shaka.dash.SegmentTemplate;
  196.     const MpdUtils = shaka.dash.MpdUtils;
  197.     const segmentInfo =
  198.         MpdUtils.parseSegmentInfo(context, SegmentTemplate.fromInheritance_);
  200.     const media = MpdUtils.inheritAttribute(
  201.         context, SegmentTemplate.fromInheritance_, 'media');
  202.     const index = MpdUtils.inheritAttribute(
  203.         context, SegmentTemplate.fromInheritance_, 'index');
  205.     return {
  206.       segmentDuration: segmentInfo.segmentDuration,
  207.       timescale: segmentInfo.timescale,
  208.       startNumber: segmentInfo.startNumber,
  209.       scaledPresentationTimeOffset: segmentInfo.scaledPresentationTimeOffset,
  210.       unscaledPresentationTimeOffset:
  211.           segmentInfo.unscaledPresentationTimeOffset,
  212.       timeline: segmentInfo.timeline,
  213.       mediaTemplate: media,
  214.       indexTemplate: index,
  215.     };
  216.   }
  218.   /**
  219.    * Verifies a SegmentTemplate info object.
  220.    *
  221.    * @param {shaka.dash.DashParser.Context} context
  222.    * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  223.    * @private
  224.    */
  225.   static checkSegmentTemplateInfo_(context, info) {
  226.     let n = 0;
  227.     n += info.indexTemplate ? 1 : 0;
  228.     n += info.timeline ? 1 : 0;
  229.     n += info.segmentDuration ? 1 : 0;
  231.     if (n == 0) {
  232.       shaka.log.error(
  233.           'SegmentTemplate does not contain any segment information:',
  234.           'the SegmentTemplate must contain either an index URL template',
  235.           'a SegmentTimeline, or a segment duration.',
  236.           context.representation);
  237.       throw new shaka.util.Error(
  238.           shaka.util.Error.Severity.CRITICAL,
  239.           shaka.util.Error.Category.MANIFEST,
  240.           shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  241.     } else if (n != 1) {
  242.       shaka.log.warning(
  243.           'SegmentTemplate containes multiple segment information sources:',
  244.           'the SegmentTemplate should only contain an index URL template,',
  245.           'a SegmentTimeline or a segment duration.',
  246.           context.representation);
  247.       if (info.indexTemplate) {
  248.         shaka.log.info('Using the index URL template by default.');
  249.         info.timeline = null;
  250.         info.segmentDuration = null;
  251.       } else {
  252.         goog.asserts.assert(info.timeline, 'There should be a timeline');
  253.         shaka.log.info('Using the SegmentTimeline by default.');
  254.         info.segmentDuration = null;
  255.       }
  256.     }
  258.     if (!info.indexTemplate && !info.mediaTemplate) {
  259.       shaka.log.error(
  260.           'SegmentTemplate does not contain sufficient segment information:',
  261.           'the SegmentTemplate\'s media URL template is missing.',
  262.           context.representation);
  263.       throw new shaka.util.Error(
  264.           shaka.util.Error.Severity.CRITICAL,
  265.           shaka.util.Error.Category.MANIFEST,
  266.           shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  267.     }
  268.   }
  270.   /**
  271.    * Generates a SegmentIndex from an index URL template.
  272.    *
  273.    * @param {shaka.dash.DashParser.Context} context
  274.    * @param {shaka.dash.DashParser.RequestSegmentCallback} requestSegment
  275.    * @param {shaka.media.InitSegmentReference} init
  276.    * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  277.    * @return {!Promise.<shaka.media.SegmentIndex>}
  278.    * @private
  279.    */
  280.   static generateSegmentIndexFromIndexTemplate_(
  281.       context, requestSegment, init, info) {
  282.     const MpdUtils = shaka.dash.MpdUtils;
  283.     const ManifestParserUtils = shaka.util.ManifestParserUtils;
  285.     goog.asserts.assert(info.indexTemplate, 'must be using index template');
  286.     const filledTemplate = MpdUtils.fillUriTemplate(
  287.         info.indexTemplate, context.representation.id,
  288.         null, null, context.bandwidth || null, null);
  290.     const resolvedUris = ManifestParserUtils.resolveUris(
  291.         context.representation.getBaseUris(), [filledTemplate]);
  293.     return shaka.dash.SegmentBase.generateSegmentIndexFromUris(
  294.         context, requestSegment, init, resolvedUris, 0, null,
  295.         info.scaledPresentationTimeOffset);
  296.   }
  298.   /**
  299.    * Generates a SegmentIndex from fixed-duration segments.
  300.    *
  301.    * @param {shaka.dash.DashParser.Context} context
  302.    * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  303.    * @param {number} segmentLimit The maximum number of segments to generate.
  304.    * @param {shaka.media.InitSegmentReference} initSegmentReference
  305.    * @param {!Object.<string, number>} periodDurationMap
  306.    * @param {shaka.extern.aes128Key|undefined} aes128Key
  307.    * @return {!Promise.<shaka.media.SegmentIndex>}
  308.    * @private
  309.    */
  310.   static generateSegmentIndexFromDuration_(
  311.       context, info, segmentLimit, initSegmentReference, periodDurationMap,
  312.       aes128Key) {
  313.     goog.asserts.assert(info.mediaTemplate,
  314.         'There should be a media template with duration');
  316.     const MpdUtils = shaka.dash.MpdUtils;
  317.     const ManifestParserUtils = shaka.util.ManifestParserUtils;
  319.     const presentationTimeline = context.presentationTimeline;
  321.     // Capture values that could change as the parsing context moves on to
  322.     // other parts of the manifest.
  323.     const periodStart = context.periodInfo.start;
  324.     const periodId = context.period.id;
  325.     const initialPeriodDuration = context.periodInfo.duration;
  327.     // For multi-period live streams the period duration may not be known until
  328.     // the following period appears in an updated manifest. periodDurationMap
  329.     // provides the updated period duration.
  330.     const getPeriodEnd = () => {
  331.       const periodDuration =
  332.         (periodId != null && periodDurationMap[periodId]) ||
  333.         initialPeriodDuration;
  334.       const periodEnd = periodDuration ?
  335.         (periodStart + periodDuration) : Infinity;
  336.       return periodEnd;
  337.     };
  339.     const segmentDuration = info.segmentDuration;
  340.     goog.asserts.assert(
  341.         segmentDuration != null, 'Segment duration must not be null!');
  343.     const startNumber = info.startNumber;
  344.     const timescale = info.timescale;
  346.     const template = info.mediaTemplate;
  347.     const bandwidth = context.bandwidth || null;
  348.     const id = context.representation.id;
  349.     const getBaseUris = context.representation.getBaseUris;
  351.     const timestampOffset = periodStart - info.scaledPresentationTimeOffset;
  353.     // Computes the range of presentation timestamps both within the period and
  354.     // available.  This is an intersection of the period range and the
  355.     // availability window.
  356.     const computeAvailablePeriodRange = () => {
  357.       return [
  358.         Math.max(
  359.             presentationTimeline.getSegmentAvailabilityStart(),
  360.             periodStart),
  362.         Math.min(
  363.             presentationTimeline.getSegmentAvailabilityEnd(),
  364.             getPeriodEnd()),
  365.       ];
  366.     };
  368.     // Computes the range of absolute positions both within the period and
  369.     // available.  The range is inclusive.  These are the positions for which we
  370.     // will generate segment references.
  371.     const computeAvailablePositionRange = () => {
  372.       // In presentation timestamps.
  373.       const availablePresentationTimes = computeAvailablePeriodRange();
  374.       goog.asserts.assert(availablePresentationTimes.every(isFinite),
  375.           'Available presentation times must be finite!');
  376.       goog.asserts.assert(availablePresentationTimes.every((x) => x >= 0),
  377.           'Available presentation times must be positive!');
  378.       goog.asserts.assert(segmentDuration != null,
  379.           'Segment duration must not be null!');
  381.       // In period-relative timestamps.
  382.       const availablePeriodTimes =
  383.           availablePresentationTimes.map((x) => x - periodStart);
  384.       // These may sometimes be reversed ([1] <= [0]) if the period is
  385.       // completely unavailable.  The logic will still work if this happens,
  386.       // because we will simply generate no references.
  388.       // In period-relative positions (0-based).
  389.       const availablePeriodPositions = [
  390.         Math.ceil(availablePeriodTimes[0] / segmentDuration),
  391.         Math.ceil(availablePeriodTimes[1] / segmentDuration) - 1,
  392.       ];
  394.       // In absolute positions.
  395.       const availablePresentationPositions =
  396.           availablePeriodPositions.map((x) => x + startNumber);
  397.       return availablePresentationPositions;
  398.     };
  400.     // For Live, we must limit the initial SegmentIndex in size, to avoid
  401.     // consuming too much CPU or memory for content with gigantic
  402.     // timeShiftBufferDepth (which can have values up to and including
  403.     // Infinity).
  404.     const range = computeAvailablePositionRange();
  405.     const minPosition = context.dynamic ?
  406.         Math.max(range[0], range[1] - segmentLimit + 1) :
  407.         range[0];
  408.     const maxPosition = range[1];
  410.     const references = [];
  411.     const createReference = (position) => {
  412.       // These inner variables are all scoped to the inner loop, and can be used
  413.       // safely in the callback below.
  415.       goog.asserts.assert(segmentDuration != null,
  416.           'Segment duration must not be null!');
  418.       // Relative to the period start.
  419.       const positionWithinPeriod = position - startNumber;
  420.       const segmentPeriodTime = positionWithinPeriod * segmentDuration;
  422.       // What will appear in the actual segment files.  The media timestamp is
  423.       // what is expected in the $Time$ template.
  424.       const segmentMediaTime = segmentPeriodTime +
  425.           info.scaledPresentationTimeOffset;
  427.       const getUris = () => {
  428.         let time = segmentMediaTime * timescale;
  429.         if ('BigInt' in window && time > Number.MAX_SAFE_INTEGER) {
  430.           time = BigInt(segmentMediaTime) * BigInt(timescale);
  431.         }
  432.         const mediaUri = MpdUtils.fillUriTemplate(
  433.             template, id, position, /* subNumber= */ null, bandwidth, time);
  434.         return ManifestParserUtils.resolveUris(getBaseUris(), [mediaUri]);
  435.       };
  437.       // Relative to the presentation.
  438.       const segmentStart = segmentPeriodTime + periodStart;
  439.       const trueSegmentEnd = segmentStart + segmentDuration;
  440.       // Cap the segment end at the period end so that references from the
  441.       // next period will fit neatly after it.
  442.       const segmentEnd = Math.min(trueSegmentEnd, getPeriodEnd());
  444.       // This condition will be true unless the segmentStart was >= periodEnd.
  445.       // If we've done the position calculations correctly, this won't happen.
  446.       goog.asserts.assert(segmentStart < segmentEnd,
  447.           'Generated a segment outside of the period!');
  449.       const ref = new shaka.media.SegmentReference(
  450.           segmentStart,
  451.           segmentEnd,
  452.           getUris,
  453.           /* startByte= */ 0,
  454.           /* endByte= */ null,
  455.           initSegmentReference,
  456.           timestampOffset,
  457.           /* appendWindowStart= */ periodStart,
  458.           /* appendWindowEnd= */ getPeriodEnd(),
  459.           /* partialReferences= */ [],
  460.           /* tilesLayout= */ '',
  461.           /* tileDuration= */ null,
  462.           /* syncTime= */ null,
  463.           shaka.media.SegmentReference.Status.AVAILABLE,
  464.           aes128Key);
  465.       // This is necessary information for thumbnail streams:
  466.       ref.trueEndTime = trueSegmentEnd;
  467.       return ref;
  468.     };
  470.     for (let position = minPosition; position <= maxPosition; ++position) {
  471.       const reference = createReference(position);
  472.       references.push(reference);
  473.     }
  475.     /** @type {shaka.media.SegmentIndex} */
  476.     const segmentIndex = new shaka.media.SegmentIndex(references);
  478.     // If the availability timeline currently ends before the period, we will
  479.     // need to add references over time.
  480.     const willNeedToAddReferences =
  481.         presentationTimeline.getSegmentAvailabilityEnd() < getPeriodEnd();
  483.     // When we start a live stream with a period that ends within the
  484.     // availability window we will not need to add more references, but we will
  485.     // need to evict old references.
  486.     const willNeedToEvictReferences = presentationTimeline.isLive();
  488.     if (willNeedToAddReferences || willNeedToEvictReferences) {
  489.       // The period continues to get longer over time, so check for new
  490.       // references once every |segmentDuration| seconds.
  491.       // We clamp to |minPosition| in case the initial range was reversed and no
  492.       // references were generated.  Otherwise, the update would start creating
  493.       // negative positions for segments in periods which begin in the future.
  494.       let nextPosition = Math.max(minPosition, maxPosition + 1);
  495.       segmentIndex.updateEvery(segmentDuration, () => {
  496.         // Evict any references outside the window.
  497.         const availabilityStartTime =
  498.           presentationTimeline.getSegmentAvailabilityStart();
  499.         segmentIndex.evict(availabilityStartTime);
  501.         // Compute any new references that need to be added.
  502.         const [_, maxPosition] = computeAvailablePositionRange();
  503.         const references = [];
  504.         while (nextPosition <= maxPosition) {
  505.           const reference = createReference(nextPosition);
  506.           references.push(reference);
  507.           nextPosition++;
  508.         }
  510.         // The timer must continue firing until the entire period is
  511.         // unavailable, so that all references will be evicted.
  512.         if (availabilityStartTime > getPeriodEnd() && !references.length) {
  513.           // Signal stop.
  514.           return null;
  515.         }
  516.         return references;
  517.       });
  518.     }
  520.     return Promise.resolve(segmentIndex);
  521.   }
  523.   /**
  524.    * Creates an init segment reference from a context object.
  525.    *
  526.    * @param {shaka.dash.DashParser.Context} context
  527.    * @param {shaka.extern.aes128Key|undefined} aes128Key
  528.    * @return {shaka.media.InitSegmentReference}
  529.    * @private
  530.    */
  531.   static createInitSegment_(context, aes128Key) {
  532.     const MpdUtils = shaka.dash.MpdUtils;
  533.     const ManifestParserUtils = shaka.util.ManifestParserUtils;
  534.     const SegmentTemplate = shaka.dash.SegmentTemplate;
  536.     const initialization = MpdUtils.inheritAttribute(
  537.         context, SegmentTemplate.fromInheritance_, 'initialization');
  538.     if (!initialization) {
  539.       return null;
  540.     }
  542.     const repId = context.representation.id;
  543.     const bandwidth = context.bandwidth || null;
  544.     const getBaseUris = context.representation.getBaseUris;
  545.     const getUris = () => {
  546.       goog.asserts.assert(initialization, 'Should have returned earler');
  547.       const filledTemplate = MpdUtils.fillUriTemplate(
  548.           initialization, repId, null, null, bandwidth, null);
  549.       const resolvedUris = ManifestParserUtils.resolveUris(
  550.           getBaseUris(), [filledTemplate]);
  551.       return resolvedUris;
  552.     };
  553.     const qualityInfo = shaka.dash.SegmentBase.createQualityInfo(context);
  554.     return new shaka.media.InitSegmentReference(
  555.         getUris,
  556.         /* startByte= */ 0,
  557.         /* endByte= */ null,
  558.         qualityInfo,
  559.         /* timescale= */ null,
  560.         /* segmentData= */ null,
  561.         aes128Key);
  562.   }
  563. };
  566. /**
  567.  * A SegmentIndex that returns segments references on demand from
  568.  * a segment timeline.
  569.  *
  570.  * @extends shaka.media.SegmentIndex
  571.  * @implements {shaka.util.IReleasable}
  572.  * @implements {Iterable.<!shaka.media.SegmentReference>}
  573.  *
  574.  * @private
  575.  *
  576.  */
  577. shaka.dash.TimelineSegmentIndex = class extends shaka.media.SegmentIndex {
  578.   /**
  579.    *
  580.    * @param {!shaka.dash.SegmentTemplate.SegmentTemplateInfo} templateInfo
  581.    * @param {?string} representationId
  582.    * @param {number} bandwidth
  583.    * @param {function():Array.<string>} getBaseUris
  584.    * @param {number} periodStart
  585.    * @param {number} periodEnd
  586.    * @param {shaka.media.InitSegmentReference} initSegmentReference
  587.    * @param {boolean} shouldFit
  588.    * @param {shaka.extern.aes128Key|undefined} aes128Key
  589.    * @param {number} segmentSequenceCadence
  590.   */
  591.   constructor(templateInfo, representationId, bandwidth, getBaseUris,
  592.       periodStart, periodEnd, initSegmentReference, shouldFit,
  593.       aes128Key, segmentSequenceCadence) {
  594.     super([]);
  596.     /** @private {?shaka.dash.SegmentTemplate.SegmentTemplateInfo} */
  597.     this.templateInfo_ = templateInfo;
  598.     /** @private {?string} */
  599.     this.representationId_ = representationId;
  600.     /** @private {number} */
  601.     this.bandwidth_ = bandwidth;
  602.     /** @private {function():Array.<string>} */
  603.     this.getBaseUris_ = getBaseUris;
  604.     /** @private {number} */
  605.     this.periodStart_ = periodStart;
  606.     /** @private {number} */
  607.     this.periodEnd_ = periodEnd;
  608.     /** @private {shaka.media.InitSegmentReference} */
  609.     this.initSegmentReference_ = initSegmentReference;
  610.     /** @private {shaka.extern.aes128Key|undefined} */
  611.     this.aes128Key_ = aes128Key;
  612.     /** @private {number} */
  613.     this.segmentSequenceCadence_ = segmentSequenceCadence;
  616.     if (shouldFit) {
  617.       this.fitTimeline();
  618.     }
  619.   }
  621.   /**
  622.    * @override
  623.    */
  624.   getNumReferences() {
  625.     if (this.templateInfo_) {
  626.       return this.templateInfo_.timeline.length;
  627.     } else {
  628.       return 0;
  629.     }
  630.   }
  632.   /**
  633.    * @override
  634.    */
  635.   release() {
  636.     super.release();
  637.     this.templateInfo_ = null;
  638.     // We cannot release other fields, as segment index can
  639.     // be recreated using only template info.
  640.   }
  643.   /**
  644.    * @override
  645.    */
  646.   evict(time) {
  647.     if (!this.templateInfo_) {
  648.       return;
  649.     }
  650.     shaka.log.debug(`${this.representationId_} Evicting at ${time}`);
  651.     let numToEvict = 0;
  652.     const timeline = this.templateInfo_.timeline;
  654.     for (let i = 0; i < timeline.length; i += 1) {
  655.       const range = timeline[i];
  656.       const end = range.end + this.periodStart_;
  657.       const start = range.start + this.periodStart_;
  659.       if (end <= time) {
  660.         shaka.log.debug(`Evicting ${start} - ${end}`);
  661.         numToEvict += 1;
  662.       } else {
  663.         break;
  664.       }
  665.     }
  667.     if (numToEvict > 0) {
  668.       this.templateInfo_.timeline = timeline.slice(numToEvict);
  669.       if (this.references.length >= numToEvict) {
  670.         this.references = this.references.slice(numToEvict);
  671.       }
  673.       this.numEvicted_ += numToEvict;
  675.       if (this.getNumReferences() === 0) {
  676.         this.release();
  677.       }
  678.     }
  679.   }
  681.   /**
  682.    * Merge new template info
  683.    * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  684.    * @param {number} periodStart
  685.    * @param {number} periodEnd
  686.    * @param {boolean} shouldFit
  687.    */
  688.   appendTemplateInfo(info, periodStart, periodEnd, shouldFit) {
  689.     if (!this.templateInfo_) {
  690.       this.templateInfo_ = info;
  691.       this.periodStart_ = periodStart;
  692.       this.periodEnd_ = periodEnd;
  693.     } else {
  694.       const currentTimeline = this.templateInfo_.timeline;
  696.       // Append timeline
  697.       const lastCurrentEntry = currentTimeline[currentTimeline.length - 1];
  698.       const newEntries = info.timeline.filter((entry) => {
  699.         return entry.start >= lastCurrentEntry.end;
  700.       });
  702.       if (newEntries.length > 0) {
  703.         shaka.log.debug(`Appending ${newEntries.length} entries`);
  704.         this.templateInfo_.timeline.push(...newEntries);
  705.       }
  707.       if (this.periodEnd_ !== periodEnd) {
  708.         this.periodEnd_ = periodEnd;
  709.       }
  710.     }
  712.     if (shouldFit) {
  713.       this.fitTimeline();
  714.     }
  715.   }
  717.   /**
  718.    *
  719.    * @param {number} time
  720.    */
  721.   isBeforeFirstEntry(time) {
  722.     const hasTimeline = this.templateInfo_ &&
  723.       this.templateInfo_.timeline && this.templateInfo_.timeline.length;
  725.     if (hasTimeline) {
  726.       const timeline = this.templateInfo_.timeline;
  727.       return time < timeline[0].start + this.periodStart_;
  728.     } else {
  729.       return false;
  730.     }
  731.   }
  733.   /**
  734.    * Fit timeline entries to period boundaries
  735.    */
  736.   fitTimeline() {
  737.     if (this.getIsImmutable()) {
  738.       return;
  739.     }
  740.     const timeline = this.templateInfo_.timeline;
  741.     while (timeline.length) {
  742.       const lastTimePeriod = timeline[timeline.length - 1];
  743.       if (lastTimePeriod.start >= this.periodEnd_) {
  744.         timeline.pop();
  745.       } else {
  746.         break;
  747.       }
  748.     }
  750.     this.evict(this.periodStart_);
  752.     if (timeline.length === 0) {
  753.       return;
  754.     }
  756.     if (this.periodEnd_ !== Infinity) {
  757.       // Adjust the last timeline entry to match the period end
  758.       const lastTimePeriod = timeline[timeline.length - 1];
  759.       // NOTE: end should be relative to period start
  760.       lastTimePeriod.end = this.periodEnd_ - this.periodStart_;
  761.     }
  762.   }
  764.   /**
  765.    * @override
  766.    */
  767.   find(time) {
  768.     shaka.log.debug(`Find ${time}`);
  770.     if (this.isBeforeFirstEntry(time)) {
  771.       return this.numEvicted_;
  772.     }
  774.     if (!this.templateInfo_) {
  775.       return null;
  776.     }
  778.     const timeline = this.templateInfo_.timeline;
  780.     // Early exit if the time isn't within this period
  781.     if (time < this.periodStart_ || time > this.periodEnd_) {
  782.       return null;
  783.     }
  785.     const lastIndex = timeline.length - 1;
  787.     for (let i = 0; i < timeline.length; i++) {
  788.       const range = timeline[i];
  789.       const start = range.start + this.periodStart_;
  790.       // A rounding error can cause /time/ to equal e.endTime or fall in between
  791.       // the references by a fraction of a second. To account for this, we use
  792.       // the start of the next segment as /end/, unless this is the last
  793.       // reference, in which case we use the period end as the /end/
  794.       let end = range.end + this.periodStart_;
  796.       if (i < lastIndex) {
  797.         end = timeline[i + 1].start + this.periodStart_;
  798.       }
  800.       if ((time >= start) && (time < end)) {
  801.         return i + this.numEvicted_;
  802.       }
  803.     }
  805.     return null;
  806.   }
  808.   /**
  809.    * @override
  810.    */
  811.   get(position) {
  812.     const correctedPosition = position - this.numEvicted_;
  813.     if (correctedPosition < 0 ||
  814.         correctedPosition >= this.getNumReferences() || !this.templateInfo_) {
  815.       return null;
  816.     }
  818.     let ref = this.references[correctedPosition];
  820.     if (!ref) {
  821.       const mediaTemplate = this.templateInfo_.mediaTemplate;
  822.       const range = this.templateInfo_.timeline[correctedPosition];
  823.       const segmentReplacement = range.segmentPosition;
  824.       const timeReplacement = this.templateInfo_
  825.           .unscaledPresentationTimeOffset + range.unscaledStart;
  826.       const timestampOffset = this.periodStart_ -
  827.         this.templateInfo_.scaledPresentationTimeOffset;
  829.       const partialSegmentRefs = [];
  831.       const partialDuration = (range.end - range.start) / range.partialSegments;
  833.       for (let i = 0; i < range.partialSegments; i++) {
  834.         const start = range.start + partialDuration * i;
  835.         const end = start + partialDuration;
  836.         const subNumber = i + 1;
  837.         let uris = null;
  838.         const getPartialUris = () => {
  839.           if (!this.templateInfo_) {
  840.             return [];
  841.           }
  842.           if (uris == null) {
  843.             uris = shaka.dash.TimelineSegmentIndex.createUris_(
  844.                 this.templateInfo_.mediaTemplate,
  845.                 this.representationId_,
  846.                 segmentReplacement,
  847.                 this.bandwidth_,
  848.                 timeReplacement,
  849.                 subNumber,
  850.                 this.getBaseUris_);
  851.           }
  852.           return uris;
  853.         };
  854.         const partial = new shaka.media.SegmentReference(
  855.             this.periodStart_ + start,
  856.             this.periodStart_ + end,
  857.             getPartialUris,
  858.             /* startByte= */ 0,
  859.             /* endByte= */ null,
  860.             this.initSegmentReference_,
  861.             timestampOffset,
  862.             this.periodStart_,
  863.             this.periodEnd_,
  864.             /* partialReferences= */ [],
  865.             /* tilesLayout= */ '',
  866.             /* tileDuration= */ null,
  867.             /* syncTime= */ null,
  868.             shaka.media.SegmentReference.Status.AVAILABLE,
  869.             this.aes128Key_);
  870.         if (this.segmentSequenceCadence_ == 0) {
  871.           if (i > 0) {
  872.             partial.markAsNonIndependent();
  873.           }
  874.         } else if ((i % this.segmentSequenceCadence_) != 0) {
  875.           partial.markAsNonIndependent();
  876.         }
  877.         partialSegmentRefs.push(partial);
  878.       }
  880.       const createUrisCb = () => {
  881.         if (range.partialSegments > 0) {
  882.           return [];
  883.         }
  884.         return shaka.dash.TimelineSegmentIndex
  885.             .createUris_(
  886.                 mediaTemplate,
  887.                 this.representationId_,
  888.                 segmentReplacement,
  889.                 this.bandwidth_,
  890.                 timeReplacement,
  891.                 /* subNumber= */ null,
  892.                 this.getBaseUris_,
  893.             );
  894.       };
  896.       ref = new shaka.media.SegmentReference(
  897.           this.periodStart_ + range.start,
  898.           this.periodStart_ + range.end,
  899.           createUrisCb,
  900.           /* startByte= */ 0,
  901.           /* endByte= */ null,
  902.           this.initSegmentReference_,
  903.           timestampOffset,
  904.           this.periodStart_,
  905.           this.periodEnd_,
  906.           partialSegmentRefs,
  907.           /* tilesLayout= */ '',
  908.           /* tileDuration= */ null,
  909.           /* syncTime= */ null,
  910.           shaka.media.SegmentReference.Status.AVAILABLE,
  911.           this.aes128Key_,
  912.           /* allPartialSegments= */ range.partialSegments > 0);
  913.       this.references[correctedPosition] = ref;
  914.     }
  916.     return ref;
  917.   }
  919.   /**
  920.    * Fill in a specific template with values to get the segment uris
  921.    *
  922.    * @return {!Array.<string>}
  923.    * @private
  924.    */
  925.   static createUris_(mediaTemplate, repId, segmentReplacement,
  926.       bandwidth, timeReplacement, subNumber, getBaseUris) {
  927.     const mediaUri = shaka.dash.MpdUtils.fillUriTemplate(
  928.         mediaTemplate, repId,
  929.         segmentReplacement, subNumber, bandwidth || null, timeReplacement);
  930.     return shaka.util.ManifestParserUtils
  931.         .resolveUris(getBaseUris(), [mediaUri])
  932.         .map((g) => {
  933.           return g.toString();
  934.         });
  935.   }
  936. };
  938. /**
  939.  * @typedef {{
  940.  *   timescale: number,
  941.  *   segmentDuration: ?number,
  942.  *   startNumber: number,
  943.  *   scaledPresentationTimeOffset: number,
  944.  *   unscaledPresentationTimeOffset: number,
  945.  *   timeline: Array.<shaka.media.PresentationTimeline.TimeRange>,
  946.  *   mediaTemplate: ?string,
  947.  *   indexTemplate: ?string
  948.  * }}
  949.  *
  950.  * @description
  951.  * Contains information about a SegmentTemplate.
  952.  *
  953.  * @property {number} timescale
  954.  *   The time-scale of the representation.
  955.  * @property {?number} segmentDuration
  956.  *   The duration of the segments in seconds, if given.
  957.  * @property {number} startNumber
  958.  *   The start number of the segments; 1 or greater.
  959.  * @property {number} scaledPresentationTimeOffset
  960.  *   The presentation time offset of the representation, in seconds.
  961.  * @property {number} unscaledPresentationTimeOffset
  962.  *   The presentation time offset of the representation, in timescale units.
  963.  * @property {Array.<shaka.media.PresentationTimeline.TimeRange>} timeline
  964.  *   The timeline of the representation, if given.  Times in seconds.
  965.  * @property {?string} mediaTemplate
  966.  *   The media URI template, if given.
  967.  * @property {?string} indexTemplate
  968.  *   The index URI template, if given.
  969.  */
  970. shaka.dash.SegmentTemplate.SegmentTemplateInfo;