Add dropped-frames-rule.md

Dash-Industry-Forum · Jan 29, 2024 · 67398f4 · 67398f4
1 parent 245588e
commit 67398f4
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 7 deletions.
diff --git a/pages/advanced/abr/abandon-request-rule.md b/pages/advanced/abr/abandon-request-rule.md
@@ -59,7 +59,7 @@ if (remainingBytesToDownload > totalBytesForOptimalRepresentation) {
 player.updateSettings({
     streaming: {
         abr: {
-            activeRules: {
+            rules: {
                 abandonRequestsRule: {
                     active: true,
                     parameters: {

diff --git a/pages/advanced/abr/dropped-frames-rule.md b/pages/advanced/abr/dropped-frames-rule.md
@@ -0,0 +1,53 @@
+---
+layout: default
+title: DroppedFramesRule
+parent: Adaptive Bitrate Streaming
+grand_parent: Advanced Features
+---
+
+# DroppedFramesRule
+
+## Description
+
+While the current throughput and the current buffer level might allow playing the video stream on a high
+quality `Representation` the underlying platform might not be able to render the content without dropping frames.
+Dropped frames refer to video frames that are not successfully delivered or displayed during playback. This can occur
+when the video playback system is unable to keep up with the required frame rate, resulting in skipped frames. Dropped
+frames can cause a decrease in video quality and a disruption in smooth playback.
+
+The `DroppedFramesRule` monitors the ratio of dropped frames and total frames and reduces the video quality if the ratio
+exceeds the value defined in `droppedFramesPercentageThreshold`:
+
+````js
+if (totalFrames > settings.get().streaming.abr.rules.droppedFramesRule.parameters.minimumSampleSize 
+    && droppedFrames / totalFrames > settings.get().streaming.abr.rules.droppedFramesRule.parameters.droppedFramesPercentageThreshold) {
+    newRepresentation = representations[i - 1];
+}
+````
+
+## Configuration Options
+
+| Parameter                          | Description                                                                                                                               |
+|:-----------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------|
+| `minimumSampleSize`                | Sum of rendered and dropped frames required for each Representation before the rule kicks in.                                             |
+| `droppedFramesPercentageThreshold` | Minimum percentage of dropped frames compared to total frames to trigger a quality downs-switch. Values are defined in the range of 0 - 1 |
+
+## Example
+
+```js
+player.updateSettings({
+    streaming: {
+        abr: {
+            rules: {
+                droppedFramesRule: {
+                    active: true,
+                    parameters: {
+                        minimumSampleSize: 375,
+                        droppedFramesPercentageThreshold: 0.15
+                    }
+                }
+            }
+        }
+    }
+});
+```
diff --git a/pages/advanced/abr/insufficient-buffer-rule.md b/pages/advanced/abr/insufficient-buffer-rule.md
@@ -41,7 +41,7 @@ So in this case we can select a maximum bitrate of `11.25 Mbit/s`.
 player.updateSettings({
     streaming: {
         abr: {
-            activeRules: {
+            rules: {
                 insufficientBufferRule: {
                     active: true,
                     parameters: {

diff --git a/pages/advanced/abr/settings.md b/pages/advanced/abr/settings.md
@@ -31,7 +31,7 @@ ABR rule (`bolaRule`). The `abr` section in `Settings.js` allows a reconfigurati
 player.updateSettings({
     streaming: {
         abr: {
-            activeRules: {
+            rules: {
                 throughputRule: {
                     active: true
                 },
@@ -64,7 +64,7 @@ can be dynamically enabled and disabled.
 ```js
 player.updateSettings({
     abr: {
-        activeRules: {
+        rules: {
             insufficientBufferRule: {
                 active: false
             },
@@ -92,7 +92,7 @@ player.updateSettings({
 |:-------------------------|:--------------------------------------------------------|
 | `insufficientBufferRule` | [InsufficientBufferRule](insufficient-buffer-rule.html) |
 | `switchHistoryRule`      | tbd                                                     |
-| `droppedFramesRule`      | tbd                                                     |
+| `droppedFramesRule`      | [DroppedFramesRule](dropped-frames-rule.html)           |
 | `abandonRequestsRule`    | [AbandonRequestRule](abandon-request-rule.html)         |
 | `l2ARule`                | [L2ARule](l2a.html)                                     |
 | `loLPRule`               | [LoL+](lol_plus.html)                                   |
@@ -108,7 +108,7 @@ use `player.addABRCustomRule()` to add your new rule:
 /* don't use dash.js default rules */
 player.updateSettings({
     abr: {
-        activeRules: {
+        rules: {
             throughputRule: {
                 active: false
             },

diff --git a/pages/advanced/abr/throughput-rule.md b/pages/advanced/abr/throughput-rule.md
@@ -31,7 +31,7 @@ parameters are documented [here](throughput-calculation.html).
 player.updateSettings({
     streaming: {
         abr: {
-            activeRules: {
+            rules: {
                 throughputRule: {
                     active: true
                 }