Source: lib/media/playhead.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.media.MediaSourcePlayhead');
  8. goog.provide('shaka.media.Playhead');
  9. goog.provide('shaka.media.SrcEqualsPlayhead');
  11. goog.require('goog.asserts');
  12. goog.require('shaka.device.DeviceFactory');
  13. goog.require('shaka.log');
  14. goog.require('shaka.media.Capabilities');
  15. goog.require('shaka.media.GapJumpingController');
  16. goog.require('shaka.media.TimeRangesUtils');
  17. goog.require('shaka.media.VideoWrapper');
  18. goog.require('shaka.util.EventManager');
  19. goog.require('shaka.util.IReleasable');
  20. goog.require('shaka.util.MediaReadyState');
  21. goog.require('shaka.util.Timer');
  22. goog.requireType('shaka.media.PresentationTimeline');
  25. /**
  26.  * Creates a Playhead, which manages the video's current time.
  27.  *
  28.  * The Playhead provides mechanisms for setting the presentation's start time,
  29.  * restricting seeking to valid time ranges, and stopping playback for startup
  30.  * and re-buffering.
  31.  *
  32.  * @extends {shaka.util.IReleasable}
  33.  * @interface
  34.  */
  35. shaka.media.Playhead = class {
  36.   /**
  37.    * Called when the Player is ready to begin playback. Anything that depends
  38.    * on setStartTime() should be done here, not in the constructor.
  39.    *
  40.    * @see https://github.com/shaka-project/shaka-player/issues/4244
  41.    */
  42.   ready() {}
  44.   /**
  45.    * Set the start time. If the content has already started playback, this will
  46.    * be ignored.
  47.    *
  48.    * @param {number|Date} startTime
  49.    */
  50.   setStartTime(startTime) {}
  52.   /**
  53.    * Get the number of playback stalls detected by the StallDetector.
  54.    *
  55.    * @return {number}
  56.    */
  57.   getStallsDetected() {}
  59.   /**
  60.    * Get the number of playback gaps jumped by the GapJumpingController.
  61.    *
  62.    * @return {number}
  63.    */
  64.   getGapsJumped() {}
  66.   /**
  67.    * Get the current playhead position. The position will be restricted to valid
  68.    * time ranges.
  69.    *
  70.    * @return {number}
  71.    */
  72.   getTime() {}
  74.   /**
  75.    * Notify the playhead that the buffered ranges have changed.
  76.    */
  77.   notifyOfBufferingChange() {}
  79.   /**
  80.    * Check if the player has buffered enough content to make it to the end of
  81.    * the presentation.
  82.    * @return {boolean}
  83.    */
  84.   isBufferedToEnd() {}
  85. };
  88. /**
  89.  * A playhead implementation that only relies on the media element.
  90.  *
  91.  * @implements {shaka.media.Playhead}
  92.  * @final
  93.  */
  94. shaka.media.SrcEqualsPlayhead = class {
  95.   /**
  96.    * @param {!HTMLMediaElement} mediaElement
  97.    */
  98.   constructor(mediaElement) {
  99.     /** @private {HTMLMediaElement} */
  100.     this.mediaElement_ = mediaElement;
  101.     /** @private {boolean} */
  102.     this.started_ = false;
  103.     /** @private {?number|Date} */
  104.     this.startTime_ = null;
  106.     /** @private {shaka.util.EventManager} */
  107.     this.eventManager_ = new shaka.util.EventManager();
  108.   }
  110.   /** @override */
  111.   ready() {
  112.     goog.asserts.assert(
  113.         this.mediaElement_ != null,
  114.         'Playhead should not be released before calling ready()',
  115.     );
  117.     // We listen for the canplay event so that we know when we can
  118.     // interact with |currentTime|.
  119.     // We were using loadeddata before, but if we set time on that event,
  120.     // browser may adjust it on its own during live playback.
  121.     const onCanPlay = () => {
  122.       if (this.startTime_ == null ||
  123.           (this.startTime_ == 0 && this.mediaElement_.duration != Infinity)) {
  124.         this.started_ = true;
  125.       } else {
  126.         const currentTime = this.mediaElement_.currentTime;
  127.         let newTime = null;
  128.         if (typeof this.startTime_ === 'number') {
  129.           newTime = this.startTime_;
  130.         } else if (this.startTime_ instanceof Date) {
  131.           const programStartTime = this.getProgramStartTime_();
  132.           if (programStartTime !== null) {
  133.             newTime = (this.startTime_.getTime() / 1000.0) - programStartTime;
  134.             newTime = this.clampTime_(newTime);
  135.           }
  136.         }
  138.         if (newTime == null) {
  139.           this.started_ = true;
  140.           return;
  141.         }
  143.         // Using the currentTime allows using a negative number in Live HLS
  144.         if (newTime < 0) {
  145.           newTime = Math.max(0, currentTime + newTime);
  146.         }
  147.         if (currentTime != newTime) {
  148.           // Startup is complete only when the video element acknowledges the
  149.           // seek.
  150.           this.eventManager_.listenOnce(this.mediaElement_, 'seeking', () => {
  151.             this.started_ = true;
  152.           });
  153.           this.mediaElement_.currentTime = newTime;
  154.         } else {
  155.           this.started_ = true;
  156.         }
  157.       }
  158.     };
  160.     shaka.util.MediaReadyState.waitForReadyState(this.mediaElement_,
  161.         HTMLMediaElement.HAVE_FUTURE_DATA,
  162.         this.eventManager_, () => {
  163.           onCanPlay();
  164.         });
  165.   }
  167.   /** @override */
  168.   release() {
  169.     if (this.eventManager_) {
  170.       this.eventManager_.release();
  171.       this.eventManager_ = null;
  172.     }
  174.     this.mediaElement_ = null;
  175.   }
  177.   /** @override */
  178.   setStartTime(startTime) {
  179.     // If we have already started playback, ignore updates to the start time.
  180.     // This is just to make things consistent.
  181.     this.startTime_ = this.started_ ? this.startTime_ : startTime;
  182.   }
  184.   /** @override */
  185.   getTime() {
  186.     // If we have not started playback yet, return the start time. However once
  187.     // we start playback we assume that we can always return the current time.
  188.     let time = this.started_ ?
  189.                  this.mediaElement_.currentTime :
  190.                  this.startTime_;
  191.     if (time instanceof Date) {
  192.       time = (time.getTime() / 1000.0) - (this.getProgramStartTime_() || 0);
  193.       time = this.clampTime_(time);
  194.     }
  196.     // In the case that we have not started playback, but the start time was
  197.     // never set, we don't know what the start time should be. To ensure we
  198.     // always return a number, we will default back to 0.
  199.     return time || 0;
  200.   }
  202.   /** @override */
  203.   getStallsDetected() {
  204.     return 0;
  205.   }
  207.   /** @override */
  208.   getGapsJumped() {
  209.     return 0;
  210.   }
  212.   /** @override */
  213.   notifyOfBufferingChange() {}
  215.   /** @override */
  216.   isBufferedToEnd() {
  217.     goog.asserts.assert(
  218.         this.mediaElement_,
  219.         'We need a video element to get buffering information');
  221.     // If we have buffered to the duration of the content, it means we will have
  222.     // enough content to buffer to the end of the presentation.
  223.     const bufferEnd =
  224.         shaka.media.TimeRangesUtils.bufferEnd(this.mediaElement_.buffered);
  226.     // Because Safari's native HLS reports slightly inaccurate values for
  227.     // bufferEnd here, we use a fudge factor.  Without this, we can end up in a
  228.     // buffering state at the end of the stream.  See issue #2117.
  229.     const fudge = 1;  // 1000 ms
  230.     return bufferEnd != null &&
  231.         bufferEnd >= this.mediaElement_.duration - fudge;
  232.   }
  234.   /**
  235.    * @return {?number} program start time in seconds.
  236.    * @private
  237.    */
  238.   getProgramStartTime_() {
  239.     if (this.mediaElement_.getStartDate) {
  240.       const startDate = this.mediaElement_.getStartDate();
  241.       const startTime = startDate.getTime();
  242.       if (!isNaN(startTime)) {
  243.         return startTime / 1000.0;
  244.       }
  245.     }
  246.     return null;
  247.   }
  250.   /**
  251.    * @param {number} time
  252.    * @return {number}
  253.    * @private
  254.    */
  255.   clampTime_(time) {
  256.     const seekable = this.mediaElement_.seekable;
  257.     if (seekable.length > 0) {
  258.       time = Math.max(seekable.start(0), time);
  259.       time = Math.min(seekable.end(seekable.length - 1), time);
  260.     }
  261.     return time;
  262.   }
  263. };
  266. /**
  267.  * A playhead implementation that relies on the media element and a manifest.
  268.  * When provided with a manifest, we can provide more accurate control than
  269.  * the SrcEqualsPlayhead.
  270.  *
  271.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  272.  *       for, and conditions on timestamp adjustment.
  273.  *
  274.  * @implements {shaka.media.Playhead}
  275.  * @final
  276.  */
  277. shaka.media.MediaSourcePlayhead = class {
  278.   /**
  279.    * @param {!HTMLMediaElement} mediaElement
  280.    * @param {shaka.extern.Manifest} manifest
  281.    * @param {shaka.extern.StreamingConfiguration} config
  282.    * @param {?number|Date} startTime
  283.    *     The playhead's initial position in seconds. If null, defaults to the
  284.    *     start of the presentation for VOD and the live-edge for live.
  285.    * @param {function()} onSeek
  286.    *     Called when the user agent seeks to a time within the presentation
  287.    *     timeline.
  288.    * @param {function(!Event)} onEvent
  289.    *     Called when an event is raised to be sent to the application.
  290.    */
  291.   constructor(mediaElement, manifest, config, startTime, onSeek, onEvent) {
  292.     /**
  293.      * The seek range must be at least this number of seconds long. If it is
  294.      * smaller than this, change it to be this big so we don't repeatedly seek
  295.      * to keep within a zero-width window.
  296.      *
  297.      * This is 3s long, to account for the weaker hardware on platforms like
  298.      * Chromecast.
  299.      *
  300.      * @private {number}
  301.      */
  302.     this.minSeekRange_ = 3.0;
  304.     /** @private {HTMLMediaElement} */
  305.     this.mediaElement_ = mediaElement;
  307.     /** @private {shaka.media.PresentationTimeline} */
  308.     this.timeline_ = manifest.presentationTimeline;
  310.     /** @private {?shaka.extern.StreamingConfiguration} */
  311.     this.config_ = config;
  313.     /** @private {function()} */
  314.     this.onSeek_ = onSeek;
  316.     /** @private {?number} */
  317.     this.lastCorrectiveSeek_ = null;
  319.     /** @private {shaka.media.GapJumpingController} */
  320.     this.gapController_ = new shaka.media.GapJumpingController(
  321.         mediaElement,
  322.         manifest.presentationTimeline,
  323.         config,
  324.         onEvent);
  326.     /** @private {shaka.media.VideoWrapper} */
  327.     this.videoWrapper_ = new shaka.media.VideoWrapper(
  328.         mediaElement,
  329.         () => this.onSeeking_(),
  330.         (realStartTime) => this.onStarted_(realStartTime),
  331.         () => this.getStartTime_(startTime));
  333.     /** @type {shaka.util.Timer} */
  334.     this.checkWindowTimer_ = new shaka.util.Timer(() => {
  335.       this.onPollWindow_();
  336.     });
  337.   }
  339.   /** @override */
  340.   ready() {
  341.     this.checkWindowTimer_.tickEvery(/* seconds= */ 0.25);
  342.   }
  344.   /** @override */
  345.   release() {
  346.     if (this.videoWrapper_) {
  347.       this.videoWrapper_.release();
  348.       this.videoWrapper_ = null;
  349.     }
  351.     if (this.gapController_) {
  352.       this.gapController_.release();
  353.       this.gapController_= null;
  354.     }
  356.     if (this.checkWindowTimer_) {
  357.       this.checkWindowTimer_.stop();
  358.       this.checkWindowTimer_ = null;
  359.     }
  361.     this.config_ = null;
  362.     this.timeline_ = null;
  363.     this.videoWrapper_ = null;
  364.     this.mediaElement_ = null;
  366.     this.onSeek_ = () => {};
  367.   }
  369.   /** @override */
  370.   setStartTime(startTime) {
  371.     this.videoWrapper_.setTime(this.getStartTime_(startTime));
  372.   }
  374.   /** @override */
  375.   getTime() {
  376.     const time = this.videoWrapper_.getTime();
  378.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  379.     // ensure timing issues don't cause us to return a time outside the segment
  380.     // availability window.  E.g., the user agent seeks and calls this function
  381.     // before we receive the 'seeking' event.
  382.     //
  383.     // We don't buffer when the livestream video is paused and the playhead time
  384.     // is out of the seek range; thus, we do not clamp the current time when the
  385.     // video is paused.
  386.     // https://github.com/shaka-project/shaka-player/issues/1121
  387.     if (this.mediaElement_.readyState > 0 && !this.mediaElement_.paused) {
  388.       return this.clampTime_(time);
  389.     }
  391.     return time;
  392.   }
  394.   /** @override */
  395.   getStallsDetected() {
  396.     return this.gapController_.getStallsDetected();
  397.   }
  399.   /** @override */
  400.   getGapsJumped() {
  401.     return this.gapController_.getGapsJumped();
  402.   }
  404.   /**
  405.    * Gets the playhead's initial position in seconds.
  406.    *
  407.    * @param {?number|Date} startTime
  408.    * @return {number}
  409.    * @private
  410.    */
  411.   getStartTime_(startTime) {
  412.     if (startTime == null) {
  413.       if (this.timeline_.getDuration() < Infinity) {
  414.         // If the presentation is VOD, or if the presentation is live but has
  415.         // finished broadcasting, then start from the beginning.
  416.         startTime = this.timeline_.getSeekRangeStart();
  417.       } else {
  418.         // Otherwise, start near the live-edge.
  419.         startTime = this.timeline_.getSeekRangeEnd();
  420.       }
  421.     } else if (startTime instanceof Date) {
  422.       const presentationStartTime =
  423.           this.timeline_.getInitialProgramDateTime() ||
  424.           this.timeline_.getPresentationStartTime();
  425.       goog.asserts.assert(presentationStartTime != null,
  426.           'Presentation start time should not be null!');
  427.       startTime = (startTime.getTime() / 1000.0) - presentationStartTime;
  428.     } else if (startTime < 0) {
  429.       // For live streams, if the startTime is negative, start from a certain
  430.       // offset time from the live edge.  If the offset from the live edge is
  431.       // not available, start from the current available segment start point
  432.       // instead, handled by clampTime_().
  433.       startTime = this.timeline_.getSeekRangeEnd() + startTime;
  434.     }
  436.     return this.clampSeekToDuration_(
  437.         this.clampTime_(/** @type {number} */(startTime)));
  438.   }
  440.   /** @override */
  441.   notifyOfBufferingChange() {
  442.     this.gapController_.onSegmentAppended();
  443.   }
  445.   /** @override */
  446.   isBufferedToEnd() {
  447.     goog.asserts.assert(
  448.         this.mediaElement_,
  449.         'We need a video element to get buffering information');
  450.     goog.asserts.assert(
  451.         this.timeline_,
  452.         'We need a timeline to get buffering information');
  454.     // Live streams are "buffered to the end" when they have buffered to the
  455.     // live edge or beyond (into the region covered by the presentation delay).
  456.     if (this.timeline_.isLive()) {
  457.       const liveEdge = this.timeline_.getSegmentAvailabilityEnd();
  458.       const bufferEnd =
  459.           shaka.media.TimeRangesUtils.bufferEnd(this.mediaElement_.buffered);
  461.       if (bufferEnd != null && bufferEnd >= liveEdge) {
  462.         return true;
  463.       }
  464.     }
  466.     return false;
  467.   }
  469.   /**
  470.    * Called on a recurring timer to keep the playhead from falling outside the
  471.    * availability window.
  472.    *
  473.    * @private
  474.    */
  475.   onPollWindow_() {
  476.     // Don't catch up to the seek range when we are paused or empty.
  477.     // The definition of "seeking" says that we are seeking until the buffered
  478.     // data intersects with the playhead.  If we fall outside of the seek range,
  479.     // it doesn't matter if we are in a "seeking" state.  We can and should go
  480.     // ahead and catch up while seeking.
  481.     if (this.mediaElement_.readyState == 0 || this.mediaElement_.paused) {
  482.       return;
  483.     }
  485.     const currentTime = this.videoWrapper_.getTime();
  486.     let seekStart = this.timeline_.getSeekRangeStart();
  487.     const seekEnd = this.timeline_.getSeekRangeEnd();
  489.     if (seekEnd - seekStart < this.minSeekRange_) {
  490.       seekStart = seekEnd - this.minSeekRange_;
  491.     }
  493.     if (currentTime < seekStart) {
  494.       // The seek range has moved past the playhead.  Move ahead to catch up.
  495.       const targetTime = this.reposition_(currentTime);
  496.       shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  497.                      ' seconds to catch up with the seek range.');
  498.       this.mediaElement_.currentTime = targetTime;
  499.     }
  500.   }
  502.   /**
  503.    * Called when the video element has started up and is listening for new seeks
  504.    *
  505.    * @param {number} startTime
  506.    * @private
  507.    */
  508.   onStarted_(startTime) {
  509.     this.gapController_.onStarted(startTime);
  510.   }
  512.   /**
  513.    * Handles when a seek happens on the video.
  514.    *
  515.    * @private
  516.    */
  517.   onSeeking_() {
  518.     this.gapController_.onSeeking();
  519.     const currentTime = this.videoWrapper_.getTime();
  520.     const targetTime = this.reposition_(currentTime);
  522.     const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  524.     // We don't need to perform corrective seeks for the playhead range when
  525.     // MediaSource's setLiveSeekableRange() can handle it for us.
  526.     const mightNeedCorrectiveSeek =
  527.         !shaka.media.Capabilities.isInfiniteLiveStreamDurationSupported();
  529.     if (mightNeedCorrectiveSeek &&
  530.         Math.abs(targetTime - currentTime) > gapLimit) {
  531.       let canCorrectiveSeek = false;
  532.       const seekDelay = shaka.device.DeviceFactory.getDevice().seekDelay();
  533.       if (seekDelay) {
  534.         // You can only seek like this every so often. This is to prevent an
  535.         // infinite loop on systems where changing currentTime takes a
  536.         // significant amount of time (e.g. Chromecast).
  537.         const time = Date.now() / 1000;
  538.         if (!this.lastCorrectiveSeek_ ||
  539.             this.lastCorrectiveSeek_ < time - seekDelay) {
  540.           this.lastCorrectiveSeek_ = time;
  541.           canCorrectiveSeek = true;
  542.         }
  543.       } else {
  544.         canCorrectiveSeek = true;
  545.       }
  546.       if (canCorrectiveSeek) {
  547.         this.videoWrapper_.setTime(targetTime);
  548.         return;
  549.       }
  550.     }
  552.     shaka.log.v1('Seek to ' + currentTime);
  553.     this.onSeek_();
  554.   }
  556.   /**
  557.    * Clamp seek times and playback start times so that we never seek to the
  558.    * presentation duration.  Seeking to or starting at duration does not work
  559.    * consistently across browsers.
  560.    *
  561.    * @see https://github.com/shaka-project/shaka-player/issues/979
  562.    * @param {number} time
  563.    * @return {number} The adjusted seek time.
  564.    * @private
  565.    */
  566.   clampSeekToDuration_(time) {
  567.     const duration = this.timeline_.getDuration();
  568.     if (time >= duration) {
  569.       goog.asserts.assert(this.config_.durationBackoff >= 0,
  570.           'Duration backoff must be non-negative!');
  571.       return duration - this.config_.durationBackoff;
  572.     }
  573.     return time;
  574.   }
  576.   /**
  577.    * Computes a new playhead position that's within the presentation timeline.
  578.    *
  579.    * @param {number} currentTime
  580.    * @return {number} The time to reposition the playhead to.
  581.    * @private
  582.    */
  583.   reposition_(currentTime) {
  584.     goog.asserts.assert(
  585.         this.config_,
  586.         'Cannot reposition playhead when it has been destroyed');
  588.     /** @type {function(number)} */
  589.     const isBuffered = (playheadTime) => shaka.media.TimeRangesUtils.isBuffered(
  590.         this.mediaElement_.buffered, playheadTime);
  592.     const rebufferingGoal = this.config_.rebufferingGoal;
  593.     const safeSeekOffset = this.config_.safeSeekOffset;
  595.     let start = this.timeline_.getSeekRangeStart();
  596.     const end = this.timeline_.getSeekRangeEnd();
  597.     const duration = this.timeline_.getDuration();
  599.     if (end - start < this.minSeekRange_) {
  600.       start = end - this.minSeekRange_;
  601.     }
  603.     // With live content, the beginning of the availability window is moving
  604.     // forward.  This means we cannot seek to it since we will "fall" outside
  605.     // the window while we buffer.  So we define a "safe" region that is far
  606.     // enough away.  For VOD, |safe == start|.
  607.     const safe = this.timeline_.getSafeSeekRangeStart(rebufferingGoal);
  609.     // These are the times to seek to rather than the exact destinations.  When
  610.     // we seek, we will get another event (after a slight delay) and these steps
  611.     // will run again.  So if we seeked directly to |start|, |start| would move
  612.     // on the next call and we would loop forever.
  613.     const seekStart = this.timeline_.getSafeSeekRangeStart(safeSeekOffset);
  614.     const seekSafe = this.timeline_.getSafeSeekRangeStart(
  615.         rebufferingGoal + safeSeekOffset);
  617.     if (currentTime >= duration) {
  618.       shaka.log.v1('Playhead past duration.');
  619.       return this.clampSeekToDuration_(currentTime);
  620.     }
  622.     if (currentTime > end) {
  623.       shaka.log.v1('Playhead past end.');
  624.       // We remove the safeSeekEndOffset of the seek end to avoid the player
  625.       // to be block at the edge in a live stream
  626.       return end - this.config_.safeSeekEndOffset;
  627.     }
  629.     if (currentTime < start) {
  630.       if (this.timeline_.isLive() &&
  631.           this.config_.returnToEndOfLiveWindowWhenOutside) {
  632.         return end - this.config_.safeSeekEndOffset;
  633.       }
  634.       if (isBuffered(seekStart)) {
  635.         shaka.log.v1('Playhead before start & start is buffered');
  636.         return seekStart;
  637.       } else {
  638.         shaka.log.v1('Playhead before start & start is unbuffered');
  639.         return seekSafe;
  640.       }
  641.     }
  643.     if (currentTime >= safe || isBuffered(currentTime)) {
  644.       shaka.log.v1('Playhead in safe region or in buffered region.');
  645.       return currentTime;
  646.     } else {
  647.       shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  648.       return seekSafe;
  649.     }
  650.   }
  652.   /**
  653.    * Clamps the given time to the seek range.
  654.    *
  655.    * @param {number} time The time in seconds.
  656.    * @return {number} The clamped time in seconds.
  657.    * @private
  658.    */
  659.   clampTime_(time) {
  660.     const start = this.timeline_.getSeekRangeStart();
  661.     if (time < start) {
  662.       return start;
  663.     }
  665.     const end = this.timeline_.getSeekRangeEnd();
  666.     if (time > end) {
  667.       return end;
  668.     }
  670.     return time;
  671.   }
  672. };