Source: lib/dash/segment_template.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.dash.SegmentTemplate');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.dash.MpdUtils');
  22. goog.require('shaka.dash.SegmentBase');
  23. goog.require('shaka.log');
  24. goog.require('shaka.media.InitSegmentReference');
  25. goog.require('shaka.media.SegmentIndex');
  26. goog.require('shaka.media.SegmentReference');
  27. goog.require('shaka.util.Error');
  28. goog.require('shaka.util.ManifestParserUtils');
  31. /**
  32.  * @namespace shaka.dash.SegmentTemplate
  33.  * @summary A set of functions for parsing SegmentTemplate elements.
  34.  */
  37. /**
  38.  * Creates a new Stream object or updates the Stream in the manifest.
  39.  *
  40.  * @param {shaka.dash.DashParser.Context} context
  41.  * @param {shaka.dash.DashParser.RequestInitSegmentCallback} requestInitSegment
  42.  * @param {!Object.<string, !shaka.media.SegmentIndex>} segmentIndexMap
  43.  * @param {boolean} isUpdate True if the manifest is being updated.
  44.  * @throws shaka.util.Error When there is a parsing error.
  45.  * @return {shaka.dash.DashParser.StreamInfo}
  46.  */
  47. shaka.dash.SegmentTemplate.createStream = function(
  48.     context, requestInitSegment, segmentIndexMap, isUpdate) {
  49.   goog.asserts.assert(context.representation.segmentTemplate,
  50.                       'Should only be called with SegmentTemplate');
  51.   const SegmentTemplate = shaka.dash.SegmentTemplate;
  53.   let init = SegmentTemplate.createInitSegment_(context);
  54.   let info = SegmentTemplate.parseSegmentTemplateInfo_(context);
  56.   SegmentTemplate.checkSegmentTemplateInfo_(context, info);
  58.   /** @type {?shaka.dash.DashParser.SegmentIndexFunctions} */
  59.   let segmentIndexFunctions = null;
  60.   if (info.indexTemplate) {
  61.     segmentIndexFunctions = SegmentTemplate.createFromIndexTemplate_(
  62.         context, requestInitSegment, init, info);
  63.   } else if (info.segmentDuration) {
  64.     if (!isUpdate) {
  65.       context.presentationTimeline.notifyMaxSegmentDuration(
  66.           info.segmentDuration);
  67.       context.presentationTimeline.notifyMinSegmentStartTime(
  68.         context.periodInfo.start);
  69.     }
  70.     segmentIndexFunctions = SegmentTemplate.createFromDuration_(context, info);
  71.   } else {
  72.     /** @type {shaka.media.SegmentIndex} */
  73.     let segmentIndex = null;
  74.     let id = null;
  75.     if (context.period.id && context.representation.id) {
  76.       // Only check/store the index if period and representation IDs are set.
  77.       id = context.period.id + ',' + context.representation.id;
  78.       segmentIndex = segmentIndexMap[id];
  79.     }
  81.     let references = SegmentTemplate.createFromTimeline_(context, info);
  83.     // Don't fit live content, since it might receive more segments.
  84.     // Unless that live content is multi-period; it's safe to fit every period
  85.     // but the last one, since only the last period might receive new segments.
  86.     let shouldFit = !context.dynamic || !context.periodInfo.isLastPeriod;
  88.     if (segmentIndex) {
  89.       if (shouldFit) {
  90.         // Fit the new references before merging them, so that the merge
  91.         // algorithm has a more accurate view of their start and end times.
  92.         let wrapper = new shaka.media.SegmentIndex(references);
  93.         wrapper.fit(context.periodInfo.duration);
  94.       }
  96.       segmentIndex.merge(references);
  97.       let start = context.presentationTimeline.getSegmentAvailabilityStart();
  98.       segmentIndex.evict(start - context.periodInfo.start);
  99.     } else {
  100.       context.presentationTimeline.notifySegments(
  101.           references, context.periodInfo.start);
  102.       segmentIndex = new shaka.media.SegmentIndex(references);
  103.       if (id && context.dynamic) {
  104.         segmentIndexMap[id] = segmentIndex;
  105.       }
  106.     }
  108.     if (shouldFit) {
  109.       segmentIndex.fit(context.periodInfo.duration);
  110.     }
  112.     segmentIndexFunctions = {
  113.       createSegmentIndex: Promise.resolve.bind(Promise),
  114.       findSegmentPosition: segmentIndex.find.bind(segmentIndex),
  115.       getSegmentReference: segmentIndex.get.bind(segmentIndex),
  116.     };
  117.   }
  119.   return {
  120.     createSegmentIndex: segmentIndexFunctions.createSegmentIndex,
  121.     findSegmentPosition: segmentIndexFunctions.findSegmentPosition,
  122.     getSegmentReference: segmentIndexFunctions.getSegmentReference,
  123.     initSegmentReference: init,
  124.     scaledPresentationTimeOffset: info.scaledPresentationTimeOffset,
  125.   };
  126. };
  129. /**
  130.  * @typedef {{
  131.  *   timescale: number,
  132.  *   segmentDuration: ?number,
  133.  *   startNumber: number,
  134.  *   scaledPresentationTimeOffset: number,
  135.  *   unscaledPresentationTimeOffset: number,
  136.  *   timeline: Array.<shaka.dash.MpdUtils.TimeRange>,
  137.  *   mediaTemplate: ?string,
  138.  *   indexTemplate: ?string
  139.  * }}
  140.  * @private
  141.  *
  142.  * @description
  143.  * Contains information about a SegmentTemplate.
  144.  *
  145.  * @property {number} timescale
  146.  *   The time-scale of the representation.
  147.  * @property {?number} segmentDuration
  148.  *   The duration of the segments in seconds, if given.
  149.  * @property {number} startNumber
  150.  *   The start number of the segments; 1 or greater.
  151.  * @property {number} scaledPresentationTimeOffset
  152.  *   The presentation time offset of the representation, in seconds.
  153.  * @property {number} unscaledPresentationTimeOffset
  154.  *   The presentation time offset of the representation, in timescale units.
  155.  * @property {Array.<shaka.dash.MpdUtils.TimeRange>} timeline
  156.  *   The timeline of the representation, if given.  Times in seconds.
  157.  * @property {?string} mediaTemplate
  158.  *   The media URI template, if given.
  159.  * @property {?string} indexTemplate
  160.  *   The index URI template, if given.
  161.  */
  162. shaka.dash.SegmentTemplate.SegmentTemplateInfo;
  165. /**
  166.  * @param {?shaka.dash.DashParser.InheritanceFrame} frame
  167.  * @return {Element}
  168.  * @private
  169.  */
  170. shaka.dash.SegmentTemplate.fromInheritance_ = function(frame) {
  171.   return frame.segmentTemplate;
  172. };
  175. /**
  176.  * Parses a SegmentTemplate element into an info object.
  177.  *
  178.  * @param {shaka.dash.DashParser.Context} context
  179.  * @return {shaka.dash.SegmentTemplate.SegmentTemplateInfo}
  180.  * @private
  181.  */
  182. shaka.dash.SegmentTemplate.parseSegmentTemplateInfo_ = function(context) {
  183.   const SegmentTemplate = shaka.dash.SegmentTemplate;
  184.   const MpdUtils = shaka.dash.MpdUtils;
  185.   let segmentInfo =
  186.       MpdUtils.parseSegmentInfo(context, SegmentTemplate.fromInheritance_);
  188.   let media = MpdUtils.inheritAttribute(
  189.       context, SegmentTemplate.fromInheritance_, 'media');
  190.   let index = MpdUtils.inheritAttribute(
  191.       context, SegmentTemplate.fromInheritance_, 'index');
  193.   return {
  194.     segmentDuration: segmentInfo.segmentDuration,
  195.     timescale: segmentInfo.timescale,
  196.     startNumber: segmentInfo.startNumber,
  197.     scaledPresentationTimeOffset: segmentInfo.scaledPresentationTimeOffset,
  198.     unscaledPresentationTimeOffset: segmentInfo.unscaledPresentationTimeOffset,
  199.     timeline: segmentInfo.timeline,
  200.     mediaTemplate: media,
  201.     indexTemplate: index,
  202.   };
  203. };
  206. /**
  207.  * Verifies a SegmentTemplate info object.
  208.  *
  209.  * @param {shaka.dash.DashParser.Context} context
  210.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  211.  * @throws shaka.util.Error When there is a parsing error.
  212.  * @private
  213.  */
  214. shaka.dash.SegmentTemplate.checkSegmentTemplateInfo_ = function(context, info) {
  215.   let n = 0;
  216.   n += info.indexTemplate ? 1 : 0;
  217.   n += info.timeline ? 1 : 0;
  218.   n += info.segmentDuration ? 1 : 0;
  220.   if (n == 0) {
  221.     shaka.log.error(
  222.         'SegmentTemplate does not contain any segment information:',
  223.         'the SegmentTemplate must contain either an index URL template',
  224.         'a SegmentTimeline, or a segment duration.',
  225.         context.representation);
  226.     throw new shaka.util.Error(
  227.         shaka.util.Error.Severity.CRITICAL,
  228.         shaka.util.Error.Category.MANIFEST,
  229.         shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  230.   } else if (n != 1) {
  231.     shaka.log.warning(
  232.         'SegmentTemplate containes multiple segment information sources:',
  233.         'the SegmentTemplate should only contain an index URL template,',
  234.         'a SegmentTimeline or a segment duration.',
  235.         context.representation);
  236.     if (info.indexTemplate) {
  237.       shaka.log.info('Using the index URL template by default.');
  238.       info.timeline = null;
  239.       info.segmentDuration = null;
  240.     } else {
  241.       goog.asserts.assert(info.timeline, 'There should be a timeline');
  242.       shaka.log.info('Using the SegmentTimeline by default.');
  243.       info.segmentDuration = null;
  244.     }
  245.   }
  247.   if (!info.indexTemplate && !info.mediaTemplate) {
  248.     shaka.log.error(
  249.         'SegmentTemplate does not contain sufficient segment information:',
  250.         'the SegmentTemplate\'s media URL template is missing.',
  251.         context.representation);
  252.     throw new shaka.util.Error(
  253.         shaka.util.Error.Severity.CRITICAL,
  254.         shaka.util.Error.Category.MANIFEST,
  255.         shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  256.   }
  257. };
  260. /**
  261.  * Creates segment index functions from a index URL template.
  262.  *
  263.  * @param {shaka.dash.DashParser.Context} context
  264.  * @param {shaka.dash.DashParser.RequestInitSegmentCallback} requestInitSegment
  265.  * @param {shaka.media.InitSegmentReference} init
  266.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  267.  * @throws shaka.util.Error When there is a parsing error.
  268.  * @return {shaka.dash.DashParser.SegmentIndexFunctions}
  269.  * @private
  270.  */
  271. shaka.dash.SegmentTemplate.createFromIndexTemplate_ = function(
  272.     context, requestInitSegment, init, info) {
  273.   const MpdUtils = shaka.dash.MpdUtils;
  274.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  276.   // Determine the container type.
  277.   let containerType = context.representation.mimeType.split('/')[1];
  278.   if ((containerType != 'mp4') && (containerType != 'webm')) {
  279.     shaka.log.error(
  280.         'SegmentTemplate specifies an unsupported container type.',
  281.         context.representation);
  282.     throw new shaka.util.Error(
  283.         shaka.util.Error.Severity.CRITICAL,
  284.         shaka.util.Error.Category.MANIFEST,
  285.         shaka.util.Error.Code.DASH_UNSUPPORTED_CONTAINER);
  286.   }
  288.   if ((containerType == 'webm') && !init) {
  289.     shaka.log.error(
  290.         'SegmentTemplate does not contain sufficient segment information:',
  291.         'the SegmentTemplate uses a WebM container,',
  292.         'but does not contain an initialization URL template.',
  293.         context.representation);
  294.     throw new shaka.util.Error(
  295.         shaka.util.Error.Severity.CRITICAL,
  296.         shaka.util.Error.Category.MANIFEST,
  297.         shaka.util.Error.Code.DASH_WEBM_MISSING_INIT);
  298.   }
  300.   goog.asserts.assert(info.indexTemplate, 'must be using index template');
  301.   let filledTemplate = MpdUtils.fillUriTemplate(
  302.       info.indexTemplate, context.representation.id,
  303.       null, context.bandwidth || null, null);
  305.   let resolvedUris = ManifestParserUtils.resolveUris(
  306.       context.representation.baseUris, [filledTemplate]);
  308.   return shaka.dash.SegmentBase.createSegmentIndexFromUris(
  309.       context, requestInitSegment, init, resolvedUris, 0, null, containerType,
  310.       info.scaledPresentationTimeOffset);
  311. };
  314. /**
  315.  * Creates segment index functions from a segment duration.
  316.  *
  317.  * @param {shaka.dash.DashParser.Context} context
  318.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  319.  * @return {shaka.dash.DashParser.SegmentIndexFunctions}
  320.  * @private
  321.  */
  322. shaka.dash.SegmentTemplate.createFromDuration_ = function(context, info) {
  323.   goog.asserts.assert(info.mediaTemplate,
  324.                       'There should be a media template with duration');
  325.   const MpdUtils = shaka.dash.MpdUtils;
  326.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  328.   let periodDuration = context.periodInfo.duration;
  329.   let segmentDuration = info.segmentDuration;
  330.   let startNumber = info.startNumber;
  331.   let timescale = info.timescale;
  333.   let template = info.mediaTemplate;
  334.   let bandwidth = context.bandwidth || null;
  335.   let id = context.representation.id;
  336.   let baseUris = context.representation.baseUris;
  338.   let find = function(periodTime) {
  339.     if (periodTime < 0) {
  340.       return null;
  341.     } else if (periodDuration && periodTime >= periodDuration) {
  342.       return null;
  343.     }
  345.     return Math.floor(periodTime / segmentDuration);
  346.   };
  347.   let get = function(position) {
  348.     let segmentStart = position * segmentDuration;
  349.     // Cap the segment end at the period end, to avoid period transition issues
  350.     // in StreamingEngine.
  351.     let segmentEnd = segmentStart + segmentDuration;
  352.     if (periodDuration) segmentEnd = Math.min(segmentEnd, periodDuration);
  354.     // Do not construct segments references that should not exist.
  355.     if (segmentEnd < 0) {
  356.       return null;
  357.     } else if (periodDuration && segmentStart >= periodDuration) {
  358.       return null;
  359.     }
  361.     let getUris = function() {
  362.       let mediaUri = MpdUtils.fillUriTemplate(
  363.           template, id, position + startNumber, bandwidth,
  364.           segmentStart * timescale);
  365.       return ManifestParserUtils.resolveUris(baseUris, [mediaUri]);
  366.     };
  368.     return new shaka.media.SegmentReference(
  369.         position, segmentStart, segmentEnd, getUris, 0, null);
  370.   };
  372.   return {
  373.     createSegmentIndex: Promise.resolve.bind(Promise),
  374.     findSegmentPosition: find,
  375.     getSegmentReference: get,
  376.   };
  377. };
  380. /**
  381.  * Creates segment references from a timeline.
  382.  *
  383.  * @param {shaka.dash.DashParser.Context} context
  384.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  385.  * @return {!Array.<!shaka.media.SegmentReference>}
  386.  * @private
  387.  */
  388. shaka.dash.SegmentTemplate.createFromTimeline_ = function(context, info) {
  389.   goog.asserts.assert(info.mediaTemplate,
  390.                       'There should be a media template with a timeline');
  391.   const MpdUtils = shaka.dash.MpdUtils;
  392.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  394.   /** @type {!Array.<!shaka.media.SegmentReference>} */
  395.   let references = [];
  396.   for (let i = 0; i < info.timeline.length; i++) {
  397.     let start = info.timeline[i].start;
  398.     let unscaledStart = info.timeline[i].unscaledStart;
  399.     let end = info.timeline[i].end;
  401.     // Note: i = k - 1, where k indicates the k'th segment listed in the MPD.
  402.     // (See section 5.3.9.5.3 of the DASH spec.)
  403.     let segmentReplacement = i + info.startNumber;
  405.     // Consider the presentation time offset in segment uri computation
  406.     let timeReplacement = unscaledStart +
  407.         info.unscaledPresentationTimeOffset;
  408.     let createUris = (function(
  409.             template, repId, bandwidth, baseUris, segmentId, time) {
  410.           let mediaUri = MpdUtils.fillUriTemplate(
  411.               template, repId, segmentId, bandwidth, time);
  412.           return ManifestParserUtils.resolveUris(baseUris, [mediaUri])
  413.               .map(function(g) { return g.toString(); });
  414.         }.bind(null, info.mediaTemplate, context.representation.id,
  415.                context.bandwidth || null, context.representation.baseUris,
  416.                segmentReplacement, timeReplacement));
  418.     references.push(new shaka.media.SegmentReference(
  419.         segmentReplacement, start, end, createUris, 0, null));
  420.   }
  422.   return references;
  423. };
  426. /**
  427.  * Creates an init segment reference from a context object.
  428.  *
  429.  * @param {shaka.dash.DashParser.Context} context
  430.  * @return {shaka.media.InitSegmentReference}
  431.  * @private
  432.  */
  433. shaka.dash.SegmentTemplate.createInitSegment_ = function(context) {
  434.   const MpdUtils = shaka.dash.MpdUtils;
  435.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  436.   const SegmentTemplate = shaka.dash.SegmentTemplate;
  438.   let initialization = MpdUtils.inheritAttribute(
  439.       context, SegmentTemplate.fromInheritance_, 'initialization');
  440.   if (!initialization) {
  441.     return null;
  442.   }
  444.   let repId = context.representation.id;
  445.   let bandwidth = context.bandwidth || null;
  446.   let baseUris = context.representation.baseUris;
  447.   let getUris = function() {
  448.     goog.asserts.assert(initialization, 'Should have returned earler');
  449.     let filledTemplate = MpdUtils.fillUriTemplate(
  450.         initialization, repId, null, bandwidth, null);
  451.     let resolvedUris = ManifestParserUtils.resolveUris(
  452.         baseUris, [filledTemplate]);
  453.     return resolvedUris;
  454.   };
  456.   return new shaka.media.InitSegmentReference(getUris, 0, null);
  457. };