Source: lib/media/presentation_timeline.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.PresentationTimeline');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.log');
  22. goog.require('shaka.media.SegmentReference');
  25. /**
  26.  * Creates a PresentationTimeline.
  27.  *
  28.  * @param {?number} presentationStartTime The wall-clock time, in seconds,
  29.  *   when the presentation started or will start. Only required for live.
  30.  * @param {number} presentationDelay The delay to give the presentation, in
  31.  *   seconds.  Only required for live.
  32.  * @param {boolean=} autoCorrectDrift Whether to account for drift when
  33.  *   determining the availability window.
  34.  *
  35.  * @see {shaka.extern.Manifest}
  36.  * @see {@tutorial architecture}
  37.  *
  38.  * @constructor
  39.  * @struct
  40.  * @export
  41.  */
  42. shaka.media.PresentationTimeline = function(
  43.     presentationStartTime, presentationDelay, autoCorrectDrift = true) {
  44.   /** @private {?number} */
  45.   this.presentationStartTime_ = presentationStartTime;
  47.   /** @private {number} */
  48.   this.presentationDelay_ = presentationDelay;
  50.   /** @private {number} */
  51.   this.duration_ = Infinity;
  53.   /** @private {number} */
  54.   this.segmentAvailabilityDuration_ = Infinity;
  56.   /**
  57.    * The maximum segment duration (in seconds).  Can be based on explicitly-
  58.    * known segments or on signalling in the manifest.
  59.    *
  60.    * @private {number}
  61.    */
  62.   this.maxSegmentDuration_ = 1;
  64.   /**
  65.    * The minimum segment start time (in seconds, in the presentation timeline)
  66.    * for segments we explicitly know about.
  67.    *
  68.    * This is null if we have no explicit descriptions of segments, such as in
  69.    * DASH when using SegmentTemplate w/ duration.
  70.    *
  71.    * @private {?number}
  72.    */
  73.   this.minSegmentStartTime_ = null;
  75.   /**
  76.    * The maximum segment end time (in seconds, in the presentation timeline) for
  77.    * segments we explicitly know about.
  78.    *
  79.    * This is null if we have no explicit descriptions of segments, such as in
  80.    * DASH when using SegmentTemplate w/ duration.  When this is non-null, the
  81.    * presentation start time is calculated from the segment end times.
  82.    *
  83.    * @private {?number}
  84.    */
  85.   this.maxSegmentEndTime_ = null;
  87.   /** @private {number} */
  88.   this.clockOffset_ = 0;
  90.   /** @private {boolean} */
  91.   this.static_ = true;
  93.   /** @private {number} */
  94.   this.userSeekStart_ = 0;
  96.   /** @private {boolean} */
  97.   this.autoCorrectDrift_ = autoCorrectDrift;
  98. };
  101. /**
  102.  * @return {number} The presentation's duration in seconds.
  103.  *   Infinity indicates that the presentation continues indefinitely.
  104.  * @export
  105.  */
  106. shaka.media.PresentationTimeline.prototype.getDuration = function() {
  107.   return this.duration_;
  108. };
  111. /**
  112.  * @return {number} The presentation's max segment duration in seconds.
  113.  */
  114. shaka.media.PresentationTimeline.prototype.getMaxSegmentDuration = function() {
  115.   return this.maxSegmentDuration_;
  116. };
  119. /**
  120.  * Sets the presentation's duration.
  121.  *
  122.  * @param {number} duration The presentation's duration in seconds.
  123.  *   Infinity indicates that the presentation continues indefinitely.
  124.  * @export
  125.  */
  126. shaka.media.PresentationTimeline.prototype.setDuration = function(duration) {
  127.   goog.asserts.assert(duration > 0, 'duration must be > 0');
  128.   this.duration_ = duration;
  129. };
  132. /**
  133.  * @return {?number} The presentation's start time in seconds.
  134.  * @export
  135.  */
  136. shaka.media.PresentationTimeline.prototype.getPresentationStartTime =
  137.     function() {
  138.   return this.presentationStartTime_;
  139. };
  142. /**
  143.  * Sets the clock offset, which is the difference between the client's clock
  144.  * and the server's clock, in milliseconds (i.e., serverTime = Date.now() +
  145.  * clockOffset).
  146.  *
  147.  * @param {number} offset The clock offset, in ms.
  148.  * @export
  149.  */
  150. shaka.media.PresentationTimeline.prototype.setClockOffset = function(offset) {
  151.   this.clockOffset_ = offset;
  152. };
  155. /**
  156.  * Sets the presentation's static flag.
  157.  *
  158.  * @param {boolean} isStatic If true, the presentation is static, meaning all
  159.  *   segments are available at once.
  160.  * @export
  161.  */
  162. shaka.media.PresentationTimeline.prototype.setStatic = function(isStatic) {
  163.   // NOTE: the argument name is not "static" because that's a keyword in ES6
  164.   this.static_ = isStatic;
  165. };
  168. /**
  169.  * Sets the presentation's segment availability duration. The segment
  170.  * availability duration should only be set for live.
  171.  *
  172.  * @param {number} segmentAvailabilityDuration The presentation's new segment
  173.  *   availability duration in seconds.
  174.  * @export
  175.  */
  176. shaka.media.PresentationTimeline.prototype.setSegmentAvailabilityDuration =
  177.     function(segmentAvailabilityDuration) {
  178.   goog.asserts.assert(segmentAvailabilityDuration >= 0,
  179.                       'segmentAvailabilityDuration must be >= 0');
  180.   this.segmentAvailabilityDuration_ = segmentAvailabilityDuration;
  181. };
  184. /**
  185.  * Sets the presentation delay in seconds.
  186.  *
  187.  * @param {number} delay
  188.  * @export
  189.  */
  190. shaka.media.PresentationTimeline.prototype.setDelay = function(delay) {
  191.   // NOTE: This is no longer used internally, but is exported.
  192.   // So we cannot remove it without deprecating it and waiting one release
  193.   // cycle, or else we risk breaking custom manifest parsers.
  194.   goog.asserts.assert(delay >= 0, 'delay must be >= 0');
  195.   this.presentationDelay_ = delay;
  196. };
  199. /**
  200.  * Gets the presentation delay in seconds.
  201.  * @return {number}
  202.  * @export
  203.  */
  204. shaka.media.PresentationTimeline.prototype.getDelay = function() {
  205.   return this.presentationDelay_;
  206. };
  209. /**
  210.  * Gives PresentationTimeline a Stream's segments so it can size and position
  211.  * the segment availability window, and account for missing segment
  212.  * information.  This function should be called once for each Stream (no more,
  213.  * no less).
  214.  *
  215.  * @param {!Array.<!shaka.media.SegmentReference>} references
  216.  * @param {number} periodStart
  217.  * @export
  218.  */
  219. shaka.media.PresentationTimeline.prototype.notifySegments = function(
  220.     references, periodStart) {
  221.   if (references.length == 0) {
  222.     return;
  223.   }
  225.   // TODO: Make SegmentReferences use timestamps in the presentation timeline,
  226.   // not the period timeline.
  227.   const firstReferenceStartTime = references[0].startTime + periodStart;
  228.   const lastReferenceEndTime =
  229.       references[references.length - 1].endTime + periodStart;
  231.   this.notifyMinSegmentStartTime(firstReferenceStartTime);
  233.   this.maxSegmentDuration_ = references.reduce(
  234.       function(max, r) { return Math.max(max, r.endTime - r.startTime); },
  235.       this.maxSegmentDuration_);
  237.   this.maxSegmentEndTime_ =
  238.       Math.max(this.maxSegmentEndTime_, lastReferenceEndTime);
  240.   if (this.presentationStartTime_ != null && this.autoCorrectDrift_) {
  241.     // Since we have explicit segment end times, calculate a presentation start
  242.     // based on them.  This start time accounts for drift.
  243.     // Date.now() is in milliseconds, from which we compute "now" in seconds.
  244.     let now = (Date.now() + this.clockOffset_) / 1000.0;
  245.     this.presentationStartTime_ =
  246.         now - this.maxSegmentEndTime_ - this.maxSegmentDuration_;
  247.   }
  249.   shaka.log.v1('notifySegments:',
  250.                'maxSegmentDuration=' + this.maxSegmentDuration_);
  251. };
  254. /**
  255.  * Gives PresentationTimeline a Stream's minimum segment start time.
  256.  *
  257.  * @param {number} startTime
  258.  * @export
  259.  */
  260. shaka.media.PresentationTimeline.prototype.notifyMinSegmentStartTime = function(
  261.     startTime) {
  262.   if (this.minSegmentStartTime_ == null) {
  263.     // No data yet, and Math.min(null, startTime) is always 0.  So just store
  264.     // startTime.
  265.     this.minSegmentStartTime_ = startTime;
  266.   } else {
  267.     this.minSegmentStartTime_ =
  268.         Math.min(this.minSegmentStartTime_, startTime);
  269.   }
  270. };
  273. /**
  274.  * Gives PresentationTimeline a Stream's maximum segment duration so it can
  275.  * size and position the segment availability window.  This function should be
  276.  * called once for each Stream (no more, no less), but does not have to be
  277.  * called if notifySegments() is called instead for a particular stream.
  278.  *
  279.  * @param {number} maxSegmentDuration The maximum segment duration for a
  280.  *   particular stream.
  281.  * @export
  282.  */
  283. shaka.media.PresentationTimeline.prototype.notifyMaxSegmentDuration = function(
  284.     maxSegmentDuration) {
  285.   this.maxSegmentDuration_ = Math.max(
  286.       this.maxSegmentDuration_, maxSegmentDuration);
  288.   shaka.log.v1('notifyNewSegmentDuration:',
  289.                'maxSegmentDuration=' + this.maxSegmentDuration_);
  290. };
  293. /**
  294.  * Offsets the segment times by the given amount.
  295.  *
  296.  * @param {number} offset The number of seconds to offset by.  A positive number
  297.  *   adjusts the segment times forward.
  298.  * @export
  299.  */
  300. shaka.media.PresentationTimeline.prototype.offset = function(offset) {
  301.   if (this.minSegmentStartTime_ != null) {
  302.     this.minSegmentStartTime_ += offset;
  303.   }
  304.   if (this.maxSegmentEndTime_ != null) {
  305.     this.maxSegmentEndTime_ += offset;
  306.   }
  307. };
  310. /**
  311.  * @return {boolean} True if the presentation is live; otherwise, return
  312.  *   false.
  313.  * @export
  314.  */
  315. shaka.media.PresentationTimeline.prototype.isLive = function() {
  316.   return this.duration_ == Infinity &&
  317.          !this.static_;
  318. };
  321. /**
  322.  * @return {boolean} True if the presentation is in progress (meaning not live,
  323.  *   but also not completely available); otherwise, return false.
  324.  * @export
  325.  */
  326. shaka.media.PresentationTimeline.prototype.isInProgress = function() {
  327.   return this.duration_ != Infinity &&
  328.          !this.static_;
  329. };
  332. /**
  333.  * Gets the presentation's current segment availability start time.  Segments
  334.  * ending at or before this time should be assumed to be unavailable.
  335.  *
  336.  * @return {number} The current segment availability start time, in seconds,
  337.  *   relative to the start of the presentation.
  338.  * @export
  339.  */
  340. shaka.media.PresentationTimeline.prototype.getSegmentAvailabilityStart =
  341.     function() {
  342.   goog.asserts.assert(this.segmentAvailabilityDuration_ >= 0,
  343.                       'The availability duration should be positive');
  345.   if (this.segmentAvailabilityDuration_ == Infinity) {
  346.     return this.userSeekStart_;
  347.   }
  349.   let end = this.getSegmentAvailabilityEnd();
  350.   let start = end - this.segmentAvailabilityDuration_;
  351.   return Math.max(this.userSeekStart_, start);
  352. };
  355. /**
  356.  * Sets the start time of the user-defined seek range.  This is only used for
  357.  * VOD content.
  358.  *
  359.  * @param {number} time
  360.  * @export
  361.  */
  362. shaka.media.PresentationTimeline.prototype.setUserSeekStart =
  363.     function(time) {
  364.   this.userSeekStart_ = time;
  365. };
  368. /**
  369.  * Gets the presentation's current segment availability end time.  Segments
  370.  * starting after this time should be assumed to be unavailable.
  371.  *
  372.  * @return {number} The current segment availability end time, in seconds,
  373.  *   relative to the start of the presentation.  Always returns the
  374.  *   presentation's duration for video-on-demand.
  375.  * @export
  376.  */
  377. shaka.media.PresentationTimeline.prototype.getSegmentAvailabilityEnd =
  378.     function() {
  379.   if (!this.isLive() && !this.isInProgress()) {
  380.     return this.duration_;
  381.   }
  383.   return Math.min(this.getLiveEdge_(), this.duration_);
  384. };
  387. /**
  388.  * Gets the seek range start time, offset by the given amount.  This is used to
  389.  * ensure that we don't "fall" back out of the seek window while we are
  390.  * buffering.
  391.  *
  392.  * @param {number} offset The offset to add to the start time.
  393.  * @return {number} The current seek start time, in seconds, relative to the
  394.  *   start of the presentation.
  395.  * @export
  396.  */
  397. shaka.media.PresentationTimeline.prototype.getSafeSeekRangeStart = function(
  398.     offset) {
  399.   // The earliest known segment time, ignoring segment availability duration.
  400.   const earliestSegmentTime =
  401.       Math.max(this.minSegmentStartTime_, this.userSeekStart_);
  402.   if (this.segmentAvailabilityDuration_ == Infinity) {
  403.     return earliestSegmentTime;
  404.   }
  406.   // AKA the live edge for live streams.
  407.   const availabilityEnd = this.getSegmentAvailabilityEnd();
  409.   // The ideal availability start, not considering known segments.
  410.   const availabilityStart = availabilityEnd - this.segmentAvailabilityDuration_;
  412.   // Add the offset to the availability start to ensure that we don't fall
  413.   // outside the availability window while we buffer; we don't need to add the
  414.   // offset to earliestSegmentTime since that won't change over time.
  415.   // Also see: https://github.com/google/shaka-player/issues/692
  416.   const desiredStart =
  417.       Math.min(availabilityStart + offset, this.getSeekRangeEnd());
  418.   return Math.max(earliestSegmentTime, desiredStart);
  419. };
  422. /**
  423.  * Gets the seek range start time.
  424.  *
  425.  * @return {number}
  426.  * @export
  427.  */
  428. shaka.media.PresentationTimeline.prototype.getSeekRangeStart = function() {
  429.   return this.getSafeSeekRangeStart(/* offset */ 0);
  430. };
  433. /**
  434.  * Gets the seek range end.
  435.  *
  436.  * @return {number}
  437.  * @export
  438.  */
  439. shaka.media.PresentationTimeline.prototype.getSeekRangeEnd = function() {
  440.   let useDelay = this.isLive() || this.isInProgress();
  441.   let delay = useDelay ? this.presentationDelay_ : 0;
  442.   return Math.max(0, this.getSegmentAvailabilityEnd() - delay);
  443. };
  446. /**
  447.  * True if the presentation start time is being used to calculate the live edge.
  448.  * Using the presentation start time means that the stream may be subject to
  449.  * encoder drift.  At runtime, we will avoid using the presentation start time
  450.  * whenever possible.
  451.  *
  452.  * @return {boolean}
  453.  * @export
  454.  */
  455. shaka.media.PresentationTimeline.prototype.usingPresentationStartTime =
  456.     function() {
  457.   // If it's VOD, IPR, or an HLS "event", we are not using the presentation
  458.   // start time.
  459.   if (this.presentationStartTime_ == null) {
  460.     return false;
  461.   }
  463.   // If we have explicit segment times, we're not using the presentation
  464.   // start time.
  465.   if (this.maxSegmentEndTime_ != null) {
  466.     return false;
  467.   }
  469.   return true;
  470. };
  473. /**
  474.  * @return {number} The current presentation time in seconds.
  475.  * @private
  476.  */
  477. shaka.media.PresentationTimeline.prototype.getLiveEdge_ = function() {
  478.   goog.asserts.assert(this.presentationStartTime_ != null,
  479.                       'Cannot compute timeline live edge without start time');
  480.   // Date.now() is in milliseconds, from which we compute "now" in seconds.
  481.   let now = (Date.now() + this.clockOffset_) / 1000.0;
  482.   return Math.max(
  483.       0, now - this.maxSegmentDuration_ - this.presentationStartTime_);
  484. };
  487. if (goog.DEBUG) {
  488.   /**
  489.    * Debug only: assert that the timeline parameters make sense for the type of
  490.    *   presentation (VOD, IPR, live).
  491.    */
  492.   shaka.media.PresentationTimeline.prototype.assertIsValid = function() {
  493.     if (this.isLive()) {
  494.       // Implied by isLive(): infinite and dynamic.
  495.       // Live streams should have a start time.
  496.       goog.asserts.assert(this.presentationStartTime_ != null,
  497.           'Detected as live stream, but does not match our model of live!');
  498.     } else if (this.isInProgress()) {
  499.       // Implied by isInProgress(): finite and dynamic.
  500.       // IPR streams should have a start time, and segments should not expire.
  501.       goog.asserts.assert(this.presentationStartTime_ != null &&
  502.                           this.segmentAvailabilityDuration_ == Infinity,
  503.           'Detected as IPR stream, but does not match our model of IPR!');
  504.     } else {  // VOD
  505.       // VOD segments should not expire and the presentation should be finite
  506.       // and static.
  507.       goog.asserts.assert(this.segmentAvailabilityDuration_ == Infinity &&
  508.                           this.duration_ != Infinity &&
  509.                           this.static_,
  510.           'Detected as VOD stream, but does not match our model of VOD!');
  511.     }
  512.   };
  513. }