Source: lib/media/playhead.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.media.Playhead');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.log');
  22. goog.require('shaka.media.GapJumpingController');
  23. goog.require('shaka.media.TimeRangesUtils');
  24. goog.require('shaka.media.VideoWrapper');
  25. goog.require('shaka.util.IDestroyable');
  26. goog.require('shaka.util.StreamUtils');
  27. goog.require('shaka.util.Timer');
  31. /**
  32.  * Creates a Playhead, which manages the video's current time.
  33.  *
  34.  * The Playhead provides mechanisms for setting the presentation's start time,
  35.  * restricting seeking to valid time ranges, and stopping playback for startup
  36.  * and re-buffering.
  37.  *
  38.  * @param {!HTMLMediaElement} video
  39.  * @param {shakaExtern.Manifest} manifest
  40.  * @param {shakaExtern.StreamingConfiguration} config
  41.  * @param {?number} startTime The playhead's initial position in seconds. If
  42.  *   null, defaults to the start of the presentation for VOD and the live-edge
  43.  *   for live.
  44.  * @param {function()} onSeek Called when the user agent seeks to a time within
  45.  *   the presentation timeline.
  46.  * @param {function(!Event)} onEvent Called when an event is raised to be sent
  47.  *   to the application.
  48.  *
  49.  * @constructor
  50.  * @struct
  51.  * @implements {shaka.util.IDestroyable}
  52.  */
  53. shaka.media.Playhead = function(
  54.     video, manifest, config, startTime, onSeek, onEvent) {
  55.   /** @private {HTMLMediaElement} */
  56.   this.video_ = video;
  58.   /** @private {?shakaExtern.Manifest} */
  59.   this.manifest_ = manifest;
  61.   /** @private {?shakaExtern.StreamingConfiguration} */
  62.   this.config_ = config;
  64.   /** @private {?function()} */
  65.   this.onSeek_ = onSeek;
  67.   /** @private {?shaka.util.Timer} */
  68.   this.checkWindowTimer_ = null;
  70.   /** @private {?number} */
  71.   this.lastCorrectiveSeek_;
  73.   /** @private {shaka.media.GapJumpingController} */
  74.   this.gapController_ =
  75.       new shaka.media.GapJumpingController(video, manifest, config, onEvent);
  77.   /** @private {shaka.media.VideoWrapper} */
  78.   this.videoWrapper_ = new shaka.media.VideoWrapper(
  79.       video, this.onSeeking_.bind(this), this.getStartTime_(startTime));
  82.   let poll = this.onPollWindow_ .bind(this);
  83.   this.checkWindowTimer_ = new shaka.util.Timer(poll);
  84.   this.checkWindowTimer_.scheduleRepeated(0.25);
  85. };
  88. /**
  89.  * This is the minimum size (in seconds) that the seek range can be.  If it is
  90.  * smaller than this, change it to be this big so we don't repeatedly seek to
  91.  * keep within a zero-width window.
  92.  * This has been increased to 3s long, to account for the weaker hardware on
  93.  * Chromecasts.
  94.  * @private {number}
  95.  * @const
  96.  */
  97. shaka.media.Playhead.MIN_SEEK_RANGE_ = 3.0;
  100. /** @override */
  101. shaka.media.Playhead.prototype.destroy = function() {
  102.   let p = Promise.all([
  103.     this.videoWrapper_.destroy(),
  104.     this.gapController_.destroy(),
  105.   ]);
  106.   this.videoWrapper_ = null;
  107.   this.gapController_ = null;
  109.   if (this.checkWindowTimer_ != null) {
  110.     this.checkWindowTimer_.cancel();
  111.     this.checkWindowTimer_ = null;
  112.   }
  114.   this.video_ = null;
  115.   this.manifest_ = null;
  116.   this.config_ = null;
  117.   this.onSeek_ = null;
  119.   return p;
  120. };
  123. /**
  124.  * Adjust the start time.  Used by Player to implement the
  125.  * streaming.startAtSegmentBoundary configuration.
  126.  *
  127.  * @param {number} startTime
  128.  */
  129. shaka.media.Playhead.prototype.setStartTime = function(startTime) {
  130.   this.videoWrapper_.setTime(startTime);
  131. };
  134. /**
  135.  * Gets the playhead's current (logical) position.
  136.  *
  137.  * @return {number}
  138.  */
  139. shaka.media.Playhead.prototype.getTime = function() {
  140.   let time = this.videoWrapper_.getTime();
  141.   if (this.video_.readyState > 0) {
  142.     // Although we restrict the video's currentTime elsewhere, clamp it here to
  143.     // ensure timing issues don't cause us to return a time outside the segment
  144.     // availability window.  E.g., the user agent seeks and calls this function
  145.     // before we receive the 'seeking' event.
  146.     //
  147.     // We don't buffer when the livestream video is paused and the playhead time
  148.     // is out of the seek range; thus, we do not clamp the current time when the
  149.     // video is paused.
  150.     // https://github.com/google/shaka-player/issues/1121
  151.     if (!this.video_.paused) {
  152.       time = this.clampTime_(time);
  153.     }
  154.   }
  156.   return time;
  157. };
  160. /**
  161.  * Gets the playhead's initial position in seconds.
  162.  *
  163.  * @param {?number} startTime
  164.  * @return {number}
  165.  * @private
  166.  */
  167. shaka.media.Playhead.prototype.getStartTime_ = function(startTime) {
  168.   let timeline = this.manifest_.presentationTimeline;
  169.   if (startTime == null) {
  170.     if (timeline.getDuration() < Infinity) {
  171.       // If the presentation is VOD, or if the presentation is live but has
  172.       // finished broadcasting, then start from the beginning.
  173.       startTime = timeline.getSeekRangeStart();
  174.     } else {
  175.       // Otherwise, start near the live-edge.
  176.       startTime = timeline.getSeekRangeEnd();
  177.     }
  178.   } else if (startTime < 0) {
  179.     // For live streams, if the startTime is negative, start from a certain
  180.     // offset time from the live edge.  If the offset from the live edge is not
  181.     // available, start from the current available segment start point instead,
  182.     // handled by clampTime_().
  183.     startTime = timeline.getSeekRangeEnd() + startTime;
  184.   }
  185.   return this.clampSeekToDuration_(this.clampTime_(startTime));
  186. };
  189. /**
  190.  * Stops the playhead for buffering, or resumes the playhead after buffering.
  191.  *
  192.  * @param {boolean} buffering True to stop the playhead; false to allow it to
  193.  *   continue.
  194.  */
  195. shaka.media.Playhead.prototype.setBuffering = function(buffering) {
  196.   this.videoWrapper_.setBuffering(buffering);
  197. };
  200. /**
  201.  * Gets the current effective playback rate.  This may be negative even if the
  202.  * browser does not directly support rewinding.
  203.  * @return {number}
  204.  */
  205. shaka.media.Playhead.prototype.getPlaybackRate = function() {
  206.   return this.videoWrapper_.getPlaybackRate();
  207. };
  210. /**
  211.  * Sets the playback rate.
  212.  * @param {number} rate
  213.  */
  214. shaka.media.Playhead.prototype.setPlaybackRate = function(rate) {
  215.   this.videoWrapper_.setPlaybackRate(rate);
  216. };
  219. /**
  220.  * Called when a segment is appended by StreamingEngine, but not when a clear is
  221.  * pending.  This means StreamingEngine will continue buffering forward from
  222.  * what is buffered, so that we know about any gaps before the start.
  223.  */
  224. shaka.media.Playhead.prototype.onSegmentAppended = function() {
  225.   this.gapController_.onSegmentAppended();
  226. };
  229. /**
  230.  * Called on a recurring timer to keep the playhead from falling outside the
  231.  * availability window.
  232.  *
  233.  * @private
  234.  */
  235. shaka.media.Playhead.prototype.onPollWindow_ = function() {
  236.   // Don't catch up to the seek range when we are paused or empty.
  237.   // The definition of "seeking" says that we are seeking until the buffered
  238.   // data intersects with the playhead.  If we fall outside of the seek range,
  239.   // it doesn't matter if we are in a "seeking" state.  We can and should go
  240.   // ahead and catch up while seeking.
  241.   if (this.video_.readyState == 0 || this.video_.paused) {
  242.     return;
  243.   }
  245.   let currentTime = this.video_.currentTime;
  246.   let timeline = this.manifest_.presentationTimeline;
  247.   let seekStart = timeline.getSeekRangeStart();
  248.   let seekEnd = timeline.getSeekRangeEnd();
  250.   const minRange = shaka.media.Playhead.MIN_SEEK_RANGE_;
  251.   if (seekEnd - seekStart < minRange) {
  252.     seekStart = seekEnd - minRange;
  253.   }
  255.   if (currentTime < seekStart) {
  256.     // The seek range has moved past the playhead.  Move ahead to catch up.
  257.     let targetTime = this.reposition_(currentTime);
  258.     shaka.log.info('Jumping forward ' + (targetTime - currentTime) +
  259.                    ' seconds to catch up with the seek range.');
  260.     this.video_.currentTime = targetTime;
  261.   }
  262. };
  265. /**
  266.  * Handles when a seek happens on the video.
  267.  *
  268.  * @private
  269.  */
  270. shaka.media.Playhead.prototype.onSeeking_ = function() {
  271.   this.gapController_.onSeeking();
  272.   let currentTime = this.videoWrapper_.getTime();
  273.   let targetTime = this.reposition_(currentTime);
  275.   const gapLimit = shaka.media.GapJumpingController.BROWSER_GAP_TOLERANCE;
  276.   if (Math.abs(targetTime - currentTime) > gapLimit) {
  277.     // You can only seek like this every so often. This is to prevent an
  278.     // infinite loop on systems where changing currentTime takes a significant
  279.     // amount of time (e.g. Chromecast).
  280.     let time = new Date().getTime() / 1000;
  281.     if (!this.lastCorrectiveSeek_ || this.lastCorrectiveSeek_ < time - 1) {
  282.       this.lastCorrectiveSeek_ = time;
  283.       this.videoWrapper_.setTime(targetTime);
  284.       return;
  285.     }
  286.   }
  288.   shaka.log.v1('Seek to ' + currentTime);
  289.   this.onSeek_();
  290. };
  293. /**
  294.  * Clamp seek times and playback start times so that we never seek to the
  295.  * presentation duration.  Seeking to or starting at duration does not work
  296.  * consistently across browsers.
  297.  *
  298.  * TODO: Clean up and simplify Playhead.  There are too many layers of, methods
  299.  * for, and conditions on timestamp adjustment.
  300.  *
  301.  * @see https://github.com/google/shaka-player/issues/979
  302.  * @param {number} time
  303.  * @return {number} The adjusted seek time.
  304.  * @private
  305.  */
  306. shaka.media.Playhead.prototype.clampSeekToDuration_ = function(time) {
  307.   let timeline = this.manifest_.presentationTimeline;
  308.   let duration = timeline.getDuration();
  309.   if (time >= duration) {
  310.     goog.asserts.assert(this.config_.durationBackoff >= 0,
  311.                         'Duration backoff must be non-negative!');
  312.     return duration - this.config_.durationBackoff;
  313.   }
  314.   return time;
  315. };
  318. /**
  319.  * Computes a new playhead position that's within the presentation timeline.
  320.  *
  321.  * @param {number} currentTime
  322.  * @return {number} The time to reposition the playhead to.
  323.  * @private
  324.  */
  325. shaka.media.Playhead.prototype.reposition_ = function(currentTime) {
  326.   goog.asserts.assert(this.manifest_ && this.config_, 'Must not be destroyed');
  328.   /** @type {function(number)} */
  329.   let isBuffered =
  330.       shaka.media.TimeRangesUtils.isBuffered.bind(null, this.video_.buffered);
  332.   let rebufferingGoal = shaka.util.StreamUtils.getRebufferingGoal(
  333.       this.manifest_, this.config_, 1 /* scaleFactor */);
  335.   let timeline = this.manifest_.presentationTimeline;
  336.   let start = timeline.getSeekRangeStart();
  337.   let end = timeline.getSeekRangeEnd();
  338.   let duration = timeline.getDuration();
  340.   const minRange = shaka.media.Playhead.MIN_SEEK_RANGE_;
  341.   if (end - start < minRange) {
  342.     start = end - minRange;
  343.   }
  345.   // With live content, the beginning of the availability window is moving
  346.   // forward.  This means we cannot seek to it since we will "fall" outside the
  347.   // window while we buffer.  So we define a "safe" region that is far enough
  348.   // away.  For VOD, |safe == start|.
  349.   let safe = timeline.getSafeSeekRangeStart(rebufferingGoal);
  351.   // These are the times to seek to rather than the exact destinations.  When
  352.   // we seek, we will get another event (after a slight delay) and these steps
  353.   // will run again.  So if we seeked directly to |start|, |start| would move
  354.   // on the next call and we would loop forever.
  355.   //
  356.   // Offset by 5 seconds since Chromecast takes a few seconds to start playing
  357.   // after a seek, even when buffered.
  358.   let seekStart = timeline.getSafeSeekRangeStart(5);
  359.   let seekSafe = timeline.getSafeSeekRangeStart(rebufferingGoal + 5);
  362.   if (currentTime >= duration) {
  363.     shaka.log.v1('Playhead past duration.');
  364.     return this.clampSeekToDuration_(currentTime);
  365.   }
  367.   if (currentTime > end) {
  368.     shaka.log.v1('Playhead past end.');
  369.     return end;
  370.   }
  372.   if (currentTime < start) {
  373.     if (isBuffered(seekStart)) {
  374.       shaka.log.v1('Playhead before start & start is buffered');
  375.       return seekStart;
  376.     } else {
  377.       shaka.log.v1('Playhead before start & start is unbuffered');
  378.       return seekSafe;
  379.     }
  380.   }
  382.   if (currentTime >= safe || isBuffered(currentTime)) {
  383.     shaka.log.v1('Playhead in safe region or in buffered region.');
  384.     return currentTime;
  385.   } else {
  386.     shaka.log.v1('Playhead outside safe region & in unbuffered region.');
  387.     return seekSafe;
  388.   }
  389. };
  392. /**
  393.  * Clamps the given time to the seek range.
  394.  *
  395.  * @param {number} time The time in seconds.
  396.  * @return {number} The clamped time in seconds.
  397.  * @private
  398.  */
  399. shaka.media.Playhead.prototype.clampTime_ = function(time) {
  400.   let start = this.manifest_.presentationTimeline.getSeekRangeStart();
  401.   if (time < start) return start;
  403.   let end = this.manifest_.presentationTimeline.getSeekRangeEnd();
  404.   if (time > end) return end;
  406.   return time;
  407. };