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');
  26. /**
  27.  * Creates a PresentationTimeline.
  28.  *
  29.  * @param {?number} presentationStartTime The wall-clock time, in seconds,
  30.  *   when the presentation started or will start. Only required for live.
  31.  * @param {number} presentationDelay The delay to give the presentation, in
  32.  *   seconds.  Only required for live.
  33.  *
  34.  * @see {shakaExtern.Manifest}
  35.  * @see {@tutorial architecture}
  36.  *
  37.  * @constructor
  38.  * @struct
  39.  * @export
  40.  */
  41. shaka.media.PresentationTimeline = function(
  42.     presentationStartTime, presentationDelay) {
  43.   /** @private {?number} */
  44.   this.presentationStartTime_ = presentationStartTime;
  46.   /** @private {number} */
  47.   this.presentationDelay_ = presentationDelay;
  49.   /** @private {number} */
  50.   this.duration_ = Infinity;
  52.   /** @private {number} */
  53.   this.segmentAvailabilityDuration_ = Infinity;
  55.   /** @private {number} */
  56.   this.maxSegmentDuration_ = 1;
  58.   /** @private {number} */
  59.   this.maxFirstSegmentStartTime_ = 0;
  61.   /** @private {number} */
  62.   this.clockOffset_ = 0;
  64.   /** @private {boolean} */
  65.   this.static_ = true;
  67.   /** @private {number} */
  68.   this.userSeekStart_ = 0;
  69. };
  72. /**
  73.  * @return {number} The presentation's duration in seconds.
  74.  *   Infinity indicates that the presentation continues indefinitely.
  75.  * @export
  76.  */
  77. shaka.media.PresentationTimeline.prototype.getDuration = function() {
  78.   return this.duration_;
  79. };
  82. /**
  83.  * @return {number} The presentation's max segment duration in seconds.
  84.  */
  85. shaka.media.PresentationTimeline.prototype.getMaxSegmentDuration = function() {
  86.   return this.maxSegmentDuration_;
  87. };
  90. /**
  91.  * Sets the presentation's duration.
  92.  *
  93.  * @param {number} duration The presentation's duration in seconds.
  94.  *   Infinity indicates that the presentation continues indefinitely.
  95.  * @export
  96.  */
  97. shaka.media.PresentationTimeline.prototype.setDuration = function(duration) {
  98.   goog.asserts.assert(duration > 0, 'duration must be > 0');
  99.   this.duration_ = duration;
  100. };
  103. /**
  104.  * @return {?number} The presentation's start time in seconds.
  105.  * @export
  106.  */
  107. shaka.media.PresentationTimeline.prototype.getPresentationStartTime =
  108.     function() {
  109.   return this.presentationStartTime_;
  110. };
  113. /**
  114.  * Sets the clock offset, which is the difference between the client's clock
  115.  * and the server's clock, in milliseconds (i.e., serverTime = Date.now() +
  116.  * clockOffset).
  117.  *
  118.  * @param {number} offset The clock offset, in ms.
  119.  * @export
  120.  */
  121. shaka.media.PresentationTimeline.prototype.setClockOffset = function(offset) {
  122.   this.clockOffset_ = offset;
  123. };
  126. /**
  127.  * Sets the presentation's static flag.
  128.  *
  129.  * @param {boolean} isStatic If true, the presentation is static, meaning all
  130.  *   segments are available at once.
  131.  * @export
  132.  */
  133. shaka.media.PresentationTimeline.prototype.setStatic = function(isStatic) {
  134.   // NOTE: the argument name is not "static" because that's a keyword in ES6
  135.   this.static_ = isStatic;
  136. };
  139. /**
  140.  * Sets the presentation's segment availability duration. The segment
  141.  * availability duration should only be set for live.
  142.  *
  143.  * @param {number} segmentAvailabilityDuration The presentation's new segment
  144.  *   availability duration in seconds.
  145.  * @export
  146.  */
  147. shaka.media.PresentationTimeline.prototype.setSegmentAvailabilityDuration =
  148.     function(segmentAvailabilityDuration) {
  149.   goog.asserts.assert(segmentAvailabilityDuration >= 0,
  150.                       'segmentAvailabilityDuration must be >= 0');
  151.   this.segmentAvailabilityDuration_ = segmentAvailabilityDuration;
  152. };
  155. /**
  156.  * Sets the presentation delay.
  157.  *
  158.  * @param {number} delay
  159.  * @export
  160.  */
  161. shaka.media.PresentationTimeline.prototype.setDelay = function(delay) {
  162.   goog.asserts.assert(delay >= 0, 'delay must be >= 0');
  163.   this.presentationDelay_ = delay;
  164. };
  167. /**
  168.  * Gives PresentationTimeline a Stream's segments so it can size and position
  169.  * the segment availability window, and account for missing segment
  170.  * information.  This function should be called once for each Stream (no more,
  171.  * no less).
  172.  *
  173.  * @param {!Array.<!shaka.media.SegmentReference>} references
  174.  * @param {boolean} isFirstPeriod
  175.  * @export
  176.  */
  177. shaka.media.PresentationTimeline.prototype.notifySegments = function(
  178.     references, isFirstPeriod) {
  179.   if (references.length == 0) {
  180.     return;
  181.   }
  183.   if (isFirstPeriod) {
  184.     this.maxFirstSegmentStartTime_ =
  185.         Math.max(this.maxFirstSegmentStartTime_, references[0].startTime);
  186.   }
  188.   this.maxSegmentDuration_ = references.reduce(
  189.       function(max, r) { return Math.max(max, r.endTime - r.startTime); },
  190.       this.maxSegmentDuration_);
  192.   shaka.log.v1('notifySegments:',
  193.                'maxSegmentDuration=' + this.maxSegmentDuration_);
  194. };
  197. /**
  198.  * Gives PresentationTimeline a Stream's maximum segment duration so it can
  199.  * size and position the segment availability window.  This function should be
  200.  * called once for each Stream (no more, no less), but does not have to be
  201.  * called if notifySegments() is called instead for a particular stream.
  202.  *
  203.  * @param {number} maxSegmentDuration The maximum segment duration for a
  204.  *   particular stream.
  205.  * @export
  206.  */
  207. shaka.media.PresentationTimeline.prototype.notifyMaxSegmentDuration = function(
  208.     maxSegmentDuration) {
  209.   this.maxSegmentDuration_ = Math.max(
  210.       this.maxSegmentDuration_, maxSegmentDuration);
  212.   shaka.log.v1('notifyNewSegmentDuration:',
  213.                'maxSegmentDuration=' + this.maxSegmentDuration_);
  214. };
  217. /**
  218.  * Offsets the segment times by the given amount.
  219.  *
  220.  * @param {number} offset The number of seconds to offset by.  A positive number
  221.  *   adjusts the segment times forward.
  222.  * @export
  223.  */
  224. shaka.media.PresentationTimeline.prototype.offset = function(offset) {
  225.   this.maxFirstSegmentStartTime_ += offset;
  226. };
  229. /**
  230.  * @return {boolean} True if the presentation is live; otherwise, return
  231.  *   false.
  232.  * @export
  233.  */
  234. shaka.media.PresentationTimeline.prototype.isLive = function() {
  235.   return this.duration_ == Infinity &&
  236.          !this.static_;
  237. };
  240. /**
  241.  * @return {boolean} True if the presentation is in progress (meaning not live,
  242.  *   but also not completely available); otherwise, return false.
  243.  * @export
  244.  */
  245. shaka.media.PresentationTimeline.prototype.isInProgress = function() {
  246.   return this.duration_ != Infinity &&
  247.          !this.static_;
  248. };
  251. /**
  252.  * Gets the presentation's current segment availability start time.  Segments
  253.  * ending at or before this time should be assumed to be unavailable.
  254.  *
  255.  * @return {number} The current segment availability start time, in seconds,
  256.  *   relative to the start of the presentation.
  257.  * @export
  258.  */
  259. shaka.media.PresentationTimeline.prototype.getSegmentAvailabilityStart =
  260.     function() {
  261.   goog.asserts.assert(this.segmentAvailabilityDuration_ >= 0,
  262.                       'The availability duration should be positive');
  264.   if (this.segmentAvailabilityDuration_ == Infinity) {
  265.     return this.userSeekStart_;
  266.   }
  268.   let end = this.getSegmentAvailabilityEnd();
  269.   let start = end - this.segmentAvailabilityDuration_;
  270.   return Math.max(this.userSeekStart_, start);
  271. };
  274. /**
  275.  * Sets the start time of the user-defined seek range.  This is only used for
  276.  * VOD content.
  277.  *
  278.  * @param {number} time
  279.  * @export
  280.  */
  281. shaka.media.PresentationTimeline.prototype.setUserSeekStart =
  282.     function(time) {
  283.   this.userSeekStart_ = time;
  284. };
  287. /**
  288.  * Gets the presentation's current segment availability end time.  Segments
  289.  * starting after this time should be assumed to be unavailable.
  290.  *
  291.  * @return {number} The current segment availability end time, in seconds,
  292.  *   relative to the start of the presentation.  Always returns the
  293.  *   presentation's duration for video-on-demand.
  294.  * @export
  295.  */
  296. shaka.media.PresentationTimeline.prototype.getSegmentAvailabilityEnd =
  297.     function() {
  298.   if (!this.isLive() && !this.isInProgress()) {
  299.     return this.duration_;
  300.   }
  302.   return Math.min(this.getLiveEdge_(), this.duration_);
  303. };
  306. /**
  307.  * Gets the seek range start time, offset by the given amount.  This is used to
  308.  * ensure that we don't "fall" back out of the seek window while we are
  309.  * buffering.
  310.  *
  311.  * @param {number} offset The offset to add to the start time.
  312.  * @return {number} The current seek start time, in seconds, relative to the
  313.  *   start of the presentation.
  314.  * @export
  315.  */
  316. shaka.media.PresentationTimeline.prototype.getSafeSeekRangeStart = function(
  317.     offset) {
  318.   // The start of the seek window, ignoring segment availability duration.
  319.   const seekStart =
  320.       Math.max(this.maxFirstSegmentStartTime_, this.userSeekStart_);
  321.   if (this.segmentAvailabilityDuration_ == Infinity) {
  322.     return seekStart;
  323.   }
  325.   const availabilityEnd = this.getSegmentAvailabilityEnd();
  326.   const availabilityStart = availabilityEnd - this.segmentAvailabilityDuration_;
  327.   // Add the offset to the availability start to ensure that we don't fall
  328.   // outside the availability window while we buffer; we don't need to add the
  329.   // offset to seekStart since that won't change over time.
  330.   // Also see: https://github.com/google/shaka-player/issues/692
  331.   const desiredStart =
  332.       Math.min(availabilityStart + offset, this.getSeekRangeEnd());
  333.   return Math.max(seekStart, desiredStart);
  334. };
  337. /**
  338.  * Gets the seek range start time.
  339.  *
  340.  * @return {number}
  341.  * @export
  342.  */
  343. shaka.media.PresentationTimeline.prototype.getSeekRangeStart = function() {
  344.   return this.getSafeSeekRangeStart(/* offset */ 0);
  345. };
  348. /**
  349.  * Gets the seek range end.
  350.  *
  351.  * @return {number}
  352.  * @export
  353.  */
  354. shaka.media.PresentationTimeline.prototype.getSeekRangeEnd = function() {
  355.   let useDelay = this.isLive() || this.isInProgress();
  356.   let delay = useDelay ? this.presentationDelay_ : 0;
  357.   return Math.max(0, this.getSegmentAvailabilityEnd() - delay);
  358. };
  361. /**
  362.  * @return {number} The current presentation time in seconds.
  363.  * @private
  364.  */
  365. shaka.media.PresentationTimeline.prototype.getLiveEdge_ = function() {
  366.   goog.asserts.assert(this.presentationStartTime_ != null,
  367.                       'Cannot compute timeline live edge without start time');
  368.   let now = (Date.now() + this.clockOffset_) / 1000.0;
  369.   return Math.max(
  370.       0, now - this.maxSegmentDuration_ - this.presentationStartTime_);
  371. };
  374. if (goog.DEBUG) {
  375.   /**
  376.    * Debug only: assert that the timeline parameters make sense for the type of
  377.    *   presentation (VOD, IPR, live).
  378.    */
  379.   shaka.media.PresentationTimeline.prototype.assertIsValid = function() {
  380.     if (this.isLive()) {
  381.       // Implied by isLive(): infinite and dynamic.
  382.       // Live streams should have a start time.
  383.       goog.asserts.assert(this.presentationStartTime_ != null,
  384.           'Detected as live stream, but does not match our model of live!');
  385.     } else if (this.isInProgress()) {
  386.       // Implied by isInProgress(): finite and dynamic.
  387.       // IPR streams should have a start time, and segments should not expire.
  388.       goog.asserts.assert(this.presentationStartTime_ != null &&
  389.                           this.segmentAvailabilityDuration_ == Infinity,
  390.           'Detected as IPR stream, but does not match our model of IPR!');
  391.     } else {  // VOD
  392.       // VOD segments should not expire and the presentation should be finite
  393.       // and static.
  394.       goog.asserts.assert(this.segmentAvailabilityDuration_ == Infinity &&
  395.                           this.duration_ != Infinity &&
  396.                           this.static_,
  397.           'Detected as VOD stream, but does not match our model of VOD!');
  398.     }
  399.   };
  400. }