Quantize offsets diffs (adding deadband) (#749)

* Quantize offsets diffs (adding deadband)
Also reuse maxDriftAdjustment for start time adjustment instead of the constant

* spelling

Author: milos-lk

pkg/synchronizer/track.go

@@ -34,7 +34,6 @@ import (
 const (
 	cStartTimeAdjustWindow    = 2 * time.Minute
 	cStartTimeAdjustThreshold = 5 * time.Second
-	cStartTimeAdjustStep      = 5 * time.Millisecond
 
 	cHighDriftLoggingThreshold = 20 * time.Millisecond
 )
@@ -646,6 +645,12 @@ func (t *TrackSynchronizer) shouldAdjustPTS() bool {
 	if t.track.Kind() == webrtc.RTPCodecTypeAudio && !t.rtcpSenderReportRebaseEnabled {
 		adjustmentEnabled = !t.audioPTSAdjustmentsDisabled
 	}
+	// add a deadband of t.maxDriftAdjustment to make sure no PTS adjustment is smaller than that
+	diff := t.desiredPTSOffset - t.currentPTSOffset
+	if diff > -t.maxDriftAdjustment && diff < t.maxDriftAdjustment {
+		return false
+	}
+
 	return adjustmentEnabled && (t.currentPTSOffset != t.desiredPTSOffset)
 }
 
@@ -657,11 +662,11 @@ func (t *TrackSynchronizer) applyQuantizedStartTimeAdvance(deltaTotal time.Durat
 	// include any prior residual
 	deltaTotal += t.startTimeAdjustResidual
 
-	quanta := deltaTotal / cStartTimeAdjustStep
-	residual := deltaTotal % cStartTimeAdjustStep
+	quanta := deltaTotal / t.maxDriftAdjustment
+	residual := deltaTotal % t.maxDriftAdjustment
 
 	if quanta > 0 {
-		applied := quanta * cStartTimeAdjustStep
+		applied := quanta * t.maxDriftAdjustment
 		t.startTime = t.startTime.Add(-applied)
 		t.totalStartTimeAdjustment += applied
 		t.startTimeAdjustResidual = residual

pkg/synchronizer/track_test.go

@@ -164,3 +164,86 @@ func TestGetPTSWithRebase_PropelsForward(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, want, adj2)
 }
+
+func TestShouldAdjustPTS_Deadband_Suppresses(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeVideo) // video avoids audio gating path
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+
+	// within dead-band: +4ms
+	ts.desiredPTSOffset = 104 * time.Millisecond
+
+	// ensure throttle window has elapsed
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.False(t, ts.shouldAdjustPTS(), "delta < step should suppress adjustment")
+}
+
+func TestShouldAdjustPTS_Deadband_BoundaryAdjusts(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeVideo)
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+
+	// exactly at boundary: +5ms
+	ts.desiredPTSOffset = 105 * time.Millisecond
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.True(t, ts.shouldAdjustPTS(), "delta == step should allow adjustment")
+}
+
+func TestShouldAdjustPTS_Deadband_AboveAdjusts(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeVideo)
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+
+	// above dead-band: +12ms
+	ts.desiredPTSOffset = 112 * time.Millisecond
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.True(t, ts.shouldAdjustPTS(), "delta > step should allow adjustment")
+}
+
+func TestShouldAdjustPTS_Deadband_NegativeDelta_Suppresses(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeVideo)
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+
+	// within dead-band on negative side: -4ms
+	ts.desiredPTSOffset = 96 * time.Millisecond
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.False(t, ts.shouldAdjustPTS(), "negative delta with |delta| < step should suppress adjustment")
+}
+
+func TestShouldAdjustPTS_Deadband_NegativeDelta_AboveAdjusts(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeVideo)
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+
+	// beyond dead-band on negative side: -6ms
+	ts.desiredPTSOffset = 94 * time.Millisecond
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.True(t, ts.shouldAdjustPTS(), "negative delta with |delta| > step should allow adjustment")
+}
+
+func TestShouldAdjustPTS_AudioGating_DisabledBlocks(t *testing.T) {
+	clock := uint32(48000)
+	ts := newTSForTests(t, clock, webrtc.RTPCodecTypeAudio)
+
+	// Force the path where audio gating can block adjustments:
+	ts.rtcpSenderReportRebaseEnabled = false
+	ts.audioPTSAdjustmentsDisabled = true
+
+	ts.maxDriftAdjustment = 5 * time.Millisecond
+	ts.currentPTSOffset = 100 * time.Millisecond
+	ts.desiredPTSOffset = 140 * time.Millisecond // large delta
+	ts.nextPTSAdjustmentAt = mono.Now().Add(-time.Second)
+
+	require.False(t, ts.shouldAdjustPTS(), "audio gating should block adjustment when disabled")
+}