📝 doc: Update API Documentation for the feature

canalplus · Mar 2, 2022 · 775d48c · 775d48c
1 parent 6a36c27
commit 775d48c
Show file tree

Hide file tree

Showing 6 changed files with 135 additions and 43 deletions.
diff --git a/doc/api/Buffer_Control/.docConfig.json b/doc/api/Buffer_Control/.docConfig.json
@@ -1,28 +1,35 @@
 {
-  "pages": [
-    {
-      "path": "./setWantedBufferAhead.md",
-      "displayName": "setWantedBufferAhead"
-    },
-    {
-      "path": "./getWantedBufferAhead.md",
-      "displayName": "getWantedBufferAhead"
-    },
-    {
-      "path": "./setMaxBufferBehind.md",
-      "displayName": "setMaxBufferBehind"
-    },
-    {
-      "path": "./getMaxBufferBehind.md",
-      "displayName": "getMaxBufferBehind"
-    },
-    {
-      "path": "./setMaxBufferAhead.md",
-      "displayName": "setMaxBufferAhead"
-    },
-    {
-      "path": "./getMaxBufferAhead.md",
-      "displayName": "getMaxBufferAhead"
-    }
-  ]
-}
+    "pages": [{
+            "path": "./setWantedBufferAhead.md",
+            "displayName": "setWantedBufferAhead"
+        },
+        {
+            "path": "./getWantedBufferAhead.md",
+            "displayName": "getWantedBufferAhead"
+        },
+        {
+            "path": "./setMaxBufferBehind.md",
+            "displayName": "setMaxBufferBehind"
+        },
+        {
+            "path": "./getMaxBufferBehind.md",
+            "displayName": "getMaxBufferBehind"
+        },
+        {
+            "path": "./setMaxBufferAhead.md",
+            "displayName": "setMaxBufferAhead"
+        },
+        {
+            "path": "./getMaxBufferAhead.md",
+            "displayName": "getMaxBufferAhead"
+        },
+        {
+            "path": "./getMaxVideoBufferSize.md",
+            "displayName": "getMaxVideoBufferSize"
+        },
+        {
+            "path": "./setMaxVideoBufferSize.md",
+            "displayName": "setMaxVideoBufferSize"
+        }
+    ]
+}
diff --git a/doc/api/Buffer_Control/getMaxVideoBufferSize.md b/doc/api/Buffer_Control/getMaxVideoBufferSize.md
@@ -0,0 +1,19 @@
+# getMaxBufferSize
+
+## Description
+
+Returns the maximum video buffer memory size limit , in kilobytes.
+
+This setting can be updated either by:
+
+- calling the [setMaxVideoBufferSize](./setMaxVideoBufferSize.md) method.
+- instanciating an RxPlayer with a `maxVideoBufferSize` property set.
+
+## Syntax
+
+```js
+const bufferSize = player.getMaxBufferSize();
+```
+
+  - **return value** `number`: Maximum buffer memory size limit,
+  in kilobytes. 
diff --git a/doc/api/Buffer_Control/setMaxVideoBufferSize.md b/doc/api/Buffer_Control/setMaxVideoBufferSize.md
@@ -0,0 +1,40 @@
+# setMaxVideoBufferSize
+
+## Description
+
+Set the maximum memory the video buffer can take up in the memory, in kilobytes
+Defaults at `Infinity`
+
+Once this value is reached, the player won't try to download new video
+segments anymore.
+
+This feature was designed with devices that have limited memory and trying to play very
+high bitrates tracks in minds. 
+
+However on some custom targets, or just to better control the memory footprint
+of the player, you might want to set this limit.
+
+You can set it to `Infinity` to remove this limit and just let the browser do
+this job instead.
+
+<div class="warning">
+This option will have no effects if we didn't buffer at least <b>MIN_BUFFER_LENGTH</b> 
+<i>( defaults at 5sec )</i>
+</div>
+
+<div class="warning">
+In <i>DirectFile</i> mode (see <a
+href="../Loading_a_Content.md#transport">loadVideo options</a>),
+this method has no effect.
+</div>
+
+## Syntax
+
+```js
+player.setMaxVideoBufferSize(bufferSize);
+```
+
+- **arguments**:
+
+  1. _bufferSize_ `number`: Maximum amount of memory the buffer can download,
+    in kilobytes
diff --git a/doc/api/Creating_a_Player.md b/doc/api/Creating_a_Player.md
@@ -291,6 +291,31 @@ This option will have no effect for contents loaded in <i>Directfile</i>
 mode (see <a href="./Loading_a_Content.md#transport">loadVideo options</a>).
 </div>
 
