@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.255 → 1.0.256

package/dist/SpatialAudioManager.d.ts

@@ -50,7 +50,6 @@ export declare class SpatialAudioManager extends EventManager {
     private localParticipantId;
     private isMasterMuted;
     private smoothedPanValues;
-    private lastGainValue;
     private lastPanValue;
     private lastSpatialUpdateTime;
     private _spatialDebugTimes;
@@ -60,6 +59,9 @@ export declare class SpatialAudioManager extends EventManager {
     private cachedSpeakerPositions;
     private cachedListenerPosition;
     private positionSnapThreshold;
+    private cachedGainValues;
+    private gainChangeThreshold;
+    private minimumStableGain;
     private _listenerDebugLogTime?;
     private mlSuppressor;
     private mlModelReady;

package/dist/SpatialAudioManager.js

@@ -23,9 +23,6 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         // PAN SMOOTHING: Prevents random left/right jumping
         // Stores the previous smoothed pan value for each participant
         this.smoothedPanValues = new Map();
-        // GAIN SMOOTHING: Prevents audio clicks/pops from rapid gain changes
-        // Tracks last applied gain value per participant for smooth ramping
-        this.lastGainValue = new Map();
         // PAN SMOOTHING: Tracks last applied pan value to skip micro-changes
         this.lastPanValue = new Map();
         // UPDATE THROTTLE: Tracks last spatial update time to prevent too-frequent updates
@@ -49,6 +46,15 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         // 0.30m = 30cm - ignores pixel streaming jitter, physics wobble, breathing
         // ALIGNED with server-side 100cm filter - this catches smaller jitter
         this.positionSnapThreshold = 0.30;
+        // GAIN STABILIZATION: Prevents gain fluctuations when distance is stable
+        // Caches last calculated gain value for each participant
+        this.cachedGainValues = new Map();
+        // Minimum gain change (0-1 scale) to trigger update
+        // 0.08 = 8% change required - filters out tiny distance jitter
+        this.gainChangeThreshold = 0.08;
+        // Minimum stable gain floor - never go below this when participant is audible
+        // This ensures audio is always clearly audible when within max distance
+        this.minimumStableGain = 0.15; // 15% minimum when within range
         // NOTE: Rate limiting variables removed - setTargetAtTime provides sufficient smoothing
         // The smoothPanValue() and position snapping handle jitter reduction
         // ML Noise Suppressor (TensorFlow.js-based)
@@ -401,7 +407,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             if (distance >= maxDistance) {
                 // Smooth fade to zero - prevents click (100ms fade)
                 nodes.gain.gain.setTargetAtTime(0, this.audioContext.currentTime, 0.033);
-                this.lastGainValue.set(participantId, 0);
+                this.cachedGainValues.set(participantId, 0);
                 return; // Skip all other processing
             }
             // Step 3: Calculate relative vector (speaker relative to listener)
@@ -433,23 +439,52 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             // SMOOTH THE PAN VALUE to prevent random left/right jumping
             const smoothedPanValue = this.smoothPanValue(participantId, rawPanValue);
             const panning = this.panningFromPanValue(smoothedPanValue, dxLocal);
-            // Calculate gain DIRECTLY based on distance - NO complex smoothing
-            // The gain formula: sqrt curve from 100% (0.5m) to 20% (15m)
-            const gain = this.calculateLogarithmicGain(distance);
+            // Calculate gain based on distance
+            const calculatedGain = this.calculateLogarithmicGain(distance);
+            let newGainValue = calculatedGain / 100; // Convert to 0-1 range
+            // Apply minimum stable gain floor - ensures audio is always clearly audible
+            // when within max distance (15m). This prevents "too quiet" audio.
+            newGainValue = Math.max(newGainValue, this.minimumStableGain);
+            // GAIN STABILIZATION: Only update gain if change exceeds threshold
+            // This prevents audio fluctuations when users are stationary
+            const cachedGain = this.cachedGainValues.get(participantId);
+            let finalGainValue = newGainValue;
+            if (cachedGain !== undefined && cachedGain > 0) {
+                const gainChange = Math.abs(newGainValue - cachedGain);
+                // HYSTERESIS: Use different thresholds for increasing vs decreasing gain
+                // This prevents oscillation around threshold boundaries
+                const isIncreasing = newGainValue > cachedGain;
+                const effectiveThreshold = isIncreasing
+                    ? this.gainChangeThreshold * 0.8 // Easier to increase (respond to getting closer)
+                    : this.gainChangeThreshold * 1.2; // Harder to decrease (resist getting quieter)
+                if (gainChange < effectiveThreshold) {
+                    // Change too small - keep cached value for stability
+                    finalGainValue = cachedGain;
+                }
+                else {
+                    // Significant change - use weighted average for smooth transition
+                    // Blend 70% new value with 30% cached value
+                    finalGainValue = newGainValue * 0.7 + cachedGain * 0.3;
+                    this.cachedGainValues.set(participantId, finalGainValue);
+                }
+            }
+            else {
+                // First time or was muted - cache the value
+                this.cachedGainValues.set(participantId, newGainValue);
+            }
             // Apply panning
             this.applyStereoPanning(participantId, panning);
             // Apply gain with Web Audio's built-in smoothing (setTargetAtTime)
-            // This is the ONLY smoothing needed - no additional rate limiting
-            const gainValue = gain / 100; // Convert to 0-1 range
             const currentTime = this.audioContext.currentTime;
             try {
                 // setTargetAtTime provides smooth exponential interpolation
-                // Time constant 0.1 = ~300ms to settle (prevents clicks)
-                nodes.gain.gain.setTargetAtTime(gainValue, currentTime, 0.1);
+                // Time constant 0.25 = ~750ms to settle (very smooth transitions)
+                // Longer time constant prevents audible gain jumps
+                nodes.gain.gain.setTargetAtTime(finalGainValue, currentTime, 0.25);
             }
             catch (err) {
                 // Fallback: If scheduling fails, set value directly (rare edge case)
-                nodes.gain.gain.value = gainValue;
+                nodes.gain.gain.value = finalGainValue;
             }
         }
     }
