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

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;
     /**

package/dist/SpatialAudioManager.js

@@ -17,6 +17,8 @@ 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
@@ -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;
@@ -380,6 +391,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;
@@ -729,12 +743,6 @@ 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();
@@ -843,6 +851,12 @@ registerProcessor('odyssey-denoise', OdysseyDenoiseProcessor);
             noiseFloor: 0.004,
             release: 0.18,
         };
+        const noiseGateDefaults = {
+            enabled: false,
+        };
+        const outboundDefaults = {
+            enabled: false,
+        };
         return {
             distance: {
                 refDistance: options?.distance?.refDistance ?? distanceDefaults.refDistance,
@@ -856,6 +870,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.13",
   "description": "Odyssey Spatial Audio & Video SDK using MediaSoup for real-time communication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",