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 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() {}
  78. };
  81. /**
  82.  * A playhead implementation that only relies on the media element.
  83.  *
  84.  * @implements {shaka.media.Playhead}
  85.  * @final
  86.  */
  87. shaka.media.SrcEqualsPlayhead = class {
  88.   /**
  89.    * @param {!HTMLMediaElement} mediaElement
  90.    */
  91.   constructor(mediaElement) {
  92.     /** @private {HTMLMediaElement} */
  93.     this.mediaElement_ = mediaElement;
  94.     /** @private {boolean} */
  95.     this.started_ = false;
  96.     /** @private {?number} */
  97.     this.startTime_ = null;
  99.     /** @private {shaka.util.EventManager} */
  100.     this.eventManager_ = new shaka.util.EventManager();
  101.   }
  103.   /** @override */
  104.   ready() {
  105.     goog.asserts.assert(
  106.         this.mediaElement_ != null,
  107.         'Playhead should not be released before calling ready()',
  108.     );
  110.     // We listen for the loaded-data-event so that we know when we can
  111.     // interact with |currentTime|.
  112.     const onLoaded = () => {
  113.       if (this.startTime_ == null || this.startTime_ == 0) {
  114.         this.started_ = true;
  115.       } else {
  116.         // Startup is complete only when the video element acknowledges the
  117.         // seek.
  118.         this.eventManager_.listenOnce(this.mediaElement_, 'seeking', () => {
  119.           this.started_ = true;
  120.         });
  122.         const currentTime = this.mediaElement_.currentTime;
  123.         // Using the currentTime allows using a negative number in Live HLS
  124.         const newTime = Math.max(0, currentTime + this.startTime_);
  125.         this.mediaElement_.currentTime = newTime;
  126.       }
  127.     };
  129.     shaka.util.MediaReadyState.waitForReadyState(this.mediaElement_,
  130.         HTMLMediaElement.HAVE_CURRENT_DATA,
  131.         this.eventManager_, () => {
  132.           onLoaded();
  133.         });
  134.   }
  136.   /** @override */
  137.   release() {
  138.     if (this.eventManager_) {
  139.       this.eventManager_.release();
  140.       this.eventManager_ = null;
  141.     }
  143.     this.mediaElement_ = null;
  144.   }
  146.   /** @override */
  147.   setStartTime(startTime) {
  148.     // If we have already started playback, ignore updates to the start time.
  149.     // This is just to make things consistent.
  150.     this.startTime_ = this.started_ ? this.startTime_ : startTime;
  151.   }
  153.   /** @override */
  154.   getTime() {
  155.     // If we have not started playback yet, return the start time. However once
  156.     // we start playback we assume that we can always return the current time.
  157.     const time = this.started_ ?
  158.                  this.mediaElement_.currentTime :
  159.                  this.startTime_;
  161.     // In the case that we have not started playback, but the start time was
  162.     // never set, we don't know what the start time should be. To ensure we
  163.     // always return a number, we will default back to 0.
  164.     return time || 0;
  165.   }
  167.   /** @override */
  168.   getStallsDetected() {
  169.     return 0;
  170.   }
  172.   /** @override */
  173.   getGapsJumped() {
  174.     return 0;
  175.   }
  177.   /** @override */
  178.   notifyOfBufferingChange() {}
  179. };
  182. /**
  183.  * A playhead implementation that relies on the media element and a manifest.
  184.  * When provided with a manifest, we can provide more accurate control than
  185.  * the SrcEqualsPlayhead.
  186.  *
  187.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  188.  *       for, and conditions on timestamp adjustment.
  189.  *
  190.  * @implements {shaka.media.Playhead}
  191.  * @final
  192.  */
  193. shaka.media.MediaSourcePlayhead = class {
  194.   /**
  195.    * @param {!HTMLMediaElement} mediaElement
  196.    * @param {shaka.extern.Manifest} manifest
  197.    * @param {shaka.extern.StreamingConfiguration} config
  198.    * @param {?number} startTime
  199.    *     The playhead's initial position in seconds. If null, defaults to the
  200.    *     start of the presentation for VOD and the live-edge for live.
  201.    * @param {function()} onSeek
  202.    *     Called when the user agent seeks to a time within the presentation
  203.    *     timeline.
  204.    * @param {function(!Event)} onEvent
  205.    *     Called when an event is raised to be sent to the application.
  206.    */
  207.   constructor(mediaElement, manifest, config, startTime, onSeek, onEvent) {
  208.     /**
  209.      * The seek range must be at least this number of seconds long. If it is
  210.      * smaller than this, change it to be this big so we don't repeatedly seek
  211.      * to keep within a zero-width window.
  212.      *
  213.      * This is 3s long, to account for the weaker hardware on platforms like
  214.      * Chromecast.
  215.      *
  216.      * @private {number}
  217.      */
  218.     this.minSeekRange_ = 3.0;
  220.     /** @private {HTMLMediaElement} */
  221.     this.mediaElement_ = mediaElement;
  223.     /** @private {shaka.media.PresentationTimeline} */
  224.     this.timeline_ = manifest.presentationTimeline;
  226.     /** @private {number} */
  227.     this.minBufferTime_ = manifest.minBufferTime || 0;
  229.     /** @private {?shaka.extern.StreamingConfiguration} */
  230.     this.config_ = config;
  232.     /** @private {function()} */
  233.     this.onSeek_ = onSeek;
  235.     /** @private {?number} */
  236.     this.lastCorrectiveSeek_ = null;
  238.     /** @private {shaka.media.StallDetector} */
  239.     this.stallDetector_ =
  240.         this.createStallDetector_(mediaElement, config, onEvent);
  242.     /** @private {shaka.media.GapJumpingController} */
  243.     this.gapController_ = new shaka.media.GapJumpingController(
  244.         mediaElement,
  245.         manifest.presentationTimeline,
  246.         config,
  247.         this.stallDetector_,
  248.         onEvent);
  250.     /** @private {shaka.media.VideoWrapper} */
  251.     this.videoWrapper_ = new shaka.media.VideoWrapper(
  252.         mediaElement,
  253.         () => this.onSeeking_(),
  254.         (realStartTime) => this.onStarted_(realStartTime),
  255.         () => this.getStartTime_(startTime));
  257.     /** @type {shaka.util.Timer} */
  258.     this.checkWindowTimer_ = new shaka.util.Timer(() => {
  259.       this.onPollWindow_();
  260.     });
  261.   }
  263.   /** @override */
  264.   ready() {
  265.     this.checkWindowTimer_.tickEvery(/* seconds= */ 0.25);
  266.   }
  268.   /** @override */
  269.   release() {
  270.     if (this.videoWrapper_) {
  271.       this.videoWrapper_.release();
  272.       this.videoWrapper_ = null;
  273.     }
  275.     if (this.gapController_) {
  276.       this.gapController_.release();
  277.       this.gapController_= null;
  278.     }
  280.     if (this.checkWindowTimer_) {
  281.       this.checkWindowTimer_.stop();
  282.       this.checkWindowTimer_ = null;
  283.     }
  285.     this.config_ = null;
  286.     this.timeline_ = null;
  287.     this.videoWrapper_ = null;
  288.     this.mediaElement_ = null;
  290.     this.onSeek_ = () => {};
  291.   }
  293.   /** @override */
  294.   setStartTime(startTime) {
  295.     this.videoWrapper_.setTime(startTime);
  296.   }
  298.   /** @override */
  299.   getTime() {
  300.     const time = this.videoWrapper_.getTime();
  302.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  303.     // ensure timing issues don't cause us to return a time outside the segment
  304.     // availability window.  E.g., the user agent seeks and calls this function
  305.     // before we receive the 'seeking' event.
  306.     //
  307.     // We don't buffer when the livestream video is paused and the playhead time
  308.     // is out of the seek range; thus, we do not clamp the current time when the
  309.     // video is paused.
  310.     // https://github.com/shaka-project/shaka-player/issues/1121
  311.     if (this.mediaElement_.readyState > 0 && !this.mediaElement_.paused) {
  312.       return this.clampTime_(time);
  313.     }
  315.     return time;
  316.   }
  318.   /** @override */
  319.   getStallsDetected() {
  320.     return this.stallDetector_ ? this.stallDetector_.getStallsDetected() : 0;
  321.   }
  323.   /** @override */
  324.   getGapsJumped() {
  325.     return this.gapController_.getGapsJumped();
  326.   }
  328.   /**
  329.    * Gets the playhead's initial position in seconds.
  330.    *
  331.    * @param {?number} startTime
  332.    * @return {number}
  333.    * @private
  334.    */
  335.   getStartTime_(startTime) {
  336.     if (startTime == null) {
  337.       if (this.timeline_.getDuration() < Infinity) {
  338.         // If the presentation is VOD, or if the presentation is live but has
  339.         // finished broadcasting, then start from the beginning.
  340.         startTime = this.timeline_.getSeekRangeStart();
  341.       } else {
  342.         // Otherwise, start near the live-edge.
  343.         startTime = this.timeline_.getSeekRangeEnd();
  344.       }
  345.     } else if (startTime < 0) {
  346.       // For live streams, if the startTime is negative, start from a certain
  347.       // offset time from the live edge.  If the offset from the live edge is
  348.       // not available, start from the current available segment start point
  349.       // instead, handled by clampTime_().
  350.       startTime = this.timeline_.getSeekRangeEnd() + startTime;
  351.     }
  353.     return this.clampSeekToDuration_(this.clampTime_(startTime));
  354.   }
  356.   /** @override */
  357.   notifyOfBufferingChange() {
  358.     this.gapController_.onSegmentAppended();
  359.   }
  361.   /**
  362.    * Called on a recurring timer to keep the playhead from falling outside the
  363.    * availability window.
  364.    *
  365.    * @private
  366.    */
  367.   onPollWindow_() {
  368.     // Don't catch up to the seek range when we are paused or empty.
  369.     // The definition of "seeking" says that we are seeking until the buffered
  370.     // data intersects with the playhead.  If we fall outside of the seek range,
  371.     // it doesn't matter if we are in a "seeking" state.  We can and should go
  372.     // ahead and catch up while seeking.
  373.     if (this.mediaElement_.readyState == 0 || this.mediaElement_.paused) {
  374.       return;
  375.     }
  377.     const currentTime = this.videoWrapper_.getTime();
  378.     let seekStart = this.timeline_.getSeekRangeStart();
  379.     const seekEnd = this.timeline_.getSeekRangeEnd();
  381.     if (seekEnd - seekStart < this.minSeekRange_) {
  382.       seekStart = seekEnd - this.minSeekRange_;
  383.     }
  385.     if (currentTime < seekStart) {
  386.       // The seek range has moved past the playhead.  Move ahead to catch up.
  387.       const targetTime = this.reposition_(currentTime);
  388.       shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  389.                      ' seconds to catch up with the seek range.');
  390.       this.mediaElement_.currentTime = targetTime;
  391.     }
  392.   }
  394.   /**
  395.    * Called when the video element has started up and is listening for new seeks
  396.    *
  397.    * @param {number} startTime
  398.    * @private
  399.    */
  400.   onStarted_(startTime) {
  401.     this.gapController_.onStarted(startTime);
  402.   }
  404.   /**
  405.    * Handles when a seek happens on the video.
  406.    *
  407.    * @private
  408.    */
  409.   onSeeking_() {
  410.     this.gapController_.onSeeking();
  411.     const currentTime = this.videoWrapper_.getTime();
  412.     const targetTime = this.reposition_(currentTime);
  414.     const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  415.     if (Math.abs(targetTime - currentTime) > gapLimit) {
  416.       // You can only seek like this every so often. This is to prevent an
  417.       // infinite loop on systems where changing currentTime takes a significant
  418.       // amount of time (e.g. Chromecast).
  419.       const time = Date.now() / 1000;
  420.       if (!this.lastCorrectiveSeek_ || this.lastCorrectiveSeek_ < time - 1) {
  421.         this.lastCorrectiveSeek_ = time;
  422.         this.videoWrapper_.setTime(targetTime);
  423.         return;
  424.       }
  425.     }
  427.     shaka.log.v1('Seek to ' + currentTime);
  428.     this.onSeek_();
  429.   }
  431.   /**
  432.    * Clamp seek times and playback start times so that we never seek to the
  433.    * presentation duration.  Seeking to or starting at duration does not work
  434.    * consistently across browsers.
  435.    *
  436.    * @see https://github.com/shaka-project/shaka-player/issues/979
  437.    * @param {number} time
  438.    * @return {number} The adjusted seek time.
  439.    * @private
  440.    */
  441.   clampSeekToDuration_(time) {
  442.     const duration = this.timeline_.getDuration();
  443.     if (time >= duration) {
  444.       goog.asserts.assert(this.config_.durationBackoff >= 0,
  445.           'Duration backoff must be non-negative!');
  446.       return duration - this.config_.durationBackoff;
  447.     }
  448.     return time;
  449.   }
  451.   /**
  452.    * Computes a new playhead position that's within the presentation timeline.
  453.    *
  454.    * @param {number} currentTime
  455.    * @return {number} The time to reposition the playhead to.
  456.    * @private
  457.    */
  458.   reposition_(currentTime) {
  459.     goog.asserts.assert(
  460.         this.config_,
  461.         'Cannot reposition playhead when it has beeen destroyed');
  463.     /** @type {function(number)} */
  464.     const isBuffered = (playheadTime) => shaka.media.TimeRangesUtils.isBuffered(
  465.         this.mediaElement_.buffered, playheadTime);
  467.     const rebufferingGoal = Math.max(
  468.         this.minBufferTime_,
  469.         this.config_.rebufferingGoal);
  471.     const safeSeekOffset = this.config_.safeSeekOffset;
  473.     let start = this.timeline_.getSeekRangeStart();
  474.     const end = this.timeline_.getSeekRangeEnd();
  475.     const duration = this.timeline_.getDuration();
  477.     if (end - start < this.minSeekRange_) {
  478.       start = end - this.minSeekRange_;
  479.     }
  481.     // With live content, the beginning of the availability window is moving
  482.     // forward.  This means we cannot seek to it since we will "fall" outside
  483.     // the window while we buffer.  So we define a "safe" region that is far
  484.     // enough away.  For VOD, |safe == start|.
  485.     const safe = this.timeline_.getSafeSeekRangeStart(rebufferingGoal);
  487.     // These are the times to seek to rather than the exact destinations.  When
  488.     // we seek, we will get another event (after a slight delay) and these steps
  489.     // will run again.  So if we seeked directly to |start|, |start| would move
  490.     // on the next call and we would loop forever.
  491.     const seekStart = this.timeline_.getSafeSeekRangeStart(safeSeekOffset);
  492.     const seekSafe = this.timeline_.getSafeSeekRangeStart(
  493.         rebufferingGoal + safeSeekOffset);
  495.     if (currentTime >= duration) {
  496.       shaka.log.v1('Playhead past duration.');
  497.       return this.clampSeekToDuration_(currentTime);
  498.     }
  500.     if (currentTime > end) {
  501.       shaka.log.v1('Playhead past end.');
  502.       return end;
  503.     }
  505.     if (currentTime < start) {
  506.       if (isBuffered(seekStart)) {
  507.         shaka.log.v1('Playhead before start & start is buffered');
  508.         return seekStart;
  509.       } else {
  510.         shaka.log.v1('Playhead before start & start is unbuffered');
  511.         return seekSafe;
  512.       }
  513.     }
  515.     if (currentTime >= safe || isBuffered(currentTime)) {
  516.       shaka.log.v1('Playhead in safe region or in buffered region.');
  517.       return currentTime;
  518.     } else {
  519.       shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  520.       return seekSafe;
  521.     }
  522.   }
  524.   /**
  525.    * Clamps the given time to the seek range.
  526.    *
  527.    * @param {number} time The time in seconds.
  528.    * @return {number} The clamped time in seconds.
  529.    * @private
  530.    */
  531.   clampTime_(time) {
  532.     const start = this.timeline_.getSeekRangeStart();
  533.     if (time < start) {
  534.       return start;
  535.     }
  537.     const end = this.timeline_.getSeekRangeEnd();
  538.     if (time > end) {
  539.       return end;
  540.     }
  542.     return time;
  543.   }
  545.   /**
  546.    * Create and configure a stall detector using the player's streaming
  547.    * configuration settings. If the player is configured to have no stall
  548.    * detector, this will return |null|.
  549.    *
  550.    * @param {!HTMLMediaElement} mediaElement
  551.    * @param {shaka.extern.StreamingConfiguration} config
  552.    * @param {function(!Event)} onEvent
  553.    *     Called when an event is raised to be sent to the application.
  554.    * @return {shaka.media.StallDetector}
  555.    * @private
  556.    */
  557.   createStallDetector_(mediaElement, config, onEvent) {
  558.     if (!config.stallEnabled) {
  559.       return null;
  560.     }
  562.     // Cache the values from the config so that changes to the config won't
  563.     // change the initialized behaviour.
  564.     const threshold = config.stallThreshold;
  565.     const skip = config.stallSkip;
  567.     // When we see a stall, we will try to "jump-start" playback by moving the
  568.     // playhead forward.
  569.     const detector = new shaka.media.StallDetector(
  570.         new shaka.media.StallDetector.MediaElementImplementation(mediaElement),
  571.         threshold, onEvent);
  573.     detector.onStall((at, duration) => {
  574.       shaka.log.debug(`Stall detected at ${at} for ${duration} seconds.`);
  576.       if (skip) {
  577.         shaka.log.debug(`Seeking forward ${skip} seconds to break stall.`);
  578.         mediaElement.currentTime += skip;
  579.       } else {
  580.         shaka.log.debug('Pausing and unpausing to break stall.');
  581.         mediaElement.pause();
  582.         mediaElement.play();
  583.       }
  584.     });
  586.     return detector;
  587.   }
  588. };