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;
  97.     /** @private {boolean} */
  98.     this.startTimeLocked_ = false;
  99.   }
  102.   /**
  103.    * @return {number} The presentation's duration in seconds.
  104.    *   Infinity indicates that the presentation continues indefinitely.
  105.    * @export
  106.    */
  107.   getDuration() {
  108.     return this.duration_;
  109.   }
  112.   /**
  113.    * @return {number} The presentation's max segment duration in seconds.
  114.    * @export
  115.    */
  116.   getMaxSegmentDuration() {
  117.     return this.maxSegmentDuration_;
  118.   }
  121.   /**
  122.    * Sets the presentation's start time.
  123.    *
  124.    * @param {number} presentationStartTime The wall-clock time, in seconds,
  125.    *   when the presentation started or will start. Only required for live.
  126.    * @export
  127.    */
  128.   setPresentationStartTime(presentationStartTime) {
  129.     goog.asserts.assert(presentationStartTime >= 0,
  130.         'presentationStartTime must be >= 0');
  131.     this.presentationStartTime_ = presentationStartTime;
  132.   }
  135.   /**
  136.    * Sets the presentation's duration.
  137.    *
  138.    * @param {number} duration The presentation's duration in seconds.
  139.    *   Infinity indicates that the presentation continues indefinitely.
  140.    * @export
  141.    */
  142.   setDuration(duration) {
  143.     goog.asserts.assert(duration > 0, 'duration must be > 0');
  144.     this.duration_ = duration;
  145.   }
  148.   /**
  149.    * @return {?number} The presentation's start time in seconds.
  150.    * @export
  151.    */
  152.   getPresentationStartTime() {
  153.     return this.presentationStartTime_;
  154.   }
  157.   /**
  158.    * Sets the clock offset, which is the difference between the client's clock
  159.    * and the server's clock, in milliseconds (i.e., serverTime = Date.now() +
  160.    * clockOffset).
  161.    *
  162.    * @param {number} offset The clock offset, in ms.
  163.    * @export
  164.    */
  165.   setClockOffset(offset) {
  166.     this.clockOffset_ = offset;
  167.   }
  170.   /**
  171.    * Sets the presentation's static flag.
  172.    *
  173.    * @param {boolean} isStatic If true, the presentation is static, meaning all
  174.    *   segments are available at once.
  175.    * @export
  176.    */
  177.   setStatic(isStatic) {
  178.     // NOTE: the argument name is not "static" because that's a keyword in ES6
  179.     this.static_ = isStatic;
  180.   }
  183.   /**
  184.    * Sets the presentation's segment availability duration. The segment
  185.    * availability duration should only be set for live.
  186.    *
  187.    * @param {number} segmentAvailabilityDuration The presentation's new segment
  188.    *   availability duration in seconds.
  189.    * @export
  190.    */
  191.   setSegmentAvailabilityDuration(segmentAvailabilityDuration) {
  192.     goog.asserts.assert(segmentAvailabilityDuration >= 0,
  193.         'segmentAvailabilityDuration must be >= 0');
  194.     this.segmentAvailabilityDuration_ = segmentAvailabilityDuration;
  195.   }
  198.   /**
  199.    * Sets the presentation delay in seconds.
  200.    *
  201.    * @param {number} delay
  202.    * @export
  203.    */
  204.   setDelay(delay) {
  205.     // NOTE: This is no longer used internally, but is exported.
  206.     // So we cannot remove it without deprecating it and waiting one release
  207.     // cycle, or else we risk breaking custom manifest parsers.
  208.     goog.asserts.assert(delay >= 0, 'delay must be >= 0');
  209.     this.presentationDelay_ = delay;
  210.   }
  213.   /**
  214.    * Gets the presentation delay in seconds.
  215.    * @return {number}
  216.    * @export
  217.    */
  218.   getDelay() {
  219.     return this.presentationDelay_;
  220.   }
  223.   /**
  224.    * Gives PresentationTimeline an array of segments so it can size and position
  225.    * the segment availability window, and account for missing segment
  226.    * information.  These segments do not necessarily need to all be from the
  227.    * same stream.
  228.    *
  229.    * @param {!Array.<!shaka.media.SegmentReference>} references
  230.    * @export
  231.    */
  232.   notifySegments(references) {
  233.     if (references.length == 0) {
  234.       return;
  235.     }
  237.     let firstReferenceStartTime = references[0].startTime;
  238.     let lastReferenceEndTime = references[0].endTime;
  240.     // Date.now() is in milliseconds, from which we compute "now" in seconds.
  241.     const now = (Date.now() + this.clockOffset_) / 1000.0;
  243.     for (const reference of references) {
  244.       // Exclude segments that are in the "future".
  245.       if (now < reference.startTime) {
  246.         continue;
  247.       }
  249.       firstReferenceStartTime = Math.min(
  250.           firstReferenceStartTime, reference.startTime);
  251.       lastReferenceEndTime = Math.max(lastReferenceEndTime, reference.endTime);
  252.       this.maxSegmentDuration_ = Math.max(
  253.           this.maxSegmentDuration_, reference.endTime - reference.startTime);
  254.     }
  255.     this.notifyMinSegmentStartTime(firstReferenceStartTime);
  256.     this.maxSegmentEndTime_ =
  257.         Math.max(this.maxSegmentEndTime_, lastReferenceEndTime);
  259.     if (this.presentationStartTime_ != null && this.autoCorrectDrift_ &&
  260.         !this.startTimeLocked_) {
  261.       // Since we have explicit segment end times, calculate a presentation
  262.       // start based on them.  This start time accounts for drift.
  263.       this.presentationStartTime_ =
  264.           now - this.maxSegmentEndTime_ - this.maxSegmentDuration_;
  265.     }
  267.     shaka.log.v1('notifySegments:',
  268.         'maxSegmentDuration=' + this.maxSegmentDuration_);
  269.   }
  272.   /**
  273.    * Lock the presentation timeline's start time.  After this is called, no
  274.    * further adjustments to presentationStartTime_ will be permitted.
  275.    *
  276.    * This should be called after all Periods have been parsed, and all calls to
  277.    * notifySegments() from the initial manifest parse have been made.
  278.    *
  279.    * Without this, we can get assertion failures in SegmentIndex for certain
  280.    * DAI content.  If DAI adds ad segments to the manifest faster than
  281.    * real-time, adjustments to presentationStartTime_ can cause availability
  282.    * windows to jump around on updates.
  283.    *
  284.    * @export
  285.    */
  286.   lockStartTime() {
  287.     this.startTimeLocked_ = true;
  288.   }
  291.   /**
  292.    * Returns if the presentation timeline's start time is locked.
  293.    *
  294.    * @return {boolean}
  295.    * @export
  296.    */
  297.   isStartTimeLocked() {
  298.     return this.startTimeLocked_;
  299.   }
  302.   /**
  303.    * Gives PresentationTimeline a Stream's minimum segment start time.
  304.    *
  305.    * @param {number} startTime
  306.    * @export
  307.    */
  308.   notifyMinSegmentStartTime(startTime) {
  309.     if (this.minSegmentStartTime_ == null) {
  310.       // No data yet, and Math.min(null, startTime) is always 0.  So just store
  311.       // startTime.
  312.       this.minSegmentStartTime_ = startTime;
  313.     } else {
  314.       this.minSegmentStartTime_ =
  315.           Math.min(this.minSegmentStartTime_, startTime);
  316.     }
  317.   }
  320.   /**
  321.    * Gives PresentationTimeline a Stream's maximum segment duration so it can
  322.    * size and position the segment availability window.  This function should be
  323.    * called once for each Stream (no more, no less), but does not have to be
  324.    * called if notifySegments() is called instead for a particular stream.
  325.    *
  326.    * @param {number} maxSegmentDuration The maximum segment duration for a
  327.    *   particular stream.
  328.    * @export
  329.    */
  330.   notifyMaxSegmentDuration(maxSegmentDuration) {
  331.     this.maxSegmentDuration_ = Math.max(
  332.         this.maxSegmentDuration_, maxSegmentDuration);
  334.     shaka.log.v1('notifyNewSegmentDuration:',
  335.         'maxSegmentDuration=' + this.maxSegmentDuration_);
  336.   }
  339.   /**
  340.    * Offsets the segment times by the given amount.
  341.    *
  342.    * @param {number} offset The number of seconds to offset by.  A positive
  343.    *   number adjusts the segment times forward.
  344.    * @export
  345.    */
  346.   offset(offset) {
  347.     if (this.minSegmentStartTime_ != null) {
  348.       this.minSegmentStartTime_ += offset;
  349.     }
  350.     if (this.maxSegmentEndTime_ != null) {
  351.       this.maxSegmentEndTime_ += offset;
  352.     }
  353.   }
  356.   /**
  357.    * @return {boolean} True if the presentation is live; otherwise, return
  358.    *   false.
  359.    * @export
  360.    */
  361.   isLive() {
  362.     return this.duration_ == Infinity &&
  363.            !this.static_;
  364.   }
  367.   /**
  368.    * @return {boolean} True if the presentation is in progress (meaning not
  369.    *   live, but also not completely available); otherwise, return false.
  370.    * @export
  371.    */
  372.   isInProgress() {
  373.     return this.duration_ != Infinity &&
  374.            !this.static_;
  375.   }
  378.   /**
  379.    * Gets the presentation's current segment availability start time.  Segments
  380.    * ending at or before this time should be assumed to be unavailable.
  381.    *
  382.    * @return {number} The current segment availability start time, in seconds,
  383.    *   relative to the start of the presentation.
  384.    * @export
  385.    */
  386.   getSegmentAvailabilityStart() {
  387.     goog.asserts.assert(this.segmentAvailabilityDuration_ >= 0,
  388.         'The availability duration should be positive');
  390.     const end = this.getSegmentAvailabilityEnd();
  391.     const start = end - this.segmentAvailabilityDuration_;
  392.     return Math.max(this.userSeekStart_, start);
  393.   }
  396.   /**
  397.    * Sets the start time of the user-defined seek range.  This is only used for
  398.    * VOD content.
  399.    *
  400.    * @param {number} time
  401.    * @export
  402.    */
  403.   setUserSeekStart(time) {
  404.     this.userSeekStart_ = time;
  405.   }
  408.   /**
  409.    * Gets the presentation's current segment availability end time.  Segments
  410.    * starting after this time should be assumed to be unavailable.
  411.    *
  412.    * @return {number} The current segment availability end time, in seconds,
  413.    *   relative to the start of the presentation.  For VOD, the availability
  414.    *   end time is the content's duration.  If the Player's playRangeEnd
  415.    *   configuration is used, this can override the duration.
  416.    * @export
  417.    */
  418.   getSegmentAvailabilityEnd() {
  419.     if (!this.isLive() && !this.isInProgress()) {
  420.       // It's a static manifest (can also be a dynamic->static conversion)
  421.       if (this.maxSegmentEndTime_) {
  422.         // If we know segment times, use the min of that and duration.
  423.         // Note that the playRangeEnd configuration changes this.duration_.
  424.         // See https://github.com/shaka-project/shaka-player/issues/4026
  425.         return Math.min(this.maxSegmentEndTime_, this.duration_);
  426.       } else {
  427.         // If we don't have segment times, use duration.
  428.         return this.duration_;
  429.       }
  430.     }
  431.     // Can be either live or "in-progress recording" (live with known duration)
  432.     return Math.min(this.getLiveEdge_() + this.availabilityTimeOffset_,
  433.         this.duration_);
  434.   }
  437.   /**
  438.    * Gets the seek range start time, offset by the given amount.  This is used
  439.    * to ensure that we don't "fall" back out of the seek window while we are
  440.    * buffering.
  441.    *
  442.    * @param {number} offset The offset to add to the start time for live
  443.    *   streams.
  444.    * @return {number} The current seek start time, in seconds, relative to the
  445.    *   start of the presentation.
  446.    * @export
  447.    */
  448.   getSafeSeekRangeStart(offset) {
  449.     // The earliest known segment time, ignoring segment availability duration.
  450.     const earliestSegmentTime =
  451.         Math.max(this.minSegmentStartTime_, this.userSeekStart_);
  453.     // For VOD, the offset and end time are ignored, and we just return the
  454.     // earliest segment time.  All segments are "safe" in VOD.  However, we
  455.     // should round up to the nearest millisecond to avoid issues like
  456.     // https://github.com/shaka-project/shaka-player/issues/2831, in which we
  457.     // tried to seek repeatedly to catch up to the seek range, and never
  458.     // actually "arrived" within it.  The video's currentTime is not as
  459.     // accurate as the JS number representing the earliest segment time for
  460.     // some content.
  461.     if (this.segmentAvailabilityDuration_ == Infinity) {
  462.       return Math.ceil(earliestSegmentTime * 1e3) / 1e3;
  463.     }
  465.     // AKA the live edge for live streams.
  466.     const availabilityEnd = this.getSegmentAvailabilityEnd();
  468.     // The ideal availability start, not considering known segments.
  469.     const availabilityStart =
  470.         availabilityEnd - this.segmentAvailabilityDuration_;
  472.     // Add the offset to the availability start to ensure that we don't fall
  473.     // outside the availability window while we buffer; we don't need to add the
  474.     // offset to earliestSegmentTime since that won't change over time.
  475.     // Also see: https://github.com/shaka-project/shaka-player/issues/692
  476.     const desiredStart =
  477.         Math.min(availabilityStart + offset, this.getSeekRangeEnd());
  478.     return Math.max(earliestSegmentTime, desiredStart);
  479.   }
  482.   /**
  483.    * Gets the seek range start time.
  484.    *
  485.    * @return {number}
  486.    * @export
  487.    */
  488.   getSeekRangeStart() {
  489.     return this.getSafeSeekRangeStart(/* offset= */ 0);
  490.   }
  493.   /**
  494.    * Gets the seek range end.
  495.    *
  496.    * @return {number}
  497.    * @export
  498.    */
  499.   getSeekRangeEnd() {
  500.     const useDelay = this.isLive() || this.isInProgress();
  501.     const delay = useDelay ? this.presentationDelay_ : 0;
  502.     return Math.max(0, this.getSegmentAvailabilityEnd() - delay);
  503.   }
  506.   /**
  507.    * True if the presentation start time is being used to calculate the live
  508.    * edge.
  509.    * Using the presentation start time means that the stream may be subject to
  510.    * encoder drift.  At runtime, we will avoid using the presentation start time
  511.    * whenever possible.
  512.    *
  513.    * @return {boolean}
  514.    * @export
  515.    */
  516.   usingPresentationStartTime() {
  517.     // If it's VOD, IPR, or an HLS "event", we are not using the presentation
  518.     // start time.
  519.     if (this.presentationStartTime_ == null) {
  520.       return false;
  521.     }
  523.     // If we have explicit segment times, we're not using the presentation
  524.     // start time.
  525.     if (this.maxSegmentEndTime_ != null && this.autoCorrectDrift_) {
  526.       return false;
  527.     }
  529.     return true;
  530.   }
  533.   /**
  534.    * @return {number} The current presentation time in seconds.
  535.    * @private
  536.    */
  537.   getLiveEdge_() {
  538.     goog.asserts.assert(this.presentationStartTime_ != null,
  539.         'Cannot compute timeline live edge without start time');
  540.     // Date.now() is in milliseconds, from which we compute "now" in seconds.
  541.     const now = (Date.now() + this.clockOffset_) / 1000.0;
  542.     return Math.max(
  543.         0, now - this.maxSegmentDuration_ - this.presentationStartTime_);
  544.   }
  546.   /**
  547.    * Sets the presentation's segment availability time offset. This should be
  548.    * only set for Low Latency Dash.
  549.    * The segments are available earlier for download than the availability start
  550.    * time, so we can move closer to the live edge.
  551.    *
  552.    * @param {number} offset
  553.    * @export
  554.    */
  555.   setAvailabilityTimeOffset(offset) {
  556.     this.availabilityTimeOffset_ = offset;
  557.   }
  559.   /**
  560.    * Debug only: assert that the timeline parameters make sense for the type
  561.    * of presentation (VOD, IPR, live).
  562.    */
  563.   assertIsValid() {
  564.     if (goog.DEBUG) {
  565.       if (this.isLive()) {
  566.         // Implied by isLive(): infinite and dynamic.
  567.         // Live streams should have a start time.
  568.         goog.asserts.assert(this.presentationStartTime_ != null,
  569.             'Detected as live stream, but does not match our model of live!');
  570.       } else if (this.isInProgress()) {
  571.         // Implied by isInProgress(): finite and dynamic.
  572.         // IPR streams should have a start time, and segments should not expire.
  573.         goog.asserts.assert(this.presentationStartTime_ != null &&
  574.                             this.segmentAvailabilityDuration_ == Infinity,
  575.         'Detected as IPR stream, but does not match our model of IPR!');
  576.       } else {  // VOD
  577.         // VOD segments should not expire and the presentation should be finite
  578.         // and static.
  579.         goog.asserts.assert(this.segmentAvailabilityDuration_ == Infinity &&
  580.                             this.duration_ != Infinity &&
  581.                             this.static_,
  582.         'Detected as VOD stream, but does not match our model of VOD!');
  583.       }
  584.     }
  585.   }
  586. };