Source: lib/media/playhead_observer.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.PlayheadObserver');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.media.TimeRangesUtils');
  22. goog.require('shaka.util.ConfigUtils');
  23. goog.require('shaka.util.EventManager');
  24. goog.require('shaka.util.FakeEvent');
  25. goog.require('shaka.util.IDestroyable');
  26. goog.require('shaka.util.StreamUtils');
  30. /**
  31.  * This observes the current playhead position to raise events.  This will only
  32.  * observe the playhead, {@link shaka.media.Playhead} will modify it. This will:
  33.  * <ul>
  34.  *   <li>Track buffering state and call |onBuffering|.</li>
  35.  *   <li>Track current Period and call |onChangePeriod|.</li>
  36.  *   <li>Track timeline regions and raise respective events.</li>
  37.  * </ul>
  38.  *
  39.  * @param {HTMLMediaElement} video
  40.  * @param {MediaSource} mediaSource
  41.  * @param {shakaExtern.Manifest} manifest
  42.  * @param {shakaExtern.StreamingConfiguration} config
  43.  * @param {function(boolean)} onBuffering Called and passed true when stopped
  44.  *   for buffering; called and passed false when proceeding after buffering.
  45.  *   If passed true, the callback should not set the video's playback rate.
  46.  * @param {function(!Event)} onEvent Called when an event is raised to be sent
  47.  *   to the application.
  48.  * @param {function()} onChangePeriod Called when the playhead moves to a
  49.  *   different Period.
  50.  *
  51.  * @constructor
  52.  * @struct
  53.  * @implements {shaka.util.IDestroyable}
  54.  */
  55. shaka.media.PlayheadObserver = function(
  56.     video, mediaSource, manifest, config, onBuffering, onEvent,
  57.     onChangePeriod) {
  58.   /** @private {HTMLMediaElement} */
  59.   this.video_ = video;
  61.   /** @private {MediaSource} */
  62.   this.mediaSource_ = mediaSource;
  64.   /** @private {?shakaExtern.Manifest} */
  65.   this.manifest_ = manifest;
  67.   /** @private {?shakaExtern.StreamingConfiguration} */
  68.   this.config_ = config;
  70.   /** @private {?function(boolean)} */
  71.   this.onBuffering_ = onBuffering;
  73.   /** @private {?function(!Event)} */
  74.   this.onEvent_ = onEvent;
  76.   /** @private {?function()} */
  77.   this.onChangePeriod_ = onChangePeriod;
  79.   /** @private {!Array.<shaka.media.PlayheadObserver.TimelineRegion>} */
  80.   this.timelineRegions_ = [];
  82.   /** @private {shaka.util.EventManager} */
  83.   this.eventManager_ = new shaka.util.EventManager();
  85.   /** @private {boolean} */
  86.   this.buffering_ = false;
  88.   /** @private {number} */
  89.   this.curPeriodIndex_ = -1;
  91.   /** @private {?number} */
  92.   this.watchdogTimer_ = null;
  95.   this.startWatchdogTimer_();
  96. };
  99. /**
  100.  * The threshold for underflow, in seconds.  If there is less than this amount
  101.  * of data buffered, we will consider the player to be out of data.
  102.  *
  103.  * @private {number}
  104.  * @const
  105.  */
  106. shaka.media.PlayheadObserver.UNDERFLOW_THRESHOLD_ = 0.5;
  109. /**
  110.  * @enum {number}
  111.  * @private
  112.  */
  113. shaka.media.PlayheadObserver.RegionLocation_ = {
  114.   FUTURE_REGION: 1,
  115.   INSIDE: 2,
  116.   PAST_REGION: 3
  117. };
  120. /**
  121.  * @typedef {{
  122.  *   info: shakaExtern.TimelineRegionInfo,
  123.  *   status: shaka.media.PlayheadObserver.RegionLocation_
  124.  * }}
  125.  *
  126.  * @property {shakaExtern.TimelineRegionInfo} info
  127.  *   The info for this timeline region.
  128.  * @property {shaka.media.PlayheadObserver.RegionLocation_} status
  129.  *   This tracks where the region is relative to the playhead. This tracks
  130.  *   whether we are before or after the region so we can raise events if we pass
  131.  *   it.
  132.  */
  133. shaka.media.PlayheadObserver.TimelineRegion;
  136. /** @override */
  137. shaka.media.PlayheadObserver.prototype.destroy = function() {
  138.   var p = this.eventManager_ ? this.eventManager_.destroy() : Promise.resolve();
  140.   this.eventManager_ = null;
  141.   this.cancelWatchdogTimer_();
  143.   this.video_ = null;
  144.   this.mediaSource_ = null;
  145.   this.manifest_ = null;
  146.   this.config_ = null;
  147.   this.onBuffering_ = null;
  148.   this.onEvent_ = null;
  149.   this.onChangePeriod_ = null;
  150.   this.timelineRegions_ = [];
  152.   return p;
  153. };
  156. /** Called when a seek completes. */
  157. shaka.media.PlayheadObserver.prototype.seeked = function() {
  158.   this.timelineRegions_.forEach(
  159.       this.updateTimelineRegion_.bind(this, /* isSeek */ true));
  160. };
  163. /**
  164.  * Adds a new timeline region.  Events will be raised whenever the playhead
  165.  * enters or exits the given region.  This method will raise a
  166.  * 'timelineregionadded' event.
  167.  * @param {shakaExtern.TimelineRegionInfo} regionInfo
  168.  */
  169. shaka.media.PlayheadObserver.prototype.addTimelineRegion = function(
  170.     regionInfo) {
  171.   // Check there isn't an existing event with the same scheme ID and time range.
  172.   // This ensures that the manifest parser doesn't need to also track which
  173.   // events have already been added.
  174.   var hasExistingRegion = this.timelineRegions_.some(function(existing) {
  175.     return existing.info.schemeIdUri == regionInfo.schemeIdUri &&
  176.         existing.info.startTime == regionInfo.startTime &&
  177.         existing.info.endTime == regionInfo.endTime;
  178.   });
  179.   if (hasExistingRegion) return;
  181.   var region = {
  182.     info: regionInfo,
  183.     status: shaka.media.PlayheadObserver.RegionLocation_.FUTURE_REGION
  184.   };
  185.   this.timelineRegions_.push(region);
  187.   var cloneTimelineInfo_ = shaka.media.PlayheadObserver.cloneTimelineInfo_;
  188.   var event = new shaka.util.FakeEvent(
  189.       'timelineregionadded', {detail: cloneTimelineInfo_(regionInfo)});
  190.   this.onEvent_(event);
  192.   // Pretend this is a seek so it will ignore if it should be PAST_REGION but
  193.   // still fire an event if it should be INSIDE.
  194.   this.updateTimelineRegion_(/* isSeek */ true, region);
  195. };
  198. /**
  199.  * Clones the given TimelineRegionInfo so the app can modify it without
  200.  * modifying our internal objects.
  201.  * @param {shakaExtern.TimelineRegionInfo} source
  202.  * @return {shakaExtern.TimelineRegionInfo}
  203.  * @private
  204.  */
  205. shaka.media.PlayheadObserver.cloneTimelineInfo_ = function(source) {
  206.   var copy = shaka.util.ConfigUtils.cloneObject(source);
  207.   // cloneObject uses JSON to clone, which won't copy the DOM element.
  208.   copy.eventElement = source.eventElement;
  209.   return copy;
  210. };
  213. /**
  214.  * Updates the status of a timeline region and fires any enter/exit events.
  215.  * @param {boolean} isSeek
  216.  * @param {shaka.media.PlayheadObserver.TimelineRegion} region
  217.  * @private
  218.  */
  219. shaka.media.PlayheadObserver.prototype.updateTimelineRegion_ = function(
  220.     isSeek, region) {
  221.   var RegionLocation = shaka.media.PlayheadObserver.RegionLocation_;
  222.   var cloneTimelineInfo_ = shaka.media.PlayheadObserver.cloneTimelineInfo_;
  224.   // The events are fired when the playhead enters a region.  We fire both
  225.   // events when passing over a region and not seeking since the playhead was
  226.   // in the region but left before we saw it.  We don't fire both when seeking
  227.   // since the playhead was never in the region.
  228.   //
  229.   // |--------------------------------------|
  230.   // | From \ To |  FUTURE | INSIDE | PAST  |
  231.   // |   FUTURE  |         |  enter | both* |
  232.   // |   INSIDE  |   exit  |        | exit  |
  233.   // |    PAST   |   both* |  enter |       |
  234.   // |--------------------------------------|
  235.   // * Only when not seeking.
  236.   var newStatus = region.info.startTime > this.video_.currentTime ?
  237.       RegionLocation.FUTURE_REGION :
  238.       (region.info.endTime < this.video_.currentTime ?
  239.            RegionLocation.PAST_REGION :
  240.            RegionLocation.INSIDE);
  241.   var wasInside = region.status == RegionLocation.INSIDE;
  242.   var isInside = newStatus == RegionLocation.INSIDE;
  244.   if (newStatus != region.status) {
  245.     var passedRegion = !wasInside && !isInside;
  246.     if (!(isSeek && passedRegion)) {
  247.       if (!wasInside) {
  248.         this.onEvent_(new shaka.util.FakeEvent(
  249.             'timelineregionenter',
  250.             {'detail': cloneTimelineInfo_(region.info)}));
  251.       }
  252.       if (!isInside) {
  253.         this.onEvent_(new shaka.util.FakeEvent(
  254.             'timelineregionexit', {'detail': cloneTimelineInfo_(region.info)}));
  255.       }
  256.     }
  257.     region.status = newStatus;
  258.   }
  259. };
  262. /**
  263.  * Starts the watchdog timer.
  264.  * @private
  265.  */
  266. shaka.media.PlayheadObserver.prototype.startWatchdogTimer_ = function() {
  267.   this.cancelWatchdogTimer_();
  268.   this.watchdogTimer_ =
  269.       window.setTimeout(this.onWatchdogTimer_.bind(this), 250);
  270. };
  273. /**
  274.  * Cancels the watchdog timer, if any.
  275.  * @private
  276.  */
  277. shaka.media.PlayheadObserver.prototype.cancelWatchdogTimer_ = function() {
  278.   if (this.watchdogTimer_) {
  279.     window.clearTimeout(this.watchdogTimer_);
  280.     this.watchdogTimer_ = null;
  281.   }
  282. };
  285. /**
  286.  * Called on a recurring timer to detect buffering events and Period changes.
  287.  * @private
  288.  */
  289. shaka.media.PlayheadObserver.prototype.onWatchdogTimer_ = function() {
  290.   this.watchdogTimer_ = null;
  291.   this.startWatchdogTimer_();
  293.   goog.asserts.assert(this.manifest_ && this.config_, 'Must not be destroyed');
  294.   var newPeriod = shaka.util.StreamUtils.findPeriodContainingTime(
  295.       this.manifest_, this.video_.currentTime);
  296.   if (newPeriod != this.curPeriodIndex_) {
  297.     // Ignore seek to start time, the first 'trackschanged' event is handled
  298.     // during player.load().
  299.     if (this.curPeriodIndex_ != -1)
  300.       this.onChangePeriod_();
  301.     this.curPeriodIndex_ = newPeriod;
  302.   }
  304.   // This uses an intersection of buffered ranges for both audio and video, so
  305.   // it's an accurate way to determine if we are buffering or not.
  306.   var bufferedAhead = shaka.media.TimeRangesUtils.bufferedAheadOf(
  307.       this.video_.buffered, this.video_.currentTime);
  308.   var bufferEnd = shaka.media.TimeRangesUtils.bufferEnd(this.video_.buffered);
  309.   var threshold = shaka.media.PlayheadObserver.UNDERFLOW_THRESHOLD_;
  311.   var timeline = this.manifest_.presentationTimeline;
  312.   var liveEdge = timeline.getSegmentAvailabilityEnd();
  313.   var bufferedToLiveEdge = timeline.isLive() && bufferEnd >= liveEdge;
  314.   var noMoreSegments = this.mediaSource_.readyState == 'ended';
  316.   var atEnd = bufferedToLiveEdge || this.video_.ended || noMoreSegments;
  317.   if (!this.buffering_) {
  318.     // If there are no buffered ranges but the playhead is at the end of
  319.     // the video then we shouldn't enter a buffering state.
  320.     if (!atEnd && bufferedAhead < threshold) {
  321.       this.setBuffering_(true);
  322.     }
  323.   } else {
  324.     var rebufferingGoal = shaka.util.StreamUtils.getRebufferingGoal(
  325.         this.manifest_, this.config_, 1 /* scaleFactor */);
  326.     if (atEnd || bufferedAhead >= rebufferingGoal) {
  327.       this.setBuffering_(false);
  328.     }
  329.   }
  331.   this.timelineRegions_.forEach(
  332.       this.updateTimelineRegion_.bind(this, /* isSeek */ false));
  333. };
  336. /**
  337.  * Stops the playhead for buffering, or resumes the playhead after buffering.
  338.  *
  339.  * @param {boolean} buffering True to stop the playhead; false to allow it to
  340.  *   continue.
  341.  * @private
  342.  */
  343. shaka.media.PlayheadObserver.prototype.setBuffering_ = function(buffering) {
  344.   if (buffering != this.buffering_) {
  345.     this.buffering_ = buffering;
  346.     this.onBuffering_(buffering);
  347.   }
  348. };