Source: lib/media/region_observer.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.media.RegionObserver');
  9. goog.require('shaka.media.IPlayheadObserver');
  10. goog.require('shaka.media.RegionTimeline');
  11. goog.require('shaka.util.EventManager');
  12. goog.require('shaka.util.FakeEvent');
  13. goog.require('shaka.util.FakeEventTarget');
  16. /**
  17.  * The region observer watches a region timeline and playhead, and fires events
  18.  * ('enter', 'exit', 'skip') as the playhead moves.
  19.  *
  20.  * @implements {shaka.media.IPlayheadObserver}
  21.  * @final
  22.  */
  23. shaka.media.RegionObserver = class extends shaka.util.FakeEventTarget {
  24.   /**
  25.    * Create a region observer for the given timeline. The observer does not
  26.    * own the timeline, only uses it. This means that the observer should NOT
  27.    * destroy the timeline.
  28.    *
  29.    * @param {!shaka.media.RegionTimeline} timeline
  30.    * @param {boolean} startsPastZero
  31.    */
  32.   constructor(timeline, startsPastZero) {
  33.     super();
  35.     /** @private {shaka.media.RegionTimeline} */
  36.     this.timeline_ = timeline;
  38.     /**
  39.      * Whether the asset is expected to start at a time beyond 0 seconds.
  40.      * For example, if the asset is a live stream.
  41.      * If true, we will not start polling for regions until the playhead has
  42.      * moved past 0 seconds, to avoid bad behaviors where the current time is
  43.      * briefly 0 before we have enough data to play.
  44.      * @private {boolean}
  45.      */
  46.     this.startsPastZero_ = startsPastZero;
  48.     /**
  49.      * A mapping between a region and where we previously were relative to it.
  50.      * When the value here differs from what we calculate, it means we moved and
  51.      * should fire an event.
  52.      *
  53.      * @private {!Map.<shaka.extern.TimelineRegionInfo,
  54.      *                 shaka.media.RegionObserver.RelativePosition_>}
  55.      */
  56.     this.oldPosition_ = new Map();
  58.     // To make the rules easier to read, alias all the relative positions.
  59.     const RelativePosition = shaka.media.RegionObserver.RelativePosition_;
  60.     const BEFORE_THE_REGION = RelativePosition.BEFORE_THE_REGION;
  61.     const IN_THE_REGION = RelativePosition.IN_THE_REGION;
  62.     const AFTER_THE_REGION = RelativePosition.AFTER_THE_REGION;
  64.     /**
  65.      * A read-only collection of rules for what to do when we change position
  66.      * relative to a region.
  67.      *
  68.      * @private {!Iterable.<shaka.media.RegionObserver.Rule_>}
  69.      */
  70.     this.rules_ = [
  71.       {
  72.         weWere: null,
  73.         weAre: IN_THE_REGION,
  74.         invoke: (region, seeking) => this.onEvent_('enter', region, seeking),
  75.       },
  76.       {
  77.         weWere: BEFORE_THE_REGION,
  78.         weAre: IN_THE_REGION,
  79.         invoke: (region, seeking) => this.onEvent_('enter', region, seeking),
  80.       },
  81.       {
  82.         weWere: AFTER_THE_REGION,
  83.         weAre: IN_THE_REGION,
  84.         invoke: (region, seeking) => this.onEvent_('enter', region, seeking),
  85.       },
  86.       {
  87.         weWere: IN_THE_REGION,
  88.         weAre: BEFORE_THE_REGION,
  89.         invoke: (region, seeking) => this.onEvent_('exit', region, seeking),
  90.       },
  91.       {
  92.         weWere: IN_THE_REGION,
  93.         weAre: AFTER_THE_REGION,
  94.         invoke: (region, seeking) => this.onEvent_('exit', region, seeking),
  95.       },
  96.       {
  97.         weWere: BEFORE_THE_REGION,
  98.         weAre: AFTER_THE_REGION,
  99.         invoke: (region, seeking) => this.onEvent_('skip', region, seeking),
  100.       },
  101.       {
  102.         weWere: AFTER_THE_REGION,
  103.         weAre: BEFORE_THE_REGION,
  104.         invoke: (region, seeking) => this.onEvent_('skip', region, seeking),
  105.       },
  106.     ];
  108.     /** @private {shaka.util.EventManager} */
  109.     this.eventManager_ = new shaka.util.EventManager();
  111.     this.eventManager_.listen(this.timeline_, 'regionremove', (event) => {
  112.       /** @type {shaka.extern.TimelineRegionInfo} */
  113.       const region = event['region'];
  114.       this.oldPosition_.delete(region);
  115.     });
  116.   }
  118.   /** @override */
  119.   release() {
  120.     this.timeline_ = null;
  122.     // Clear our maps so that we are not holding onto any more information than
  123.     // needed.
  124.     this.oldPosition_.clear();
  126.     this.eventManager_.release();
  127.     this.eventManager_ = null;
  129.     super.release();
  130.   }
  132.   /** @override */
  133.   poll(positionInSeconds, wasSeeking) {
  134.     const RegionObserver = shaka.media.RegionObserver;
  135.     if (this.startsPastZero_ && positionInSeconds == 0) {
  136.       // Don't start checking regions until the timeline has begun moving.
  137.       return;
  138.     }
  139.     // Now that we have seen the playhead go past 0, it's okay if it goes
  140.     // back there (e.g. seeking back to the start).
  141.     this.startsPastZero_ = false;
  143.     for (const region of this.timeline_.regions()) {
  144.       const previousPosition = this.oldPosition_.get(region);
  145.       const currentPosition = RegionObserver.determinePositionRelativeTo_(
  146.           region, positionInSeconds);
  148.       // We will only use |previousPosition| and |currentPosition|, so we can
  149.       // update our state now.
  150.       this.oldPosition_.set(region, currentPosition);
  152.       for (const rule of this.rules_) {
  153.         if (rule.weWere == previousPosition && rule.weAre == currentPosition) {
  154.           rule.invoke(region, wasSeeking);
  155.         }
  156.       }
  157.     }
  158.   }
  160.   /**
  161.    * Dispatch events of the given type.  All event types in this class have the
  162.    * same parameters: region and seeking.
  163.    *
  164.    * @param {string} eventType
  165.    * @param {shaka.extern.TimelineRegionInfo} region
  166.    * @param {boolean} seeking
  167.    * @private
  168.    */
  169.   onEvent_(eventType, region, seeking) {
  170.     const event = new shaka.util.FakeEvent(eventType, new Map([
  171.       ['region', region],
  172.       ['seeking', seeking],
  173.     ]));
  174.     this.dispatchEvent(event);
  175.   }
  177.   /**
  178.    * Get the relative position of the playhead to |region| when the playhead is
  179.    * at |seconds|. We treat the region's start and end times as inclusive
  180.    * bounds.
  181.    *
  182.    * @param {shaka.extern.TimelineRegionInfo} region
  183.    * @param {number} seconds
  184.    * @return {shaka.media.RegionObserver.RelativePosition_}
  185.    * @private
  186.    */
  187.   static determinePositionRelativeTo_(region, seconds) {
  188.     const RelativePosition = shaka.media.RegionObserver.RelativePosition_;
  190.     if (seconds < region.startTime) {
  191.       return RelativePosition.BEFORE_THE_REGION;
  192.     }
  194.     if (seconds > region.endTime) {
  195.       return RelativePosition.AFTER_THE_REGION;
  196.     }
  198.     return RelativePosition.IN_THE_REGION;
  199.   }
  200. };
  202. /**
  203.  * An enum of relative positions between the playhead and a region. Each is
  204.  * phrased so that it works in "The playhead is X" where "X" is any value in
  205.  * the enum.
  206.  *
  207.  * @enum {number}
  208.  * @private
  209.  */
  210. shaka.media.RegionObserver.RelativePosition_ = {
  211.   BEFORE_THE_REGION: 1,
  212.   IN_THE_REGION: 2,
  213.   AFTER_THE_REGION: 3,
  214. };
  216. /**
  217.  * All region observer events (onEnter, onExit, and onSkip) will be passed the
  218.  * region that the playhead is interacting with and whether or not the playhead
  219.  * moving is part of a seek event.
  220.  *
  221.  * @typedef {function(shaka.extern.TimelineRegionInfo, boolean)}
  222.  */
  223. shaka.media.RegionObserver.EventListener;
  225. /**
  226.  * @typedef {{
  227.  *    weWere: ?shaka.media.RegionObserver.RelativePosition_,
  228.  *    weAre: ?shaka.media.RegionObserver.RelativePosition_,
  229.  *    invoke: shaka.media.RegionObserver.EventListener
  230.  * }}
  231.  *
  232.  * @private
  233.  */
  234. shaka.media.RegionObserver.Rule_;