feat: add liveSyncTargetLatency option and deprecate liveSyncMinLaten…

…cy and liveSyncMaxLatency options (#6822)

Follow-up from #6683
to add a target latency config and deprecate the existing min/max
options.

demo/config.js

@@ -491,22 +491,18 @@ shakaDemo.Config = class {
         .addBoolInput_('Disable Video Prefetch',
             'streaming.disableVideoPrefetch')
         .addBoolInput_('Live Sync', 'streaming.liveSync')
-        .addNumberInput_('Target latency tolerance',
-            'streaming.liveSyncTargetLatencyTolerance',
+        .addNumberInput_('Target latency for live sync',
+            'streaming.liveSyncTargetLatency',
             /* canBeDecimal= */ true,
             /* canBeZero= */ true)
-        .addNumberInput_('Max latency for live sync',
-            'streaming.liveSyncMaxLatency',
+        .addNumberInput_('Target latency tolerance',
+            'streaming.liveSyncTargetLatencyTolerance',
             /* canBeDecimal= */ true,
             /* canBeZero= */ true)
         .addNumberInput_('Playback rate for live sync',
             'streaming.liveSyncPlaybackRate',
             /* canBeDecimal= */ true,
             /* canBeZero= */ false)
-        .addNumberInput_('Min latency for live sync',
-            'streaming.liveSyncMinLatency',
-            /* canBeDecimal= */ true,
-            /* canBeZero= */ true)
         .addNumberInput_('Min playback rate for live sync',
             'streaming.liveSyncMinPlaybackRate',
             /* canBeDecimal= */ true)

docs/tutorials/upgrade.md

@@ -104,6 +104,9 @@ application:
       `shaka.util.StringUtils.htmlUnescape` for this purpose.
     - `streaming.useNativeHlsOnSafari` has removed. Now we have another config to do the same for FairPlay `streaming.useNativeHlsForFairPlay` or for HLS (any browser) `streaming.preferNativeHls`.
     - `mediaSource.sourceBufferExtraFeatures` has been replaced with `mediaSource.addExtraFeaturesToSourceBuffer` callback.
+    - `streaming.liveSyncMinLatency` and `streaming.liveSyncMaxLatency` have
+      been removed in favor of `streaming.liveSyncTargetLatency`. (deprecated
+      in v4.10.0)
 
   - Plugin changes:
     - `TextDisplayer` plugins must implement the `configure()` method.

externs/shaka/player.js

@@ -1300,10 +1300,9 @@ shaka.extern.ManifestConfiguration;
  *   disableTextPrefetch: boolean,
  *   disableVideoPrefetch: boolean,
  *   liveSync: boolean,
+ *   liveSyncTargetLatency: number,
  *   liveSyncTargetLatencyTolerance: number,
- *   liveSyncMaxLatency: number,
  *   liveSyncPlaybackRate: number,
- *   liveSyncMinLatency: number,
  *   liveSyncMinPlaybackRate: number,
  *   liveSyncPanicMode: boolean,
  *   liveSyncPanicThreshold: number,
@@ -1466,19 +1465,16 @@ shaka.extern.ManifestConfiguration;
  *   rate. Defaults to <code>false</code>.
  *   Note: on some SmartTVs, if this is activated, it may not work or the sound
  *   may be lost when activated.
+ * @property {number} liveSyncTargetLatency
+ *   Preferred latency, in seconds. Effective only if liveSync is true.
+ *   Defaults to <code>0.5</code>.
  * @property {number} liveSyncTargetLatencyTolerance
  *   Latency tolerance for target latency, in seconds. Effective only if
  *   liveSync is true. Defaults to <code>0.5</code>.
- * @property {number} liveSyncMaxLatency
- *   Maximum acceptable latency, in seconds. Effective only if liveSync is
- *   true. Defaults to <code>1</code>.
  * @property {number} liveSyncPlaybackRate
  *   Playback rate used for latency chasing. It is recommended to use a value
  *   between 1 and 2. Effective only if liveSync is true. Defaults to
  *   <code>1.1</code>.
- * @property {number} liveSyncMinLatency
- *   Minimum acceptable latency, in seconds. Effective only if liveSync is
- *   true. Defaults to <code>0</code>.
  * @property {number} liveSyncMinPlaybackRate
  *   Minimum playback rate used for latency chasing. It is recommended to use a
  *   value between 0 and 1. Effective only if liveSync is true. Defaults to

lib/player.js

@@ -3650,6 +3650,37 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
           'streaming.preferNativeHls instead.');
     }
 
+    // map liveSyncMinLatency and liveSyncMaxLatency to liveSyncTargetLatency
+    // if liveSyncTargetLatency isn't set.
+    if (config['streaming'] &&
+      !('liveSyncTargetLatency' in config['streaming']) &&
+      ('liveSyncMinLatency' in config['streaming'] ||
+       'liveSyncMaxLatency' in config['streaming'])) {
+      const min = config['streaming']['liveSyncMinLatency'] || 0;
+      const max = config['streaming']['liveSyncMaxLatency'] || 1;
+      const mid = Math.abs(max - min) / 2;
+      config['streaming']['liveSyncTargetLatency'] = min + mid;
+      config['streaming']['liveSyncTargetLatencyTolerance'] = mid;
+    }
+    // Deprecate 'streaming.liveSyncMaxLatency' configuration.
+    if (config['streaming'] && 'liveSyncMaxLatency' in config['streaming']) {
+      shaka.Deprecate.deprecateFeature(5,
+          'streaming.liveSyncMaxLatency',
+          'Please Use streaming.liveSyncTargetLatency and ' +
+          'streaming.liveSyncTargetLatencyTolerance instead. ' +
+          'Or, set the values in your DASH manifest');
+      delete config['streaming']['liveSyncMaxLatency'];
+    }
+    // Deprecate 'streaming.liveSyncMinLatency' configuration.
+    if (config['streaming'] && 'liveSyncMinLatency' in config['streaming']) {
+      shaka.Deprecate.deprecateFeature(5,
+          'streaming.liveSyncMinLatency',
+          'Please Use streaming.liveSyncTargetLatency and ' +
+          'streaming.liveSyncTargetLatencyTolerance instead. ' +
+          'Or, set the values in your DASH manifest');
+      delete config['streaming']['liveSyncMinLatency'];
+    }
+
     // Deprecate 'mediaSource.sourceBufferExtraFeatures' configuration.
     if (config['mediaSource'] &&
         'sourceBufferExtraFeatures' in config['mediaSource']) {
@@ -6325,44 +6356,41 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
 
     let liveSyncMaxLatency;
     let liveSyncPlaybackRate;
+    let liveSyncMinLatency;
+    let liveSyncMinPlaybackRate;
+    const liveSyncTargetLatencyTolerance =
+      this.config_.streaming.liveSyncTargetLatencyTolerance;
+
     if (this.config_.streaming.liveSync) {
-      liveSyncMaxLatency = this.config_.streaming.liveSyncMaxLatency;
+      const liveSyncTargetLatency =
+        this.config_.streaming.liveSyncTargetLatency;
+      liveSyncMaxLatency =
+        liveSyncTargetLatency + liveSyncTargetLatencyTolerance;
+      liveSyncMinLatency = Math.max(0,
+          liveSyncTargetLatency - liveSyncTargetLatencyTolerance);
       liveSyncPlaybackRate = this.config_.streaming.liveSyncPlaybackRate;
+      liveSyncMinPlaybackRate = this.config_.streaming.liveSyncMinPlaybackRate;
     } else {
       // serviceDescription must override if it is defined in the MPD and
       // liveSync configuration is not set.
       if (this.manifest_ && this.manifest_.serviceDescription) {
-        liveSyncMaxLatency = this.config_.streaming.liveSyncMaxLatency;
         if (this.manifest_.serviceDescription.targetLatency != null) {
           liveSyncMaxLatency =
               this.manifest_.serviceDescription.targetLatency +
-              this.config_.streaming.liveSyncTargetLatencyTolerance;
+              liveSyncTargetLatencyTolerance;
         } else if (this.manifest_.serviceDescription.maxLatency != null) {
           liveSyncMaxLatency = this.manifest_.serviceDescription.maxLatency;
         }
-        liveSyncPlaybackRate =
-          this.manifest_.serviceDescription.maxPlaybackRate ||
-          this.config_.streaming.liveSyncPlaybackRate;
-      }
-    }
-
-    let liveSyncMinLatency;
-    let liveSyncMinPlaybackRate;
-    if (this.config_.streaming.liveSync) {
-      liveSyncMinLatency = this.config_.streaming.liveSyncMinLatency;
-      liveSyncMinPlaybackRate = this.config_.streaming.liveSyncMinPlaybackRate;
-    } else {
-      // serviceDescription must override if it is defined in the MPD and
-      // liveSync configuration is not set.
-      if (this.manifest_ && this.manifest_.serviceDescription) {
-        liveSyncMinLatency = this.config_.streaming.liveSyncMinLatency;
         if (this.manifest_.serviceDescription.targetLatency != null) {
-          liveSyncMinLatency =
+          liveSyncMinLatency = Math.max(0,
               this.manifest_.serviceDescription.targetLatency -
-              this.config_.streaming.liveSyncTargetLatencyTolerance;
+              liveSyncTargetLatencyTolerance);
         } else if (this.manifest_.serviceDescription.minLatency != null) {
           liveSyncMinLatency = this.manifest_.serviceDescription.minLatency;
         }
+        liveSyncPlaybackRate =
+          this.manifest_.serviceDescription.maxPlaybackRate ||
+          this.config_.streaming.liveSyncPlaybackRate;
         liveSyncMinPlaybackRate =
           this.manifest_.serviceDescription.minPlaybackRate ||
           this.config_.streaming.liveSyncMinPlaybackRate;

lib/util/player_configuration.js

@@ -239,10 +239,9 @@ shaka.util.PlayerConfiguration = class {
       disableTextPrefetch: false,
       disableVideoPrefetch: false,
       liveSync: false,
+      liveSyncTargetLatency: 0.5,
       liveSyncTargetLatencyTolerance: 0.5,
-      liveSyncMaxLatency: 1,
       liveSyncPlaybackRate: 1.1,
-      liveSyncMinLatency: 0,
       liveSyncMinPlaybackRate: 0.95,
       liveSyncPanicMode: false,
       liveSyncPanicThreshold: 60,