@@ -469,7 +504,8 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             // Smooth ramp to 0 (muted) or 1 (unmuted) - prevents click
             // Time constant 0.05 = ~150ms to reach target (3 time constants)
             nodes.gain.gain.setTargetAtTime(muted ? 0 : 1, this.audioContext.currentTime, 0.05);
-            this.lastGainValue.set(participantId, muted ? 0 : 1);
+            // Update cached gain value when muting/unmuting
+            this.cachedGainValues.set(participantId, muted ? 0 : 1);
         }
     }
     /**
@@ -665,6 +701,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             this.participantNodes.delete(participantId);
             // Clean up smoothed pan value tracking
             this.smoothedPanValues.delete(participantId);
+            // Clean up cached gain values
+            this.cachedGainValues.delete(participantId);
+            // Clean up cached speaker position
+            this.cachedSpeakerPositions.delete(participantId);
         }
     }
     async resumeAudioContext() {
@@ -1047,9 +1087,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
      * - 10m+ → 5% (minimum, barely audible)
      */
     calculateLogarithmicGain(distance) {
-        const minDistance = 1.0; // Full volume at 1m or closer
-        const minGain = 5; // Minimum 5% at far distances (barely audible)
-        const falloffRate = 0.15; // Controls how fast volume drops (higher = faster)
+        const minDistance = 1.5; // Full volume at 1.5m or closer (conversation distance)
+        const minGain = 20; // Minimum 20% at far distances (still clearly audible)
+        const falloffRate = 0.12; // Controls how fast volume drops (lower = gentler)
         // Full volume within minimum distance
         if (distance <= minDistance)
             return 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newgameplusinc/odyssey-audio-video-sdk-dev",
-  "version": "1.0.255",
+  "version": "1.0.256",
   "description": "Odyssey Spatial Audio & Video SDK using MediaSoup for real-time communication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",