@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.62 → 1.0.64

package/README.md

@@ -78,7 +78,7 @@ sdk.setListenerFromLSD(listenerPos, cameraPos, lookAtPos);
 ### Web Audio Algorithms
 - **Coordinate normalization** – Unreal sends centimeters; `SpatialAudioManager` auto-detects large values and converts to meters once.
 - **Orientation math** – `setListenerFromLSD()` builds forward/right/up vectors from camera/LookAt to keep the listener aligned with head movement.
-- **Dynamic distance gain** – `updateSpatialAudio()` measures distance from listener → source and applies a smooth rolloff curve, so distant avatars fade to silence.
+- **Dynamic distance gain** – `updateSpatialAudio()` measures distance from listener → source and applies a quadratic rolloff curve (0.5m-10m range). Voices gradually fade from 100% (0.5m clear) to complete silence at 10m+. Distance calculated from listener's HEAD position to participant's standing position.
 - **Noise handling** – the AudioWorklet denoiser now runs an adaptive multi-band gate (per W3C AudioWorklet guidance) before the high/low-pass filters, stripping constant HVAC/fan noise even when the speaker is close. A newly added silence gate mutes tracks entirely after ~250 ms of sub-noise-floor energy, eliminating hiss during dead air without touching spatial cues.
 
 #### Noise-Cancellation Stack (What’s Included)

package/dist/SpatialAudioManager.d.ts

