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