Merge pull request #13 from Sendspin/task/unify-deadband-thresholds

Unify deadband thresholds and remove obsolete properties

Author: chrisuthe

src/Sendspin.SDK/Audio/SyncCorrectionCalculator.cs

@@ -259,19 +259,9 @@ private bool UpdateCorrectionInternal(double smoothedMicroseconds)
         var absError = Math.Abs(smoothedMicroseconds);
 
         // Thresholds from options
-        var deadbandThreshold = _options.EntryDeadbandMicroseconds;
+        var deadbandThreshold = _options.DeadbandMicroseconds;
         var resamplingThreshold = _options.ResamplingThresholdMicroseconds;
 
-        // Use exit deadband (hysteresis) if we're currently correcting
-        if (_currentMode != SyncCorrectionMode.None && absError < _options.ExitDeadbandMicroseconds)
-        {
-            _currentMode = SyncCorrectionMode.None;
-            _targetPlaybackRate = 1.0;
-            _dropEveryNFrames = 0;
-            _insertEveryNFrames = 0;
-            return HasChanged(previousMode, previousDrop, previousInsert, previousRate);
-        }
-
         // Tier 1: Deadband - error is small enough to ignore
         if (absError < deadbandThreshold)
         {

src/Sendspin.SDK/Audio/SyncCorrectionOptions.cs

@@ -29,11 +29,6 @@ namespace Sendspin.SDK.Audio;
 /// filter jitter and prevent oscillation. Proportional correction prevents overshoot
 /// by adjusting rate based on error magnitude rather than using fixed rate steps.
 /// </para>
-/// <para>
-/// <b>Note:</b> The <see cref="EntryDeadbandMicroseconds"/>, <see cref="ExitDeadbandMicroseconds"/>,
-/// and <see cref="BypassDeadband"/> properties are retained for backward compatibility but are no
-/// longer used.
-/// </para>
 /// </remarks>
 /// <example>
 /// <code>
@@ -48,36 +43,15 @@ namespace Sendspin.SDK.Audio;
 public sealed class SyncCorrectionOptions
 {
     /// <summary>
-    /// Gets or sets the error threshold to START correcting (microseconds).
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// <b>Deprecated:</b> This property is no longer used. The sync correction now uses
-    /// fixed discrete thresholds matching the JS library: 1ms deadband, 8ms for 1% correction,
-    /// 15ms for 2% correction.
-    /// </para>
-    /// <para>
-    /// Retained for backward compatibility. Default: 2000 (2ms).
-    /// </para>
-    /// </remarks>
-    [Obsolete("No longer used. Discrete thresholds are now fixed to match JS library.")]
-    public long EntryDeadbandMicroseconds { get; set; } = 2_000;
-
-    /// <summary>
-    /// Gets or sets the error threshold to STOP correcting (microseconds).
+    /// Gets or sets the deadband threshold (microseconds).
+    /// Sync errors below this are ignored — no correction is applied.
     /// </summary>
     /// <remarks>
-    /// <para>
-    /// <b>Deprecated:</b> This property is no longer used. The hysteresis deadband has been
-    /// removed in favor of EMA smoothing and discrete rate steps, which provide more stable
-    /// correction without oscillation.
-    /// </para>
-    /// <para>
-    /// Retained for backward compatibility. Default: 500 (0.5ms).
-    /// </para>
+    /// Matches the JS/CLI spec: 1ms deadband. Errors within this range are
+    /// considered "in sync" and do not trigger rate adjustment or frame manipulation.
+    /// Default: 1000 (1ms).
     /// </remarks>
-    [Obsolete("No longer used. Hysteresis replaced by EMA smoothing.")]
-    public long ExitDeadbandMicroseconds { get; set; } = 500;
+    public long DeadbandMicroseconds { get; set; } = 1_000;
 
     /// <summary>
     /// Gets or sets the maximum playback rate adjustment (0.0 to 1.0).
@@ -194,23 +168,6 @@ public sealed class SyncCorrectionOptions
     /// </remarks>
     public long ScheduledStartGraceWindowMicroseconds { get; set; } = 10_000;
 
-    /// <summary>
-    /// Gets or sets whether to bypass the deadband entirely.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// <b>Deprecated:</b> This property is no longer used. The sync correction now uses
-    /// EMA-smoothed error values with discrete rate steps, which eliminates the need for
-    /// deadband bypass. The EMA filter provides natural smoothing that handles small
-    /// errors without requiring continuous micro-adjustments.
-    /// </para>
-    /// <para>
-    /// Retained for backward compatibility. Default: false.
-    /// </para>
-    /// </remarks>
-    [Obsolete("No longer used. EMA smoothing replaces the need for deadband bypass.")]
-    public bool BypassDeadband { get; set; }
-
     /// <summary>
     /// Gets the minimum playback rate (1.0 - MaxSpeedCorrection).
     /// </summary>
@@ -227,25 +184,11 @@ public sealed class SyncCorrectionOptions
     /// <exception cref="ArgumentException">Thrown when options are invalid.</exception>
     public void Validate()
     {
-        if (EntryDeadbandMicroseconds < 0)
-        {
-            throw new ArgumentException(
-                "EntryDeadbandMicroseconds must be non-negative.",
-                nameof(EntryDeadbandMicroseconds));
-        }
-
-        if (ExitDeadbandMicroseconds < 0)
-        {
-            throw new ArgumentException(
-                "ExitDeadbandMicroseconds must be non-negative.",
-                nameof(ExitDeadbandMicroseconds));
-        }
-
-        if (ExitDeadbandMicroseconds >= EntryDeadbandMicroseconds && !BypassDeadband)
+        if (DeadbandMicroseconds < 0)
         {
             throw new ArgumentException(
-                "ExitDeadbandMicroseconds must be less than EntryDeadbandMicroseconds to create hysteresis.",
-                nameof(ExitDeadbandMicroseconds));
+                "DeadbandMicroseconds must be non-negative.",
+                nameof(DeadbandMicroseconds));
         }
 
         if (MaxSpeedCorrection is <= 0 or > 1.0)
@@ -311,8 +254,7 @@ public void Validate()
     /// <returns>A new instance with the same values.</returns>
     public SyncCorrectionOptions Clone() => new()
     {
-        EntryDeadbandMicroseconds = EntryDeadbandMicroseconds,
-        ExitDeadbandMicroseconds = ExitDeadbandMicroseconds,
+        DeadbandMicroseconds = DeadbandMicroseconds,
         MaxSpeedCorrection = MaxSpeedCorrection,
         CorrectionTargetSeconds = CorrectionTargetSeconds,
         ResamplingThresholdMicroseconds = ResamplingThresholdMicroseconds,
@@ -321,7 +263,6 @@ public void Validate()
         StartupGracePeriodMicroseconds = StartupGracePeriodMicroseconds,
         ScheduledStartGraceWindowMicroseconds = ScheduledStartGraceWindowMicroseconds,
         ReconnectStabilizationMicroseconds = ReconnectStabilizationMicroseconds,
-        BypassDeadband = BypassDeadband,
     };
 
     /// <summary>
@@ -338,8 +279,7 @@ public void Validate()
     /// </remarks>
     public static SyncCorrectionOptions CliDefaults => new()
     {
-        EntryDeadbandMicroseconds = 2_000,
-        ExitDeadbandMicroseconds = 500,
+        DeadbandMicroseconds = 1_000,
         MaxSpeedCorrection = 0.04,        // 4% vs Windows 2%
         CorrectionTargetSeconds = 2.0,    // 2s vs Windows 3s
         ResamplingThresholdMicroseconds = 15_000,

src/Sendspin.SDK/Audio/TimedAudioBuffer.cs

@@ -1080,7 +1080,7 @@ private void CalculateSyncError(long currentLocalTime)
     /// Implements a tiered correction strategy:
     /// </para>
     /// <list type="bullet">
-    /// <item>Error &lt; 1ms (deadband): No correction, playback rate = 1.0</item>
+    /// <item>Error &lt; deadband (default 1ms): No correction, playback rate = 1.0</item>
     /// <item>Error 1-15ms: Proportional rate adjustment (error / targetSeconds), clamped to max</item>
     /// <item>Error &gt; 15ms: Frame drop/insert for faster correction</item>
     /// </list>
@@ -1125,12 +1125,12 @@ private void UpdateCorrectionRate()
         // Use smoothed error for correction decisions (filters measurement jitter)
         var absError = Math.Abs(_smoothedSyncErrorMicroseconds);
 
-        // Thresholds for correction tiers
-        const long DeadbandThreshold = 1_000;      // 1ms - no correction below this
-        const long ResamplingThreshold = 15_000;   // 15ms - above this use drop/insert
+        // Thresholds for correction tiers (from options)
+        var deadbandThreshold = _syncOptions.DeadbandMicroseconds;
+        var resamplingThreshold = _syncOptions.ResamplingThresholdMicroseconds;
 
         // Tier 1: Deadband - error is small enough to ignore
-        if (absError < DeadbandThreshold)
+        if (absError < deadbandThreshold)
         {
             LogCorrectionModeTransition(SyncCorrectionMode.None);
             SetTargetPlaybackRate(1.0);
@@ -1143,7 +1143,7 @@ private void UpdateCorrectionRate()
         // Rate = 1.0 + (error_µs / target_seconds / 1,000,000)
         // This calculates the rate needed to eliminate the error over the target time.
         // Example: 10ms error with 3s target → rate = 1.00333 (0.33% faster)
-        if (absError < ResamplingThreshold)
+        if (absError < resamplingThreshold)
         {
             // Log transition from drop/insert mode back to resampling (effectively None for drop/insert)
             LogCorrectionModeTransition(SyncCorrectionMode.Resampling);