Source: lib/media/segment_index.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.media.SegmentIndex');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.log');
  22. goog.require('shaka.media.SegmentReference');
  23. goog.require('shaka.util.IDestroyable');
  24. goog.require('shaka.util.ManifestParserUtils');
  28. /**
  29.  * Creates a SegmentIndex.
  30.  *
  31.  * @param {!Array.<!shaka.media.SegmentReference>} references The list of
  32.  *   SegmentReferences, which must be sorted first by their start times
  33.  *   (ascending) and second by their end times (ascending), and have
  34.  *   continuous, increasing positions.
  35.  *
  36.  * @constructor
  37.  * @struct
  38.  * @implements {shaka.util.IDestroyable}
  39.  * @export
  40.  */
  41. shaka.media.SegmentIndex = function(references) {
  42.   if (goog.DEBUG) {
  43.     shaka.media.SegmentIndex.assertCorrectReferences_(references);
  44.   }
  46.   /** @private {Array.<!shaka.media.SegmentReference>} */
  47.   this.references_ = references;
  48. };
  51. /**
  52.  * @override
  53.  * @export
  54.  */
  55. shaka.media.SegmentIndex.prototype.destroy = function() {
  56.   this.references_ = null;
  57.   return Promise.resolve();
  58. };
  61. /**
  62.  * Finds the position of the segment for the given time, in seconds, relative
  63.  * to the start of a particular Period. Returns the position of the segment
  64.  * with the largest end time if more than one segment is known for the given
  65.  * time.
  66.  *
  67.  * @param {number} time
  68.  * @return {?number} The position of the segment, or null
  69.  *   if the position of the segment could not be determined.
  70.  * @export
  71.  */
  72. shaka.media.SegmentIndex.prototype.find = function(time) {
  73.   // For live streams, searching from the end is faster. For VOD, it balances
  74.   // out either way. In both cases, references_.length is small enough that the
  75.   // difference isn't huge.
  76.   for (var i = this.references_.length - 1; i >= 0; --i) {
  77.     var r = this.references_[i];
  78.     // Note that a segment ends immediately before the end time.
  79.     if ((time >= r.startTime) && (time < r.endTime)) {
  80.       return r.position;
  81.     }
  82.   }
  83.   if (this.references_.length && time < this.references_[0].startTime)
  84.     return this.references_[0].position;
  86.   return null;
  87. };
  90. /**
  91.  * Gets the SegmentReference for the segment at the given position.
  92.  *
  93.  * @param {number} position The position of the segment.
  94.  * @return {shaka.media.SegmentReference} The SegmentReference, or null if
  95.  *   no such SegmentReference exists.
  96.  * @export
  97.  */
  98. shaka.media.SegmentIndex.prototype.get = function(position) {
  99.   if (this.references_.length == 0)
  100.     return null;
  102.   var index = position - this.references_[0].position;
  103.   if (index < 0 || index >= this.references_.length)
  104.     return null;
  106.   return this.references_[index];
  107. };
  110. /**
  111.  * Offset all segment references by a fixed amount.
  112.  *
  113.  * @param {number} offset The amount to add to each segment's start and end
  114.  *   times.
  115.  * @export
  116.  */
  117. shaka.media.SegmentIndex.prototype.offset = function(offset) {
  118.   for (var i = 0; i < this.references_.length; ++i) {
  119.     this.references_[i].startTime += offset;
  120.     this.references_[i].endTime += offset;
  121.   }
  122. };
  125. /**
  126.  * Merges the given SegmentReferences.  Supports extending the original
  127.  * references only.  Will not replace old references or interleave new ones.
  128.  *
  129.  * @param {!Array.<!shaka.media.SegmentReference>} references The list of
  130.  *   SegmentReferences, which must be sorted first by their start times
  131.  *   (ascending) and second by their end times (ascending), and have
  132.  *   continuous, increasing positions.
  133.  * @export
  134.  */
  135. shaka.media.SegmentIndex.prototype.merge = function(references) {
  136.   if (goog.DEBUG) {
  137.     shaka.media.SegmentIndex.assertCorrectReferences_(references);
  138.   }
  140.   var newReferences = [];
  141.   var i = 0;
  142.   var j = 0;
  144.   while ((i < this.references_.length) && (j < references.length)) {
  145.     var r1 = this.references_[i];
  146.     var r2 = references[j];
  148.     if (r1.startTime < r2.startTime) {
  149.       newReferences.push(r1);
  150.       i++;
  151.     } else if (r1.startTime > r2.startTime) {
  152.       if (i == 0) {
  153.         // If the reference appears before any existing reference, it may have
  154.         // been evicted before; in this case, simply add it back and it will be
  155.         // evicted again later.
  156.         newReferences.push(r2);
  157.       } else {
  158.         // Drop the new reference if it would have to be interleaved with the
  159.         // old one.  Issue a warning, since this is not a supported update.
  160.         shaka.log.warning('Refusing to rewrite original references on update!');
  161.       }
  162.       j++;
  163.     } else {
  164.       // When period is changed, fit() will expand the last segment to the start
  165.       // of the next period.  So, it is valid to have end time updated to the
  166.       // last segment reference in a period.
  167.       if (Math.abs(r1.endTime - r2.endTime) > 0.1) {
  168.         goog.asserts.assert(r2.endTime > r1.endTime &&
  169.             i == this.references_.length - 1 &&
  170.             j == references.length - 1,
  171.             'This should be an update of the last segment in a period');
  172.         var r = new shaka.media.SegmentReference(r1.position,
  173.             r2.startTime, r2.endTime, r2.getUris, r2.startByte, r2.endByte);
  174.         newReferences.push(r);
  175.       } else {
  176.         // Drop the new reference if there's an old reference with the
  177.         // same time.
  178.         newReferences.push(r1);
  179.       }
  180.       i++;
  181.       j++;
  182.     }
  183.   }
  185.   while (i < this.references_.length) {
  186.     newReferences.push(this.references_[i++]);
  187.   }
  189.   if (newReferences.length) {
  190.     // The rest of these refs may need to be renumbered.
  191.     var nextPosition = newReferences[newReferences.length - 1].position + 1;
  192.     while (j < references.length) {
  193.       var r = references[j++];
  194.       var r2 = new shaka.media.SegmentReference(nextPosition++,
  195.           r.startTime, r.endTime, r.getUris, r.startByte, r.endByte);
  196.       newReferences.push(r2);
  197.     }
  198.   } else {
  199.     newReferences = references;
  200.   }
  202.   if (goog.DEBUG) {
  203.     shaka.media.SegmentIndex.assertCorrectReferences_(newReferences);
  204.   }
  206.   this.references_ = newReferences;
  207. };
  210. /**
  211.  * Replace existing references with new ones, without merging.
  212.  *
  213.  * @param {!Array.<!shaka.media.SegmentReference>} newReferences
  214.  */
  215. shaka.media.SegmentIndex.prototype.replace = function(newReferences) {
  216.   if (goog.DEBUG) {
  217.     shaka.media.SegmentIndex.assertCorrectReferences_(newReferences);
  218.   }
  219.   this.references_ = newReferences;
  220. };
  223. /**
  224.  * Removes all SegmentReferences that end before the given time.
  225.  *
  226.  * @param {number} time The time in seconds.
  227.  * @export
  228.  */
  229. shaka.media.SegmentIndex.prototype.evict = function(time) {
  230.   for (var i = 0; i < this.references_.length; ++i) {
  231.     if (this.references_[i].endTime > time) {
  232.       this.references_.splice(0, i);
  233.       return;
  234.     }
  235.   }
  236.   this.references_ = [];
  237. };
  240. /**
  241.  * Expands the first SegmentReference so it begins at the start of its Period
  242.  * if it already begins close to the start of its Period.
  243.  *
  244.  * Also expands or contracts the last SegmentReference so it ends at the end of
  245.  * its Period.
  246.  *
  247.  * Do not call on the last period of a live presentation (unknown duration).
  248.  * It is okay to call on the other periods of a live presentation, where the
  249.  * duration is known and another period has been added.
  250.  *
  251.  * @param {?number} periodDuration
  252.  */
  253. shaka.media.SegmentIndex.prototype.fit = function(periodDuration) {
  254.   /** @const {number} */
  255.   var tolerance = shaka.util.ManifestParserUtils.GAP_OVERLAP_TOLERANCE_SECONDS;
  257.   goog.asserts.assert(periodDuration != null,
  258.                       'Period duration must be known for static content!');
  259.   goog.asserts.assert(periodDuration != Infinity,
  260.                       'Period duration must be finite for static content!');
  262.   // Trim out references we will never use.
  263.   while (this.references_.length) {
  264.     var lastReference = this.references_[this.references_.length - 1];
  265.     if (lastReference.startTime >= periodDuration) {
  266.       this.references_.pop();
  267.     } else {
  268.       break;
  269.     }
  270.   }
  271.   while (this.references_.length) {
  272.     var firstReference = this.references_[0];
  273.     if (firstReference.endTime <= 0) {
  274.       this.references_.shift();
  275.     } else {
  276.       break;
  277.     }
  278.   }
  280.   if (this.references_.length == 0)
  281.     return;
  283.   // Adjust the first SegmentReference if the start time is smaller than the gap
  284.   // tolerance (including negative).
  285.   var firstReference = this.references_[0];
  286.   if (firstReference.startTime < tolerance) {
  287.     this.references_[0] =
  288.         new shaka.media.SegmentReference(
  289.             firstReference.position,
  290.             /* startTime */ 0,
  291.             firstReference.endTime,
  292.             firstReference.getUris,
  293.             firstReference.startByte,
  294.             firstReference.endByte);
  295.   }
  297.   // Adjust the last SegmentReference.
  298.   var lastReference = this.references_[this.references_.length - 1];
  299.   this.references_[this.references_.length - 1] =
  300.       new shaka.media.SegmentReference(
  301.           lastReference.position,
  302.           lastReference.startTime,
  303.           /* endTime */ periodDuration,
  304.           lastReference.getUris,
  305.           lastReference.startByte,
  306.           lastReference.endByte);
  307. };
  310. if (goog.DEBUG) {
  311.   /**
  312.    * Asserts that the given SegmentReferences are sorted and have continuous,
  313.    * increasing positions.
  314.    *
  315.    * @param {!Array.<shaka.media.SegmentReference>} references
  316.    * @private
  317.    */
  318.   shaka.media.SegmentIndex.assertCorrectReferences_ = function(references) {
  319.     goog.asserts.assert(references.every(function(r2, i) {
  320.       if (i == 0) return true;
  321.       var r1 = references[i - 1];
  322.       if (r2.position != r1.position + 1) return false;
  323.       if (r1.startTime < r2.startTime) {
  324.         return true;
  325.       } else if (r1.startTime > r2.startTime) {
  326.         return false;
  327.       } else {
  328.         if (r1.endTime <= r2.endTime) {
  329.           return true;
  330.         } else {
  331.           return false;
  332.         }
  333.       }
  334.     }), 'SegmentReferences are incorrect');
  335.   };
  336. }