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.       if (this.stream_.fastSwitching && reference.isPartial() &&
  124.           reference.isLastPartial()) {
  125.         break;
  126.       }
  127.     }
  128.     this.clearInitSegments_();
  129.   }
  131.   /**
  132.    * Fetch init segment.
  133.    *
  134.    * @param {!shaka.media.InitSegmentReference} initSegmentReference
  135.    */
  136.   prefetchInitSegment(initSegmentReference) {
  137.     goog.asserts.assert(this.prefetchLimit_ > 0,
  138.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  140.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  141.     if (!this.stream_.segmentIndex) {
  142.       shaka.log.debug(logPrefix, 'missing segmentIndex');
  143.       return;
  144.     }
  146.     // init segments are ignored from the prefetch limit
  147.     const initSegments = Array.from(this.initSegmentPrefetchMap_.keys());
  148.     const someReference = initSegments.some((reference) => {
  149.       return shaka.media.InitSegmentReference.equal(
  150.           reference, initSegmentReference);
  151.     });
  152.     if (!someReference) {
  153.       const segmentPrefetchOperation =
  154.         new shaka.media.SegmentPrefetchOperation(this.fetchDispatcher_);
  155.       segmentPrefetchOperation.dispatchFetch(
  156.           initSegmentReference, this.stream_);
  157.       this.initSegmentPrefetchMap_.set(
  158.           initSegmentReference, segmentPrefetchOperation);
  159.     }
  160.   }
  162.   /**
  163.    * Get the result of prefetched segment if already exists.
  164.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  165.    *        reference
  166.    * @param {?function(BufferSource):!Promise=} streamDataCallback
  167.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  168.    * @public
  169.    */
  170.   getPrefetchedSegment(reference, streamDataCallback) {
  171.     goog.asserts.assert(this.prefetchLimit_ > 0,
  172.         'SegmentPrefetch can not be used when prefetchLimit <= 0.');
  174.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  176.     let prefetchMap = this.segmentPrefetchMap_;
  177.     if (reference instanceof shaka.media.InitSegmentReference) {
  178.       prefetchMap = this.initSegmentPrefetchMap_;
  179.     }
  181.     if (prefetchMap.has(reference)) {
  182.       const segmentPrefetchOperation = prefetchMap.get(reference);
  183.       if (streamDataCallback) {
  184.         segmentPrefetchOperation.setStreamDataCallback(streamDataCallback);
  185.       }
  186.       if (reference instanceof shaka.media.SegmentReference) {
  187.         shaka.log.debug(
  188.             logPrefix,
  189.             'reused prefetched segment at time:', reference.startTime,
  190.             'mapSize', prefetchMap.size);
  191.       } else {
  192.         shaka.log.debug(
  193.             logPrefix,
  194.             'reused prefetched init segment at time, mapSize',
  195.             prefetchMap.size);
  196.       }
  197.       return segmentPrefetchOperation.getOperation();
  198.     } else {
  199.       if (reference instanceof shaka.media.SegmentReference) {
  200.         shaka.log.debug(
  201.             logPrefix,
  202.             'missed segment at time:', reference.startTime,
  203.             'mapSize', prefetchMap.size);
  204.       } else {
  205.         shaka.log.debug(
  206.             logPrefix,
  207.             'missed init segment at time, mapSize',
  208.             prefetchMap.size);
  209.       }
  210.       return null;
  211.     }
  212.   }
  214.   /**
  215.    * Clear All Helper
  216.    * @private
  217.    */
  218.   clearMap_(map) {
  219.     for (const reference of map.keys()) {
  220.       if (reference) {
  221.         this.abortPrefetchedSegment_(reference);
  222.       }
  223.     }
  224.   }
  226.   /** */
  227.   resetPosition() {
  228.     this.iterator_ = null;
  229.   }
  231.   /**
  232.    * Clear all segment data.
  233.    * @public
  234.    */
  235.   clearAll() {
  236.     this.clearMap_(this.segmentPrefetchMap_);
  237.     this.clearMap_(this.initSegmentPrefetchMap_);
  238.     this.resetPosition();
  239.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  240.     shaka.log.debug(logPrefix, 'cleared all');
  241.   }
  243.   /**
  244.    * Remove a reference of prefetched segment if already exists.
  245.    * @param {!shaka.media.SegmentReference} reference
  246.    * @public
  247.    */
  248.   removeReference(reference) {
  249.     this.abortPrefetchedSegment_(reference);
  250.   }
  252.   /**
  253.    * @param {number} time
  254.    * @param {boolean=} clearInitSegments
  255.    */
  256.   evict(time, clearInitSegments = false) {
  257.     for (const ref of this.segmentPrefetchMap_.keys()) {
  258.       if (time > ref.endTime) {
  259.         this.abortPrefetchedSegment_(ref);
  260.       }
  261.     }
  262.     if (clearInitSegments) {
  263.       this.clearInitSegments_();
  264.     }
  265.   }
  267.   /**
  268.    * @param {boolean} reverse
  269.    */
  270.   setReverse(reverse) {
  271.     this.reverse_ = reverse;
  272.     if (this.iterator_) {
  273.       this.iterator_.setReverse(reverse);
  274.     }
  275.   }
  277.   /**
  278.    * Remove all init segments that don't have associated segments in
  279.    * the segment prefetch map.
  280.    * By default, with delete on get, the init segments should get removed as
  281.    * they are used. With deleteOnGet set to false, we need to clear them
  282.    * every so often once the segments that are associated with each init segment
  283.    * is no longer prefetched.
  284.    * @private
  285.    */
  286.   clearInitSegments_() {
  287.     const segmentReferences = Array.from(this.segmentPrefetchMap_.keys());
  288.     for (const initSegmentReference of this.initSegmentPrefetchMap_.keys()) {
  289.       // if no segment references this init segment, we should remove it.
  290.       const someReference = segmentReferences.some((segmentReference) => {
  291.         return shaka.media.InitSegmentReference.equal(
  292.             segmentReference.initSegmentReference, initSegmentReference);
  293.       });
  294.       if (!someReference) {
  295.         this.abortPrefetchedSegment_(initSegmentReference);
  296.       }
  297.     }
  298.   }
  300.   /**
  301.    * Reset the prefetchLimit and clear all internal states.
  302.    * Called by StreamingEngine when configure() was called.
  303.    * @param {number} newPrefetchLimit
  304.    * @public
  305.    */
  306.   resetLimit(newPrefetchLimit) {
  307.     goog.asserts.assert(newPrefetchLimit >= 0,
  308.         'The new prefetch limit must be >= 0.');
  310.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  311.     shaka.log.debug(logPrefix, 'resetting prefetch limit to', newPrefetchLimit);
  312.     this.prefetchLimit_ = newPrefetchLimit;
  313.     const keyArr = Array.from(this.segmentPrefetchMap_.keys());
  314.     while (keyArr.length > newPrefetchLimit) {
  315.       const reference = keyArr.pop();
  316.       if (reference) {
  317.         this.abortPrefetchedSegment_(reference);
  318.       }
  319.     }
  320.     this.clearInitSegments_();
  321.   }
  323.   /**
  324.    * Called by Streaming Engine when switching variant.
  325.    * @param {shaka.extern.Stream} stream
  326.    * @public
  327.    */
  328.   switchStream(stream) {
  329.     if (stream && stream !== this.stream_) {
  330.       this.clearAll();
  331.       this.stream_ = stream;
  332.     }
  333.   }
  335.   /**
  336.    * Get the current stream.
  337.    * @public
  338.    * @return {shaka.extern.Stream}
  339.    */
  340.   getStream() {
  341.     return this.stream_;
  342.   }
  344.   /**
  345.    * Remove a segment from prefetch map and abort it.
  346.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  347.    *        reference
  348.    * @private
  349.    */
  350.   abortPrefetchedSegment_(reference) {
  351.     const logPrefix = shaka.media.SegmentPrefetch.logPrefix_(this.stream_);
  353.     let prefetchMap = this.segmentPrefetchMap_;
  354.     if (reference instanceof shaka.media.InitSegmentReference) {
  355.       prefetchMap = this.initSegmentPrefetchMap_;
  356.     }
  358.     const segmentPrefetchOperation = prefetchMap.get(reference);
  359.     prefetchMap.delete(reference);
  361.     if (segmentPrefetchOperation) {
  362.       segmentPrefetchOperation.abort();
  363.       if (reference instanceof shaka.media.SegmentReference) {
  364.         shaka.log.debug(
  365.             logPrefix,
  366.             'pop and abort prefetched segment at time:', reference.startTime);
  367.       } else {
  368.         shaka.log.debug(logPrefix, 'pop and abort prefetched init segment');
  369.       }
  370.     }
  371.   }
  373.   /**
  374.    * The prefix of the logs that are created in this class.
  375.    * @return {string}
  376.    * @private
  377.    */
  378.   static logPrefix_(stream) {
  379.     return 'SegmentPrefetch(' + stream.type + ':' + stream.id + ')';
  380.   }
  381. };
  383. /**
  384.  * @summary
  385.  * This class manages a segment prefetch operation.
  386.  */
  387. shaka.media.SegmentPrefetchOperation = class {
  388.   /**
  389.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  390.    */
  391.   constructor(fetchDispatcher) {
  392.     /** @private {shaka.media.SegmentPrefetch.FetchDispatcher} */
  393.     this.fetchDispatcher_ = fetchDispatcher;
  395.     /** @private {?function(BufferSource):!Promise} */
  396.     this.streamDataCallback_ = null;
  398.     /** @private {?shaka.net.NetworkingEngine.PendingRequest} */
  399.     this.operation_ = null;
  400.   }
  402.   /**
  403.    * @param {shaka.media.SegmentPrefetch.FetchDispatcher} fetchDispatcher
  404.    */
  405.   replaceFetchDispatcher(fetchDispatcher) {
  406.     this.fetchDispatcher_ = fetchDispatcher;
  407.   }
  409.   /**
  410.    * Fetch a segments
  411.    *
  412.    * @param {!(shaka.media.SegmentReference|shaka.media.InitSegmentReference)}
  413.    *        reference
  414.    * @param {!shaka.extern.Stream} stream
  415.    * @public
  416.    */
  417.   dispatchFetch(reference, stream) {
  418.     // We need to store the data, because streamDataCallback_ might not be
  419.     // available when you start getting the first data.
  420.     let buffered = new Uint8Array(0);
  421.     this.operation_ = this.fetchDispatcher_(
  422.         reference, stream, async (data) => {
  423.           if (buffered.byteLength > 0) {
  424.             buffered = shaka.util.Uint8ArrayUtils.concat(buffered, data);
  425.           } else {
  426.             buffered = data;
  427.           }
  428.           if (this.streamDataCallback_) {
  429.             await this.streamDataCallback_(buffered);
  430.             buffered = new Uint8Array(0);
  431.           }
  432.         });
  433.   }
  435.   /**
  436.    * Get the operation of prefetched segment if already exists.
  437.    *
  438.    * @return {?shaka.net.NetworkingEngine.PendingRequest} op
  439.    * @public
  440.    */
  441.   getOperation() {
  442.     return this.operation_;
  443.   }
  445.   /**
  446.    * @param {?function(BufferSource):!Promise} streamDataCallback
  447.    * @public
  448.    */
  449.   setStreamDataCallback(streamDataCallback) {
  450.     this.streamDataCallback_ = streamDataCallback;
  451.   }
  453.   /**
  454.    * Abort the current operation if exists.
  455.    */
  456.   abort() {
  457.     if (this.operation_) {
  458.       this.operation_.abort();
  459.     }
  460.   }
  461. };
  463. /**
  464.  * @typedef {function(
  465.  *  !(shaka.media.InitSegmentReference|shaka.media.SegmentReference),
  466.  *  shaka.extern.Stream,
  467.  *  ?function(BufferSource):!Promise=
  468.  * ):!shaka.net.NetworkingEngine.PendingRequest}
  469.  *
  470.  * @description
  471.  * A callback function that fetches a segment.
  472.  * @export
  473.  */
  474. shaka.media.SegmentPrefetch.FetchDispatcher;