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.     }
  68.     segmentIndexFunctions = SegmentTemplate.createFromDuration_(context, info);
  69.   } else {
  70.     /** @type {shaka.media.SegmentIndex} */
  71.     let segmentIndex = null;
  72.     let id = null;
  73.     if (context.period.id && context.representation.id) {
  74.       // Only check/store the index if period and representation IDs are set.
  75.       id = context.period.id + ',' + context.representation.id;
  76.       segmentIndex = segmentIndexMap[id];
  77.     }
  79.     let references = SegmentTemplate.createFromTimeline_(context, info);
  81.     // Don't fit live content, since it might receive more segments.
  82.     // Unless that live content is multi-period; it's safe to fit every period
  83.     // but the last one, since only the last period might receive new segments.
  84.     let shouldFit = !context.dynamic || !context.periodInfo.isLastPeriod;
  86.     if (segmentIndex) {
  87.       if (shouldFit) {
  88.         // Fit the new references before merging them, so that the merge
  89.         // algorithm has a more accurate view of their start and end times.
  90.         let wrapper = new shaka.media.SegmentIndex(references);
  91.         wrapper.fit(context.periodInfo.duration);
  92.       }
  94.       segmentIndex.merge(references);
  95.       let start = context.presentationTimeline.getSegmentAvailabilityStart();
  96.       segmentIndex.evict(start - context.periodInfo.start);
  97.     } else {
  98.       context.presentationTimeline.notifySegments(
  99.           references, context.periodInfo.index == 0);
  100.       segmentIndex = new shaka.media.SegmentIndex(references);
  101.       if (id && context.dynamic) {
  102.         segmentIndexMap[id] = segmentIndex;
  103.       }
  104.     }
  106.     if (shouldFit) {
  107.       segmentIndex.fit(context.periodInfo.duration);
  108.     }
  110.     segmentIndexFunctions = {
  111.       createSegmentIndex: Promise.resolve.bind(Promise),
  112.       findSegmentPosition: segmentIndex.find.bind(segmentIndex),
  113.       getSegmentReference: segmentIndex.get.bind(segmentIndex)
  114.     };
  115.   }
  117.   return {
  118.     createSegmentIndex: segmentIndexFunctions.createSegmentIndex,
  119.     findSegmentPosition: segmentIndexFunctions.findSegmentPosition,
  120.     getSegmentReference: segmentIndexFunctions.getSegmentReference,
  121.     initSegmentReference: init,
  122.     scaledPresentationTimeOffset: info.scaledPresentationTimeOffset
  123.   };
  124. };
  127. /**
  128.  * @typedef {{
  129.  *   timescale: number,
  130.  *   segmentDuration: ?number,
  131.  *   startNumber: number,
  132.  *   scaledPresentationTimeOffset: number,
  133.  *   unscaledPresentationTimeOffset: number,
  134.  *   timeline: Array.<shaka.dash.MpdUtils.TimeRange>,
  135.  *   mediaTemplate: ?string,
  136.  *   indexTemplate: ?string
  137.  * }}
  138.  * @private
  139.  *
  140.  * @description
  141.  * Contains information about a SegmentTemplate.
  142.  *
  143.  * @property {number} timescale
  144.  *   The time-scale of the representation.
  145.  * @property {?number} segmentDuration
  146.  *   The duration of the segments in seconds, if given.
  147.  * @property {number} startNumber
  148.  *   The start number of the segments; 1 or greater.
  149.  * @property {number} scaledPresentationTimeOffset
  150.  *   The presentation time offset of the representation, in seconds.
  151.  * @property {number} unscaledPresentationTimeOffset
  152.  *   The presentation time offset of the representation, in timescale units.
  153.  * @property {Array.<shaka.dash.MpdUtils.TimeRange>} timeline
  154.  *   The timeline of the representation, if given.  Times in seconds.
  155.  * @property {?string} mediaTemplate
  156.  *   The media URI template, if given.
  157.  * @property {?string} indexTemplate
  158.  *   The index URI template, if given.
  159.  */
  160. shaka.dash.SegmentTemplate.SegmentTemplateInfo;
  163. /**
  164.  * @param {?shaka.dash.DashParser.InheritanceFrame} frame
  165.  * @return {Element}
  166.  * @private
  167.  */
  168. shaka.dash.SegmentTemplate.fromInheritance_ = function(frame) {
  169.   return frame.segmentTemplate;
  170. };
  173. /**
  174.  * Parses a SegmentTemplate element into an info object.
  175.  *
  176.  * @param {shaka.dash.DashParser.Context} context
  177.  * @return {shaka.dash.SegmentTemplate.SegmentTemplateInfo}
  178.  * @private
  179.  */
  180. shaka.dash.SegmentTemplate.parseSegmentTemplateInfo_ = function(context) {
  181.   const SegmentTemplate = shaka.dash.SegmentTemplate;
  182.   const MpdUtils = shaka.dash.MpdUtils;
  183.   let segmentInfo =
  184.       MpdUtils.parseSegmentInfo(context, SegmentTemplate.fromInheritance_);
  186.   let media = MpdUtils.inheritAttribute(
  187.       context, SegmentTemplate.fromInheritance_, 'media');
  188.   let index = MpdUtils.inheritAttribute(
  189.       context, SegmentTemplate.fromInheritance_, 'index');
  191.   return {
  192.     segmentDuration: segmentInfo.segmentDuration,
  193.     timescale: segmentInfo.timescale,
  194.     startNumber: segmentInfo.startNumber,
  195.     scaledPresentationTimeOffset: segmentInfo.scaledPresentationTimeOffset,
  196.     unscaledPresentationTimeOffset: segmentInfo.unscaledPresentationTimeOffset,
  197.     timeline: segmentInfo.timeline,
  198.     mediaTemplate: media,
  199.     indexTemplate: index
  200.   };
  201. };
  204. /**
  205.  * Verifies a SegmentTemplate info object.
  206.  *
  207.  * @param {shaka.dash.DashParser.Context} context
  208.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  209.  * @throws shaka.util.Error When there is a parsing error.
  210.  * @private
  211.  */
  212. shaka.dash.SegmentTemplate.checkSegmentTemplateInfo_ = function(context, info) {
  213.   let n = 0;
  214.   n += info.indexTemplate ? 1 : 0;
  215.   n += info.timeline ? 1 : 0;
  216.   n += info.segmentDuration ? 1 : 0;
  218.   if (n == 0) {
  219.     shaka.log.error(
  220.         'SegmentTemplate does not contain any segment information:',
  221.         'the SegmentTemplate must contain either an index URL template',
  222.         'a SegmentTimeline, or a segment duration.',
  223.         context.representation);
  224.     throw new shaka.util.Error(
  225.         shaka.util.Error.Severity.CRITICAL,
  226.         shaka.util.Error.Category.MANIFEST,
  227.         shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  228.   } else if (n != 1) {
  229.     shaka.log.warning(
  230.         'SegmentTemplate containes multiple segment information sources:',
  231.         'the SegmentTemplate should only contain an index URL template,',
  232.         'a SegmentTimeline or a segment duration.',
  233.         context.representation);
  234.     if (info.indexTemplate) {
  235.       shaka.log.info('Using the index URL template by default.');
  236.       info.timeline = null;
  237.       info.segmentDuration = null;
  238.     } else {
  239.       goog.asserts.assert(info.timeline, 'There should be a timeline');
  240.       shaka.log.info('Using the SegmentTimeline by default.');
  241.       info.segmentDuration = null;
  242.     }
  243.   }
  245.   if (!info.indexTemplate && !info.mediaTemplate) {
  246.     shaka.log.error(
  247.         'SegmentTemplate does not contain sufficient segment information:',
  248.         'the SegmentTemplate\'s media URL template is missing.',
  249.         context.representation);
  250.     throw new shaka.util.Error(
  251.         shaka.util.Error.Severity.CRITICAL,
  252.         shaka.util.Error.Category.MANIFEST,
  253.         shaka.util.Error.Code.DASH_NO_SEGMENT_INFO);
  254.   }
  255. };
  258. /**
  259.  * Creates segment index functions from a index URL template.
  260.  *
  261.  * @param {shaka.dash.DashParser.Context} context
  262.  * @param {shaka.dash.DashParser.RequestInitSegmentCallback} requestInitSegment
  263.  * @param {shaka.media.InitSegmentReference} init
  264.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  265.  * @throws shaka.util.Error When there is a parsing error.
  266.  * @return {shaka.dash.DashParser.SegmentIndexFunctions}
  267.  * @private
  268.  */
  269. shaka.dash.SegmentTemplate.createFromIndexTemplate_ = function(
  270.     context, requestInitSegment, init, info) {
  271.   const MpdUtils = shaka.dash.MpdUtils;
  272.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  274.   // Determine the container type.
  275.   let containerType = context.representation.mimeType.split('/')[1];
  276.   if ((containerType != 'mp4') && (containerType != 'webm')) {
  277.     shaka.log.error(
  278.         'SegmentTemplate specifies an unsupported container type.',
  279.         context.representation);
  280.     throw new shaka.util.Error(
  281.         shaka.util.Error.Severity.CRITICAL,
  282.         shaka.util.Error.Category.MANIFEST,
  283.         shaka.util.Error.Code.DASH_UNSUPPORTED_CONTAINER);
  284.   }
  286.   if ((containerType == 'webm') && !init) {
  287.     shaka.log.error(
  288.         'SegmentTemplate does not contain sufficient segment information:',
  289.         'the SegmentTemplate uses a WebM container,',
  290.         'but does not contain an initialization URL template.',
  291.         context.representation);
  292.     throw new shaka.util.Error(
  293.         shaka.util.Error.Severity.CRITICAL,
  294.         shaka.util.Error.Category.MANIFEST,
  295.         shaka.util.Error.Code.DASH_WEBM_MISSING_INIT);
  296.   }
  298.   goog.asserts.assert(info.indexTemplate, 'must be using index template');
  299.   let filledTemplate = MpdUtils.fillUriTemplate(
  300.       info.indexTemplate, context.representation.id,
  301.       null, context.bandwidth || null, null);
  303.   let resolvedUris = ManifestParserUtils.resolveUris(
  304.       context.representation.baseUris, [filledTemplate]);
  306.   return shaka.dash.SegmentBase.createSegmentIndexFromUris(
  307.       context, requestInitSegment, init, resolvedUris, 0, null, containerType,
  308.       info.scaledPresentationTimeOffset);
  309. };
  312. /**
  313.  * Creates segment index functions from a segment duration.
  314.  *
  315.  * @param {shaka.dash.DashParser.Context} context
  316.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  317.  * @return {shaka.dash.DashParser.SegmentIndexFunctions}
  318.  * @private
  319.  */
  320. shaka.dash.SegmentTemplate.createFromDuration_ = function(context, info) {
  321.   goog.asserts.assert(info.mediaTemplate,
  322.                       'There should be a media template with duration');
  323.   const MpdUtils = shaka.dash.MpdUtils;
  324.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  326.   let periodDuration = context.periodInfo.duration;
  327.   let segmentDuration = info.segmentDuration;
  328.   let startNumber = info.startNumber;
  329.   let timescale = info.timescale;
  331.   let template = info.mediaTemplate;
  332.   let bandwidth = context.bandwidth || null;
  333.   let id = context.representation.id;
  334.   let baseUris = context.representation.baseUris;
  336.   let find = function(periodTime) {
  337.     if (periodTime < 0) {
  338.       return null;
  339.     } else if (periodDuration && periodTime >= periodDuration) {
  340.       return null;
  341.     }
  343.     return Math.floor(periodTime / segmentDuration);
  344.   };
  345.   let get = function(position) {
  346.     let segmentStart = position * segmentDuration;
  347.     // Cap the segment end at the period end, to avoid period transition issues
  348.     // in StreamingEngine.
  349.     let segmentEnd = segmentStart + segmentDuration;
  350.     if (periodDuration) segmentEnd = Math.min(segmentEnd, periodDuration);
  352.     // Do not construct segments references that should not exist.
  353.     if (segmentEnd < 0) {
  354.       return null;
  355.     } else if (periodDuration && segmentStart >= periodDuration) {
  356.       return null;
  357.     }
  359.     let getUris = function() {
  360.       let mediaUri = MpdUtils.fillUriTemplate(
  361.           template, id, position + startNumber, bandwidth,
  362.           segmentStart * timescale);
  363.       return ManifestParserUtils.resolveUris(baseUris, [mediaUri]);
  364.     };
  366.     return new shaka.media.SegmentReference(
  367.         position, segmentStart, segmentEnd, getUris, 0, null);
  368.   };
  370.   return {
  371.     createSegmentIndex: Promise.resolve.bind(Promise),
  372.     findSegmentPosition: find,
  373.     getSegmentReference: get
  374.   };
  375. };
  378. /**
  379.  * Creates segment references from a timeline.
  380.  *
  381.  * @param {shaka.dash.DashParser.Context} context
  382.  * @param {shaka.dash.SegmentTemplate.SegmentTemplateInfo} info
  383.  * @return {!Array.<!shaka.media.SegmentReference>}
  384.  * @private
  385.  */
  386. shaka.dash.SegmentTemplate.createFromTimeline_ = function(context, info) {
  387.   goog.asserts.assert(info.mediaTemplate,
  388.                       'There should be a media template with a timeline');
  389.   const MpdUtils = shaka.dash.MpdUtils;
  390.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  392.   /** @type {!Array.<!shaka.media.SegmentReference>} */
  393.   let references = [];
  394.   for (let i = 0; i < info.timeline.length; i++) {
  395.     let start = info.timeline[i].start;
  396.     let unscaledStart = info.timeline[i].unscaledStart;
  397.     let end = info.timeline[i].end;
  399.     // Note: i = k - 1, where k indicates the k'th segment listed in the MPD.
  400.     // (See section 5.3.9.5.3 of the DASH spec.)
  401.     let segmentReplacement = i + info.startNumber;
  403.     // Consider the presentation time offset in segment uri computation
  404.     let timeReplacement = unscaledStart +
  405.         info.unscaledPresentationTimeOffset;
  406.     let createUris = (function(
  407.             template, repId, bandwidth, baseUris, segmentId, time) {
  408.           let mediaUri = MpdUtils.fillUriTemplate(
  409.               template, repId, segmentId, bandwidth, time);
  410.           return ManifestParserUtils.resolveUris(baseUris, [mediaUri])
  411.               .map(function(g) { return g.toString(); });
  412.         }.bind(null, info.mediaTemplate, context.representation.id,
  413.                context.bandwidth || null, context.representation.baseUris,
  414.                segmentReplacement, timeReplacement));
  416.     references.push(new shaka.media.SegmentReference(
  417.         segmentReplacement, start, end, createUris, 0, null));
  418.   }
  420.   return references;
  421. };
  424. /**
  425.  * Creates an init segment reference from a context object.
  426.  *
  427.  * @param {shaka.dash.DashParser.Context} context
  428.  * @return {shaka.media.InitSegmentReference}
  429.  * @private
  430.  */
  431. shaka.dash.SegmentTemplate.createInitSegment_ = function(context) {
  432.   const MpdUtils = shaka.dash.MpdUtils;
  433.   const ManifestParserUtils = shaka.util.ManifestParserUtils;
  434.   const SegmentTemplate = shaka.dash.SegmentTemplate;
  436.   let initialization = MpdUtils.inheritAttribute(
  437.       context, SegmentTemplate.fromInheritance_, 'initialization');
  438.   if (!initialization) {
  439.     return null;
  440.   }
  442.   let repId = context.representation.id;
  443.   let bandwidth = context.bandwidth || null;
  444.   let baseUris = context.representation.baseUris;
  445.   let getUris = function() {
  446.     goog.asserts.assert(initialization, 'Should have returned earler');
  447.     let filledTemplate = MpdUtils.fillUriTemplate(
  448.         initialization, repId, null, bandwidth, null);
  449.     let resolvedUris = ManifestParserUtils.resolveUris(
  450.         baseUris, [filledTemplate]);
  451.     return resolvedUris;
  452.   };
  454.   return new shaka.media.InitSegmentReference(getUris, 0, null);
  455. };