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.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} startTime
  49.    */
  50.   setStartTime(startTime) {}
  52.   /**
  53.    * Get the current playhead position. The position will be restricted to valid
  54.    * time ranges.
  55.    *
  56.    * @return {number}
  57.    */
  58.   getTime() {}
  60.   /**
  61.    * Notify the playhead that the buffered ranges have changed.
  62.    */
  63.   notifyOfBufferingChange() {}
  64. };
  67. /**
  68.  * A playhead implementation that only relies on the media element.
  69.  *
  70.  * @implements {shaka.media.Playhead}
  71.  * @final
  72.  */
  73. shaka.media.SrcEqualsPlayhead = class {
  74.   /**
  75.    * @param {!HTMLMediaElement} mediaElement
  76.    */
  77.   constructor(mediaElement) {
  78.     /** @private {HTMLMediaElement} */
  79.     this.mediaElement_ = mediaElement;
  80.     /** @private {boolean} */
  81.     this.started_ = false;
  82.     /** @private {?number} */
  83.     this.startTime_ = null;
  85.     /** @private {shaka.util.EventManager} */
  86.     this.eventManager_ = new shaka.util.EventManager();
  87.   }
  89.   /** @override */
  90.   ready() {
  91.     goog.asserts.assert(
  92.         this.mediaElement_ != null,
  93.         'Playhead should not be released before calling ready()',
  94.     );
  96.     // We listen for the loaded-data-event so that we know when we can
  97.     // interact with |currentTime|.
  98.     const onLoaded = () => {
  99.       if (this.startTime_ == null || this.startTime_ == 0) {
  100.         this.started_ = true;
  101.       } else {
  102.         // Startup is complete only when the video element acknowledges the
  103.         // seek.
  104.         this.eventManager_.listenOnce(this.mediaElement_, 'seeking', () => {
  105.           this.started_ = true;
  106.         });
  108.         const currentTime = this.mediaElement_.currentTime;
  109.         // Using the currentTime allows using a negative number in Live HLS
  110.         const newTime = Math.max(0, currentTime + this.startTime_);
  111.         this.mediaElement_.currentTime = newTime;
  112.       }
  113.     };
  115.     shaka.util.MediaReadyState.waitForReadyState(this.mediaElement_,
  116.         HTMLMediaElement.HAVE_CURRENT_DATA,
  117.         this.eventManager_, () => {
  118.           onLoaded();
  119.         });
  120.   }
  122.   /** @override */
  123.   release() {
  124.     if (this.eventManager_) {
  125.       this.eventManager_.release();
  126.       this.eventManager_ = null;
  127.     }
  129.     this.mediaElement_ = null;
  130.   }
  132.   /** @override */
  133.   setStartTime(startTime) {
  134.     // If we have already started playback, ignore updates to the start time.
  135.     // This is just to make things consistent.
  136.     this.startTime_ = this.started_ ? this.startTime_ : startTime;
  137.   }
  139.   /** @override */
  140.   getTime() {
  141.     // If we have not started playback yet, return the start time. However once
  142.     // we start playback we assume that we can always return the current time.
  143.     const time = this.started_ ?
  144.                  this.mediaElement_.currentTime :
  145.                  this.startTime_;
  147.     // In the case that we have not started playback, but the start time was
  148.     // never set, we don't know what the start time should be. To ensure we
  149.     // always return a number, we will default back to 0.
  150.     return time || 0;
  151.   }
  153.   /** @override */
  154.   notifyOfBufferingChange() {}
  155. };
  158. /**
  159.  * A playhead implementation that relies on the media element and a manifest.
  160.  * When provided with a manifest, we can provide more accurate control than
  161.  * the SrcEqualsPlayhead.
  162.  *
  163.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  164.  *       for, and conditions on timestamp adjustment.
  165.  *
  166.  * @implements {shaka.media.Playhead}
  167.  * @final
  168.  */
  169. shaka.media.MediaSourcePlayhead = class {
  170.   /**
  171.    * @param {!HTMLMediaElement} mediaElement
  172.    * @param {shaka.extern.Manifest} manifest
  173.    * @param {shaka.extern.StreamingConfiguration} config
  174.    * @param {?number} startTime
  175.    *     The playhead's initial position in seconds. If null, defaults to the
  176.    *     start of the presentation for VOD and the live-edge for live.
  177.    * @param {function()} onSeek
  178.    *     Called when the user agent seeks to a time within the presentation
  179.    *     timeline.
  180.    * @param {function(!Event)} onEvent
  181.    *     Called when an event is raised to be sent to the application.
  182.    */
  183.   constructor(mediaElement, manifest, config, startTime, onSeek, onEvent) {
  184.     /**
  185.      * The seek range must be at least this number of seconds long. If it is
  186.      * smaller than this, change it to be this big so we don't repeatedly seek
  187.      * to keep within a zero-width window.
  188.      *
  189.      * This is 3s long, to account for the weaker hardware on platforms like
  190.      * Chromecast.
  191.      *
  192.      * @private {number}
  193.      */
  194.     this.minSeekRange_ = 3.0;
  196.     /** @private {HTMLMediaElement} */
  197.     this.mediaElement_ = mediaElement;
  199.     /** @private {shaka.media.PresentationTimeline} */
  200.     this.timeline_ = manifest.presentationTimeline;
  202.     /** @private {number} */
  203.     this.minBufferTime_ = manifest.minBufferTime || 0;
  205.     /** @private {?shaka.extern.StreamingConfiguration} */
  206.     this.config_ = config;
  208.     /** @private {function()} */
  209.     this.onSeek_ = onSeek;
  211.     /** @private {?number} */
  212.     this.lastCorrectiveSeek_ = null;
  214.     /** @private {shaka.media.GapJumpingController} */
  215.     this.gapController_ = new shaka.media.GapJumpingController(
  216.         mediaElement,
  217.         manifest.presentationTimeline,
  218.         config,
  219.         this.createStallDetector_(mediaElement, config),
  220.         onEvent);
  222.     /** @private {shaka.media.VideoWrapper} */
  223.     this.videoWrapper_ = new shaka.media.VideoWrapper(
  224.         mediaElement,
  225.         () => this.onSeeking_(),
  226.         this.getStartTime_(startTime));
  228.     /** @type {shaka.util.Timer} */
  229.     this.checkWindowTimer_ = new shaka.util.Timer(() => {
  230.       this.onPollWindow_();
  231.     });
  232.   }
  234.   /** @override */
  235.   ready() {
  236.     this.checkWindowTimer_.tickEvery(/* seconds= */ 0.25);
  237.   }
  239.   /** @override */
  240.   release() {
  241.     if (this.videoWrapper_) {
  242.       this.videoWrapper_.release();
  243.       this.videoWrapper_ = null;
  244.     }
  246.     if (this.gapController_) {
  247.       this.gapController_.release();
  248.       this.gapController_= null;
  249.     }
  251.     if (this.checkWindowTimer_) {
  252.       this.checkWindowTimer_.stop();
  253.       this.checkWindowTimer_ = null;
  254.     }
  256.     this.config_ = null;
  257.     this.timeline_ = null;
  258.     this.videoWrapper_ = null;
  259.     this.mediaElement_ = null;
  261.     this.onSeek_ = () => {};
  262.   }
  264.   /** @override */
  265.   setStartTime(startTime) {
  266.     this.videoWrapper_.setTime(startTime);
  267.   }
  269.   /** @override */
  270.   getTime() {
  271.     const time = this.videoWrapper_.getTime();
  273.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  274.     // ensure timing issues don't cause us to return a time outside the segment
  275.     // availability window.  E.g., the user agent seeks and calls this function
  276.     // before we receive the 'seeking' event.
  277.     //
  278.     // We don't buffer when the livestream video is paused and the playhead time
  279.     // is out of the seek range; thus, we do not clamp the current time when the
  280.     // video is paused.
  281.     // https://github.com/shaka-project/shaka-player/issues/1121
  282.     if (this.mediaElement_.readyState > 0 && !this.mediaElement_.paused) {
  283.       return this.clampTime_(time);
  284.     }
  286.     return time;
  287.   }
  289.   /**
  290.    * Gets the playhead's initial position in seconds.
  291.    *
  292.    * @param {?number} startTime
  293.    * @return {number}
  294.    * @private
  295.    */
  296.   getStartTime_(startTime) {
  297.     if (startTime == null) {
  298.       if (this.timeline_.getDuration() < Infinity) {
  299.         // If the presentation is VOD, or if the presentation is live but has
  300.         // finished broadcasting, then start from the beginning.
  301.         startTime = this.timeline_.getSeekRangeStart();
  302.       } else {
  303.         // Otherwise, start near the live-edge.
  304.         startTime = this.timeline_.getSeekRangeEnd();
  305.       }
  306.     } else if (startTime < 0) {
  307.       // For live streams, if the startTime is negative, start from a certain
  308.       // offset time from the live edge.  If the offset from the live edge is
  309.       // not available, start from the current available segment start point
  310.       // instead, handled by clampTime_().
  311.       startTime = this.timeline_.getSeekRangeEnd() + startTime;
  312.     }
  314.     return this.clampSeekToDuration_(this.clampTime_(startTime));
  315.   }
  317.   /** @override */
  318.   notifyOfBufferingChange() {
  319.     this.gapController_.onSegmentAppended();
  320.   }
  322.   /**
  323.    * Called on a recurring timer to keep the playhead from falling outside the
  324.    * availability window.
  325.    *
  326.    * @private
  327.    */
  328.   onPollWindow_() {
  329.     // Don't catch up to the seek range when we are paused or empty.
  330.     // The definition of "seeking" says that we are seeking until the buffered
  331.     // data intersects with the playhead.  If we fall outside of the seek range,
  332.     // it doesn't matter if we are in a "seeking" state.  We can and should go
  333.     // ahead and catch up while seeking.
  334.     if (this.mediaElement_.readyState == 0 || this.mediaElement_.paused) {
  335.       return;
  336.     }
  338.     const currentTime = this.videoWrapper_.getTime();
  339.     let seekStart = this.timeline_.getSeekRangeStart();
  340.     const seekEnd = this.timeline_.getSeekRangeEnd();
  342.     if (seekEnd - seekStart < this.minSeekRange_) {
  343.       seekStart = seekEnd - this.minSeekRange_;
  344.     }
  346.     if (currentTime < seekStart) {
  347.       // The seek range has moved past the playhead.  Move ahead to catch up.
  348.       const targetTime = this.reposition_(currentTime);
  349.       shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  350.                      ' seconds to catch up with the seek range.');
  351.       this.mediaElement_.currentTime = targetTime;
  352.     }
  353.   }
  355.   /**
  356.    * Handles when a seek happens on the video.
  357.    *
  358.    * @private
  359.    */
  360.   onSeeking_() {
  361.     this.gapController_.onSeeking();
  362.     const currentTime = this.videoWrapper_.getTime();
  363.     const targetTime = this.reposition_(currentTime);
  365.     const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  366.     if (Math.abs(targetTime - currentTime) > gapLimit) {
  367.       // You can only seek like this every so often. This is to prevent an
  368.       // infinite loop on systems where changing currentTime takes a significant
  369.       // amount of time (e.g. Chromecast).
  370.       const time = Date.now() / 1000;
  371.       if (!this.lastCorrectiveSeek_ || this.lastCorrectiveSeek_ < time - 1) {
  372.         this.lastCorrectiveSeek_ = time;
  373.         this.videoWrapper_.setTime(targetTime);
  374.         return;
  375.       }
  376.     }
  378.     shaka.log.v1('Seek to ' + currentTime);
  379.     this.onSeek_();
  380.   }
  382.   /**
  383.    * Clamp seek times and playback start times so that we never seek to the
  384.    * presentation duration.  Seeking to or starting at duration does not work
  385.    * consistently across browsers.
  386.    *
  387.    * @see https://github.com/shaka-project/shaka-player/issues/979
  388.    * @param {number} time
  389.    * @return {number} The adjusted seek time.
  390.    * @private
  391.    */
  392.   clampSeekToDuration_(time) {
  393.     const duration = this.timeline_.getDuration();
  394.     if (time >= duration) {
  395.       goog.asserts.assert(this.config_.durationBackoff >= 0,
  396.           'Duration backoff must be non-negative!');
  397.       return duration - this.config_.durationBackoff;
  398.     }
  399.     return time;
  400.   }
  402.   /**
  403.    * Computes a new playhead position that's within the presentation timeline.
  404.    *
  405.    * @param {number} currentTime
  406.    * @return {number} The time to reposition the playhead to.
  407.    * @private
  408.    */
  409.   reposition_(currentTime) {
  410.     goog.asserts.assert(
  411.         this.config_,
  412.         'Cannot reposition playhead when it has beeen destroyed');
  414.     /** @type {function(number)} */
  415.     const isBuffered = (playheadTime) => shaka.media.TimeRangesUtils.isBuffered(
  416.         this.mediaElement_.buffered, playheadTime);
  418.     const rebufferingGoal = Math.max(
  419.         this.minBufferTime_,
  420.         this.config_.rebufferingGoal);
  422.     const safeSeekOffset = this.config_.safeSeekOffset;
  424.     let start = this.timeline_.getSeekRangeStart();
  425.     const end = this.timeline_.getSeekRangeEnd();
  426.     const duration = this.timeline_.getDuration();
  428.     if (end - start < this.minSeekRange_) {
  429.       start = end - this.minSeekRange_;
  430.     }
  432.     // With live content, the beginning of the availability window is moving
  433.     // forward.  This means we cannot seek to it since we will "fall" outside
  434.     // the window while we buffer.  So we define a "safe" region that is far
  435.     // enough away.  For VOD, |safe == start|.
  436.     const safe = this.timeline_.getSafeSeekRangeStart(rebufferingGoal);
  438.     // These are the times to seek to rather than the exact destinations.  When
  439.     // we seek, we will get another event (after a slight delay) and these steps
  440.     // will run again.  So if we seeked directly to |start|, |start| would move
  441.     // on the next call and we would loop forever.
  442.     const seekStart = this.timeline_.getSafeSeekRangeStart(safeSeekOffset);
  443.     const seekSafe = this.timeline_.getSafeSeekRangeStart(
  444.         rebufferingGoal + safeSeekOffset);
  446.     if (currentTime >= duration) {
  447.       shaka.log.v1('Playhead past duration.');
  448.       return this.clampSeekToDuration_(currentTime);
  449.     }
  451.     if (currentTime > end) {
  452.       shaka.log.v1('Playhead past end.');
  453.       return end;
  454.     }
  456.     if (currentTime < start) {
  457.       if (isBuffered(seekStart)) {
  458.         shaka.log.v1('Playhead before start & start is buffered');
  459.         return seekStart;
  460.       } else {
  461.         shaka.log.v1('Playhead before start & start is unbuffered');
  462.         return seekSafe;
  463.       }
  464.     }
  466.     if (currentTime >= safe || isBuffered(currentTime)) {
  467.       shaka.log.v1('Playhead in safe region or in buffered region.');
  468.       return currentTime;
  469.     } else {
  470.       shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  471.       return seekSafe;
  472.     }
  473.   }
  475.   /**
  476.    * Clamps the given time to the seek range.
  477.    *
  478.    * @param {number} time The time in seconds.
  479.    * @return {number} The clamped time in seconds.
  480.    * @private
  481.    */
  482.   clampTime_(time) {
  483.     const start = this.timeline_.getSeekRangeStart();
  484.     if (time < start) {
  485.       return start;
  486.     }
  488.     const end = this.timeline_.getSeekRangeEnd();
  489.     if (time > end) {
  490.       return end;
  491.     }
  493.     return time;
  494.   }
  496.   /**
  497.    * Create and configure a stall detector using the player's streaming
  498.    * configuration settings. If the player is configured to have no stall
  499.    * detector, this will return |null|.
  500.    *
  501.    * @param {!HTMLMediaElement} mediaElement
  502.    * @param {shaka.extern.StreamingConfiguration} config
  503.    * @return {shaka.media.StallDetector}
  504.    * @private
  505.    */
  506.   createStallDetector_(mediaElement, config) {
  507.     if (!config.stallEnabled) {
  508.       return null;
  509.     }
  511.     // Cache the values from the config so that changes to the config won't
  512.     // change the initialized behaviour.
  513.     const threshold = config.stallThreshold;
  514.     const skip = config.stallSkip;
  516.     // When we see a stall, we will try to "jump-start" playback by moving the
  517.     // playhead forward.
  518.     const detector = new shaka.media.StallDetector(
  519.         new shaka.media.StallDetector.MediaElementImplementation(mediaElement),
  520.         threshold);
  522.     detector.onStall((at, duration) => {
  523.       shaka.log.debug(`Stall detected at ${at} for ${duration} seconds.`);
  525.       if (skip) {
  526.         shaka.log.debug(`Seeking forward ${skip} seconds to break stall.`);
  527.         mediaElement.currentTime += skip;
  528.       } else {
  529.         shaka.log.debug('Pausing and unpausing to break stall.');
  530.         mediaElement.pause();
  531.         mediaElement.play();
  532.       }
  533.     });
  535.     return detector;
  536.   }
  537. };