@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.12 → 1.0.14

package/README.md

@@ -13,7 +13,7 @@ It mirrors the production SDK used by Odyssey V2 and ships ready-to-drop into an
 - 🧭 **Accurate pose propagation** – `updatePosition()` streams listener pose to the SFU while `participant-position-updated` keeps the local store in sync.
 - 🎧 **Studio-grade spatial audio** – each remote participant gets a dedicated Web Audio graph: denoiser → high-pass → low-pass → HRTF `PannerNode` → adaptive gain → master compressor.
 - 🎥 **Camera-ready streams** – video tracks are exposed separately so UI layers can render muted `<video>` tags while audio stays inside Web Audio.
-- 🎙️ **Clean microphone uplink** – optional `enhanceOutgoingAudioTrack` helper runs mic input through denoiser + EQ + compressor before hitting the SFU.
+- 🎙️ **Clean microphone uplink (opt‑in)** – when `outboundTuning.enabled=true`, `enhanceOutgoingAudioTrack` runs mic input through denoiser + EQ + compressor before hitting the SFU.
 - 🔁 **EventEmitter contract** – subscribe to `room-joined`, `consumer-created`, `participant-position-updated`, etc., without touching Socket.IO directly.
 
 ## Quick Start
@@ -81,6 +81,7 @@ sdk.setListenerFromLSD(listenerPos, cameraPos, lookAtPos);
 - **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.
 - **Noise handling** – optional AudioWorklet denoiser plus high/low-pass filters trim rumble & hiss before HRTF processing.
+- **Dynamic gate (opt-in)** – enable via `noiseGate.enabled=true` to let the SDK automatically clamp remote tracks when they’re idle.
 
 #### How Spatial Audio Is Built
 1. **Telemetry ingestion** – each LSD packet is passed through `setListenerFromLSD(listenerPos, cameraPos, lookAtPos)` so the Web Audio listener matches the player’s real head/camera pose.
@@ -90,11 +91,12 @@ sdk.setListenerFromLSD(listenerPos, cameraPos, lookAtPos);
 4. **Distance-aware gain** – the manager stores the latest listener pose and computes the Euclidean distance to each remote participant on every update. A custom rolloff curve adjusts gain before the compressor, giving the “someone on my left / far away” perception without blowing out master levels.
 5. **Left/right rendering** – because the panner uses `panningModel = "HRTF"`, browsers feed the processed signal into the user’s audio hardware with head-related transfer functions, producing natural interaural time/intensity differences.
 
-#### How Microphone Audio Is Tuned Before Sending
+#### How Microphone Audio Is Tuned Before Sending (Opt-In)
+> Disabled by default. Enable via `new SpatialAudioManager({ outboundTuning: { enabled: true } })`.
 1. **Hardware constraints first** – the SDK requests `noiseSuppression`, `echoCancellation`, and `autoGainControl` on the raw `MediaStreamTrack` (plus Chromium-specific `goog*` flags).
 2. **Web Audio pre-flight** – `enhanceOutgoingAudioTrack(track)` clones the mic into a dedicated `AudioContext` and chain: `Denoiser → 50/60 Hz notches → Low-shelf rumble cut → High-pass (95 Hz) → Low-pass (7.2 kHz) → High-shelf tame → Presence boost → Dynamics compressor → Adaptive gate`.
 3. **Adaptive gate** – a lightweight RMS monitor clamps the gate gain when only background hiss remains, but opens instantly when speech energy rises.
-4. **Clean stream to SFU** – the processed track is what you pass to `produceTrack`, so every participant receives the filtered audio (and your local store uses the same track for mute toggles).
+4. **Clean stream to SFU** – the processed track is what you pass to `produceTrack`, so every participant receives the filtered audio (and your local store uses the same track for mute toggles). Toggle the feature off to fall back to raw WebRTC audio instantly.
 
 ## Video Flow (Capture ↔ Rendering)
 

package/dist/SpatialAudioManager.d.ts

@@ -12,9 +12,17 @@ type DenoiserOptions = {
     noiseFloor?: number;
     release?: number;
 };
