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.  * @template T
  22.  * @final
  23.  */
  24. shaka.media.RegionObserver = class extends shaka.util.FakeEventTarget {
  25.   /**
  26.    * Create a region observer for the given timeline. The observer does not
  27.    * own the timeline, only uses it. This means that the observer should NOT
  28.    * destroy the timeline.
  29.    *
  30.    * @param {!shaka.media.RegionTimeline<T>} timeline
  31.    * @param {boolean} startsPastZero
  32.    */
  33.   constructor(timeline, startsPastZero) {
  34.     super();
  36.     /** @private {shaka.media.RegionTimeline<T>} */
  37.     this.timeline_ = timeline;
  39.     /**
  40.      * Whether the asset is expected to start at a time beyond 0 seconds.
  41.      * For example, if the asset is a live stream.
  42.      * If true, we will not start polling for regions until the playhead has
  43.      * moved past 0 seconds, to avoid bad behaviors where the current time is
  44.      * briefly 0 before we have enough data to play.
  45.      * @private {boolean}
  46.      */
  47.     this.startsPastZero_ = startsPastZero;
  49.     /**
  50.      * A mapping between a region and where we previously were relative to it.
  51.      * When the value here differs from what we calculate, it means we moved and
  52.      * should fire an event.
  53.      *
  54.      * @private {!Map<T, 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) => {
  100.           if (seeking) {
  101.             this.onEvent_('skip', region, seeking);
  102.           } else {
  103.             // This is the case of regions whose duration is smaller than the
  104.             // resolution of our polling.
  105.             this.onEvent_('enter', region, seeking);
  106.             this.onEvent_('exit', region, seeking);
  107.           }
  108.         },
  109.       },
  110.       {
  111.         weWere: AFTER_THE_REGION,
  112.         weAre: BEFORE_THE_REGION,
  113.         invoke: (region, seeking) => this.onEvent_('skip', region, seeking),
  114.       },
  115.     ];
  117.     /** @private {shaka.util.EventManager} */
  118.     this.eventManager_ = new shaka.util.EventManager();
  120.     this.eventManager_.listen(this.timeline_, 'regionremove', (event) => {
  121.       /** @type {T} */
  122.       const region = event['region'];
  123.       this.oldPosition_.delete(region);
  124.     });
  125.   }
  127.   /** @override */
  128.   release() {
  129.     this.timeline_ = null;
  131.     // Clear our maps so that we are not holding onto any more information than
  132.     // needed.
  133.     this.oldPosition_.clear();
  135.     this.eventManager_.release();
  136.     this.eventManager_ = null;
  138.     super.release();
  139.   }
  141.   /** @override */
  142.   poll(positionInSeconds, wasSeeking) {
  143.     const RegionObserver = shaka.media.RegionObserver;
  144.     if (this.startsPastZero_ && positionInSeconds == 0) {
  145.       // Don't start checking regions until the timeline has begun moving.
  146.       return;
  147.     }
  148.     // Now that we have seen the playhead go past 0, it's okay if it goes
  149.     // back there (e.g. seeking back to the start).
  150.     this.startsPastZero_ = false;
  152.     for (const region of this.timeline_.regions()) {
  153.       const previousPosition = this.oldPosition_.get(region);
  154.       const currentPosition = RegionObserver.determinePositionRelativeTo_(
  155.           region, positionInSeconds);
  157.       // We will only use |previousPosition| and |currentPosition|, so we can
  158.       // update our state now.
  159.       this.oldPosition_.set(region, currentPosition);
  161.       for (const rule of this.rules_) {
  162.         if (rule.weWere == previousPosition && rule.weAre == currentPosition) {
  163.           rule.invoke(region, wasSeeking);
  164.         }
  165.       }
  166.     }
  167.   }
  169.   /**
  170.    * Dispatch events of the given type.  All event types in this class have the
  171.    * same parameters: region and seeking.
  172.    *
  173.    * @param {string} eventType
  174.    * @param {T} region
  175.    * @param {boolean} seeking
  176.    * @private
  177.    */
  178.   onEvent_(eventType, region, seeking) {
  179.     const event = new shaka.util.FakeEvent(eventType, new Map([
  180.       ['region', region],
  181.       ['seeking', seeking],
  182.     ]));
  183.     this.dispatchEvent(event);
  184.   }
  186.   /**
  187.    * Get the relative position of the playhead to |region| when the playhead is
  188.    * at |seconds|. We treat the region's start and end times as inclusive
  189.    * bounds.
  190.    *
  191.    * @template T
  192.    * @param {T} region
  193.    * @param {number} seconds
  194.    * @return {shaka.media.RegionObserver.RelativePosition_}
  195.    * @private
  196.    */
  197.   static determinePositionRelativeTo_(region, seconds) {
  198.     const RelativePosition = shaka.media.RegionObserver.RelativePosition_;
  200.     if (seconds < region.startTime) {
  201.       return RelativePosition.BEFORE_THE_REGION;
  202.     }
  204.     if (seconds > region.endTime) {
  205.       return RelativePosition.AFTER_THE_REGION;
  206.     }
  208.     return RelativePosition.IN_THE_REGION;
  209.   }
  210. };
  212. /**
  213.  * An enum of relative positions between the playhead and a region. Each is
  214.  * phrased so that it works in "The playhead is X" where "X" is any value in
  215.  * the enum.
  216.  *
  217.  * @enum {number}
  218.  * @private
  219.  */
  220. shaka.media.RegionObserver.RelativePosition_ = {
  221.   BEFORE_THE_REGION: 1,
  222.   IN_THE_REGION: 2,
  223.   AFTER_THE_REGION: 3,
  224. };
  226. /**
  227.  * All region observer events (onEnter, onExit, and onSkip) will be passed the
  228.  * region that the playhead is interacting with and whether or not the playhead
  229.  * moving is part of a seek event.
  230.  *
  231.  * @typedef {function(?, boolean)}
  232.  */
  233. shaka.media.RegionObserver.EventListener;
  235. /**
  236.  * @typedef {{
  237.  *    weWere: ?shaka.media.RegionObserver.RelativePosition_,
  238.  *    weAre: ?shaka.media.RegionObserver.RelativePosition_,
  239.  *    invoke: shaka.media.RegionObserver.EventListener
  240.  * }}
  241.  *
  242.  * @private
  243.  */
  244. shaka.media.RegionObserver.Rule_;