+### maxVideoBufferSize
+
+_type_: `Number|undefined`
+
+_defaults_: `Infinity`
+
+Set the maximum size of video the buffer in the memory, in kilobytes (kb).
+Once this value is reached, the player won't try to download new video
+segments anymore
+
+<div class="warning">
+The internal checks of the RxPlayer is based on an estimation of what the RxPlayer think
+is currently buffered and an estimation of the size of the next segments. 
+</div>
+
+<div class="warning">
+This option will have no effects if we didn't buffer at least <b>MIN_BUFFER_LENGTH</b> 
+<i>( defaults at 5sec )</i>
+</div>
+
+<div class="warning">
+This option will have no effect for contents loaded in <i>Directfile</i>
+mode (see <a href="./Loading_a_Content.md#transport">loadVideo options</a>).
+</div>
+
 ### preferredAudioTracks
 
 _type_: `Array.<Object|null>`

diff --git a/src/config.ts b/src/config.ts
@@ -181,7 +181,7 @@ export default {
   DEFAULT_WANTED_BUFFER_AHEAD: 30,
 
   /**
-   * Default video buffer memory limit in kilobytes..
+   * Default video buffer memory limit in kilobytes.
    * Once enough video content has been downloaded to fill the buffer up to
    * DEFAULT_MAX_VIDEO_BUFFER_SIZE , we will stop downloading
    * content.
@@ -1233,21 +1233,22 @@ export default {
   BUFFERED_HISTORY_MAXIMUM_ENTRIES: 200,
 
   /**
-   * Minimum buffer (in seconds ) we should have, regardless of memory
+   * Minimum buffer (in seconds) we should have, regardless of memory
    * constraints
    */
   MIN_BUFFER_LENGTH : 5,
 
   /**
-   * Minimum distance (in seconds) from the end
+   * Minimum buffer in seconds ahead relative to current time
    * we should be able to download
-   * Before starting to garbage collect previous segments
+   * Before trying to agressively free up memory
    */
   MIN_BUFFER_DISTANCE_BEFORE_CLEAN_UP: 10,
 
   /**
-   * How much close to the current position we should garbage collect
-   * If we have the memory is saturated
+   * Distance in seconds behind the current position
+   * the player will free up to in the case we agressively free up memory
+   * It is set to avoid playback issues
    */
   UPTO_CURRENT_POSITION_CLEANUP : 5,
 };
diff --git a/src/core/stream/representation/representation_stream.ts b/src/core/stream/representation/representation_stream.ts
@@ -379,16 +379,16 @@ export default function RepresentationStream<TSegmentDataType>({
                                 imminentDiscontinuity: status.imminentDiscontinuity,
                                 hasFinishedLoading: status.hasFinishedLoading,
                                 neededSegments: status.neededSegments } });
-      const gcedPosition = Math.max(
-        0,
-        wantedStartPosition - UPTO_CURRENT_POSITION_CLEANUP);
-
-      const bufferRemoval = status.isBufferFull ?
-            segmentBuffer
-              .removeBuffer(0, gcedPosition)
-              // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-              .pipe(ignoreElements()) :
-            EMPTY;
+      let bufferRemoval = EMPTY;
+      if (status.isBufferFull) {
+        const gcedPosition = Math.max(
+          0,
+          wantedStartPosition - UPTO_CURRENT_POSITION_CLEANUP);
+        bufferRemoval = segmentBuffer
+          .removeBuffer(0, gcedPosition)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+          .pipe(ignoreElements());
+      }
       return status.shouldRefreshManifest ?
         observableConcat(observableOf(EVENTS.needsManifestRefresh()),
                          bufferStatusEvt, bufferRemoval) :