+type NoiseGateOptions = {
+    enabled?: boolean;
+};
+type OutboundTuningOptions = {
+    enabled?: boolean;
+};
 type SpatialAudioOptions = {
     distance?: SpatialAudioDistanceConfig;
     denoiser?: DenoiserOptions;
+    noiseGate?: NoiseGateOptions;
+    outboundTuning?: OutboundTuningOptions;
 };
 export declare class SpatialAudioManager extends EventManager {
     private audioContext;
@@ -31,6 +39,8 @@ export declare class SpatialAudioManager extends EventManager {
     private stabilityState;
     private outgoingProcessors;
     private listenerDirection;
+    private noiseGateEnabled;
+    private outboundTuningEnabled;
     constructor(options?: SpatialAudioOptions);
     getAudioContext(): AudioContext;
     /**
@@ -104,6 +114,10 @@ export declare class SpatialAudioManager extends EventManager {
     private applyHardwareNoiseConstraints;
     private startOutboundMonitor;
     private cleanupOutboundProcessor;
+    private toWebAudioPosition;
+    private toWebAudioDirection;
+    private convertListenerOrientation;
+    private normalizeVector;
     private ensureDenoiseWorklet;
     private resolveOptions;
 }

package/dist/SpatialAudioManager.js

@@ -17,11 +17,13 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             up: { x: 0, y: 0, z: 1 },
         };
         this.options = this.resolveOptions(options);
+        this.noiseGateEnabled = this.options.noiseGate?.enabled ?? false;
+        this.outboundTuningEnabled = this.options.outboundTuning?.enabled ?? false;
         // Use high sample rate for best audio quality
         this.audioContext = new AudioContext({ sampleRate: 48000 });
         // Master gain
         this.masterGainNode = this.audioContext.createGain();
-        this.masterGainNode.gain.value = 5.0;
+        this.masterGainNode.gain.value = 1.8; // Lower headroom to avoid hiss from boosted noise floor
         // Compressor for dynamic range control and preventing distortion
         this.compressor = this.audioContext.createDynamicsCompressor();
         this.compressor.threshold.value = -24; // dB
@@ -126,16 +128,20 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         }
         currentNode.connect(highpassFilter);
         highpassFilter.connect(lowpassFilter);
-        lowpassFilter.connect(noiseGate);
+        let postFilterNode = lowpassFilter;
+        if (this.noiseGateEnabled) {
+            lowpassFilter.connect(noiseGate);
+            postFilterNode = noiseGate;
+        }
         if (bypassSpatialization) {
             console.log(`🔊 TESTING: Connecting audio directly to destination (bypassing spatial audio) for ${participantId}`);
-            noiseGate.connect(analyser);
+            postFilterNode.connect(analyser);
             analyser.connect(this.masterGainNode);
         }
         else {
             // Standard spatialized path with full audio chain
-            // Audio Chain: source -> filters -> noiseGate -> panner -> analyser -> gain -> masterGain -> compressor -> destination
-            noiseGate.connect(panner);
+            // Audio Chain: source -> filters -> (optional gate) -> panner -> analyser -> gain -> masterGain -> compressor -> destination
+            postFilterNode.connect(panner);
             panner.connect(analyser);
             analyser.connect(gain);
             gain.connect(this.masterGainNode);
@@ -156,7 +162,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             targetGain: 1,
             networkMuted: false,
         });
-        if (typeof track.onmute !== "undefined") {
+        if (this.noiseGateEnabled && typeof track.onmute !== "undefined") {
             track.onmute = () => this.handleTrackStability(participantId, true);
             track.onunmute = () => this.handleTrackStability(participantId, false);
         }
@@ -176,11 +182,13 @@ class SpatialAudioManager extends EventManager_1.EventManager {
                 rolloffFactor: panner.rolloffFactor,
             },
         });
-        // Start monitoring audio levels
-        this.startMonitoring(participantId);
+        // Start monitoring audio levels if gate enabled
+        if (this.noiseGateEnabled) {
+            this.startMonitoring(participantId);
+        }
     }
     async enhanceOutgoingAudioTrack(track) {
-        if (track.kind !== "audio") {
+        if (track.kind !== "audio" || !this.outboundTuningEnabled) {
             return track;
         }
         const existingProcessor = Array.from(this.outgoingProcessors.values()).find((processor) => processor.originalTrack === track);
@@ -305,6 +313,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         return processedTrack;
     }
     startMonitoring(participantId) {
+        if (!this.noiseGateEnabled) {
+            return;
+        }
         const nodes = this.participantNodes.get(participantId);
         if (!nodes)
             return;
@@ -329,8 +340,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
                 const smoothing = 0.2;
                 stability.smoothedLevel =
                     stability.smoothedLevel * (1 - smoothing) + normalizedLevel * smoothing;
-                const gateOpenThreshold = 0.035; // empirical speech/noise split
-                const gateCloseThreshold = 0.015;
+                const gateOpenThreshold = 0.028; // tuned for speech presence
+                const gateCloseThreshold = 0.012;
+                const noiseFloorGain = 0.12;
                 let targetGain = stability.targetGain;
                 if (stability.networkMuted) {
                     targetGain = 0;
@@ -339,13 +351,13 @@ class SpatialAudioManager extends EventManager_1.EventManager {
                     targetGain = 0;
                 }
                 else if (stability.smoothedLevel < gateOpenThreshold) {
-                    targetGain = 0.35;
+                    targetGain = noiseFloorGain;
                 }
                 else {
                     targetGain = 1;
                 }
                 if (Math.abs(targetGain - stability.targetGain) > 0.05) {
-                    const ramp = targetGain > stability.targetGain ? 0.03 : 0.12;
+                    const ramp = targetGain > stability.targetGain ? 0.04 : 0.18;
                     noiseGate.gain.setTargetAtTime(targetGain, this.audioContext.currentTime, ramp);
                     stability.targetGain = targetGain;
                 }
@@ -380,6 +392,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         this.monitoringIntervals.set(participantId, interval);
     }
     handleTrackStability(participantId, muted) {
+        if (!this.noiseGateEnabled) {
+            return;
+        }
         const nodes = this.participantNodes.get(participantId);
         if (!nodes)
             return;
@@ -414,7 +429,8 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         if (nodes?.panner) {
             const distanceConfig = this.getDistanceConfig();
             const normalizedPosition = this.normalizePositionUnits(position);
-            const targetPosition = this.applySpatialBoostIfNeeded(normalizedPosition);
+            const webAudioPosition = this.toWebAudioPosition(normalizedPosition);
+            const targetPosition = this.applySpatialBoostIfNeeded(webAudioPosition);
             // Update position (where the sound is coming from)
             nodes.panner.positionX.setValueAtTime(targetPosition.x, this.audioContext.currentTime);
             nodes.panner.positionY.setValueAtTime(targetPosition.y, this.audioContext.currentTime);
@@ -422,18 +438,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             // Update orientation (where the participant is facing)
             // This makes the audio source directional based on participant's direction
             if (direction) {
-                // Normalize direction vector
-                const length = Math.sqrt(direction.x * direction.x +
-                    direction.y * direction.y +
-                    direction.z * direction.z);
-                if (length > 0.001) {
-                    const normX = direction.x / length;
-                    const normY = direction.y / length;
-                    const normZ = direction.z / length;
-                    nodes.panner.orientationX.setValueAtTime(normX, this.audioContext.currentTime);
-                    nodes.panner.orientationY.setValueAtTime(normY, this.audioContext.currentTime);
-                    nodes.panner.orientationZ.setValueAtTime(normZ, this.audioContext.currentTime);
-                }
+                const convertedDirection = this.toWebAudioDirection(direction);
+                nodes.panner.orientationX.setValueAtTime(convertedDirection.x, this.audioContext.currentTime);
+                nodes.panner.orientationY.setValueAtTime(convertedDirection.y, this.audioContext.currentTime);
+                nodes.panner.orientationZ.setValueAtTime(convertedDirection.z, this.audioContext.currentTime);
             }
             const listenerPos = this.listenerPosition;
             const distance = this.getDistanceBetween(listenerPos, targetPosition);
@@ -513,32 +521,23 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         if (!listener) {
             return;
         }
-        this.listenerPosition = { ...normalizedPosition };
+        const convertedPosition = this.toWebAudioPosition(normalizedPosition);
+        const convertedOrientation = this.convertListenerOrientation(orientation);
+        this.listenerPosition = { ...convertedPosition };
         this.listenerInitialized = true;
-        this.listenerDirection = {
-            forward: {
-                x: orientation.forwardX,
-                y: orientation.forwardY,
-                z: orientation.forwardZ,
-            },
-            up: {
-                x: orientation.upX,
-                y: orientation.upY,
-                z: orientation.upZ,
-            },
-        };
+        this.listenerDirection = convertedOrientation;
         if (listener.positionX) {
-            listener.positionX.setValueAtTime(normalizedPosition.x, this.audioContext.currentTime);
-            listener.positionY.setValueAtTime(normalizedPosition.y, this.audioContext.currentTime);
-            listener.positionZ.setValueAtTime(normalizedPosition.z, this.audioContext.currentTime);
+            listener.positionX.setValueAtTime(convertedPosition.x, this.audioContext.currentTime);
+            listener.positionY.setValueAtTime(convertedPosition.y, this.audioContext.currentTime);
+            listener.positionZ.setValueAtTime(convertedPosition.z, this.audioContext.currentTime);
         }
         if (listener.forwardX) {
-            listener.forwardX.setValueAtTime(orientation.forwardX, this.audioContext.currentTime);
-            listener.forwardY.setValueAtTime(orientation.forwardY, this.audioContext.currentTime);
-            listener.forwardZ.setValueAtTime(orientation.forwardZ, this.audioContext.currentTime);
-            listener.upX.setValueAtTime(orientation.upX, this.audioContext.currentTime);
-            listener.upY.setValueAtTime(orientation.upY, this.audioContext.currentTime);
-            listener.upZ.setValueAtTime(orientation.upZ, this.audioContext.currentTime);
+            listener.forwardX.setValueAtTime(convertedOrientation.forward.x, this.audioContext.currentTime);
+            listener.forwardY.setValueAtTime(convertedOrientation.forward.y, this.audioContext.currentTime);
+            listener.forwardZ.setValueAtTime(convertedOrientation.forward.z, this.audioContext.currentTime);
+            listener.upX.setValueAtTime(convertedOrientation.up.x, this.audioContext.currentTime);
+            listener.upY.setValueAtTime(convertedOrientation.up.y, this.audioContext.currentTime);
+            listener.upZ.setValueAtTime(convertedOrientation.up.z, this.audioContext.currentTime);
         }
         if (Math.random() < 0.01) {
             console.log(`🎧 [Spatial Audio] Listener updated:`, {
@@ -638,7 +637,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         const normalized = (distance - config.refDistance) /
             Math.max(config.maxDistance - config.refDistance, 0.001);
         const shaped = Math.pow(Math.max(0, 1 - normalized), Math.max(1.2, config.rolloffFactor * 1.05));
-        return Math.min(1, Math.max(0.01, shaped));
+        return Math.min(1, Math.max(0.001, shaped));
     }
     normalizePositionUnits(position) {
         const distanceConfig = this.getDistanceConfig();
@@ -729,17 +728,54 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         clearInterval(processor.monitor);
         processor.processedTrack.removeEventListener("ended", processor.cleanupListener);
         processor.originalTrack.removeEventListener("ended", processor.cleanupListener);
-        try {
-            processor.originalTrack.stop();
-        }
-        catch (error) {
-            console.warn("⚠️ Unable to stop original track during cleanup", error);
-        }
         processor.destinationStream.getTracks().forEach((t) => t.stop());
         processor.sourceStream.getTracks().forEach((t) => t.stop());
         processor.context.close();
         this.outgoingProcessors.delete(processorId);
     }
+    toWebAudioPosition(position) {
+        return {
+            x: position.y,
+            y: position.z,
+            z: -position.x,
+        };
+    }
+    toWebAudioDirection(vector) {
+        return this.normalizeVector(this.toWebAudioPosition(vector));
+    }
+    convertListenerOrientation(orientation) {
+        const forward = this.toWebAudioDirection({
+            x: orientation.forwardX,
+            y: orientation.forwardY,
+            z: orientation.forwardZ,
+        });
+        const upRaw = this.toWebAudioDirection({
+            x: orientation.upX,
+            y: orientation.upY,
+            z: orientation.upZ,
+        });
+        const dot = forward.x * upRaw.x + forward.y * upRaw.y + forward.z * upRaw.z;
+        const upOrtho = {
+            x: upRaw.x - dot * forward.x,
+            y: upRaw.y - dot * forward.y,
+            z: upRaw.z - dot * forward.z,
+        };
+        return {
+            forward,
+            up: this.normalizeVector(upOrtho, { x: 0, y: 1, z: 0 }),
+        };
+    }
+    normalizeVector(vector, fallback = { x: 0, y: 0, z: -1 }) {
+        const length = Math.hypot(vector.x, vector.y, vector.z);
+        if (length < 1e-5) {
+            return { ...fallback };
+        }
+        return {
+            x: vector.x / length,
+            y: vector.y / length,
+            z: vector.z / length,
+        };
+    }
     async ensureDenoiseWorklet(targetContext = this.audioContext) {
         if (!this.isDenoiserEnabled()) {
             return;
@@ -843,6 +879,12 @@ registerProcessor('odyssey-denoise', OdysseyDenoiseProcessor);
             noiseFloor: 0.004,
             release: 0.18,
         };
+        const noiseGateDefaults = {
+            enabled: true,
+        };
+        const outboundDefaults = {
+            enabled: false,
+        };
         return {
             distance: {
                 refDistance: options?.distance?.refDistance ?? distanceDefaults.refDistance,
@@ -856,6 +898,12 @@ registerProcessor('odyssey-denoise', OdysseyDenoiseProcessor);
                 noiseFloor: options?.denoiser?.noiseFloor ?? denoiserDefaults.noiseFloor,
                 release: options?.denoiser?.release ?? denoiserDefaults.release,
             },
+            noiseGate: {
+                enabled: options?.noiseGate?.enabled ?? noiseGateDefaults.enabled,
+            },
+            outboundTuning: {
+                enabled: options?.outboundTuning?.enabled ?? outboundDefaults.enabled,
+            },
         };
     }
 }

package/package.json

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