feat: Support customizing clearBuffers and safeMargin when select var…

…iants by label (#4770)

Currently, selectVariantsByLabel doesn't support customizing
clearBuffers and safeMargin. This pr is to change the function
signature, so that we'll able to decide if we want to keep some amount
of buffer when we change track.

AUTHORS

@@ -88,6 +88,7 @@ ViacomCBS <*@viacomcbs.com>
 Vincent Valot <[email protected]>
 V-Nova Limited <*@v-nova.com>
 Wayne Morgan <[email protected]>
+Wen Ren <[email protected]>
 Raymond Cheng <[email protected]>
 Blue Billywig <*@bluebillywig.com>
 João Nabais <[email protected]>

CONTRIBUTORS

@@ -127,6 +127,7 @@ Vignesh Venkatasubramanian <[email protected]>
 Vincent Valot <[email protected]>
 Vinod Balakrishnan <[email protected]>
 Wayne Morgan <[email protected]>
+Wen Ren <[email protected]>
 Yohann Connell <[email protected]>
 Raymond Cheng <[email protected]>
 Janroel Koppen <[email protected]>

lib/player.js

@@ -4242,9 +4242,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * are expected to have the same variant.audio.
    *
    * @param {string} label
+   * @param {boolean=} clearBuffer Optional clear buffer or not when
+   *  switch to new variant
+   *  Defaults to true if not provided
+   * @param {number=} safeMargin Optional amount of buffer (in seconds) to
+   *   retain when clearing the buffer.
+   *   Defaults to 0 if not provided. Ignored if clearBuffer is false.
    * @export
    */
-  selectVariantsByLabel(label) {
+  selectVariantsByLabel(label, clearBuffer = true, safeMargin = 0) {
     if (this.manifest_ && this.playhead_) {
       let firstVariantWithLabel = null;
       for (const variant of this.manifest_.variants) {
@@ -4268,7 +4274,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
           new shaka.media.PreferenceBasedCriteria(
               firstVariantWithLabel.language, '', 0, label);
 
-      this.chooseVariantAndSwitch_();
+      this.chooseVariantAndSwitch_(clearBuffer, safeMargin);
     }
   }
 
@@ -5713,9 +5719,15 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
    * Called after a config change, a key status event, or an explicit language
    * change.
    *
+   * @param {boolean=} clearBuffer Optional clear buffer or not when
+   *  switch to new variant
+   *  Defaults to true if not provided
+   * @param {number=} safeMargin Optional amount of buffer (in seconds) to
+   *   retain when clearing the buffer.
+   *   Defaults to 0 if not provided. Ignored if clearBuffer is false.
    * @private
    */
-  chooseVariantAndSwitch_() {
+  chooseVariantAndSwitch_(clearBuffer = true, safeMargin = 0) {
     goog.asserts.assert(this.config_, 'Must not be destroyed');
 
     // Because we're running this after a config change (manual language
@@ -5724,7 +5736,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
     const chosenVariant = this.chooseVariant_();
     if (chosenVariant) {
       this.switchVariant_(chosenVariant, /* fromAdaptation= */ true,
-          /* clearBuffers= */ true, /* safeMargin= */ 0);
+          clearBuffer, safeMargin);
     }
   }