@@ -112,6 +112,13 @@ export declare class SpatialAudioManager extends EventManager {
      * @param muted True to mute, false to unmute
      */
     setParticipantMuted(participantId: string, muted: boolean): void;
+    /**
+     * Update listener position and orientation
+     * The \"listener\" is YOU - where your ears/head are positioned
+     *
+     * @param position Your HEAD position (camera position), not body position!
+     * @param orientation Which way your head is facing (forward and up vectors)
+     */
     setListenerPosition(position: Position, orientation: {
         forwardX: number;
         forwardY: number;
@@ -122,7 +129,10 @@ export declare class SpatialAudioManager extends EventManager {
     }): void;
     /**
      * Update listener orientation from LSD camera direction
-     * @param cameraPos Camera position in world space
+     * IMPORTANT: Uses CAMERA position (head) as listener, not body position!
+     *
+     * @param listenerPos Player body position (for reference, not used as listener)
+     * @param cameraPos Camera/HEAD position - THIS is the actual listener position for audio
      * @param lookAtPos Look-at position (where camera is pointing)
      */
     setListenerFromLSD(listenerPos: Position, cameraPos: Position, lookAtPos: Position): void;
@@ -171,13 +181,13 @@ export declare class SpatialAudioManager extends EventManager {
     /**
      * Calculate gain based on distance using logarithmic scale
      * Distance range: 0.5m to 5m
-     * Gain range: 100% to 0%
+     * Gain range: 100% to 20% (never goes to 0 for better audibility)
      * Uses quadratic equation for human ear perception
      */
     private calculateLogarithmicGain;
     /**
-     * Apply stereo panning to participant audio
-     * Converts panning percentages to StereoPanner values
+     * Apply stereo panning to participant audio using StereoPannerNode
+     * This provides STABLE left-right panning without jitter
      */
     private applyStereoPanning;
     private ensureDenoiseWorklet;

package/dist/SpatialAudioManager.js

@@ -99,6 +99,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         const stream = new MediaStream([track]);
         const source = this.audioContext.createMediaStreamSource(stream);
         const panner = this.audioContext.createPanner();
+        const stereoPanner = this.audioContext.createStereoPanner(); // For stable L/R panning
         const analyser = this.audioContext.createAnalyser();
         const gain = this.audioContext.createGain();
         const proximityGain = this.audioContext.createGain();
@@ -142,13 +143,14 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         }
         // Create BiquadFilter nodes for static/noise reduction
         // Based on: https://tagdiwalaviral.medium.com/struggles-of-noise-reduction-in-rtc-part-2-2526f8179442
-        // HIGHPASS FILTER: Remove low-frequency rumble (< 80Hz)
+        // HIGHPASS FILTER: Remove low-frequency rumble and plosives (< 80Hz)
         // Human voice fundamental: 80-300Hz, harmonics: 300Hz-8kHz
         // This cuts BELOW voice range while preserving full voice spectrum
+        // Lower Q for gentler slope = less phase distortion = fewer onset artifacts
         const highpassFilter = this.audioContext.createBiquadFilter();
         highpassFilter.type = "highpass";
         highpassFilter.frequency.value = 80; // Cut frequencies below 80Hz (removes rumble/pops)
-        highpassFilter.Q.value = 1.0; // Quality factor
+        highpassFilter.Q.value = 0.707; // Butterworth response (gentler, reduces plosives)
         // LOWPASS FILTER: Remove high-frequency hiss (> 8000Hz)
         // Voice harmonics extend to ~8kHz - this preserves full voice richness
         // while removing digital artifacts and hiss ABOVE useful voice range
@@ -156,14 +158,14 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         lowpassFilter.type = "lowpass";
         lowpassFilter.frequency.value = 8000; // Cut frequencies above 8kHz (preserves voice harmonics)
         lowpassFilter.Q.value = 1.0; // Quality factor
-        // VOICE BAND EMPHASIS: Boost 80-300Hz fundamental range for clarity
+        // VOICE BAND EMPHASIS: Subtle boost 80-300Hz fundamental range for clarity
         // This emphasizes the base pitch without affecting harmonics
-        // Helps reduce the "pop" when someone starts speaking
+        // Reduced gain to prevent onset artifacts ("mic pop" when speaking starts)
         const voiceBandFilter = this.audioContext.createBiquadFilter();
         voiceBandFilter.type = "peaking";
         voiceBandFilter.frequency.value = 180; // Center of voice fundamental (80-300Hz)
-        voiceBandFilter.Q.value = 1.5; // Moderate width (~100-260Hz affected)
-        voiceBandFilter.gain.value = 2; // +2dB boost for clarity
+        voiceBandFilter.Q.value = 0.8; // Wider, gentler curve (reduces artifacts)
+        voiceBandFilter.gain.value = 1; // +1dB subtle boost (was 2dB - too aggressive)
         const dynamicLowpass = this.audioContext.createBiquadFilter();
         dynamicLowpass.type = "lowpass";
         dynamicLowpass.frequency.value = 7500; // Fixed for all angles
@@ -180,14 +182,25 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         panner.coneOuterAngle = 360;
         panner.coneOuterGain = 0.3; // Some sound even outside cone
         // Configure gain for individual participant volume control
-        gain.gain.value = 1.0;
+        gain.gain.value = 1.5; // Boost initial gain (was 1.0)
+        // ADD COMPRESSOR: Prevents sudden peaks and "pops" when speaking starts
+        // This is KEY to eliminating onset artifacts
+        const participantCompressor = this.audioContext.createDynamicsCompressor();
+        participantCompressor.threshold.value = -30; // Higher threshold (less compression)
+        participantCompressor.knee.value = 10; // Smooth knee for natural sound
+        participantCompressor.ratio.value = 2; // 2:1 gentle ratio (was 3:1)
+        participantCompressor.attack.value = 0.003; // 3ms fast attack for transients
+        participantCompressor.release.value = 0.15; // 150ms release for natural decay
         let currentNode = source;
+        // First apply compressor to tame initial transients (CRITICAL for preventing pops)
+        currentNode.connect(participantCompressor);
+        currentNode = participantCompressor;
         if (denoiseNode) {
             currentNode.connect(denoiseNode);
             currentNode = denoiseNode;
         }
         // Audio chain with voice optimization filters
-        // Chain: source -> [denoise] -> highpass -> voiceBand -> lowpass -> dynamicLowpass -> proximityGain -> panner -> analyser -> gain -> masterGain
+        // Chain: source -> compressor -> [denoise] -> highpass -> voiceBand -> lowpass -> dynamicLowpass -> proximityGain -> panner -> analyser -> gain -> masterGain
         currentNode.connect(highpassFilter);
         highpassFilter.connect(voiceBandFilter);
         voiceBandFilter.connect(lowpassFilter);
@@ -198,9 +211,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             analyser.connect(this.masterGainNode);
         }
         else {
-            // Standard spatialized path with full audio chain
-            // Audio Chain: source -> filters -> panner -> analyser -> gain -> masterGain -> compressor -> destination
-            proximityGain.connect(panner);
+            // Standard spatialized path with stereo panner
+            // Audio Chain: source -> compressor -> filters -> stereoPanner -> panner -> analyser -> gain -> masterGain -> compressor -> destination
+            proximityGain.connect(stereoPanner); // Stereo panner for stable L/R
+            stereoPanner.connect(panner); // Then 3D panner for distance
             panner.connect(analyser);
             analyser.connect(gain);
             gain.connect(this.masterGainNode);
@@ -208,9 +222,11 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         this.participantNodes.set(participantId, {
             source,
             panner,
+            stereoPanner,
             analyser,
             gain,
             proximityGain,
+            compressor: participantCompressor,
             highpassFilter,
             lowpassFilter,
             voiceBandFilter,
@@ -301,10 +317,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         const nodes = this.participantNodes.get(participantId);
         if (nodes?.panner) {
             const normalizedPosition = this.normalizePositionUnits(position);
-            const listenerPos = this.listenerPosition;
-            // Calculate distance (in meters)
+            const listenerPos = this.listenerPosition; // This is HEAD position (from setListenerFromLSD)
+            // Calculate distance (in meters) - from HEAD to source
             const distance = this.getDistanceBetween(listenerPos, normalizedPosition);
-            // Calculate angle between listener and source
+            // Calculate angle between listener HEAD and source
             const angle = this.calculateAngle(listenerPos, normalizedPosition, this.listenerDirection.forward);
             // Calculate stereo panning based on angle
             const panning = this.calculatePanning(angle);
@@ -314,10 +330,13 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             this.applyStereoPanning(participantId, panning);
             // Apply gain with smooth transition to reduce clicking/popping
             const gainValue = gain / 100; // Convert to 0-1 range
-            nodes.gain.gain.setTargetAtTime(gainValue, this.audioContext.currentTime, 0.05 // Smooth transition over 50ms to reduce clicking
-            );
-            // Apply proximity gain for additional distance-based attenuation
-            nodes.proximityGain.gain.setTargetAtTime(gainValue, this.audioContext.currentTime, 0.05);
+            // Use exponentialRampToValueAtTime for smoother, more natural transitions
+            // This prevents the "pop" when someone starts speaking
+            const currentTime = this.audioContext.currentTime;
+            const rampTime = 0.08; // 80ms smooth ramp
+            // Ensure we never ramp to exactly 0 (causes issues)
+            const targetGain = Math.max(0.2, gainValue); // Minimum 20% gain (was 0.001)
+            nodes.gain.gain.setTargetAtTime(targetGain, currentTime, rampTime);
             // Update 3D position for PannerNode (still used for vertical positioning)
             nodes.panner.positionY.setValueAtTime(normalizedPosition.y, this.audioContext.currentTime);
             nodes.panner.positionZ.setValueAtTime(normalizedPosition.z, this.audioContext.currentTime);
@@ -348,17 +367,28 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             nodes.gain.gain.setValueAtTime(muted ? 0 : 1, this.audioContext.currentTime);
         }
     }
+    /**
+     * Update listener position and orientation
+     * The \"listener\" is YOU - where your ears/head are positioned
+     *
+     * @param position Your HEAD position (camera position), not body position!
+     * @param orientation Which way your head is facing (forward and up vectors)
+     */
     setListenerPosition(position, orientation) {
         const normalizedPosition = this.normalizePositionUnits(position);
         this.applyListenerTransform(normalizedPosition, orientation);
     }
     /**
      * Update listener orientation from LSD camera direction
-     * @param cameraPos Camera position in world space
+     * IMPORTANT: Uses CAMERA position (head) as listener, not body position!
+     *
+     * @param listenerPos Player body position (for reference, not used as listener)
+     * @param cameraPos Camera/HEAD position - THIS is the actual listener position for audio
      * @param lookAtPos Look-at position (where camera is pointing)
      */
     setListenerFromLSD(listenerPos, cameraPos, lookAtPos) {
-        const normalizedListener = this.normalizePositionUnits(listenerPos);
+        // USE CAMERA POSITION AS LISTENER (head position, not body!)
+        const normalizedListener = this.normalizePositionUnits(cameraPos); // ✅ Changed from listenerPos
         const normalizedCamera = this.normalizePositionUnits(cameraPos);
         const normalizedLookAt = this.normalizePositionUnits(lookAtPos);
         // Calculate forward vector (from camera to look-at point)
@@ -719,32 +749,31 @@ class SpatialAudioManager extends EventManager_1.EventManager {
     /**
      * Calculate gain based on distance using logarithmic scale
      * Distance range: 0.5m to 5m
-     * Gain range: 100% to 0%
+     * Gain range: 100% to 20% (never goes to 0 for better audibility)
      * Uses quadratic equation for human ear perception
      */
     calculateLogarithmicGain(distance) {
-        const minDistance = 0.5; // meters
-        const maxDistance = 5.0; // meters
+        const minDistance = 0.5; // meters - clear voice starts here
+        const maxDistance = 10.0; // meters - complete silence beyond this
         // Clamp distance
         if (distance <= minDistance)
-            return 100;
+            return 100; // Full volume at 0.5m or closer
         if (distance >= maxDistance)
-            return 0;
+            return 0; // Complete silence at 10m or beyond
         // Normalize distance to 0-1 range
         const normalizedDistance = (distance - minDistance) / (maxDistance - minDistance);
         // Apply quadratic falloff for natural perception
-        // gain = 100 * (1 - x²)
-        // This creates a logarithmic-like curve that sounds linear to human ear
+        // gain = 100 * (1 - x²) - gradual fade from 100% to 0%
         const gain = 100 * Math.pow(1 - normalizedDistance, 2);
-        return Math.max(0, Math.min(100, gain));
+        return Math.max(0, Math.min(100, gain)); // Clamp between 0-100%
     }
     /**
-     * Apply stereo panning to participant audio
-     * Converts panning percentages to StereoPanner values
+     * Apply stereo panning to participant audio using StereoPannerNode
+     * This provides STABLE left-right panning without jitter
      */
     applyStereoPanning(participantId, panning) {
         const nodes = this.participantNodes.get(participantId);
-        if (!nodes?.panner)
+        if (!nodes?.stereoPanner)
             return;
         // Convert left/right percentages to pan value (-1 to +1)
         // If left=100, right=0 → pan = -1 (full left)
@@ -757,9 +786,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         if (leftRatio + rightRatio > 0) {
             panValue = (rightRatio - leftRatio);
         }
-        // Adjust X position for left-right panning (-1 = left, +1 = right)
+        // Use StereoPannerNode for stable, glitch-free panning
+        // This is MUCH more stable than manipulating PannerNode.positionX
         const currentTime = this.audioContext.currentTime;
-        nodes.panner.positionX.setTargetAtTime(panValue * 5, currentTime, 0.05);
+        nodes.stereoPanner.pan.setTargetAtTime(panValue, currentTime, 0.05);
     }
     async ensureDenoiseWorklet() {
         if (!this.isDenoiserEnabled()) {

package/package.json

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