Add missing types for exposed methods from the ThroughputController

Dash-Industry-Forum · Jan 21, 2025 · fe4dc0b · fe4dc0b
1 parent 1ae916c
commit fe4dc0b
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 2 deletions.
diff --git a/index.d.ts b/index.d.ts
@@ -1024,6 +1024,14 @@ declare namespace dashjs {
         value: string;
     }
 
+    export interface ThroughputDictValue {
+        downloadTimeInMs: number,
+        downloadedBytes: number,
+        latencyInMs: number
+        serviceLocation: string,
+        value: number,
+    }
+
     /**
      * Dash
      **/
@@ -2052,6 +2060,8 @@ declare namespace dashjs {
 
         getAvailableLocations(): MpdLocation[];
 
+        getAverageLatency(type: MediaType, calculationMode?: string | null, sampleSize?: number): number;
+
         getAverageThroughput(type: MediaType, calculationMode?: string | null, sampleSize?: number): number;
 
         getBufferLength(type: MediaType): number;
@@ -2088,8 +2098,12 @@ declare namespace dashjs {
 
         getProtectionController(): ProtectionController;
 
+        getRawThroughputData(type: MediaType): ThroughputDictValue[];
+
         getRepresentationsByType(type: MediaType, streamId?: string | null): Representation[];
 
+        getSafeAverageThroughput(type: MediaType, calculationMode?: string | null, sampleSize?: number): number;
+
         getSettings(): MediaPlayerSettingClass;
 
         getSource(): string | object;

diff --git a/src/core/Settings.js b/src/core/Settings.js
@@ -284,7 +284,8 @@ import Events from './events/Events.js';
  *                         throughputSlowHalfLifeSeconds: 8,
  *                         throughputFastHalfLifeSeconds: 3,
  *                         latencySlowHalfLifeCount: 2,
- *                         latencyFastHalfLifeCount: 1
+ *                         latencyFastHalfLifeCount: 1,
+ *                         weightDownloadTimeMultiplicationFactor: 0.0015
  *                     }
  *                 },
  *                 maxBitrate: {
@@ -860,12 +861,13 @@ import Events from './events/Events.js';
  * - `increaseScale`: Increase sample size by one if the ratio of current and previous sample is higher or equal this value
  * - `maxMeasurementsToKeep`: Number of samples to keep before sliding samples out of the window
  * - `averageLatencySampleAmount`: Number of latency samples to use (sample size)
- * @property {object} [ewma={throughputSlowHalfLifeSeconds=8,throughputFastHalfLifeSeconds=3,latencySlowHalfLifeCount=2,latencyFastHalfLifeCount=1}]
+ * @property {object} [ewma={throughputSlowHalfLifeSeconds=8,throughputFastHalfLifeSeconds=3,latencySlowHalfLifeCount=2,latencyFastHalfLifeCount=1, weightDownloadTimeMultiplicationFactor=0.0015}]
  * When deriving the throughput based on the exponential weighted moving average these settings define:
  * - `throughputSlowHalfLifeSeconds`: Number by which the weight of the current throughput measurement is divided, see ThroughputModel._updateEwmaValues
  * - `throughputFastHalfLifeSeconds`: Number by which the weight of the current throughput measurement is divided, see ThroughputModel._updateEwmaValues
  * - `latencySlowHalfLifeCount`: Number by which the weight of the current latency is divided, see ThroughputModel._updateEwmaValues
  * - `latencyFastHalfLifeCount`: Number by which the weight of the current latency is divided, see ThroughputModel._updateEwmaValues
+ * - `weightDownloadTimeMultiplicationFactor`: This value is multiplied with the download time in milliseconds to derive the weight for the EWMA calculation.
  */
 
 /**

diff --git a/src/streaming/MediaPlayer.js b/src/streaming/MediaPlayer.js
@@ -1232,6 +1232,20 @@ function MediaPlayer() {
         customParametersModel.restoreDefaultUTCTimingSources();
     }
 
+    /**
+     * Returns the average latency computed in the ThroughputController in millisecond
+     *
+     * @param {MediaType} type
+     * @param {string} calculationMode
+     * @param {number} sampleSize
+     * @return {number} value
+     * @memberof module:MediaPlayer
+     * @instance
+     */
+    function getAverageLatency(type, calculationMode = null, sampleSize = NaN) {
+        return throughputController ? throughputController.getAverageLatency(type, calculationMode, sampleSize) : 0;
+    }
+
     /**
      * Returns the average throughput computed in the ThroughputController in kbit/s
      *
@@ -1246,6 +1260,32 @@ function MediaPlayer() {
         return throughputController ? throughputController.getAverageThroughput(type, calculationMode, sampleSize) : 0;
     }
 
+    /**
+     * Returns the safe average throughput computed in the ThroughputController in kbit/s. The safe average throughput is the average throughput multiplied by bandwidthSafetyFactor
+     *
+     * @param {MediaType} type
+     * @param {string} calculationMode
+     * @param {number} sampleSize
+     * @return {number} value
+     * @memberof module:MediaPlayer
+     * @instance
+     */
+    function getSafeAverageThroughput(type, calculationMode = null, sampleSize = NaN) {
+        return throughputController ? throughputController.getSafeAverageThroughput(type, calculationMode, sampleSize) : 0;
+    }
+
+    /**
+     *  Returns the raw throughput data without calculating the average. This can be used to calculate the current throughput yourself.
+     *
+     * @param {MediaType} type
+     * @return {Array} value
+     * @memberof module:MediaPlayer
+     * @instance
+     */
+    function getRawThroughputData(type) {
+        return throughputController ? throughputController.getRawThroughputData(type) : [];
+    }
+
     /**
      * Sets whether withCredentials on XHR requests for a particular request
      * type is true or false
@@ -2759,6 +2799,7 @@ function MediaPlayer() {
         getAutoPlay,
         getAvailableBaseUrls,
         getAvailableLocations,
+        getAverageLatency,
         getAverageThroughput,
         getBufferLength,
         getCurrentLiveLatency,
@@ -2777,7 +2818,9 @@ function MediaPlayer() {
         getOfflineController,
         getPlaybackRate,
         getProtectionController,
+        getRawThroughputData,
         getRepresentationsByType,
+        getSafeAverageThroughput,
         getSettings,
         getSource,
         getStreamsFromManifest,