Source: lib/media/segment_prefetch.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.media.SegmentPrefetch');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.media.InitSegmentReference');
  12. goog.require('shaka.media.SegmentIterator');
  13. goog.require('shaka.media.SegmentReference');
  14. goog.require('shaka.net.NetworkingEngine');
  15. goog.require('shaka.util.Uint8ArrayUtils');
  18. /**
  19.  * @summary
  20.  * This class manages segment prefetch operations.
  21.  * Called by StreamingEngine to prefetch next N segments
  22.  * ahead of playhead, to reduce the chances of rebuffering.
  23.  */
  24. shaka.media.SegmentPrefetch = class {
  25.   /**
  26.    * @param {number} prefetchLimit
  27.    * @param {shaka.extern.Stream} stream
  28.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  29.    * @param {boolean} reverse
  30.    */
  31.   constructor(prefetchLimit, stream, fetchDispatcher, reverse) {
  32.     /** @private {number} */
  33.     this.prefetchLimit_ = prefetchLimit;
  35.     /** @private {shaka.extern.Stream} */
  36.     this.stream_ = stream;
  38.     /** @private {shaka.media.SegmentPrefetch.FetchDispatcher} */
  39.     this.fetchDispatcher_ = fetchDispatcher;
  41.     /**
  42.      * @private {!Map.<
  43.      *        !(shaka.media.SegmentReference),
  44.      *        !shaka.media.SegmentPrefetchOperation>}
  45.      */
  46.     this.segmentPrefetchMap_ = new Map();
  48.     /**
  49.      * @private {!Map.<
  50.      *        !(shaka.media.InitSegmentReference),
  51.      *        !shaka.media.SegmentPrefetchOperation>}
  52.      */
  53.     this.initSegmentPrefetchMap_ = new Map();
  55.     /** @private {?shaka.media.SegmentIterator} */
  56.     this.iterator_ = null;
  58.     /** @private {boolean} */
  59.     this.reverse_ = reverse;
  60.   }
  62.   /**
  63.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  64.    */
  65.   replaceFetchDispatcher(fetchDispatcher) {
  66.     this.fetchDispatcher_ = fetchDispatcher;
  67.     for (const operation of this.segmentPrefetchMap_.values()) {
  68.       operation.replaceFetchDispatcher(fetchDispatcher);
  69.     }
  70.   }
  72.   /**
  73.    * Fetch next segments ahead of current time.
  74.    *
  75.    * @param {number} currTime
  76.    * @param {boolean=} skipFirst
  77.    * @public
  78.    */
  79.   prefetchSegmentsByTime(currTime, skipFirst = false) {
  80.     goog.asserts.assert(this.prefetchLimit_ > 0,
  81.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  83.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  84.     if (!this.stream_.segmentIndex) {
  85.       shaka.log.debug(logPrefix, 'missing segmentIndex');
  86.       return;
  87.     }
  88.     if (!this.iterator_) {
  89.       this.iterator_ = this.stream_.segmentIndex.getIteratorForTime(
  90.           currTime, /* allowNonIndepedent= */ true, this.reverse_);
  91.     }
  92.     if (!this.iterator_) {
  93.       shaka.log.debug(logPrefix, 'missing iterator');
  94.       return;
  95.     }
  96.     if (skipFirst) {
  97.       this.iterator_.next();
  98.     }
  99.     while (this.segmentPrefetchMap_.size < this.prefetchLimit_) {
  100.       const reference = this.iterator_.next().value;
  101.       if (!reference) {
  102.         break;
  103.       }
  104.       // By default doesn't prefech preload partial segments when using
  105.       // byterange
  106.       let prefetchAllowed = true;
  107.       if (reference.isPreload() && reference.endByte != null) {
  108.         prefetchAllowed = false;
  109.       }
  110.       if (reference.getStatus() ==
  111.           shaka.media.SegmentReference.Status.MISSING) {
  112.         prefetchAllowed = false;
  113.       }
  114.       if (prefetchAllowed && reference.initSegmentReference) {
  115.         this.prefetchInitSegment(reference.initSegmentReference);
  116.       }
  117.       if (prefetchAllowed && !this.segmentPrefetchMap_.has(reference)) {
  118.         const segmentPrefetchOperation =
  119.           new shaka.media.SegmentPrefetchOperation(this.fetchDispatcher_);
  120.         segmentPrefetchOperation.dispatchFetch(reference, this.stream_);
  121.         this.segmentPrefetchMap_.set(reference, segmentPrefetchOperation);
  122.       }
  123.     }
  124.     this.clearInitSegments_();
  125.   }
  127.   /**
  128.    * Fetch init segment.
  129.    *
  130.    * @param {!shaka.media.InitSegmentReference} initSegmentReference
  131.    */
  132.   prefetchInitSegment(initSegmentReference) {
  133.     goog.asserts.assert(this.prefetchLimit_ > 0,
  134.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  136.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  137.     if (!this.stream_.segmentIndex) {
  138.       shaka.log.debug(logPrefix, 'missing segmentIndex');
  139.       return;
  140.     }
  142.     // init segments are ignored from the prefetch limit
  143.     const initSegments = Array.from(this.initSegmentPrefetchMap_.keys());
  144.     const someReference = initSegments.some((reference) => {
  145.       return shaka.media.InitSegmentReference.equal(
  146.           reference, initSegmentReference);
  147.     });
  148.     if (!someReference) {
  149.       const segmentPrefetchOperation =
  150.         new shaka.media.SegmentPrefetchOperation(this.fetchDispatcher_);
  151.       segmentPrefetchOperation.dispatchFetch(
  152.           initSegmentReference, this.stream_);
  153.       this.initSegmentPrefetchMap_.set(
  154.           initSegmentReference, segmentPrefetchOperation);
  155.     }
  156.   }
  158.   /**
  159.    * Get the result of prefetched segment if already exists.
  160.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  161.    *        reference
  162.    * @param {?function(BufferSource):!Promise=} streamDataCallback
  163.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  164.    * @public
  165.    */
  166.   getPrefetchedSegment(reference, streamDataCallback) {
  167.     goog.asserts.assert(this.prefetchLimit_ > 0,
  168.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  170.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  172.     let prefetchMap = this.segmentPrefetchMap_;
  173.     if (reference instanceof shaka.media.InitSegmentReference) {
  174.       prefetchMap = this.initSegmentPrefetchMap_;
  175.     }
  177.     if (prefetchMap.has(reference)) {
  178.       const segmentPrefetchOperation = prefetchMap.get(reference);
  179.       if (streamDataCallback) {
  180.         segmentPrefetchOperation.setStreamDataCallback(streamDataCallback);
  181.       }
  182.       if (reference instanceof shaka.media.SegmentReference) {
  183.         shaka.log.debug(
  184.             logPrefix,
  185.             'reused prefetched segment at time:', reference.startTime,
  186.             'mapSize', prefetchMap.size);
  187.       } else {
  188.         shaka.log.debug(
  189.             logPrefix,
  190.             'reused prefetched init segment at time, mapSize',
  191.             prefetchMap.size);
  192.       }
  193.       return segmentPrefetchOperation.getOperation();
  194.     } else {
  195.       if (reference instanceof shaka.media.SegmentReference) {
  196.         shaka.log.debug(
  197.             logPrefix,
  198.             'missed segment at time:', reference.startTime,
  199.             'mapSize', prefetchMap.size);
  200.       } else {
  201.         shaka.log.debug(
  202.             logPrefix,
  203.             'missed init segment at time, mapSize',
  204.             prefetchMap.size);
  205.       }
  206.       return null;
  207.     }
  208.   }
  210.   /**
  211.    * Clear All Helper
  212.    * @private
  213.    */
  214.   clearMap_(map) {
  215.     for (const reference of map.keys()) {
  216.       if (reference) {
  217.         this.abortPrefetchedSegment_(reference);
  218.       }
  219.     }
  220.   }
  222.   /** */
  223.   resetPosition() {
  224.     this.iterator_ = null;
  225.   }
  227.   /**
  228.    * Clear all segment data.
  229.    * @public
  230.    */
  231.   clearAll() {
  232.     this.clearMap_(this.segmentPrefetchMap_);
  233.     this.clearMap_(this.initSegmentPrefetchMap_);
  234.     this.resetPosition();
  235.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  236.     shaka.log.debug(logPrefix, 'cleared all');
  237.   }
  239.   /**
  240.    * Remove a reference of prefetched segment if already exists.
  241.    * @param {!shaka.media.SegmentReference} reference
  242.    * @public
  243.    */
  244.   removeReference(reference) {
  245.     this.abortPrefetchedSegment_(reference);
  246.   }
  248.   /**
  249.    * @param {number} time
  250.    * @param {boolean=} clearInitSegments
  251.    */
  252.   evict(time, clearInitSegments = false) {
  253.     for (const ref of this.segmentPrefetchMap_.keys()) {
  254.       if (time > ref.endTime) {
  255.         this.abortPrefetchedSegment_(ref);
  256.       }
  257.     }
  258.     if (clearInitSegments) {
  259.       this.clearInitSegments_();
  260.     }
  261.   }
  263.   /**
  264.    * @param {boolean} reverse
  265.    */
  266.   setReverse(reverse) {
  267.     this.reverse_ = reverse;
  268.     if (this.iterator_) {
  269.       this.iterator_.setReverse(reverse);
  270.     }
  271.   }
  273.   /**
  274.    * Remove all init segments that don't have associated segments in
  275.    * the segment prefetch map.
  276.    * By default, with delete on get, the init segments should get removed as
  277.    * they are used. With deleteOnGet set to false, we need to clear them
  278.    * every so often once the segments that are associated with each init segment
  279.    * is no longer prefetched.
  280.    * @private
  281.    */
  282.   clearInitSegments_() {
  283.     const segmentReferences = Array.from(this.segmentPrefetchMap_.keys());
  284.     for (const initSegmentReference of this.initSegmentPrefetchMap_.keys()) {
  285.       // if no segment references this init segment, we should remove it.
  286.       const someReference = segmentReferences.some((segmentReference) => {
  287.         return shaka.media.InitSegmentReference.equal(
  288.             segmentReference.initSegmentReference, initSegmentReference);
  289.       });
  290.       if (!someReference) {
  291.         this.abortPrefetchedSegment_(initSegmentReference);
  292.       }
  293.     }
  294.   }
  296.   /**
  297.    * Reset the prefetchLimit and clear all internal states.
  298.    * Called by StreamingEngine when configure() was called.
  299.    * @param {number} newPrefetchLimit
  300.    * @public
  301.    */
  302.   resetLimit(newPrefetchLimit) {
  303.     goog.asserts.assert(newPrefetchLimit >= 0,
  304.         'The new prefetch limit must be >= 0.');
  306.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  307.     shaka.log.debug(logPrefix, 'resetting prefetch limit to', newPrefetchLimit);
  308.     this.prefetchLimit_ = newPrefetchLimit;
  309.     const keyArr = Array.from(this.segmentPrefetchMap_.keys());
  310.     while (keyArr.length > newPrefetchLimit) {
  311.       const reference = keyArr.pop();
  312.       if (reference) {
  313.         this.abortPrefetchedSegment_(reference);
  314.       }
  315.     }
  316.     this.clearInitSegments_();
  317.   }
  319.   /**
  320.    * Called by Streaming Engine when switching variant.
  321.    * @param {shaka.extern.Stream} stream
  322.    * @public
  323.    */
  324.   switchStream(stream) {
  325.     if (stream && stream !== this.stream_) {
  326.       this.clearAll();
  327.       this.stream_ = stream;
  328.     }
  329.   }
  331.   /**
  332.    * Get the current stream.
  333.    * @public
  334.    * @return {shaka.extern.Stream}
  335.    */
  336.   getStream() {
  337.     return this.stream_;
  338.   }
  340.   /**
  341.    * Remove a segment from prefetch map and abort it.
  342.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  343.    *        reference
  344.    * @private
  345.    */
  346.   abortPrefetchedSegment_(reference) {
  347.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  349.     let prefetchMap = this.segmentPrefetchMap_;
  350.     if (reference instanceof shaka.media.InitSegmentReference) {
  351.       prefetchMap = this.initSegmentPrefetchMap_;
  352.     }
  354.     const segmentPrefetchOperation = prefetchMap.get(reference);
  355.     prefetchMap.delete(reference);
  357.     if (segmentPrefetchOperation) {
  358.       segmentPrefetchOperation.abort();
  359.       if (reference instanceof shaka.media.SegmentReference) {
  360.         shaka.log.debug(
  361.             logPrefix,
  362.             'pop and abort prefetched segment at time:', reference.startTime);
  363.       } else {
  364.         shaka.log.debug(logPrefix, 'pop and abort prefetched init segment');
  365.       }
  366.     }
  367.   }
  369.   /**
  370.    * The prefix of the logs that are created in this class.
  371.    * @return {string}
  372.    * @private
  373.    */
  374.   static logPrefix_(stream) {
  375.     return 'SegmentPrefetch(' + stream.type + ':' + stream.id + ')';
  376.   }
  377. };
  379. /**
  380.  * @summary
  381.  * This class manages a segment prefetch operation.
  382.  */
  383. shaka.media.SegmentPrefetchOperation = class {
  384.   /**
  385.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  386.    */
  387.   constructor(fetchDispatcher) {
  388.     /** @private {shaka.media.SegmentPrefetch.FetchDispatcher} */
  389.     this.fetchDispatcher_ = fetchDispatcher;
  391.     /** @private {?function(BufferSource):!Promise} */
  392.     this.streamDataCallback_ = null;
  394.     /** @private {?shaka.net.NetworkingEngine.PendingRequest} */
  395.     this.operation_ = null;
  396.   }
  398.   /**
  399.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  400.    */
  401.   replaceFetchDispatcher(fetchDispatcher) {
  402.     this.fetchDispatcher_ = fetchDispatcher;
  403.   }
  405.   /**
  406.    * Fetch a segments
  407.    *
  408.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  409.    *        reference
  410.    * @param {!shaka.extern.Stream} stream
  411.    * @public
  412.    */
  413.   dispatchFetch(reference, stream) {
  414.     // We need to store the data, because streamDataCallback_ might not be
  415.     // available when you start getting the first data.
  416.     let buffered = new Uint8Array(0);
  417.     this.operation_ = this.fetchDispatcher_(
  418.         reference, stream, async (data) => {
  419.           if (buffered.byteLength > 0) {
  420.             buffered = shaka.util.Uint8ArrayUtils.concat(buffered, data);
  421.           } else {
  422.             buffered = data;
  423.           }
  424.           if (this.streamDataCallback_) {
  425.             await this.streamDataCallback_(buffered);
  426.             buffered = new Uint8Array(0);
  427.           }
  428.         });
  429.   }
  431.   /**
  432.    * Get the operation of prefetched segment if already exists.
  433.    *
  434.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  435.    * @public
  436.    */
  437.   getOperation() {
  438.     return this.operation_;
  439.   }
  441.   /**
  442.    * @param {?function(BufferSource):!Promise} streamDataCallback
  443.    * @public
  444.    */
  445.   setStreamDataCallback(streamDataCallback) {
  446.     this.streamDataCallback_ = streamDataCallback;
  447.   }
  449.   /**
  450.    * Abort the current operation if exists.
  451.    */
  452.   abort() {
  453.     if (this.operation_) {
  454.       this.operation_.abort();
  455.     }
  456.   }
  457. };
  459. /**
  460.  * @typedef {function(
  461.  *  !(shaka.media.InitSegmentReference|shaka.media.SegmentReference),
  462.  *  shaka.extern.Stream,
  463.  *  ?function(BufferSource):!Promise=
  464.  * ):!shaka.net.NetworkingEngine.PendingRequest}
  465.  *
  466.  * @description
  467.  * A callback function that fetches a segment.
  468.  * @export
  469.  */
  470. shaka.media.SegmentPrefetch.FetchDispatcher;