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