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.TimeRangesUtils');
  15. goog.require('shaka.media.VideoWrapper');
  16. goog.require('shaka.util.EventManager');
  17. goog.require('shaka.util.IReleasable');
  18. goog.require('shaka.util.MediaReadyState');
  19. goog.require('shaka.util.Platform');
  20. goog.require('shaka.util.Timer');
  21. goog.requireType('shaka.media.PresentationTimeline');
  24. /**
  25.  * Creates a Playhead, which manages the video's current time.
  26.  *
  27.  * The Playhead provides mechanisms for setting the presentation's start time,
  28.  * restricting seeking to valid time ranges, and stopping playback for startup
  29.  * and re-buffering.
  30.  *
  31.  * @extends {shaka.util.IReleasable}
  32.  * @interface
  33.  */
  34. shaka.media.Playhead = class {
  35.   /**
  36.    * Called when the Player is ready to begin playback. Anything that depends
  37.    * on setStartTime() should be done here, not in the constructor.
  38.    *
  39.    * @see https://github.com/shaka-project/shaka-player/issues/4244
  40.    */
  41.   ready() {}
  43.   /**
  44.    * Set the start time. If the content has already started playback, this will
  45.    * be ignored.
  46.    *
  47.    * @param {number} startTime
  48.    */
  49.   setStartTime(startTime) {}
  51.   /**
  52.    * Get the number of playback stalls detected by the StallDetector.
  53.    *
  54.    * @return {number}
  55.    */
  56.   getStallsDetected() {}
  58.   /**
  59.    * Get the number of playback gaps jumped by the GapJumpingController.
  60.    *
  61.    * @return {number}
  62.    */
  63.   getGapsJumped() {}
  65.   /**
  66.    * Get the current playhead position. The position will be restricted to valid
  67.    * time ranges.
  68.    *
  69.    * @return {number}
  70.    */
  71.   getTime() {}
  73.   /**
  74.    * Notify the playhead that the buffered ranges have changed.
  75.    */
  76.   notifyOfBufferingChange() {}
  77. };
  80. /**
  81.  * A playhead implementation that only relies on the media element.
  82.  *
  83.  * @implements {shaka.media.Playhead}
  84.  * @final
  85.  */
  86. shaka.media.SrcEqualsPlayhead = class {
  87.   /**
  88.    * @param {!HTMLMediaElement} mediaElement
  89.    */
  90.   constructor(mediaElement) {
  91.     /** @private {HTMLMediaElement} */
  92.     this.mediaElement_ = mediaElement;
  93.     /** @private {boolean} */
  94.     this.started_ = false;
  95.     /** @private {?number} */
  96.     this.startTime_ = null;
  98.     /** @private {shaka.util.EventManager} */
  99.     this.eventManager_ = new shaka.util.EventManager();
  100.   }
  102.   /** @override */
  103.   ready() {
  104.     goog.asserts.assert(
  105.         this.mediaElement_ != null,
  106.         'Playhead should not be released before calling ready()',
  107.     );
  109.     // We listen for the loaded-data-event so that we know when we can
  110.     // interact with |currentTime|.
  111.     const onLoaded = () => {
  112.       if (this.startTime_ == null ||
  113.           (this.startTime_ == 0 && this.mediaElement_.duration != Infinity)) {
  114.         this.started_ = true;
  115.       } else {
  116.         const currentTime = this.mediaElement_.currentTime;
  117.         let newTime = this.startTime_;
  118.         // Using the currentTime allows using a negative number in Live HLS
  119.         if (this.startTime_ < 0) {
  120.           newTime = Math.max(0, currentTime + this.startTime_);
  121.         }
  122.         if (currentTime != newTime) {
  123.           // Startup is complete only when the video element acknowledges the
  124.           // seek.
  125.           this.eventManager_.listenOnce(this.mediaElement_, 'seeking', () => {
  126.             this.started_ = true;
  127.           });
  128.           this.mediaElement_.currentTime = newTime;
  129.         } else {
  130.           this.started_ = true;
  131.         }
  132.       }
  133.     };
  135.     shaka.util.MediaReadyState.waitForReadyState(this.mediaElement_,
  136.         HTMLMediaElement.HAVE_CURRENT_DATA,
  137.         this.eventManager_, () => {
  138.           onLoaded();
  139.         });
  140.   }
  142.   /** @override */
  143.   release() {
  144.     if (this.eventManager_) {
  145.       this.eventManager_.release();
  146.       this.eventManager_ = null;
  147.     }
  149.     this.mediaElement_ = null;
  150.   }
  152.   /** @override */
  153.   setStartTime(startTime) {
  154.     // If we have already started playback, ignore updates to the start time.
  155.     // This is just to make things consistent.
  156.     this.startTime_ = this.started_ ? this.startTime_ : startTime;
  157.   }
  159.   /** @override */
  160.   getTime() {
  161.     // If we have not started playback yet, return the start time. However once
  162.     // we start playback we assume that we can always return the current time.
  163.     const time = this.started_ ?
  164.                  this.mediaElement_.currentTime :
  165.                  this.startTime_;
  167.     // In the case that we have not started playback, but the start time was
  168.     // never set, we don't know what the start time should be. To ensure we
  169.     // always return a number, we will default back to 0.
  170.     return time || 0;
  171.   }
  173.   /** @override */
  174.   getStallsDetected() {
  175.     return 0;
  176.   }
  178.   /** @override */
  179.   getGapsJumped() {
  180.     return 0;
  181.   }
  183.   /** @override */
  184.   notifyOfBufferingChange() {}
  185. };
  188. /**
  189.  * A playhead implementation that relies on the media element and a manifest.
  190.  * When provided with a manifest, we can provide more accurate control than
  191.  * the SrcEqualsPlayhead.
  192.  *
  193.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  194.  *       for, and conditions on timestamp adjustment.
  195.  *
  196.  * @implements {shaka.media.Playhead}
  197.  * @final
  198.  */
  199. shaka.media.MediaSourcePlayhead = class {
  200.   /**
  201.    * @param {!HTMLMediaElement} mediaElement
  202.    * @param {shaka.extern.Manifest} manifest
  203.    * @param {shaka.extern.StreamingConfiguration} config
  204.    * @param {?number} startTime
  205.    *     The playhead's initial position in seconds. If null, defaults to the
  206.    *     start of the presentation for VOD and the live-edge for live.
  207.    * @param {function()} onSeek
  208.    *     Called when the user agent seeks to a time within the presentation
  209.    *     timeline.
  210.    * @param {function(!Event)} onEvent
  211.    *     Called when an event is raised to be sent to the application.
  212.    */
  213.   constructor(mediaElement, manifest, config, startTime, onSeek, onEvent) {
  214.     /**
  215.      * The seek range must be at least this number of seconds long. If it is
  216.      * smaller than this, change it to be this big so we don't repeatedly seek
  217.      * to keep within a zero-width window.
  218.      *
  219.      * This is 3s long, to account for the weaker hardware on platforms like
  220.      * Chromecast.
  221.      *
  222.      * @private {number}
  223.      */
  224.     this.minSeekRange_ = 3.0;
  226.     /** @private {HTMLMediaElement} */
  227.     this.mediaElement_ = mediaElement;
  229.     /** @private {shaka.media.PresentationTimeline} */
  230.     this.timeline_ = manifest.presentationTimeline;
  232.     /** @private {number} */
  233.     this.minBufferTime_ = manifest.minBufferTime || 0;
  235.     /** @private {?shaka.extern.StreamingConfiguration} */
  236.     this.config_ = config;
  238.     /** @private {function()} */
  239.     this.onSeek_ = onSeek;
  241.     /** @private {?number} */
  242.     this.lastCorrectiveSeek_ = null;
  244.     /** @private {shaka.media.GapJumpingController} */
  245.     this.gapController_ = new shaka.media.GapJumpingController(
  246.         mediaElement,
  247.         manifest.presentationTimeline,
  248.         config,
  249.         onEvent);
  251.     /** @private {shaka.media.VideoWrapper} */
  252.     this.videoWrapper_ = new shaka.media.VideoWrapper(
  253.         mediaElement,
  254.         () => this.onSeeking_(),
  255.         (realStartTime) => this.onStarted_(realStartTime),
  256.         () => this.getStartTime_(startTime));
  258.     /** @type {shaka.util.Timer} */
  259.     this.checkWindowTimer_ = new shaka.util.Timer(() => {
  260.       this.onPollWindow_();
  261.     });
  262.   }
  264.   /** @override */
  265.   ready() {
  266.     this.checkWindowTimer_.tickEvery(/* seconds= */ 0.25);
  267.   }
  269.   /** @override */
  270.   release() {
  271.     if (this.videoWrapper_) {
  272.       this.videoWrapper_.release();
  273.       this.videoWrapper_ = null;
  274.     }
  276.     if (this.gapController_) {
  277.       this.gapController_.release();
  278.       this.gapController_= null;
  279.     }
  281.     if (this.checkWindowTimer_) {
  282.       this.checkWindowTimer_.stop();
  283.       this.checkWindowTimer_ = null;
  284.     }
  286.     this.config_ = null;
  287.     this.timeline_ = null;
  288.     this.videoWrapper_ = null;
  289.     this.mediaElement_ = null;
  291.     this.onSeek_ = () => {};
  292.   }
  294.   /** @override */
  295.   setStartTime(startTime) {
  296.     this.videoWrapper_.setTime(startTime);
  297.   }
  299.   /** @override */
  300.   getTime() {
  301.     const time = this.videoWrapper_.getTime();
  303.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  304.     // ensure timing issues don't cause us to return a time outside the segment
  305.     // availability window.  E.g., the user agent seeks and calls this function
  306.     // before we receive the 'seeking' event.
  307.     //
  308.     // We don't buffer when the livestream video is paused and the playhead time
  309.     // is out of the seek range; thus, we do not clamp the current time when the
  310.     // video is paused.
  311.     // https://github.com/shaka-project/shaka-player/issues/1121
  312.     if (this.mediaElement_.readyState > 0 && !this.mediaElement_.paused) {
  313.       return this.clampTime_(time);
  314.     }
  316.     return time;
  317.   }
  319.   /** @override */
  320.   getStallsDetected() {
  321.     return this.gapController_.getStallsDetected();
  322.   }
  324.   /** @override */
  325.   getGapsJumped() {
  326.     return this.gapController_.getGapsJumped();
  327.   }
  329.   /**
  330.    * Gets the playhead's initial position in seconds.
  331.    *
  332.    * @param {?number} startTime
  333.    * @return {number}
  334.    * @private
  335.    */
  336.   getStartTime_(startTime) {
  337.     if (startTime == null) {
  338.       if (this.timeline_.getDuration() < Infinity) {
  339.         // If the presentation is VOD, or if the presentation is live but has
  340.         // finished broadcasting, then start from the beginning.
  341.         startTime = this.timeline_.getSeekRangeStart();
  342.       } else {
  343.         // Otherwise, start near the live-edge.
  344.         startTime = this.timeline_.getSeekRangeEnd();
  345.       }
  346.     } else if (startTime < 0) {
  347.       // For live streams, if the startTime is negative, start from a certain
  348.       // offset time from the live edge.  If the offset from the live edge is
  349.       // not available, start from the current available segment start point
  350.       // instead, handled by clampTime_().
  351.       startTime = this.timeline_.getSeekRangeEnd() + startTime;
  352.     }
  354.     return this.clampSeekToDuration_(this.clampTime_(startTime));
  355.   }
  357.   /** @override */
  358.   notifyOfBufferingChange() {
  359.     this.gapController_.onSegmentAppended();
  360.   }
  362.   /**
  363.    * Called on a recurring timer to keep the playhead from falling outside the
  364.    * availability window.
  365.    *
  366.    * @private
  367.    */
  368.   onPollWindow_() {
  369.     // Don't catch up to the seek range when we are paused or empty.
  370.     // The definition of "seeking" says that we are seeking until the buffered
  371.     // data intersects with the playhead.  If we fall outside of the seek range,
  372.     // it doesn't matter if we are in a "seeking" state.  We can and should go
  373.     // ahead and catch up while seeking.
  374.     if (this.mediaElement_.readyState == 0 || this.mediaElement_.paused) {
  375.       return;
  376.     }
  378.     const currentTime = this.videoWrapper_.getTime();
  379.     let seekStart = this.timeline_.getSeekRangeStart();
  380.     const seekEnd = this.timeline_.getSeekRangeEnd();
  382.     if (seekEnd - seekStart < this.minSeekRange_) {
  383.       seekStart = seekEnd - this.minSeekRange_;
  384.     }
  386.     if (currentTime < seekStart) {
  387.       // The seek range has moved past the playhead.  Move ahead to catch up.
  388.       const targetTime = this.reposition_(currentTime);
  389.       shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  390.                      ' seconds to catch up with the seek range.');
  391.       this.mediaElement_.currentTime = targetTime;
  392.     }
  393.   }
  395.   /**
  396.    * Called when the video element has started up and is listening for new seeks
  397.    *
  398.    * @param {number} startTime
  399.    * @private
  400.    */
  401.   onStarted_(startTime) {
  402.     this.gapController_.onStarted(startTime);
  403.   }
  405.   /**
  406.    * Handles when a seek happens on the video.
  407.    *
  408.    * @private
  409.    */
  410.   onSeeking_() {
  411.     this.gapController_.onSeeking();
  412.     const currentTime = this.videoWrapper_.getTime();
  413.     const targetTime = this.reposition_(currentTime);
  415.     const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  416.     if (Math.abs(targetTime - currentTime) > gapLimit) {
  417.       let canCorrectiveSeek = false;
  418.       if (shaka.util.Platform.isSeekingSlow()) {
  419.         // You can only seek like this every so often. This is to prevent an
  420.         // infinite loop on systems where changing currentTime takes a
  421.         // significant amount of time (e.g. Chromecast).
  422.         const time = Date.now() / 1000;
  423.         const seekDelay = shaka.util.Platform.isFuchsiaCastDevice() ? 3 : 1;
  424.         if (!this.lastCorrectiveSeek_ ||
  425.             this.lastCorrectiveSeek_ < time - seekDelay) {
  426.           this.lastCorrectiveSeek_ = time;
  427.           canCorrectiveSeek = true;
  428.         }
  429.       } else {
  430.         canCorrectiveSeek = true;
  431.       }
  432.       if (canCorrectiveSeek) {
  433.         this.videoWrapper_.setTime(targetTime);
  434.         return;
  435.       }
  436.     }
  438.     shaka.log.v1('Seek to ' + currentTime);
  439.     this.onSeek_();
  440.   }
  442.   /**
  443.    * Clamp seek times and playback start times so that we never seek to the
  444.    * presentation duration.  Seeking to or starting at duration does not work
  445.    * consistently across browsers.
  446.    *
  447.    * @see https://github.com/shaka-project/shaka-player/issues/979
  448.    * @param {number} time
  449.    * @return {number} The adjusted seek time.
  450.    * @private
  451.    */
  452.   clampSeekToDuration_(time) {
  453.     const duration = this.timeline_.getDuration();
  454.     if (time >= duration) {
  455.       goog.asserts.assert(this.config_.durationBackoff >= 0,
  456.           'Duration backoff must be non-negative!');
  457.       return duration - this.config_.durationBackoff;
  458.     }
  459.     return time;
  460.   }
  462.   /**
  463.    * Computes a new playhead position that's within the presentation timeline.
  464.    *
  465.    * @param {number} currentTime
  466.    * @return {number} The time to reposition the playhead to.
  467.    * @private
  468.    */
  469.   reposition_(currentTime) {
  470.     goog.asserts.assert(
  471.         this.config_,
  472.         'Cannot reposition playhead when it has beeen destroyed');
  474.     /** @type {function(number)} */
  475.     const isBuffered = (playheadTime) => shaka.media.TimeRangesUtils.isBuffered(
  476.         this.mediaElement_.buffered, playheadTime);
  478.     const rebufferingGoal = Math.max(
  479.         this.minBufferTime_,
  480.         this.config_.rebufferingGoal);
  482.     const safeSeekOffset = this.config_.safeSeekOffset;
  484.     let start = this.timeline_.getSeekRangeStart();
  485.     const end = this.timeline_.getSeekRangeEnd();
  486.     const duration = this.timeline_.getDuration();
  488.     if (end - start < this.minSeekRange_) {
  489.       start = end - this.minSeekRange_;
  490.     }
  492.     // With live content, the beginning of the availability window is moving
  493.     // forward.  This means we cannot seek to it since we will "fall" outside
  494.     // the window while we buffer.  So we define a "safe" region that is far
  495.     // enough away.  For VOD, |safe == start|.
  496.     const safe = this.timeline_.getSafeSeekRangeStart(rebufferingGoal);
  498.     // These are the times to seek to rather than the exact destinations.  When
  499.     // we seek, we will get another event (after a slight delay) and these steps
  500.     // will run again.  So if we seeked directly to |start|, |start| would move
  501.     // on the next call and we would loop forever.
  502.     const seekStart = this.timeline_.getSafeSeekRangeStart(safeSeekOffset);
  503.     const seekSafe = this.timeline_.getSafeSeekRangeStart(
  504.         rebufferingGoal + safeSeekOffset);
  506.     if (currentTime >= duration) {
  507.       shaka.log.v1('Playhead past duration.');
  508.       return this.clampSeekToDuration_(currentTime);
  509.     }
  511.     if (currentTime > end) {
  512.       shaka.log.v1('Playhead past end.');
  513.       // We remove the safeSeekEndOffset of the seek end to avoid the player
  514.       // to be block at the edge in a live stream
  515.       return end - this.config_.safeSeekEndOffset;
  516.     }
  518.     if (currentTime < start) {
  519.       if (isBuffered(seekStart)) {
  520.         shaka.log.v1('Playhead before start & start is buffered');
  521.         return seekStart;
  522.       } else {
  523.         shaka.log.v1('Playhead before start & start is unbuffered');
  524.         return seekSafe;
  525.       }
  526.     }
  528.     if (currentTime >= safe || isBuffered(currentTime)) {
  529.       shaka.log.v1('Playhead in safe region or in buffered region.');
  530.       return currentTime;
  531.     } else {
  532.       shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  533.       return seekSafe;
  534.     }
  535.   }
  537.   /**
  538.    * Clamps the given time to the seek range.
  539.    *
  540.    * @param {number} time The time in seconds.
  541.    * @return {number} The clamped time in seconds.
  542.    * @private
  543.    */
  544.   clampTime_(time) {
  545.     const start = this.timeline_.getSeekRangeStart();
  546.     if (time < start) {
  547.       return start;
  548.     }
  550.     const end = this.timeline_.getSeekRangeEnd();
  551.     if (time > end) {
  552.       return end;
  553.     }
  555.     return time;
  556.   }
  557. };