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.log');
  13. goog.require('shaka.media.GapJumpingController');
  14. goog.require('shaka.media.StallDetector');
  15. goog.require('shaka.media.StallDetector.MediaElementImplementation');
  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.Platform');
  22. goog.require('shaka.util.Timer');
  23. goog.requireType('shaka.media.PresentationTimeline');
  26. /**
  27.  * Creates a Playhead, which manages the video's current time.
  28.  *
  29.  * The Playhead provides mechanisms for setting the presentation's start time,
  30.  * restricting seeking to valid time ranges, and stopping playback for startup
  31.  * and re-buffering.
  32.  *
  33.  * @extends {shaka.util.IReleasable}
  34.  * @interface
  35.  */
  36. shaka.media.Playhead = class {
  37.   /**
  38.    * Called when the Player is ready to begin playback. Anything that depends
  39.    * on setStartTime() should be done here, not in the constructor.
  40.    *
  41.    * @see https://github.com/shaka-project/shaka-player/issues/4244
  42.    */
  43.   ready() {}
  45.   /**
  46.    * Set the start time. If the content has already started playback, this will
  47.    * be ignored.
  48.    *
  49.    * @param {number} startTime
  50.    */
  51.   setStartTime(startTime) {}
  53.   /**
  54.    * Get the number of playback stalls detected by the StallDetector.
  55.    *
  56.    * @return {number}
  57.    */
  58.   getStallsDetected() {}
  60.   /**
  61.    * Get the number of playback gaps jumped by the GapJumpingController.
  62.    *
  63.    * @return {number}
  64.    */
  65.   getGapsJumped() {}
  67.   /**
  68.    * Get the current playhead position. The position will be restricted to valid
  69.    * time ranges.
  70.    *
  71.    * @return {number}
  72.    */
  73.   getTime() {}
  75.   /**
  76.    * Notify the playhead that the buffered ranges have changed.
  77.    */
  78.   notifyOfBufferingChange() {}
  79. };
  82. /**
  83.  * A playhead implementation that only relies on the media element.
  84.  *
  85.  * @implements {shaka.media.Playhead}
  86.  * @final
  87.  */
  88. shaka.media.SrcEqualsPlayhead = class {
  89.   /**
  90.    * @param {!HTMLMediaElement} mediaElement
  91.    */
  92.   constructor(mediaElement) {
  93.     /** @private {HTMLMediaElement} */
  94.     this.mediaElement_ = mediaElement;
  95.     /** @private {boolean} */
  96.     this.started_ = false;
  97.     /** @private {?number} */
  98.     this.startTime_ = null;
  100.     /** @private {shaka.util.EventManager} */
  101.     this.eventManager_ = new shaka.util.EventManager();
  102.   }
  104.   /** @override */
  105.   ready() {
  106.     goog.asserts.assert(
  107.         this.mediaElement_ != null,
  108.         'Playhead should not be released before calling ready()',
  109.     );
  111.     // We listen for the loaded-data-event so that we know when we can
  112.     // interact with |currentTime|.
  113.     const onLoaded = () => {
  114.       if (this.startTime_ == null ||
  115.           (this.startTime_ == 0 && this.mediaElement_.duration != Infinity)) {
  116.         this.started_ = true;
  117.       } else {
  118.         const currentTime = this.mediaElement_.currentTime;
  119.         let newTime = this.startTime_;
  120.         // Using the currentTime allows using a negative number in Live HLS
  121.         if (this.startTime_ < 0) {
  122.           newTime = Math.max(0, currentTime + this.startTime_);
  123.         }
  124.         if (currentTime != newTime) {
  125.           // Startup is complete only when the video element acknowledges the
  126.           // seek.
  127.           this.eventManager_.listenOnce(this.mediaElement_, 'seeking', () => {
  128.             this.started_ = true;
  129.           });
  130.           this.mediaElement_.currentTime = newTime;
  131.         } else {
  132.           this.started_ = true;
  133.         }
  134.       }
  135.     };
  137.     shaka.util.MediaReadyState.waitForReadyState(this.mediaElement_,
  138.         HTMLMediaElement.HAVE_CURRENT_DATA,
  139.         this.eventManager_, () => {
  140.           onLoaded();
  141.         });
  142.   }
  144.   /** @override */
  145.   release() {
  146.     if (this.eventManager_) {
  147.       this.eventManager_.release();
  148.       this.eventManager_ = null;
  149.     }
  151.     this.mediaElement_ = null;
  152.   }
  154.   /** @override */
  155.   setStartTime(startTime) {
  156.     // If we have already started playback, ignore updates to the start time.
  157.     // This is just to make things consistent.
  158.     this.startTime_ = this.started_ ? this.startTime_ : startTime;
  159.   }
  161.   /** @override */
  162.   getTime() {
  163.     // If we have not started playback yet, return the start time. However once
  164.     // we start playback we assume that we can always return the current time.
  165.     const time = this.started_ ?
  166.                  this.mediaElement_.currentTime :
  167.                  this.startTime_;
  169.     // In the case that we have not started playback, but the start time was
  170.     // never set, we don't know what the start time should be. To ensure we
  171.     // always return a number, we will default back to 0.
  172.     return time || 0;
  173.   }
  175.   /** @override */
  176.   getStallsDetected() {
  177.     return 0;
  178.   }
  180.   /** @override */
  181.   getGapsJumped() {
  182.     return 0;
  183.   }
  185.   /** @override */
  186.   notifyOfBufferingChange() {}
  187. };
  190. /**
  191.  * A playhead implementation that relies on the media element and a manifest.
  192.  * When provided with a manifest, we can provide more accurate control than
  193.  * the SrcEqualsPlayhead.
  194.  *
  195.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  196.  *       for, and conditions on timestamp adjustment.
  197.  *
  198.  * @implements {shaka.media.Playhead}
  199.  * @final
  200.  */
  201. shaka.media.MediaSourcePlayhead = class {
  202.   /**
  203.    * @param {!HTMLMediaElement} mediaElement
  204.    * @param {shaka.extern.Manifest} manifest
  205.    * @param {shaka.extern.StreamingConfiguration} config
  206.    * @param {?number} startTime
  207.    *     The playhead's initial position in seconds. If null, defaults to the
  208.    *     start of the presentation for VOD and the live-edge for live.
  209.    * @param {function()} onSeek
  210.    *     Called when the user agent seeks to a time within the presentation
  211.    *     timeline.
  212.    * @param {function(!Event)} onEvent
  213.    *     Called when an event is raised to be sent to the application.
  214.    */
  215.   constructor(mediaElement, manifest, config, startTime, onSeek, onEvent) {
  216.     /**
  217.      * The seek range must be at least this number of seconds long. If it is
  218.      * smaller than this, change it to be this big so we don't repeatedly seek
  219.      * to keep within a zero-width window.
  220.      *
  221.      * This is 3s long, to account for the weaker hardware on platforms like
  222.      * Chromecast.
  223.      *
  224.      * @private {number}
  225.      */
  226.     this.minSeekRange_ = 3.0;
  228.     /** @private {HTMLMediaElement} */
  229.     this.mediaElement_ = mediaElement;
  231.     /** @private {shaka.media.PresentationTimeline} */
  232.     this.timeline_ = manifest.presentationTimeline;
  234.     /** @private {number} */
  235.     this.minBufferTime_ = manifest.minBufferTime || 0;
  237.     /** @private {?shaka.extern.StreamingConfiguration} */
  238.     this.config_ = config;
  240.     /** @private {function()} */
  241.     this.onSeek_ = onSeek;
  243.     /** @private {?number} */
  244.     this.lastCorrectiveSeek_ = null;
  246.     /** @private {shaka.media.StallDetector} */
  247.     this.stallDetector_ =
  248.         this.createStallDetector_(mediaElement, config, onEvent);
  250.     /** @private {shaka.media.GapJumpingController} */
  251.     this.gapController_ = new shaka.media.GapJumpingController(
  252.         mediaElement,
  253.         manifest.presentationTimeline,
  254.         config,
  255.         this.stallDetector_,
  256.         onEvent);
  258.     /** @private {shaka.media.VideoWrapper} */
  259.     this.videoWrapper_ = new shaka.media.VideoWrapper(
  260.         mediaElement,
  261.         () => this.onSeeking_(),
  262.         (realStartTime) => this.onStarted_(realStartTime),
  263.         () => this.getStartTime_(startTime));
  265.     /** @type {shaka.util.Timer} */
  266.     this.checkWindowTimer_ = new shaka.util.Timer(() => {
  267.       this.onPollWindow_();
  268.     });
  269.   }
  271.   /** @override */
  272.   ready() {
  273.     this.checkWindowTimer_.tickEvery(/* seconds= */ 0.25);
  274.   }
  276.   /** @override */
  277.   release() {
  278.     if (this.videoWrapper_) {
  279.       this.videoWrapper_.release();
  280.       this.videoWrapper_ = null;
  281.     }
  283.     if (this.gapController_) {
  284.       this.gapController_.release();
  285.       this.gapController_= null;
  286.     }
  288.     if (this.checkWindowTimer_) {
  289.       this.checkWindowTimer_.stop();
  290.       this.checkWindowTimer_ = null;
  291.     }
  293.     this.config_ = null;
  294.     this.timeline_ = null;
  295.     this.videoWrapper_ = null;
  296.     this.mediaElement_ = null;
  298.     this.onSeek_ = () => {};
  299.   }
  301.   /** @override */
  302.   setStartTime(startTime) {
  303.     this.videoWrapper_.setTime(startTime);
  304.   }
  306.   /** @override */
  307.   getTime() {
  308.     const time = this.videoWrapper_.getTime();
  310.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  311.     // ensure timing issues don't cause us to return a time outside the segment
  312.     // availability window.  E.g., the user agent seeks and calls this function
  313.     // before we receive the 'seeking' event.
  314.     //
  315.     // We don't buffer when the livestream video is paused and the playhead time
  316.     // is out of the seek range; thus, we do not clamp the current time when the
  317.     // video is paused.
  318.     // https://github.com/shaka-project/shaka-player/issues/1121
  319.     if (this.mediaElement_.readyState > 0 && !this.mediaElement_.paused) {
  320.       return this.clampTime_(time);
  321.     }
  323.     return time;
  324.   }
  326.   /** @override */
  327.   getStallsDetected() {
  328.     return this.stallDetector_ ? this.stallDetector_.getStallsDetected() : 0;
  329.   }
  331.   /** @override */
  332.   getGapsJumped() {
  333.     return this.gapController_.getGapsJumped();
  334.   }
  336.   /**
  337.    * Gets the playhead's initial position in seconds.
  338.    *
  339.    * @param {?number} startTime
  340.    * @return {number}
  341.    * @private
  342.    */
  343.   getStartTime_(startTime) {
  344.     if (startTime == null) {
  345.       if (this.timeline_.getDuration() < Infinity) {
  346.         // If the presentation is VOD, or if the presentation is live but has
  347.         // finished broadcasting, then start from the beginning.
  348.         startTime = this.timeline_.getSeekRangeStart();
  349.       } else {
  350.         // Otherwise, start near the live-edge.
  351.         startTime = this.timeline_.getSeekRangeEnd();
  352.       }
  353.     } else if (startTime < 0) {
  354.       // For live streams, if the startTime is negative, start from a certain
  355.       // offset time from the live edge.  If the offset from the live edge is
  356.       // not available, start from the current available segment start point
  357.       // instead, handled by clampTime_().
  358.       startTime = this.timeline_.getSeekRangeEnd() + startTime;
  359.     }
  361.     return this.clampSeekToDuration_(this.clampTime_(startTime));
  362.   }
  364.   /** @override */
  365.   notifyOfBufferingChange() {
  366.     this.gapController_.onSegmentAppended();
  367.   }
  369.   /**
  370.    * Called on a recurring timer to keep the playhead from falling outside the
  371.    * availability window.
  372.    *
  373.    * @private
  374.    */
  375.   onPollWindow_() {
  376.     // Don't catch up to the seek range when we are paused or empty.
  377.     // The definition of "seeking" says that we are seeking until the buffered
  378.     // data intersects with the playhead.  If we fall outside of the seek range,
  379.     // it doesn't matter if we are in a "seeking" state.  We can and should go
  380.     // ahead and catch up while seeking.
  381.     if (this.mediaElement_.readyState == 0 || this.mediaElement_.paused) {
  382.       return;
  383.     }
  385.     const currentTime = this.videoWrapper_.getTime();
  386.     let seekStart = this.timeline_.getSeekRangeStart();
  387.     const seekEnd = this.timeline_.getSeekRangeEnd();
  389.     if (seekEnd - seekStart < this.minSeekRange_) {
  390.       seekStart = seekEnd - this.minSeekRange_;
  391.     }
  393.     if (currentTime < seekStart) {
  394.       // The seek range has moved past the playhead.  Move ahead to catch up.
  395.       const targetTime = this.reposition_(currentTime);
  396.       shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  397.                      ' seconds to catch up with the seek range.');
  398.       this.mediaElement_.currentTime = targetTime;
  399.     }
  400.   }
  402.   /**
  403.    * Called when the video element has started up and is listening for new seeks
  404.    *
  405.    * @param {number} startTime
  406.    * @private
  407.    */
  408.   onStarted_(startTime) {
  409.     this.gapController_.onStarted(startTime);
  410.   }
  412.   /**
  413.    * Handles when a seek happens on the video.
  414.    *
  415.    * @private
  416.    */
  417.   onSeeking_() {
  418.     this.gapController_.onSeeking();
  419.     const currentTime = this.videoWrapper_.getTime();
  420.     const targetTime = this.reposition_(currentTime);
  422.     const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  423.     if (Math.abs(targetTime - currentTime) > gapLimit) {
  424.       let canCorrectiveSeek = false;
  425.       if (shaka.util.Platform.isSeekingSlow()) {
  426.         // You can only seek like this every so often. This is to prevent an
  427.         // infinite loop on systems where changing currentTime takes a
  428.         // significant amount of time (e.g. Chromecast).
  429.         const time = Date.now() / 1000;
  430.         if (!this.lastCorrectiveSeek_ || this.lastCorrectiveSeek_ < time - 1) {
  431.           this.lastCorrectiveSeek_ = time;
  432.           canCorrectiveSeek = true;
  433.         }
  434.       } else {
  435.         canCorrectiveSeek = true;
  436.       }
  437.       if (canCorrectiveSeek) {
  438.         this.videoWrapper_.setTime(targetTime);
  439.         return;
  440.       }
  441.     }
  443.     shaka.log.v1('Seek to ' + currentTime);
  444.     this.onSeek_();
  445.   }
  447.   /**
  448.    * Clamp seek times and playback start times so that we never seek to the
  449.    * presentation duration.  Seeking to or starting at duration does not work
  450.    * consistently across browsers.
  451.    *
  452.    * @see https://github.com/shaka-project/shaka-player/issues/979
  453.    * @param {number} time
  454.    * @return {number} The adjusted seek time.
  455.    * @private
  456.    */
  457.   clampSeekToDuration_(time) {
  458.     const duration = this.timeline_.getDuration();
  459.     if (time >= duration) {
  460.       goog.asserts.assert(this.config_.durationBackoff >= 0,
  461.           'Duration backoff must be non-negative!');
  462.       return duration - this.config_.durationBackoff;
  463.     }
  464.     return time;
  465.   }
  467.   /**
  468.    * Computes a new playhead position that's within the presentation timeline.
  469.    *
  470.    * @param {number} currentTime
  471.    * @return {number} The time to reposition the playhead to.
  472.    * @private
  473.    */
  474.   reposition_(currentTime) {
  475.     goog.asserts.assert(
  476.         this.config_,
  477.         'Cannot reposition playhead when it has beeen destroyed');
  479.     /** @type {function(number)} */
  480.     const isBuffered = (playheadTime) => shaka.media.TimeRangesUtils.isBuffered(
  481.         this.mediaElement_.buffered, playheadTime);
  483.     const rebufferingGoal = Math.max(
  484.         this.minBufferTime_,
  485.         this.config_.rebufferingGoal);
  487.     const safeSeekOffset = this.config_.safeSeekOffset;
  489.     let start = this.timeline_.getSeekRangeStart();
  490.     const end = this.timeline_.getSeekRangeEnd();
  491.     const duration = this.timeline_.getDuration();
  493.     if (end - start < this.minSeekRange_) {
  494.       start = end - this.minSeekRange_;
  495.     }
  497.     // With live content, the beginning of the availability window is moving
  498.     // forward.  This means we cannot seek to it since we will "fall" outside
  499.     // the window while we buffer.  So we define a "safe" region that is far
  500.     // enough away.  For VOD, |safe == start|.
  501.     const safe = this.timeline_.getSafeSeekRangeStart(rebufferingGoal);
  503.     // These are the times to seek to rather than the exact destinations.  When
  504.     // we seek, we will get another event (after a slight delay) and these steps
  505.     // will run again.  So if we seeked directly to |start|, |start| would move
  506.     // on the next call and we would loop forever.
  507.     const seekStart = this.timeline_.getSafeSeekRangeStart(safeSeekOffset);
  508.     const seekSafe = this.timeline_.getSafeSeekRangeStart(
  509.         rebufferingGoal + safeSeekOffset);
  511.     if (currentTime >= duration) {
  512.       shaka.log.v1('Playhead past duration.');
  513.       return this.clampSeekToDuration_(currentTime);
  514.     }
  516.     if (currentTime > end) {
  517.       shaka.log.v1('Playhead past end.');
  518.       return end;
  519.     }
  521.     if (currentTime < start) {
  522.       if (isBuffered(seekStart)) {
  523.         shaka.log.v1('Playhead before start & start is buffered');
  524.         return seekStart;
  525.       } else {
  526.         shaka.log.v1('Playhead before start & start is unbuffered');
  527.         return seekSafe;
  528.       }
  529.     }
  531.     if (currentTime >= safe || isBuffered(currentTime)) {
  532.       shaka.log.v1('Playhead in safe region or in buffered region.');
  533.       return currentTime;
  534.     } else {
  535.       shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  536.       return seekSafe;
  537.     }
  538.   }
  540.   /**
  541.    * Clamps the given time to the seek range.
  542.    *
  543.    * @param {number} time The time in seconds.
  544.    * @return {number} The clamped time in seconds.
  545.    * @private
  546.    */
  547.   clampTime_(time) {
  548.     const start = this.timeline_.getSeekRangeStart();
  549.     if (time < start) {
  550.       return start;
  551.     }
  553.     const end = this.timeline_.getSeekRangeEnd();
  554.     if (time > end) {
  555.       return end;
  556.     }
  558.     return time;
  559.   }
  561.   /**
  562.    * Create and configure a stall detector using the player's streaming
  563.    * configuration settings. If the player is configured to have no stall
  564.    * detector, this will return |null|.
  565.    *
  566.    * @param {!HTMLMediaElement} mediaElement
  567.    * @param {shaka.extern.StreamingConfiguration} config
  568.    * @param {function(!Event)} onEvent
  569.    *     Called when an event is raised to be sent to the application.
  570.    * @return {shaka.media.StallDetector}
  571.    * @private
  572.    */
  573.   createStallDetector_(mediaElement, config, onEvent) {
  574.     if (!config.stallEnabled) {
  575.       return null;
  576.     }
  578.     // Cache the values from the config so that changes to the config won't
  579.     // change the initialized behaviour.
  580.     const threshold = config.stallThreshold;
  581.     const skip = config.stallSkip;
  583.     // When we see a stall, we will try to "jump-start" playback by moving the
  584.     // playhead forward.
  585.     const detector = new shaka.media.StallDetector(
  586.         new shaka.media.StallDetector.MediaElementImplementation(mediaElement),
  587.         threshold, onEvent);
  589.     detector.onStall((at, duration) => {
  590.       shaka.log.debug(`Stall detected at ${at} for ${duration} seconds.`);
  592.       if (skip) {
  593.         shaka.log.debug(`Seeking forward ${skip} seconds to break stall.`);
  594.         mediaElement.currentTime += skip;
  595.       } else {
  596.         shaka.log.debug('Pausing and unpausing to break stall.');
  597.         mediaElement.pause();
  598.         mediaElement.play();
  599.       }
  600.     });
  602.     return detector;
  603.   }
  604. };