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.Error');
  16. goog.require('shaka.util.Uint8ArrayUtils');
  19. /**
  20.  * @summary
  21.  * This class manages segment prefetch operations.
  22.  * Called by StreamingEngine to prefetch next N segments
  23.  * ahead of playhead, to reduce the chances of rebuffering.
  24.  */
  25. shaka.media.SegmentPrefetch = class {
  26.   /**
  27.    * @param {number} prefetchLimit
  28.    * @param {shaka.extern.Stream} stream
  29.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  30.    * @param {boolean} reverse
  31.    */
  32.   constructor(prefetchLimit, stream, fetchDispatcher, reverse) {
  33.     /** @private {number} */
  34.     this.prefetchLimit_ = prefetchLimit;
  36.     /** @private {shaka.extern.Stream} */
  37.     this.stream_ = stream;
  39.     /** @private {shaka.media.SegmentPrefetch.FetchDispatcher} */
  40.     this.fetchDispatcher_ = fetchDispatcher;
  42.     /**
  43.      * @private {!Map<
  44.      *        !shaka.media.SegmentReference,
  45.      *        !shaka.media.SegmentPrefetchOperation>}
  46.      */
  47.     this.segmentPrefetchMap_ = new Map();
  49.     /**
  50.      * @private {!Map<
  51.      *        !shaka.media.InitSegmentReference,
  52.      *        !shaka.media.SegmentPrefetchOperation>}
  53.      */
  54.     this.initSegmentPrefetchMap_ = new Map();
  56.     /** @private {?shaka.media.SegmentIterator} */
  57.     this.iterator_ = null;
  59.     /** @private {boolean} */
  60.     this.reverse_ = reverse;
  61.   }
  63.   /**
  64.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  65.    */
  66.   replaceFetchDispatcher(fetchDispatcher) {
  67.     this.fetchDispatcher_ = fetchDispatcher;
  68.     for (const operation of this.segmentPrefetchMap_.values()) {
  69.       operation.replaceFetchDispatcher(fetchDispatcher);
  70.     }
  71.   }
  73.   /**
  74.    * Fetch next segments ahead of current time.
  75.    *
  76.    * @param {number} currTime
  77.    * @param {boolean=} skipFirst
  78.    * @return {!Promise}
  79.    * @public
  80.    */
  81.   prefetchSegmentsByTime(currTime, skipFirst = false) {
  82.     goog.asserts.assert(this.prefetchLimit_ > 0,
  83.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  85.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  86.     if (!this.stream_.segmentIndex) {
  87.       shaka.log.debug(logPrefix, 'missing segmentIndex');
  88.       return Promise.resolve();
  89.     }
  90.     if (!this.iterator_) {
  91.       this.iterator_ = this.stream_.segmentIndex.getIteratorForTime(
  92.           currTime, /* allowNonIndependent= */ true, this.reverse_);
  93.     }
  94.     if (!this.iterator_) {
  95.       shaka.log.debug(logPrefix, 'missing iterator');
  96.       return Promise.resolve();
  97.     }
  98.     if (skipFirst) {
  99.       this.iterator_.next();
  100.     }
  101.     const promises = [];
  102.     while (this.segmentPrefetchMap_.size < this.prefetchLimit_) {
  103.       const reference = this.iterator_.next().value;
  104.       if (!reference) {
  105.         break;
  106.       }
  107.       // By default doesn't prefetch preload partial segments when using
  108.       // byterange
  109.       let prefetchAllowed = true;
  110.       if (reference.isPreload() && reference.endByte != null) {
  111.         prefetchAllowed = false;
  112.       }
  113.       if (reference.getStatus() ==
  114.           shaka.media.SegmentReference.Status.MISSING) {
  115.         prefetchAllowed = false;
  116.       }
  117.       if (reference.getSegmentData(/* allowDeleteOnSingleUse= */ false)) {
  118.         prefetchAllowed = false;
  119.       }
  120.       if (prefetchAllowed && reference.initSegmentReference) {
  121.         promises.push(this.prefetchInitSegment(
  122.             reference.initSegmentReference));
  123.       }
  124.       if (prefetchAllowed && !this.segmentPrefetchMap_.has(reference)) {
  125.         const segmentPrefetchOperation =
  126.           new shaka.media.SegmentPrefetchOperation(this.fetchDispatcher_);
  127.         promises.push(segmentPrefetchOperation.dispatchFetch(
  128.             reference, this.stream_));
  129.         this.segmentPrefetchMap_.set(reference, segmentPrefetchOperation);
  130.       }
  131.     }
  132.     this.clearInitSegments_();
  133.     return Promise.all(promises);
  134.   }
  136.   /**
  137.    * Fetch init segment.
  138.    *
  139.    * @param {!shaka.media.InitSegmentReference} initSegmentReference
  140.    * @return {!Promise}
  141.    */
  142.   prefetchInitSegment(initSegmentReference) {
  143.     goog.asserts.assert(this.prefetchLimit_ > 0,
  144.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  146.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  147.     if (!this.stream_.segmentIndex) {
  148.       shaka.log.debug(logPrefix, 'missing segmentIndex');
  149.       return Promise.resolve();
  150.     }
  152.     if (initSegmentReference.getSegmentData()) {
  153.       return Promise.resolve();
  154.     }
  156.     // init segments are ignored from the prefetch limit
  157.     const initSegments = Array.from(this.initSegmentPrefetchMap_.keys());
  158.     const someReference = initSegments.some((reference) => {
  159.       return shaka.media.InitSegmentReference.equal(
  160.           reference, initSegmentReference);
  161.     });
  162.     if (someReference) {
  163.       return Promise.resolve();
  164.     }
  165.     const segmentPrefetchOperation = new shaka.media.SegmentPrefetchOperation(
  166.         this.fetchDispatcher_);
  167.     const promise = segmentPrefetchOperation.dispatchFetch(
  168.         initSegmentReference, this.stream_);
  169.     this.initSegmentPrefetchMap_.set(
  170.         initSegmentReference, segmentPrefetchOperation);
  171.     return promise;
  172.   }
  174.   /**
  175.    * Get the result of prefetched segment if already exists.
  176.    * @param {!(shaka.media.SegmentReference|
  177.    *           shaka.media.InitSegmentReference)} reference
  178.    * @param {?function(BufferSource):!Promise=} streamDataCallback
  179.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  180.    * @public
  181.    */
  182.   getPrefetchedSegment(reference, streamDataCallback) {
  183.     goog.asserts.assert(this.prefetchLimit_ > 0,
  184.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  186.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  188.     let prefetchMap = this.segmentPrefetchMap_;
  189.     if (reference instanceof shaka.media.InitSegmentReference) {
  190.       prefetchMap = this.initSegmentPrefetchMap_;
  191.     }
  193.     if (prefetchMap.has(reference)) {
  194.       const segmentPrefetchOperation = prefetchMap.get(reference);
  195.       if (streamDataCallback) {
  196.         segmentPrefetchOperation.setStreamDataCallback(streamDataCallback);
  197.       }
  198.       if (reference instanceof shaka.media.SegmentReference) {
  199.         shaka.log.debug(
  200.             logPrefix,
  201.             'reused prefetched segment at time:', reference.startTime,
  202.             'mapSize', prefetchMap.size);
  203.       } else {
  204.         shaka.log.debug(
  205.             logPrefix,
  206.             'reused prefetched init segment at time, mapSize',
  207.             prefetchMap.size);
  208.       }
  209.       return segmentPrefetchOperation.getOperation();
  210.     } else {
  211.       if (reference instanceof shaka.media.SegmentReference) {
  212.         shaka.log.debug(
  213.             logPrefix,
  214.             'missed segment at time:', reference.startTime,
  215.             'mapSize', prefetchMap.size);
  216.       } else {
  217.         shaka.log.debug(
  218.             logPrefix,
  219.             'missed init segment at time, mapSize',
  220.             prefetchMap.size);
  221.       }
  222.       return null;
  223.     }
  224.   }
  226.   /**
  227.    * Clear All Helper
  228.    * @param {!Map<T,
  229.    *        !shaka.media.SegmentPrefetchOperation>} map
  230.    * @template T SegmentReference or InitSegmentReference
  231.    * @private
  232.    */
  233.   clearMap_(map) {
  234.     for (const reference of map.keys()) {
  235.       if (reference) {
  236.         this.abortPrefetchedSegment_(reference);
  237.       }
  238.     }
  239.   }
  241.   /** */
  242.   resetPosition() {
  243.     this.iterator_ = null;
  244.   }
  246.   /**
  247.    * Clear all segment data.
  248.    * @public
  249.    */
  250.   clearAll() {
  251.     this.clearMap_(this.segmentPrefetchMap_);
  252.     this.clearMap_(this.initSegmentPrefetchMap_);
  253.     this.resetPosition();
  254.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  255.     shaka.log.debug(logPrefix, 'cleared all');
  256.   }
  258.   /**
  259.    * Remove a reference of prefetched segment if already exists.
  260.    * @param {!shaka.media.SegmentReference} reference
  261.    * @public
  262.    */
  263.   removeReference(reference) {
  264.     this.abortPrefetchedSegment_(reference);
  265.   }
  267.   /**
  268.    * @param {number} time
  269.    * @param {boolean=} clearInitSegments
  270.    */
  271.   evict(time, clearInitSegments = false) {
  272.     for (const ref of this.segmentPrefetchMap_.keys()) {
  273.       if (time > ref.endTime) {
  274.         this.abortPrefetchedSegment_(ref);
  275.       }
  276.     }
  277.     if (clearInitSegments) {
  278.       this.clearInitSegments_();
  279.     }
  280.   }
  282.   /**
  283.    * @param {boolean} reverse
  284.    */
  285.   setReverse(reverse) {
  286.     this.reverse_ = reverse;
  287.     if (this.iterator_) {
  288.       this.iterator_.setReverse(reverse);
  289.     }
  290.   }
  292.   /**
  293.    * Remove all init segments that don't have associated segments in
  294.    * the segment prefetch map.
  295.    * By default, with delete on get, the init segments should get removed as
  296.    * they are used. With deleteOnGet set to false, we need to clear them
  297.    * every so often once the segments that are associated with each init segment
  298.    * is no longer prefetched.
  299.    * @private
  300.    */
  301.   clearInitSegments_() {
  302.     const segmentReferences = Array.from(this.segmentPrefetchMap_.keys());
  303.     for (const initSegmentReference of this.initSegmentPrefetchMap_.keys()) {
  304.       // if no segment references this init segment, we should remove it.
  305.       const someReference = segmentReferences.some((segmentReference) => {
  306.         return shaka.media.InitSegmentReference.equal(
  307.             segmentReference.initSegmentReference, initSegmentReference);
  308.       });
  309.       if (!someReference) {
  310.         this.abortPrefetchedSegment_(initSegmentReference);
  311.       }
  312.     }
  313.   }
  315.   /**
  316.    * Reset the prefetchLimit and clear all internal states.
  317.    * Called by StreamingEngine when configure() was called.
  318.    * @param {number} newPrefetchLimit
  319.    * @public
  320.    */
  321.   resetLimit(newPrefetchLimit) {
  322.     goog.asserts.assert(newPrefetchLimit >= 0,
  323.         'The new prefetch limit must be >= 0.');
  325.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  326.     shaka.log.debug(logPrefix, 'resetting prefetch limit to', newPrefetchLimit);
  327.     this.prefetchLimit_ = newPrefetchLimit;
  328.     const keyArr = Array.from(this.segmentPrefetchMap_.keys());
  329.     while (keyArr.length > newPrefetchLimit) {
  330.       const reference = keyArr.pop();
  331.       if (reference) {
  332.         this.abortPrefetchedSegment_(reference);
  333.       }
  334.     }
  335.     this.clearInitSegments_();
  336.   }
  338.   /**
  339.    * Called by Streaming Engine when switching variant.
  340.    * @param {shaka.extern.Stream} stream
  341.    * @public
  342.    */
  343.   switchStream(stream) {
  344.     if (stream && stream !== this.stream_) {
  345.       this.clearAll();
  346.       this.stream_ = stream;
  347.     }
  348.   }
  350.   /**
  351.    * Get the current stream.
  352.    * @public
  353.    * @return {shaka.extern.Stream}
  354.    */
  355.   getStream() {
  356.     return this.stream_;
  357.   }
  359.   /**
  360.    * Remove a segment from prefetch map and abort it.
  361.    * @param {!(shaka.media.SegmentReference|
  362.    *           shaka.media.InitSegmentReference)} reference
  363.    * @private
  364.    */
  365.   abortPrefetchedSegment_(reference) {
  366.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  368.     let prefetchMap = this.segmentPrefetchMap_;
  369.     if (reference instanceof shaka.media.InitSegmentReference) {
  370.       prefetchMap = this.initSegmentPrefetchMap_;
  371.     }
  373.     const segmentPrefetchOperation = prefetchMap.get(reference);
  374.     prefetchMap.delete(reference);
  376.     if (segmentPrefetchOperation) {
  377.       segmentPrefetchOperation.abort();
  378.       if (reference instanceof shaka.media.SegmentReference) {
  379.         shaka.log.debug(
  380.             logPrefix,
  381.             'pop and abort prefetched segment at time:', reference.startTime);
  382.       } else {
  383.         shaka.log.debug(logPrefix, 'pop and abort prefetched init segment');
  384.       }
  385.     }
  386.   }
  388.   /**
  389.    * The prefix of the logs that are created in this class.
  390.    * @param {shaka.extern.Stream} stream
  391.    * @return {string}
  392.    * @private
  393.    */
  394.   static logPrefix_(stream) {
  395.     return 'SegmentPrefetch(' + stream.type + ':' + stream.id + ')';
  396.   }
  397. };
  399. /**
  400.  * @summary
  401.  * This class manages a segment prefetch operation.
  402.  */
  403. shaka.media.SegmentPrefetchOperation = class {
  404.   /**
  405.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  406.    */
  407.   constructor(fetchDispatcher) {
  408.     /** @private {shaka.media.SegmentPrefetch.FetchDispatcher} */
  409.     this.fetchDispatcher_ = fetchDispatcher;
  411.     /** @private {?function(BufferSource):!Promise} */
  412.     this.streamDataCallback_ = null;
  414.     /** @private {?shaka.net.NetworkingEngine.PendingRequest} */
  415.     this.operation_ = null;
  416.   }
  418.   /**
  419.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  420.    */
  421.   replaceFetchDispatcher(fetchDispatcher) {
  422.     this.fetchDispatcher_ = fetchDispatcher;
  423.   }
  425.   /**
  426.    * Fetch segments
  427.    *
  428.    * @param {!(shaka.media.SegmentReference|
  429.    *           shaka.media.InitSegmentReference)} reference
  430.    * @param {!shaka.extern.Stream} stream
  431.    * @return {!Promise}
  432.    * @public
  433.    */
  434.   dispatchFetch(reference, stream) {
  435.     // We need to store the data, because streamDataCallback_ might not be
  436.     // available when you start getting the first data.
  437.     let buffered = new Uint8Array(0);
  438.     this.operation_ = this.fetchDispatcher_(
  439.         reference, stream, async (data) => {
  440.           if (buffered.byteLength > 0) {
  441.             buffered = shaka.util.Uint8ArrayUtils.concat(buffered, data);
  442.           } else {
  443.             buffered = data;
  444.           }
  445.           if (this.streamDataCallback_) {
  446.             await this.streamDataCallback_(buffered);
  447.             buffered = new Uint8Array(0);
  448.           }
  449.         });
  450.     return this.operation_.promise.catch((e) => {
  451.       // Ignore OPERATION_ABORTED errors.
  452.       if (e instanceof shaka.util.Error &&
  453.           e.code == shaka.util.Error.Code.OPERATION_ABORTED) {
  454.         return Promise.resolve();
  455.       }
  456.       // Continue to surface other errors.
  457.       return Promise.reject(e);
  458.     });
  459.   }
  461.   /**
  462.    * Get the operation of prefetched segment if already exists.
  463.    *
  464.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  465.    * @public
  466.    */
  467.   getOperation() {
  468.     return this.operation_;
  469.   }
  471.   /**
  472.    * @param {?function(BufferSource):!Promise} streamDataCallback
  473.    * @public
  474.    */
  475.   setStreamDataCallback(streamDataCallback) {
  476.     this.streamDataCallback_ = streamDataCallback;
  477.   }
  479.   /**
  480.    * Abort the current operation if exists.
  481.    */
  482.   abort() {
  483.     if (this.operation_) {
  484.       this.operation_.abort();
  485.     }
  486.   }
  487. };
  489. /**
  490.  * @typedef {function(
  491.  *  !(shaka.media.InitSegmentReference|shaka.media.SegmentReference),
  492.  *  shaka.extern.Stream,
  493.  *  ?function(BufferSource):!Promise=
  494.  * ):!shaka.net.NetworkingEngine.PendingRequest}
  495.  *
  496.  * @description
  497.  * A callback function that fetches a segment.
  498.  * @export
  499.  */
  500. shaka.media.SegmentPrefetch.FetchDispatcher;