Source: lib/media/presentation_timeline.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.media.PresentationTimeline');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.media.SegmentReference');
  14. /**
  15.  * PresentationTimeline.
  16.  * @export
  17.  */
  18. shaka.media.PresentationTimeline = class {
  19.   /**
  20.    * @param {?number} presentationStartTime The wall-clock time, in seconds,
  21.    *   when the presentation started or will start. Only required for live.
  22.    * @param {number} presentationDelay The delay to give the presentation, in
  23.    *   seconds.  Only required for live.
  24.    * @param {boolean=} autoCorrectDrift Whether to account for drift when
  25.    *   determining the availability window.
  26.    *
  27.    * @see {shaka.extern.Manifest}
  28.    * @see {@tutorial architecture}
  29.    */
  30.   constructor(presentationStartTime, presentationDelay,
  31.       autoCorrectDrift = true) {
  32.     /** @private {?number} */
  33.     this.presentationStartTime_ = presentationStartTime;
  35.     /** @private {number} */
  36.     this.presentationDelay_ = presentationDelay;
  38.     /** @private {number} */
  39.     this.duration_ = Infinity;
  41.     /** @private {number} */
  42.     this.segmentAvailabilityDuration_ = Infinity;
  44.     /**
  45.      * The maximum segment duration (in seconds).  Can be based on explicitly-
  46.      * known segments or on signalling in the manifest.
  47.      *
  48.      * @private {number}
  49.      */
  50.     this.maxSegmentDuration_ = 1;
  52.     /**
  53.      * The minimum segment start time (in seconds, in the presentation timeline)
  54.      * for segments we explicitly know about.
  55.      *
  56.      * This is null if we have no explicit descriptions of segments, such as in
  57.      * DASH when using SegmentTemplate w/ duration.
  58.      *
  59.      * @private {?number}
  60.      */
  61.     this.minSegmentStartTime_ = null;
  63.     /**
  64.      * The maximum segment end time (in seconds, in the presentation timeline)
  65.      * for segments we explicitly know about.
  66.      *
  67.      * This is null if we have no explicit descriptions of segments, such as in
  68.      * DASH when using SegmentTemplate w/ duration.  When this is non-null, the
  69.      * presentation start time is calculated from the segment end times.
  70.      *
  71.      * @private {?number}
  72.      */
  73.     this.maxSegmentEndTime_ = null;
  75.     /** @private {number} */
  76.     this.clockOffset_ = 0;
  78.     /** @private {boolean} */
  79.     this.static_ = true;
  81.     /** @private {number} */
  82.     this.userSeekStart_ = 0;
  84.     /** @private {boolean} */
  85.     this.autoCorrectDrift_ = autoCorrectDrift;
  87.     /**
  88.      * For low latency Dash, availabilityTimeOffset indicates a segment is
  89.      * available for download earlier than its availability start time.
  90.      * This field is the minimum availabilityTimeOffset value among the
  91.      * segments. We reduce the distance from live edge by this value.
  92.      *
  93.      * @private {number}
  94.      */
  95.     this.availabilityTimeOffset_ = 0;
  96.   }
  99.   /**
  100.    * @return {number} The presentation's duration in seconds.
  101.    *   Infinity indicates that the presentation continues indefinitely.
  102.    * @export
  103.    */
  104.   getDuration() {
  105.     return this.duration_;
  106.   }
  109.   /**
  110.    * @return {number} The presentation's max segment duration in seconds.
  111.    * @export
  112.    */
  113.   getMaxSegmentDuration() {
  114.     return this.maxSegmentDuration_;
  115.   }
  118.   /**
  119.    * Sets the presentation's duration.
  120.    *
  121.    * @param {number} duration The presentation's duration in seconds.
  122.    *   Infinity indicates that the presentation continues indefinitely.
  123.    * @export
  124.    */
  125.   setDuration(duration) {
  126.     goog.asserts.assert(duration > 0, 'duration must be > 0');
  127.     this.duration_ = duration;
  128.   }
  131.   /**
  132.    * @return {?number} The presentation's start time in seconds.
  133.    * @export
  134.    */
  135.   getPresentationStartTime() {
  136.     return this.presentationStartTime_;
  137.   }
  140.   /**
  141.    * Sets the clock offset, which is the difference between the client's clock
  142.    * and the server's clock, in milliseconds (i.e., serverTime = Date.now() +
  143.    * clockOffset).
  144.    *
  145.    * @param {number} offset The clock offset, in ms.
  146.    * @export
  147.    */
  148.   setClockOffset(offset) {
  149.     this.clockOffset_ = offset;
  150.   }
  153.   /**
  154.    * Sets the presentation's static flag.
  155.    *
  156.    * @param {boolean} isStatic If true, the presentation is static, meaning all
  157.    *   segments are available at once.
  158.    * @export
  159.    */
  160.   setStatic(isStatic) {
  161.     // NOTE: the argument name is not "static" because that's a keyword in ES6
  162.     this.static_ = isStatic;
  163.   }
  166.   /**
  167.    * Sets the presentation's segment availability duration. The segment
  168.    * availability duration should only be set for live.
  169.    *
  170.    * @param {number} segmentAvailabilityDuration The presentation's new segment
  171.    *   availability duration in seconds.
  172.    * @export
  173.    */
  174.   setSegmentAvailabilityDuration(segmentAvailabilityDuration) {
  175.     goog.asserts.assert(segmentAvailabilityDuration >= 0,
  176.         'segmentAvailabilityDuration must be >= 0');
  177.     this.segmentAvailabilityDuration_ = segmentAvailabilityDuration;
  178.   }
  181.   /**
  182.    * Sets the presentation delay in seconds.
  183.    *
  184.    * @param {number} delay
  185.    * @export
  186.    */
  187.   setDelay(delay) {
  188.     // NOTE: This is no longer used internally, but is exported.
  189.     // So we cannot remove it without deprecating it and waiting one release
  190.     // cycle, or else we risk breaking custom manifest parsers.
  191.     goog.asserts.assert(delay >= 0, 'delay must be >= 0');
  192.     this.presentationDelay_ = delay;
  193.   }
  196.   /**
  197.    * Gets the presentation delay in seconds.
  198.    * @return {number}
  199.    * @export
  200.    */
  201.   getDelay() {
  202.     return this.presentationDelay_;
  203.   }
  206.   /**
  207.    * Gives PresentationTimeline a Stream's segments so it can size and position
  208.    * the segment availability window, and account for missing segment
  209.    * information.  This function should be called once for each Stream (no more,
  210.    * no less).
  211.    *
  212.    * @param {!Array.<!shaka.media.SegmentReference>} references
  213.    * @export
  214.    */
  215.   notifySegments(references) {
  216.     if (references.length == 0) {
  217.       return;
  218.     }
  220.     const firstReferenceStartTime = references[0].startTime;
  221.     const lastReferenceEndTime = references[references.length - 1].endTime;
  223.     this.notifyMinSegmentStartTime(firstReferenceStartTime);
  225.     this.maxSegmentDuration_ = references.reduce(
  226.         (max, r) => { return Math.max(max, r.endTime - r.startTime); },
  227.         this.maxSegmentDuration_);
  229.     this.maxSegmentEndTime_ =
  230.         Math.max(this.maxSegmentEndTime_, lastReferenceEndTime);
  232.     if (this.presentationStartTime_ != null && this.autoCorrectDrift_) {
  233.       // Since we have explicit segment end times, calculate a presentation
  234.       // start based on them.  This start time accounts for drift.
  235.       // Date.now() is in milliseconds, from which we compute "now" in seconds.
  236.       const now = (Date.now() + this.clockOffset_) / 1000.0;
  237.       this.presentationStartTime_ =
  238.           now - this.maxSegmentEndTime_ - this.maxSegmentDuration_;
  239.     }
  241.     shaka.log.v1('notifySegments:',
  242.         'maxSegmentDuration=' + this.maxSegmentDuration_);
  243.   }
  246.   /**
  247.    * Gives PresentationTimeline a Stream's minimum segment start time.
  248.    *
  249.    * @param {number} startTime
  250.    * @export
  251.    */
  252.   notifyMinSegmentStartTime(
  253.       startTime) {
  254.     if (this.minSegmentStartTime_ == null) {
  255.       // No data yet, and Math.min(null, startTime) is always 0.  So just store
  256.       // startTime.
  257.       this.minSegmentStartTime_ = startTime;
  258.     } else {
  259.       this.minSegmentStartTime_ =
  260.           Math.min(this.minSegmentStartTime_, startTime);
  261.     }
  262.   }
  265.   /**
  266.    * Gives PresentationTimeline a Stream's maximum segment duration so it can
  267.    * size and position the segment availability window.  This function should be
  268.    * called once for each Stream (no more, no less), but does not have to be
  269.    * called if notifySegments() is called instead for a particular stream.
  270.    *
  271.    * @param {number} maxSegmentDuration The maximum segment duration for a
  272.    *   particular stream.
  273.    * @export
  274.    */
  275.   notifyMaxSegmentDuration(maxSegmentDuration) {
  276.     this.maxSegmentDuration_ = Math.max(
  277.         this.maxSegmentDuration_, maxSegmentDuration);
  279.     shaka.log.v1('notifyNewSegmentDuration:',
  280.         'maxSegmentDuration=' + this.maxSegmentDuration_);
  281.   }
  284.   /**
  285.    * Offsets the segment times by the given amount.
  286.    *
  287.    * @param {number} offset The number of seconds to offset by.  A positive
  288.    *   number adjusts the segment times forward.
  289.    * @export
  290.    */
  291.   offset(offset) {
  292.     if (this.minSegmentStartTime_ != null) {
  293.       this.minSegmentStartTime_ += offset;
  294.     }
  295.     if (this.maxSegmentEndTime_ != null) {
  296.       this.maxSegmentEndTime_ += offset;
  297.     }
  298.   }
  301.   /**
  302.    * @return {boolean} True if the presentation is live; otherwise, return
  303.    *   false.
  304.    * @export
  305.    */
  306.   isLive() {
  307.     return this.duration_ == Infinity &&
  308.            !this.static_;
  309.   }
  312.   /**
  313.    * @return {boolean} True if the presentation is in progress (meaning not
  314.    *   live, but also not completely available); otherwise, return false.
  315.    * @export
  316.    */
  317.   isInProgress() {
  318.     return this.duration_ != Infinity &&
  319.            !this.static_;
  320.   }
  323.   /**
  324.    * Gets the presentation's current segment availability start time.  Segments
  325.    * ending at or before this time should be assumed to be unavailable.
  326.    *
  327.    * @return {number} The current segment availability start time, in seconds,
  328.    *   relative to the start of the presentation.
  329.    * @export
  330.    */
  331.   getSegmentAvailabilityStart() {
  332.     goog.asserts.assert(this.segmentAvailabilityDuration_ >= 0,
  333.         'The availability duration should be positive');
  335.     const end = this.getSegmentAvailabilityEnd();
  336.     const start = end - this.segmentAvailabilityDuration_;
  337.     return Math.max(this.userSeekStart_, start);
  338.   }
  341.   /**
  342.    * Sets the start time of the user-defined seek range.  This is only used for
  343.    * VOD content.
  344.    *
  345.    * @param {number} time
  346.    * @export
  347.    */
  348.   setUserSeekStart(time) {
  349.     this.userSeekStart_ = time;
  350.   }
  353.   /**
  354.    * Gets the presentation's current segment availability end time.  Segments
  355.    * starting after this time should be assumed to be unavailable.
  356.    *
  357.    * @return {number} The current segment availability end time, in seconds,
  358.    *   relative to the start of the presentation.  For VOD, the availability
  359.    *   end time is the content's duration.  If the Player's playRangeEnd
  360.    *   configuration is used, this can override the duration.
  361.    * @export
  362.    */
  363.   getSegmentAvailabilityEnd() {
  364.     if (!this.isLive() && !this.isInProgress()) {
  365.       // It's a static manifest (can also be a dynamic->static conversion)
  366.       if (this.maxSegmentEndTime_) {
  367.         // If we know segment times, use the min of that and duration.
  368.         // Note that the playRangeEnd configuration changes this.duration_.
  369.         // See https://github.com/shaka-project/shaka-player/issues/4026
  370.         return Math.min(this.maxSegmentEndTime_, this.duration_);
  371.       } else {
  372.         // If we don't have segment times, use duration.
  373.         return this.duration_;
  374.       }
  375.     }
  376.     // Can be either live or "in-progress recording" (live with known duration)
  377.     return Math.min(this.getLiveEdge_() + this.availabilityTimeOffset_,
  378.         this.duration_);
  379.   }
  382.   /**
  383.    * Gets the seek range start time, offset by the given amount.  This is used
  384.    * to ensure that we don't "fall" back out of the seek window while we are
  385.    * buffering.
  386.    *
  387.    * @param {number} offset The offset to add to the start time for live
  388.    *   streams.
  389.    * @return {number} The current seek start time, in seconds, relative to the
  390.    *   start of the presentation.
  391.    * @export
  392.    */
  393.   getSafeSeekRangeStart(offset) {
  394.     // The earliest known segment time, ignoring segment availability duration.
  395.     const earliestSegmentTime =
  396.         Math.max(this.minSegmentStartTime_, this.userSeekStart_);
  398.     // For VOD, the offset and end time are ignored, and we just return the
  399.     // earliest segment time.  All segments are "safe" in VOD.  However, we
  400.     // should round up to the nearest millisecond to avoid issues like
  401.     // https://github.com/shaka-project/shaka-player/issues/2831, in which we
  402.     // tried to seek repeatedly to catch up to the seek range, and never
  403.     // actually "arrived" within it.  The video's currentTime is not as
  404.     // accurate as the JS number representing the earliest segment time for
  405.     // some content.
  406.     if (this.segmentAvailabilityDuration_ == Infinity) {
  407.       return Math.ceil(earliestSegmentTime * 1e3) / 1e3;
  408.     }
  410.     // AKA the live edge for live streams.
  411.     const availabilityEnd = this.getSegmentAvailabilityEnd();
  413.     // The ideal availability start, not considering known segments.
  414.     const availabilityStart =
  415.         availabilityEnd - this.segmentAvailabilityDuration_;
  417.     // Add the offset to the availability start to ensure that we don't fall
  418.     // outside the availability window while we buffer; we don't need to add the
  419.     // offset to earliestSegmentTime since that won't change over time.
  420.     // Also see: https://github.com/shaka-project/shaka-player/issues/692
  421.     const desiredStart =
  422.         Math.min(availabilityStart + offset, this.getSeekRangeEnd());
  423.     return Math.max(earliestSegmentTime, desiredStart);
  424.   }
  427.   /**
  428.    * Gets the seek range start time.
  429.    *
  430.    * @return {number}
  431.    * @export
  432.    */
  433.   getSeekRangeStart() {
  434.     return this.getSafeSeekRangeStart(/* offset= */ 0);
  435.   }
  438.   /**
  439.    * Gets the seek range end.
  440.    *
  441.    * @return {number}
  442.    * @export
  443.    */
  444.   getSeekRangeEnd() {
  445.     const useDelay = this.isLive() || this.isInProgress();
  446.     const delay = useDelay ? this.presentationDelay_ : 0;
  447.     return Math.max(0, this.getSegmentAvailabilityEnd() - delay);
  448.   }
  451.   /**
  452.    * True if the presentation start time is being used to calculate the live
  453.    * edge.
  454.    * Using the presentation start time means that the stream may be subject to
  455.    * encoder drift.  At runtime, we will avoid using the presentation start time
  456.    * whenever possible.
  457.    *
  458.    * @return {boolean}
  459.    * @export
  460.    */
  461.   usingPresentationStartTime() {
  462.     // If it's VOD, IPR, or an HLS "event", we are not using the presentation
  463.     // start time.
  464.     if (this.presentationStartTime_ == null) {
  465.       return false;
  466.     }
  468.     // If we have explicit segment times, we're not using the presentation
  469.     // start time.
  470.     if (this.maxSegmentEndTime_ != null && this.autoCorrectDrift_) {
  471.       return false;
  472.     }
  474.     return true;
  475.   }
  478.   /**
  479.    * @return {number} The current presentation time in seconds.
  480.    * @private
  481.    */
  482.   getLiveEdge_() {
  483.     goog.asserts.assert(this.presentationStartTime_ != null,
  484.         'Cannot compute timeline live edge without start time');
  485.     // Date.now() is in milliseconds, from which we compute "now" in seconds.
  486.     const now = (Date.now() + this.clockOffset_) / 1000.0;
  487.     return Math.max(
  488.         0, now - this.maxSegmentDuration_ - this.presentationStartTime_);
  489.   }
  491.   /**
  492.    * Sets the presentation's segment availability time offset. This should be
  493.    * only set for Low Latency Dash.
  494.    * The segments are available earlier for download than the availability start
  495.    * time, so we can move closer to the live edge.
  496.    *
  497.    * @param {number} offset
  498.    * @export
  499.    */
  500.   setAvailabilityTimeOffset(offset) {
  501.     this.availabilityTimeOffset_ = offset;
  502.   }
  504.   /**
  505.    * Debug only: assert that the timeline parameters make sense for the type
  506.    * of presentation (VOD, IPR, live).
  507.    */
  508.   assertIsValid() {
  509.     if (goog.DEBUG) {
  510.       if (this.isLive()) {
  511.         // Implied by isLive(): infinite and dynamic.
  512.         // Live streams should have a start time.
  513.         goog.asserts.assert(this.presentationStartTime_ != null,
  514.             'Detected as live stream, but does not match our model of live!');
  515.       } else if (this.isInProgress()) {
  516.         // Implied by isInProgress(): finite and dynamic.
  517.         // IPR streams should have a start time, and segments should not expire.
  518.         goog.asserts.assert(this.presentationStartTime_ != null &&
  519.                             this.segmentAvailabilityDuration_ == Infinity,
  520.         'Detected as IPR stream, but does not match our model of IPR!');
  521.       } else {  // VOD
  522.         // VOD segments should not expire and the presentation should be finite
  523.         // and static.
  524.         goog.asserts.assert(this.segmentAvailabilityDuration_ == Infinity &&
  525.                             this.duration_ != Infinity &&
  526.                             this.static_,
  527.         'Detected as VOD stream, but does not match our model of VOD!');
  528.       }
  529.     }
  530.   }
  531. };