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