From 3b950bc19c07a07b180542a9a847499a8194597c Mon Sep 17 00:00:00 2001
From: Daniel Silhavy <daniel.silhavy@fokus.fraunhofer.de>
Date: Fri, 26 Jan 2024 16:54:59 +0100
Subject: [PATCH] Add description for insufficient-buffer-rule.md

---
 .../advanced/abr/insufficient-buffer-rule.md  | 55 +++++++++++++++++++
 pages/advanced/abr/settings.md                | 16 +++---
 2 files changed, 63 insertions(+), 8 deletions(-)
 create mode 100644 pages/advanced/abr/insufficient-buffer-rule.md

diff --git a/pages/advanced/abr/insufficient-buffer-rule.md b/pages/advanced/abr/insufficient-buffer-rule.md
new file mode 100644
index 0000000000..a3579d94f9
--- /dev/null
+++ b/pages/advanced/abr/insufficient-buffer-rule.md
@@ -0,0 +1,55 @@
+---
+layout: default
+title: InsufficientBufferRule
+parent: Adaptive Bitrate Streaming
+grand_parent: Advanced Features
+---
+
+# InsufficientBufferRule
+
+## Description
+
+The `InsufficientBufferRule` verifies each ABR choice to make sure the download is unlikely
+to cause a rebuffering event. The rule is best explained by looking at a concrete example. Assume the following values:
+
+* `currentThroughput` = 5Mbit/s
+* `currentSafeThroughput` = `currentThroughput` * `throughputSafetyFactor` = 5Mbit/s * 0.9 = 4.5 Mbit/s
+* `currentBufferLevel` = 10 seconds
+* `segmentDuration` = 4 seconds
+
+To avoid a buffer underrun we need to finish the download of the next segment in 10 seconds. This means we need to
+download 4 seconds of content in 10 seconds. This leads us to the following expression that we need to solve:
+
+`possibleBitrate <= currentSafeThroughput * currentBufferLevel / segmentDuration`
+
+Plugging the examples values from above we get:
+
+`possibleBitrate <= 4.5 Mbit/s * 10s / 4s`
+
+So in this case we can select a maximum bitrate of `11.25 Mbit/s`.
+
+## Configuration Options
+
+| Parameter                | Description                                                                                                               |
+|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------|
+| `throughputSafetyFactor` | The safety factor that is applied to the derived throughput, see example in the Description.                              |
+| `segmentIgnoreCount`     | This rule is not taken into account until the first `segmentIgnoreCount` media segments have been appended to the buffer. |
+
+## Example
+
+```js
+player.updateSettings({
+    streaming: {
+        abr: {
+            activeRules: {
+                insufficientBufferRule: {
+                    active: true,
+                    parameters: {
+                        throughputSafetyFactor: 0.9,
+                    }
+                }
+            }
+        }
+    }
+});
+```
diff --git a/pages/advanced/abr/settings.md b/pages/advanced/abr/settings.md
index d8f5e1b225..c5d44118f0 100644
--- a/pages/advanced/abr/settings.md
+++ b/pages/advanced/abr/settings.md
@@ -88,14 +88,14 @@ player.updateSettings({
 });
 ```
 
-| ABR Rule                 | Description                                     |
-|:-------------------------|:------------------------------------------------|
-| `insufficientBufferRule` | tbd                                             |
-| `switchHistoryRule`      | tbd                                             |
-| `droppedFramesRule`      | tbd                                             |
-| `abandonRequestsRule`    | [AbandonRequestRule](abandon-request-rule.html) |
-| `l2ARule`                | [L2ARule](l2a.html)                             |
-| `loLPRule`               | [LoL+](lol_plus.html)                           |
+| ABR Rule                 | Description                                             |
+|:-------------------------|:--------------------------------------------------------|
+| `insufficientBufferRule` | [InsufficientBufferRule](insufficient-buffer-rule.html) |
+| `switchHistoryRule`      | tbd                                                     |
+| `droppedFramesRule`      | tbd                                                     |
+| `abandonRequestsRule`    | [AbandonRequestRule](abandon-request-rule.html)         |
+| `l2ARule`                | [L2ARule](l2a.html)                                     |
+| `loLPRule`               | [LoL+](lol_plus.html)                                   |
 
 A detailed example is available [here](https://reference.dashif.org/dash.js/nightly/samples/abr/abr.html).