Source: lib/dash/mpd_utils.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.dash.MpdUtils');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.net.NetworkingEngine');
  12. goog.require('shaka.util.AbortableOperation');
  13. goog.require('shaka.util.Error');
  14. goog.require('shaka.util.Functional');
  15. goog.require('shaka.util.ManifestParserUtils');
  16. goog.require('shaka.util.XmlUtils');
  17. goog.requireType('shaka.dash.DashParser');
  20. /**
  21.  * @summary MPD processing utility functions.
  22.  */
  23. shaka.dash.MpdUtils = class {
  24.   /**
  25.    * Fills a SegmentTemplate URI template.  This function does not validate the
  26.    * resulting URI.
  27.    *
  28.    * @param {string} uriTemplate
  29.    * @param {?string} representationId
  30.    * @param {?number} number
  31.    * @param {?number} bandwidth
  32.    * @param {?number} time
  33.    * @return {string} A URI string.
  34.    * @see ISO/IEC 23009-1:2014 section 5.3.9.4.4
  35.    */
  36.   static fillUriTemplate(
  37.       uriTemplate, representationId, number, bandwidth, time) {
  38.     /** @type {!Object.<string, ?number|?string>} */
  39.     const valueTable = {
  40.       'RepresentationID': representationId,
  41.       'Number': number,
  42.       'Bandwidth': bandwidth,
  43.       'Time': time,
  44.     };
  46.     const re = /\$(RepresentationID|Number|Bandwidth|Time)?(?:%0([0-9]+)([diouxX]))?\$/g;  // eslint-disable-line max-len
  47.     const uri = uriTemplate.replace(re, (match, name, widthStr, format) => {
  48.       if (match == '$$') {
  49.         return '$';
  50.       }
  52.       let value = valueTable[name];
  53.       goog.asserts.assert(value !== undefined, 'Unrecognized identifier');
  55.       // Note that |value| may be 0 or ''.
  56.       if (value == null) {
  57.         shaka.log.warning(
  58.             'URL template does not have an available substitution for ',
  59.             'identifier "' + name + '":',
  60.             uriTemplate);
  61.         return match;
  62.       }
  64.       if (name == 'RepresentationID' && widthStr) {
  65.         shaka.log.warning(
  66.             'URL template should not contain a width specifier for identifier',
  67.             '"RepresentationID":',
  68.             uriTemplate);
  69.         widthStr = undefined;
  70.       }
  72.       if (name == 'Time') {
  73.         goog.asserts.assert(typeof value == 'number',
  74.             'Time value should be a number!');
  75.         goog.asserts.assert(Math.abs(value - Math.round(value)) < 0.2,
  76.             'Calculated $Time$ values must be close to integers');
  77.         value = Math.round(value);
  78.       }
  80.       /** @type {string} */
  81.       let valueString;
  82.       switch (format) {
  83.         case undefined:  // Happens if there is no format specifier.
  84.         case 'd':
  85.         case 'i':
  86.         case 'u':
  87.           valueString = value.toString();
  88.           break;
  89.         case 'o':
  90.           valueString = value.toString(8);
  91.           break;
  92.         case 'x':
  93.           valueString = value.toString(16);
  94.           break;
  95.         case 'X':
  96.           valueString = value.toString(16).toUpperCase();
  97.           break;
  98.         default:
  99.           goog.asserts.assert(false, 'Unhandled format specifier');
  100.           valueString = value.toString();
  101.           break;
  102.       }
  104.       // Create a padding string.
  105.       const width = window.parseInt(widthStr, 10) || 1;
  106.       const paddingSize = Math.max(0, width - valueString.length);
  107.       const padding = (new Array(paddingSize + 1)).join('0');
  109.       return padding + valueString;
  110.     });
  112.     return uri;
  113.   }
  115.   /**
  116.    * Expands a SegmentTimeline into an array-based timeline.  The results are in
  117.    * seconds.
  118.    *
  119.    * @param {!Element} segmentTimeline
  120.    * @param {number} timescale
  121.    * @param {number} unscaledPresentationTimeOffset
  122.    * @param {number} periodDuration The Period's duration in seconds.
  123.    *   Infinity indicates that the Period continues indefinitely.
  124.    * @return {!Array.<shaka.dash.MpdUtils.TimeRange>}
  125.    */
  126.   static createTimeline(
  127.       segmentTimeline, timescale, unscaledPresentationTimeOffset,
  128.       periodDuration) {
  129.     goog.asserts.assert(
  130.         timescale > 0 && timescale < Infinity,
  131.         'timescale must be a positive, finite integer');
  132.     goog.asserts.assert(
  133.         periodDuration > 0, 'period duration must be a positive integer');
  135.     // Alias.
  136.     const XmlUtils = shaka.util.XmlUtils;
  138.     const timePoints = XmlUtils.findChildren(segmentTimeline, 'S');
  140.     /** @type {!Array.<shaka.dash.MpdUtils.TimeRange>} */
  141.     const timeline = [];
  142.     let lastEndTime = -unscaledPresentationTimeOffset;
  144.     for (let i = 0; i < timePoints.length; ++i) {
  145.       const timePoint = timePoints[i];
  146.       const next = timePoints[i + 1];
  147.       let t = XmlUtils.parseAttr(timePoint, 't', XmlUtils.parseNonNegativeInt);
  148.       const d =
  149.           XmlUtils.parseAttr(timePoint, 'd', XmlUtils.parseNonNegativeInt);
  150.       const r = XmlUtils.parseAttr(timePoint, 'r', XmlUtils.parseInt);
  152.       // Adjust the start time to account for the presentation time offset.
  153.       if (t != null) {
  154.         t -= unscaledPresentationTimeOffset;
  155.       }
  157.       if (!d) {
  158.         shaka.log.warning(
  159.             '"S" element must have a duration:',
  160.             'ignoring the remaining "S" elements.', timePoint);
  161.         return timeline;
  162.       }
  164.       let startTime = t != null ? t : lastEndTime;
  166.       let repeat = r || 0;
  167.       if (repeat < 0) {
  168.         if (next) {
  169.           const nextStartTime =
  170.               XmlUtils.parseAttr(next, 't', XmlUtils.parseNonNegativeInt);
  171.           if (nextStartTime == null) {
  172.             shaka.log.warning(
  173.                 'An "S" element cannot have a negative repeat',
  174.                 'if the next "S" element does not have a valid start time:',
  175.                 'ignoring the remaining "S" elements.', timePoint);
  176.             return timeline;
  177.           } else if (startTime >= nextStartTime) {
  178.             shaka.log.warning(
  179.                 'An "S" element cannot have a negative repeatif its start ',
  180.                 'time exceeds the next "S" element\'s start time:',
  181.                 'ignoring the remaining "S" elements.', timePoint);
  182.             return timeline;
  183.           }
  184.           repeat = Math.ceil((nextStartTime - startTime) / d) - 1;
  185.         } else {
  186.           if (periodDuration == Infinity) {
  187.             // The DASH spec. actually allows the last "S" element to have a
  188.             // negative repeat value even when the Period has an infinite
  189.             // duration.  No one uses this feature and no one ever should,
  190.             // ever.
  191.             shaka.log.warning(
  192.                 'The last "S" element cannot have a negative repeat',
  193.                 'if the Period has an infinite duration:',
  194.                 'ignoring the last "S" element.', timePoint);
  195.             return timeline;
  196.           } else if (startTime / timescale >= periodDuration) {
  197.             shaka.log.warning(
  198.                 'The last "S" element cannot have a negative repeat',
  199.                 'if its start time exceeds the Period\'s duration:',
  200.                 'igoring the last "S" element.', timePoint);
  201.             return timeline;
  202.           }
  203.           repeat = Math.ceil((periodDuration * timescale - startTime) / d) - 1;
  204.         }
  205.       }
  207.       // The end of the last segment may be before the start of the current
  208.       // segment (a gap) or after the start of the current segment (an
  209.       // overlap). If there is a gap/overlap then stretch/compress the end of
  210.       // the last segment to the start of the current segment.
  211.       //
  212.       // Note: it is possible to move the start of the current segment to the
  213.       // end of the last segment, but this would complicate the computation of
  214.       // the $Time$ placeholder later on.
  215.       if ((timeline.length > 0) && (startTime != lastEndTime)) {
  216.         const delta = startTime - lastEndTime;
  218.         if (Math.abs(delta / timescale) >=
  219.             shaka.util.ManifestParserUtils.GAP_OVERLAP_TOLERANCE_SECONDS) {
  220.           shaka.log.warning(
  221.               'SegmentTimeline contains a large gap/overlap:',
  222.               'the content may have errors in it.', timePoint);
  223.         }
  225.         timeline[timeline.length - 1].end = startTime / timescale;
  226.       }
  228.       for (let j = 0; j <= repeat; ++j) {
  229.         const endTime = startTime + d;
  230.         const item = {
  231.           start: startTime / timescale,
  232.           end: endTime / timescale,
  233.           unscaledStart: startTime,
  234.         };
  235.         timeline.push(item);
  237.         startTime = endTime;
  238.         lastEndTime = endTime;
  239.       }
  240.     }
  242.     return timeline;
  243.   }
  245.   /**
  246.    * Parses common segment info for SegmentList and SegmentTemplate.
  247.    *
  248.    * @param {shaka.dash.DashParser.Context} context
  249.    * @param {function(?shaka.dash.DashParser.InheritanceFrame):Element} callback
  250.    *   Gets the element that contains the segment info.
  251.    * @return {shaka.dash.MpdUtils.SegmentInfo}
  252.    */
  253.   static parseSegmentInfo(context, callback) {
  254.     goog.asserts.assert(
  255.         callback(context.representation),
  256.         'There must be at least one element of the given type.');
  257.     const MpdUtils = shaka.dash.MpdUtils;
  258.     const XmlUtils = shaka.util.XmlUtils;
  260.     const timescaleStr =
  261.         MpdUtils.inheritAttribute(context, callback, 'timescale');
  262.     let timescale = 1;
  263.     if (timescaleStr) {
  264.       timescale = XmlUtils.parsePositiveInt(timescaleStr) || 1;
  265.     }
  267.     const durationStr =
  268.         MpdUtils.inheritAttribute(context, callback, 'duration');
  269.     let segmentDuration = XmlUtils.parsePositiveInt(durationStr || '');
  270.     const ContentType = shaka.util.ManifestParserUtils.ContentType;
  271.     // TODO: The specification is not clear, check this once it is resolved:
  272.     // https://github.com/Dash-Industry-Forum/DASH-IF-IOP/issues/404
  273.     if (context.representation.contentType == ContentType.IMAGE) {
  274.       segmentDuration = XmlUtils.parseFloat(durationStr || '');
  275.     }
  276.     if (segmentDuration) {
  277.       segmentDuration /= timescale;
  278.     }
  280.     const startNumberStr =
  281.         MpdUtils.inheritAttribute(context, callback, 'startNumber');
  282.     const unscaledPresentationTimeOffset =
  283.         Number(MpdUtils.inheritAttribute(context, callback,
  284.             'presentationTimeOffset')) || 0;
  285.     let startNumber = XmlUtils.parseNonNegativeInt(startNumberStr || '');
  286.     if (startNumberStr == null || startNumber == null) {
  287.       startNumber = 1;
  288.     }
  290.     const timelineNode =
  291.         MpdUtils.inheritChild(context, callback, 'SegmentTimeline');
  292.     /** @type {Array.<shaka.dash.MpdUtils.TimeRange>} */
  293.     let timeline = null;
  294.     if (timelineNode) {
  295.       timeline = MpdUtils.createTimeline(
  296.           timelineNode, timescale, unscaledPresentationTimeOffset,
  297.           context.periodInfo.duration || Infinity);
  298.     }
  300.     const scaledPresentationTimeOffset =
  301.         (unscaledPresentationTimeOffset / timescale) || 0;
  302.     return {
  303.       timescale: timescale,
  304.       segmentDuration: segmentDuration,
  305.       startNumber: startNumber,
  306.       scaledPresentationTimeOffset: scaledPresentationTimeOffset,
  307.       unscaledPresentationTimeOffset: unscaledPresentationTimeOffset,
  308.       timeline: timeline,
  309.     };
  310.   }
  312.   /**
  313.    * Parses common attributes for Representation, AdaptationSet, and Period.
  314.    * @param {shaka.dash.DashParser.Context} context
  315.    * @param {function(?shaka.dash.DashParser.InheritanceFrame):Element} callback
  316.    * @return {!Array.<!Element>}
  317.     */
  318.   static getNodes(context, callback) {
  319.     const Functional = shaka.util.Functional;
  320.     goog.asserts.assert(
  321.         callback(context.representation),
  322.         'There must be at least one element of the given type',
  323.     );
  325.     return [
  326.       callback(context.representation),
  327.       callback(context.adaptationSet),
  328.       callback(context.period),
  329.     ].filter(Functional.isNotNull);
  330.   }
  332.   /**
  333.    * Searches the inheritance for a Segment* with the given attribute.
  334.    *
  335.    * @param {shaka.dash.DashParser.Context} context
  336.    * @param {function(?shaka.dash.DashParser.InheritanceFrame):Element} callback
  337.    *   Gets the Element that contains the attribute to inherit.
  338.    * @param {string} attribute
  339.    * @return {?string}
  340.    */
  341.   static inheritAttribute(context, callback, attribute) {
  342.     const MpdUtils = shaka.dash.MpdUtils;
  343.     const nodes = MpdUtils.getNodes(context, callback);
  345.     let result = null;
  346.     for (const node of nodes) {
  347.       result = node.getAttribute(attribute);
  348.       if (result) {
  349.         break;
  350.       }
  351.     }
  352.     return result;
  353.   }
  355.   /**
  356.    * Searches the inheritance for a Segment* with the given child.
  357.    *
  358.    * @param {shaka.dash.DashParser.Context} context
  359.    * @param {function(?shaka.dash.DashParser.InheritanceFrame):Element} callback
  360.    *   Gets the Element that contains the child to inherit.
  361.    * @param {string} child
  362.    * @return {Element}
  363.    */
  364.   static inheritChild(context, callback, child) {
  365.     const MpdUtils = shaka.dash.MpdUtils;
  366.     const nodes = MpdUtils.getNodes(context, callback);
  368.     const XmlUtils = shaka.util.XmlUtils;
  369.     let result = null;
  370.     for (const node of nodes) {
  371.       result = XmlUtils.findChild(node, child);
  372.       if (result) {
  373.         break;
  374.       }
  375.     }
  376.     return result;
  377.   }
  379.   /**
  380.    * Follow the xlink link contained in the given element.
  381.    * It also strips the xlink properties off of the element,
  382.    * even if the process fails.
  383.    *
  384.    * @param {!Element} element
  385.    * @param {!shaka.extern.RetryParameters} retryParameters
  386.    * @param {boolean} failGracefully
  387.    * @param {string} baseUri
  388.    * @param {!shaka.net.NetworkingEngine} networkingEngine
  389.    * @param {number} linkDepth
  390.    * @return {!shaka.util.AbortableOperation.<!Element>}
  391.    * @private
  392.    */
  393.   static handleXlinkInElement_(
  394.       element, retryParameters, failGracefully, baseUri, networkingEngine,
  395.       linkDepth) {
  396.     const MpdUtils = shaka.dash.MpdUtils;
  397.     const XmlUtils = shaka.util.XmlUtils;
  398.     const Error = shaka.util.Error;
  399.     const ManifestParserUtils = shaka.util.ManifestParserUtils;
  400.     const NS = MpdUtils.XlinkNamespaceUri_;
  402.     const xlinkHref = XmlUtils.getAttributeNS(element, NS, 'href');
  403.     const xlinkActuate =
  404.         XmlUtils.getAttributeNS(element, NS, 'actuate') || 'onRequest';
  406.     // Remove the xlink properties, so it won't download again
  407.     // when re-processed.
  408.     for (const attribute of Array.from(element.attributes)) {
  409.       if (attribute.namespaceURI == NS) {
  410.         element.removeAttributeNS(attribute.namespaceURI, attribute.localName);
  411.       }
  412.     }
  414.     if (linkDepth >= 5) {
  415.       return shaka.util.AbortableOperation.failed(new Error(
  416.           Error.Severity.CRITICAL, Error.Category.MANIFEST,
  417.           Error.Code.DASH_XLINK_DEPTH_LIMIT));
  418.     }
  420.     if (xlinkActuate != 'onLoad') {
  421.       // Only xlink:actuate="onLoad" is supported.
  422.       // When no value is specified, the assumed value is "onRequest".
  423.       return shaka.util.AbortableOperation.failed(new Error(
  424.           Error.Severity.CRITICAL, Error.Category.MANIFEST,
  425.           Error.Code.DASH_UNSUPPORTED_XLINK_ACTUATE));
  426.     }
  428.     // Resolve the xlink href, in case it's a relative URL.
  429.     const uris = ManifestParserUtils.resolveUris([baseUri], [xlinkHref]);
  431.     // Load in the linked elements.
  432.     const requestType = shaka.net.NetworkingEngine.RequestType.MANIFEST;
  433.     const request =
  434.         shaka.net.NetworkingEngine.makeRequest(uris, retryParameters);
  436.     const requestOperation = networkingEngine.request(requestType, request);
  437.     // The interface is abstract, but we know it was implemented with the
  438.     // more capable internal class.
  439.     goog.asserts.assert(
  440.         requestOperation instanceof shaka.util.AbortableOperation,
  441.         'Unexpected implementation of IAbortableOperation!');
  442.     // Satisfy the compiler with a cast.
  443.     const networkOperation =
  444.     /** @type {!shaka.util.AbortableOperation.<shaka.extern.Response>} */ (
  445.         requestOperation);
  447.     // Chain onto that operation.
  448.     return networkOperation.chain(
  449.         (response) => {
  450.           // This only supports the case where the loaded xml has a single
  451.           // top-level element.  If there are multiple roots, it will be
  452.           // rejected.
  453.           const rootElem =
  454.           shaka.util.XmlUtils.parseXml(response.data, element.tagName);
  455.           if (!rootElem) {
  456.             // It was not valid XML.
  457.             return shaka.util.AbortableOperation.failed(new Error(
  458.                 Error.Severity.CRITICAL, Error.Category.MANIFEST,
  459.                 Error.Code.DASH_INVALID_XML, xlinkHref));
  460.           }
  462.           // Now that there is no other possibility of the process erroring,
  463.           // the element can be changed further.
  465.           // Remove the current contents of the node.
  466.           while (element.childNodes.length) {
  467.             element.removeChild(element.childNodes[0]);
  468.           }
  470.           // Move the children of the loaded xml into the current element.
  471.           while (rootElem.childNodes.length) {
  472.             const child = rootElem.childNodes[0];
  473.             rootElem.removeChild(child);
  474.             element.appendChild(child);
  475.           }
  477.           // Move the attributes of the loaded xml into the current element.
  478.           for (const attribute of Array.from(rootElem.attributes)) {
  479.             element.setAttributeNode(attribute.cloneNode(/* deep= */ false));
  480.           }
  482.           return shaka.dash.MpdUtils.processXlinks(
  483.               element, retryParameters, failGracefully, uris[0],
  484.               networkingEngine, linkDepth + 1);
  485.         });
  486.   }
  488.   /**
  489.    * Filter the contents of a node recursively, replacing xlink links
  490.    * with their associated online data.
  491.    *
  492.    * @param {!Element} element
  493.    * @param {!shaka.extern.RetryParameters} retryParameters
  494.    * @param {boolean} failGracefully
  495.    * @param {string} baseUri
  496.    * @param {!shaka.net.NetworkingEngine} networkingEngine
  497.    * @param {number=} linkDepth, default set to 0
  498.    * @return {!shaka.util.AbortableOperation.<!Element>}
  499.    */
  500.   static processXlinks(
  501.       element, retryParameters, failGracefully, baseUri, networkingEngine,
  502.       linkDepth = 0) {
  503.     const MpdUtils = shaka.dash.MpdUtils;
  504.     const XmlUtils = shaka.util.XmlUtils;
  505.     const NS = MpdUtils.XlinkNamespaceUri_;
  507.     if (XmlUtils.getAttributeNS(element, NS, 'href')) {
  508.       let handled = MpdUtils.handleXlinkInElement_(
  509.           element, retryParameters, failGracefully, baseUri, networkingEngine,
  510.           linkDepth);
  511.       if (failGracefully) {
  512.         // Catch any error and go on.
  513.         handled = handled.chain(undefined, (error) => {
  514.           // handleXlinkInElement_ strips the xlink properties off of the
  515.           // element even if it fails, so calling processXlinks again will
  516.           // handle whatever contents the element natively has.
  517.           return MpdUtils.processXlinks(
  518.               element, retryParameters, failGracefully, baseUri,
  519.               networkingEngine, linkDepth);
  520.         });
  521.       }
  522.       return handled;
  523.     }
  525.     const childOperations = [];
  526.     for (const child of Array.from(element.childNodes)) {
  527.       if (child instanceof Element) {
  528.         const resolveToZeroString = 'urn:mpeg:dash:resolve-to-zero:2013';
  529.         if (XmlUtils.getAttributeNS(child, NS, 'href') == resolveToZeroString) {
  530.           // This is a 'resolve to zero' code; it means the element should
  531.           // be removed, as specified by the mpeg-dash rules for xlink.
  532.           element.removeChild(child);
  533.         } else if (child.tagName != 'SegmentTimeline') {
  534.           // Don't recurse into a SegmentTimeline since xlink attributes
  535.           // aren't valid in there and looking at each segment can take a long
  536.           // time with larger manifests.
  538.           // Replace the child with its processed form.
  539.           childOperations.push(shaka.dash.MpdUtils.processXlinks(
  540.               /** @type {!Element} */ (child), retryParameters, failGracefully,
  541.               baseUri, networkingEngine, linkDepth));
  542.         }
  543.       }
  544.     }
  546.     return shaka.util.AbortableOperation.all(childOperations).chain(() => {
  547.       return element;
  548.     });
  549.   }
  550. };
  553. /**
  554.  * @typedef {{
  555.  *   start: number,
  556.  *   unscaledStart: number,
  557.  *   end: number
  558.  * }}
  559.  *
  560.  * @description
  561.  * Defines a time range of a media segment.  Times are in seconds.
  562.  *
  563.  * @property {number} start
  564.  *   The start time of the range.
  565.  * @property {number} unscaledStart
  566.  *   The start time of the range in representation timescale units.
  567.  * @property {number} end
  568.  *   The end time (exclusive) of the range.
  569.  */
  570. shaka.dash.MpdUtils.TimeRange;
  573. /**
  574.  * @typedef {{
  575.  *   timescale: number,
  576.  *   segmentDuration: ?number,
  577.  *   startNumber: number,
  578.  *   scaledPresentationTimeOffset: number,
  579.  *   unscaledPresentationTimeOffset: number,
  580.  *   timeline: Array.<shaka.dash.MpdUtils.TimeRange>
  581.  * }}
  582.  *
  583.  * @description
  584.  * Contains common information between SegmentList and SegmentTemplate items.
  585.  *
  586.  * @property {number} timescale
  587.  *   The time-scale of the representation.
  588.  * @property {?number} segmentDuration
  589.  *   The duration of the segments in seconds, if given.
  590.  * @property {number} startNumber
  591.  *   The start number of the segments; 1 or greater.
  592.  * @property {number} scaledPresentationTimeOffset
  593.  *   The presentation time offset of the representation, in seconds.
  594.  * @property {number} unscaledPresentationTimeOffset
  595.  *   The presentation time offset of the representation, in timescale units.
  596.  * @property {Array.<shaka.dash.MpdUtils.TimeRange>} timeline
  597.  *   The timeline of the representation, if given.  Times in seconds.
  598.  */
  599. shaka.dash.MpdUtils.SegmentInfo;
  602. /**
  603.  * @const {string}
  604.  * @private
  605.  */
  606. shaka.dash.MpdUtils.XlinkNamespaceUri_ = 'http://www.w3.org/1999/xlink';