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

package/README.md

@@ -1,106 +1,145 @@
-# Odyssey Spatial Audio SDK
-
-A comprehensive SDK for real-time spatial audio and video communication using MediaSoup, designed for immersive multi-user experiences in the Odyssey platform.
-
-## Purpose
-
-This package provides a complete WebRTC-based spatial audio and video solution that:
-- Manages MediaSoup connections for audio/video streaming
-- Implements spatial audio using Web Audio API with HRTF
-- Handles participant management with user profile data (bodyHeight, bodyShape, email, etc.)
-- Provides real-time position tracking for immersive spatial experiences
-
-## Installation
-
-You can install this package from npm:
-
-```bash
-npm install @newgameplusinc/odyssey-spatial-sdk-wrapper
-```
-
-Or install locally:
-
-```bash
-npm install ../mediasoup-sdk-test
-```
-
-## Usage
-
-### 1. Initialize the SDK
-
-```typescript
-import { OdysseySpatialComms } from "@newgameplusinc/odyssey-spatial-sdk-wrapper";
-
-// Initialize with your MediaSoup server URL
-const sdk = new OdysseySpatialComms("https://your-mediasoup-server.com");
-```
-
-### 2. Join a Room with User Profile Data
-
-```typescript
-const participant = await sdk.joinRoom({
-  roomId: "my-room",
-  userId: "user-123",
-  deviceId: "device-456",
-  position: { x: 0, y: 0, z: 0 },
-  direction: { x: 0, y: 0, z: 1 },
-  bodyHeight: "0.5",    // User's avatar height from Firebase
-  bodyShape: "4",       // User's avatar body shape from Firebase
-  userName: "John Doe", // User's display name
-  userEmail: "john@example.com" // User's email
+# Odyssey Audio/Video SDK (MediaSoup + Web Audio)
+
+This package exposes `OdysseySpatialComms`, a thin TypeScript client that glues together:
+
+- **MediaSoup SFU** for ultra-low-latency audio/video routing
+- **Web Audio API** for Apple-like spatial mixing via `SpatialAudioManager`
+- **Socket telemetry** (position + direction) so every browser hears/see everyone exactly where they are in the 3D world
+
+It mirrors the production SDK used by Odyssey V2 and ships ready-to-drop into any Web UI (Vue, React, plain JS).
+
+## Feature Highlights
+- 🔌 **One class to rule it all** – `OdysseySpatialComms` wires transports, producers, consumers, and room state.
+- 🧭 **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 (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
+
+```ts
+import {
+	OdysseySpatialComms,
+	Direction,
+	Position,
+} from "@newgameplusinc/odyssey-audio-video-sdk-dev";
+
+const sdk = new OdysseySpatialComms("https://mediasoup-server.example.com");
+
+// 1) Join a room
+await sdk.joinRoom({
+	roomId: "demo-room",
+	userId: "user-123",
+	deviceId: "device-123",
+	position: { x: 0, y: 0, z: 0 },
+	direction: { x: 0, y: 1, z: 0 },
 });
-```
 
-### 3. Produce Audio/Video Tracks
-
-```typescript
-// Get user media
-const stream = await navigator.mediaDevices.getUserMedia({ 
-  audio: true, 
-  video: true 
+// 2) Produce local media
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+for (const track of stream.getTracks()) {
+	await sdk.produceTrack(track);
+}
+
+// 3) Handle remote tracks
+sdk.on("consumer-created", async ({ participant, track }) => {
+	if (track.kind === "video") {
+		attachVideo(track, participant.participantId);
+	}
 });
 
-// Produce audio track
-const audioTrack = stream.getAudioTracks()[0];
-await sdk.produceTrack(audioTrack);
-
-// Produce video track
-const videoTrack = stream.getVideoTracks()[0];
-await sdk.produceTrack(videoTrack);
+// 4) Keep spatial audio honest
+sdk.updatePosition(currentPos, currentDir);
+sdk.setListenerFromLSD(listenerPos, cameraPos, lookAtPos);
 ```
 
-### 4. Update Position for Spatial Audio
+## Audio Flow (Server ↔ Browser)
 
-```typescript
-sdk.updatePosition(
-  { x: 10, y: 0, z: 5 },  // New position
-  { x: 0, y: 0, z: 1 }    // New direction
-);
 ```
-
-### 5. Listen to Events
-
-```typescript
-// New participant joined
-sdk.on("new-participant", (participant) => {
-  console.log("New participant:", participant.userName, participant.bodyHeight);
-});
-
-// Participant left
-sdk.on("participant-left", (participantId) => {
-  console.log("Participant left:", participantId);
-});
-
-// Consumer created (receiving audio/video from remote participant)
-sdk.on("consumer-created", ({ participant, track, consumer }) => {
-  console.log("Receiving", track.kind, "from", participant.userName);
-});
+┌──────────────┐   update-position   ┌──────────────┐   pose + tracks   ┌──────────────────┐
+│ Browser LSD  │ ──────────────────▶ │ MediaSoup SFU│ ────────────────▶ │ SDK Event Bus     │
+│ (Unreal data)│                     │ + Socket.IO  │                   │ (EventManager)    │
+└──────┬───────┘                     └──────┬───────┘                   └──────────┬────────┘
+	│                                    │                                  track + pose
+	│                                    │                                       ▼
+	│                           ┌────────▼────────┐                      ┌──────────────────┐
+	│ audio RTP                 │  consumer-created│                      │ SpatialAudioMgr   │
+	└──────────────────────────▶│  setup per-user │◀──────────────────────│  (Web Audio API)  │
+					└────────┬────────┘                      │  - Denoiser       │
+						  │                               │  - HP / LP        │
+						  │                               │  - HRTF Panner    │
+						  ▼                               │  - Gain + Comp    │
+					 Web Audio Graph                         └──────────┬───────┘
+						  │                                          │
+						  ▼                                          ▼
+				      Listener ears (Left/Right)                  System Output
 ```
 
-## Build
+### 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.
+- **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.
+2. **Per-participant node graph** – when `consumer-created` yields a remote audio track, `setupSpatialAudioForParticipant()` spins up an isolated graph:
+	`MediaStreamSource → (optional) Denoiser Worklet → High-Pass → Low-Pass → Panner(HRTF) → Gain → Master Compressor`.
+3. **Position + direction updates** – every `participant-position-updated` event calls `updateSpatialAudio(participantId, position, direction)`. The position feeds the panner’s XYZ, while the direction vector sets the source orientation so voices project forward relative to avatar facing.
+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 (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). Toggle the feature off to fall back to raw WebRTC audio instantly.
+
+## Video Flow (Capture ↔ Rendering)
 
-To build the package, run:
-
-```bash
-npm run build
 ```
+┌──────────────┐   produceTrack   ┌──────────────┐   RTP   ┌──────────────┐
+│ getUserMedia │ ───────────────▶ │ MediaSoup SDK│ ──────▶ │ MediaSoup SFU│
+└──────┬───────┘                  │ (Odyssey)    │         └──────┬───────┘
+	│                          └──────┬───────┘                │
+	│                   consumer-created │ track                │
+	▼                                  ▼                       │
+┌──────────────┐                   ┌──────────────┐                │
+│ Vue/React UI │ ◀─────────────── │ SDK Event Bus │ ◀──────────────┘
+│ (muted video │                   │ exposes media │
+│  elements)   │                   │ tracks        │
+└──────────────┘                   └──────────────┘
+```
+
+## Core Classes
+- `src/index.ts` – `OdysseySpatialComms` (socket lifecycle, producers/consumers, event surface).
+- `src/MediasoupManager.ts` – transport helpers for produce/consume/resume.
+- `src/SpatialAudioManager.ts` – Web Audio orchestration (listener transforms, per-participant chains, denoiser, distance math).
+- `src/EventManager.ts` – lightweight EventEmitter used by the entire SDK.
+
+## Integration Checklist
+1. **Instantiate once** per page/tab and keep it in a store (Vuex, Redux, Zustand, etc.).
+2. **Pipe LSD/Lap data** from your rendering engine into `updatePosition()` + `setListenerFromLSD()` at ~10 Hz.
+3. **Render videos muted** – never attach remote audio tracks straight to DOM; let `SpatialAudioManager` own playback.
+4. **Push avatar telemetry back to Unreal** so `remoteSpatialData` can render minimaps/circles (see Odyssey V2 `sendMediaSoupParticipantsToUnreal`).
+5. **Monitor logs** – browser console shows `🎧 SDK`, `📍 SDK`, and `🎚️ [Spatial Audio]` statements for every critical hop.
+
+## Server Contract (Socket.IO events)
+| Event | Direction | Payload |
+|-------|-----------|---------|
+| `join-room` | client → server | `{roomId, userId, deviceId, position, direction}` |
+| `room-joined` | server → client | `RoomJoinedData` (router caps, participants snapshot) |
+| `update-position` | client → server | `{participantId, conferenceId, position, direction}` |
+| `participant-position-updated` | server → client | `{participantId, position, direction, mediaState}` |
+| `consumer-created` | server → client | `{participantId, track(kind), position, direction}` |
+| `participant-media-state-updated` | server → client | `{participantId, mediaState}` |
+
+## Development Tips
+- Run `pnpm install && pnpm build` inside `mediasoup-sdk-test` to publish a fresh build.
+- Use `pnpm watch` while iterating so TypeScript outputs live under `dist/`.
+- The SDK targets evergreen browsers; for Safari <16.4 you may need to polyfill AudioWorklets or disable the denoiser via `new SpatialAudioManager({ denoiser: { enabled: false } })`.
+
+Have questions or want to extend the SDK? Start with `SpatialAudioManager` – that’s where most of the “real-world” behavior (distance feel, stereo cues, denoiser) lives.

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;
@@ -23,12 +31,16 @@ export declare class SpatialAudioManager extends EventManager {
     private monitoringIntervals;
     private compressor;
     private options;
-    private denoiseWorkletReady;
     private denoiseWorkletUrl?;
     private denoiserWasmBytes?;
+    private denoiseContextPromises;
     private listenerPosition;
     private listenerInitialized;
+    private stabilityState;
+    private outgoingProcessors;
     private listenerDirection;
+    private noiseGateEnabled;
+    private outboundTuningEnabled;
     constructor(options?: SpatialAudioOptions);
     getAudioContext(): AudioContext;
     /**
@@ -47,7 +59,9 @@ export declare class SpatialAudioManager extends EventManager {
      * @param bypassSpatialization For testing - bypasses 3D positioning
      */
     setupSpatialAudioForParticipant(participantId: string, track: MediaStreamTrack, bypassSpatialization?: boolean): Promise<void>;
+    enhanceOutgoingAudioTrack(track: MediaStreamTrack): Promise<MediaStreamTrack>;
     private startMonitoring;
+    private handleTrackStability;
     /**
      * Update spatial audio position and orientation for a participant
      *
@@ -97,6 +111,9 @@ export declare class SpatialAudioManager extends EventManager {
     private calculateDistanceGain;
     private normalizePositionUnits;
     private isDenoiserEnabled;
+    private applyHardwareNoiseConstraints;
+    private startOutboundMonitor;
+    private cleanupOutboundProcessor;
     private ensureDenoiseWorklet;
     private resolveOptions;
 }

package/dist/SpatialAudioManager.js

@@ -7,14 +7,18 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         super();
         this.participantNodes = new Map();
         this.monitoringIntervals = new Map();
-        this.denoiseWorkletReady = null;
+        this.denoiseContextPromises = new WeakMap();
         this.listenerPosition = { x: 0, y: 0, z: 0 };
         this.listenerInitialized = false;
+        this.stabilityState = new Map();
+        this.outgoingProcessors = new Map();
         this.listenerDirection = {
             forward: { x: 0, y: 1, z: 0 },
             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
@@ -69,6 +73,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         const panner = this.audioContext.createPanner();
         const analyser = this.audioContext.createAnalyser();
         const gain = this.audioContext.createGain();
+        const noiseGate = this.audioContext.createGain();
         let denoiseNode;
         if (this.isDenoiserEnabled() && typeof this.audioContext.audioWorklet !== "undefined") {
             try {
@@ -102,6 +107,8 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         lowpassFilter.type = "lowpass";
         lowpassFilter.frequency.value = 7500; // Below 8kHz to avoid flat/muffled sound
         lowpassFilter.Q.value = 1.0; // Quality factor
+        // Adaptive noise gate defaults
+        noiseGate.gain.value = 1.0;
         // Configure Panner for realistic 3D spatial audio
         const distanceConfig = this.getDistanceConfig();
         panner.panningModel = "HRTF"; // Head-Related Transfer Function for realistic 3D
@@ -121,15 +128,20 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         }
         currentNode.connect(highpassFilter);
         highpassFilter.connect(lowpassFilter);
+        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}`);
-            lowpassFilter.connect(analyser);
+            postFilterNode.connect(analyser);
             analyser.connect(this.masterGainNode);
         }
         else {
             // Standard spatialized path with full audio chain
-            // Audio Chain: source -> filters -> panner -> analyser -> gain -> masterGain -> compressor -> destination
-            lowpassFilter.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);
@@ -139,11 +151,21 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             panner,
             analyser,
             gain,
+            noiseGate,
             highpassFilter,
             lowpassFilter,
             denoiseNode,
             stream,
         });
+        this.stabilityState.set(participantId, {
+            smoothedLevel: 0,
+            targetGain: 1,
+            networkMuted: false,
+        });
+        if (this.noiseGateEnabled && typeof track.onmute !== "undefined") {
+            track.onmute = () => this.handleTrackStability(participantId, true);
+            track.onunmute = () => this.handleTrackStability(participantId, false);
+        }
         console.log(`🎧 Spatial audio setup complete for ${participantId}:`, {
             audioContextState: this.audioContext.state,
             sampleRate: this.audioContext.sampleRate,
@@ -160,15 +182,146 @@ 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" || !this.outboundTuningEnabled) {
+            return track;
+        }
+        const existingProcessor = Array.from(this.outgoingProcessors.values()).find((processor) => processor.originalTrack === track);
+        if (existingProcessor) {
+            return existingProcessor.processedTrack;
+        }
+        await this.applyHardwareNoiseConstraints(track);
+        const context = new AudioContext({ sampleRate: 48000 });
+        await context.resume();
+        const sourceStream = new MediaStream([track]);
+        const source = context.createMediaStreamSource(sourceStream);
+        let current = source;
+        let denoiseNode;
+        if (this.isDenoiserEnabled() && typeof context.audioWorklet !== "undefined") {
+            try {
+                await this.ensureDenoiseWorklet(context);
+                denoiseNode = new AudioWorkletNode(context, "odyssey-denoise", {
+                    numberOfInputs: 1,
+                    numberOfOutputs: 1,
+                    processorOptions: {
+                        enabled: true,
+                        threshold: this.options.denoiser?.threshold,
+                        noiseFloor: this.options.denoiser?.noiseFloor,
+                        release: this.options.denoiser?.release,
+                        wasmBytes: this.denoiserWasmBytes
+                            ? this.denoiserWasmBytes.slice(0)
+                            : null,
+                    },
+                });
+                current.connect(denoiseNode);
+                current = denoiseNode;
+            }
+            catch (error) {
+                console.warn("⚠️ Outgoing denoiser unavailable, continuing without it.", error);
+            }
+        }
+        const notch60 = context.createBiquadFilter();
+        notch60.type = "notch";
+        notch60.frequency.value = 60;
+        notch60.Q.value = 24;
+        current.connect(notch60);
+        current = notch60;
+        const notch50 = context.createBiquadFilter();
+        notch50.type = "notch";
+        notch50.frequency.value = 50;
+        notch50.Q.value = 24;
+        current.connect(notch50);
+        current = notch50;
+        const lowShelf = context.createBiquadFilter();
+        lowShelf.type = "lowshelf";
+        lowShelf.frequency.value = 120;
+        lowShelf.gain.value = -3;
+        current.connect(lowShelf);
+        current = lowShelf;
+        const highpassFilter = context.createBiquadFilter();
+        highpassFilter.type = "highpass";
+        highpassFilter.frequency.value = 95;
+        highpassFilter.Q.value = 0.8;
+        current.connect(highpassFilter);
+        current = highpassFilter;
+        const lowpassFilter = context.createBiquadFilter();
+        lowpassFilter.type = "lowpass";
+        lowpassFilter.frequency.value = 7200;
+        lowpassFilter.Q.value = 0.8;
+        current.connect(lowpassFilter);
+        current = lowpassFilter;
+        const hissShelf = context.createBiquadFilter();
+        hissShelf.type = "highshelf";
+        hissShelf.frequency.value = 6400;
+        hissShelf.gain.value = -4;
+        current.connect(hissShelf);
+        current = hissShelf;
+        const presenceBoost = context.createBiquadFilter();
+        presenceBoost.type = "peaking";
+        presenceBoost.frequency.value = 2400;
+        presenceBoost.Q.value = 1.1;
+        presenceBoost.gain.value = 2.4;
+        current.connect(presenceBoost);
+        current = presenceBoost;
+        const compressor = context.createDynamicsCompressor();
+        compressor.threshold.value = -18;
+        compressor.knee.value = 16;
+        compressor.ratio.value = 3.2;
+        compressor.attack.value = 0.002;
+        compressor.release.value = 0.22;
+        current.connect(compressor);
+        current = compressor;
+        const postCompressorTap = context.createGain();
+        postCompressorTap.gain.value = 1.05;
+        current.connect(postCompressorTap);
+        current = postCompressorTap;
+        const analyser = context.createAnalyser();
+        analyser.fftSize = 512;
+        current.connect(analyser);
+        const gate = context.createGain();
+        gate.gain.value = 1;
+        current.connect(gate);
+        const destination = context.createMediaStreamDestination();
+        gate.connect(destination);
+        const processedTrack = destination.stream.getAudioTracks()[0];
+        processedTrack.contentHint = "speech";
+        const processorId = processedTrack.id;
+        const monitor = this.startOutboundMonitor(processorId, analyser, gate);
+        const cleanup = () => this.cleanupOutboundProcessor(processorId);
+        processedTrack.addEventListener("ended", cleanup);
+        track.addEventListener("ended", cleanup);
+        this.outgoingProcessors.set(processorId, {
+            context,
+            sourceStream,
+            destinationStream: destination.stream,
+            analyser,
+            gate,
+            monitor,
+            originalTrack: track,
+            processedTrack,
+            cleanupListener: cleanup,
+        });
+        console.log("🎛️ [SDK] Outgoing audio tuned", {
+            originalTrackId: track.id,
+            processedTrackId: processedTrack.id,
+        });
+        return processedTrack;
     }
     startMonitoring(participantId) {
+        if (!this.noiseGateEnabled) {
+            return;
+        }
         const nodes = this.participantNodes.get(participantId);
         if (!nodes)
             return;
-        const { analyser, stream } = nodes;
+        const { analyser, stream, noiseGate } = nodes;
         const dataArray = new Uint8Array(analyser.frequencyBinCount);
+        let lastTrackLog = 0;
         // Clear any existing interval for this participant
         if (this.monitoringIntervals.has(participantId)) {
             clearInterval(this.monitoringIntervals.get(participantId));
@@ -181,16 +334,47 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             }
             const average = sum / dataArray.length;
             const audioLevel = (average / 128) * 255; // Scale to 0-255
-            console.log(`📊 Audio level for ${participantId}: ${audioLevel.toFixed(2)} (0-255 scale)`);
-            if (audioLevel < 1.0) {
+            const normalizedLevel = audioLevel / 255;
+            const stability = this.stabilityState.get(participantId);
+            if (stability) {
+                const smoothing = 0.2;
+                stability.smoothedLevel =
+                    stability.smoothedLevel * (1 - smoothing) + normalizedLevel * smoothing;
+                const gateOpenThreshold = 0.035; // empirical speech/noise split
+                const gateCloseThreshold = 0.015;
+                let targetGain = stability.targetGain;
+                if (stability.networkMuted) {
+                    targetGain = 0;
+                }
+                else if (stability.smoothedLevel < gateCloseThreshold) {
+                    targetGain = 0;
+                }
+                else if (stability.smoothedLevel < gateOpenThreshold) {
+                    targetGain = 0.35;
+                }
+                else {
+                    targetGain = 1;
+                }
+                if (Math.abs(targetGain - stability.targetGain) > 0.05) {
+                    const ramp = targetGain > stability.targetGain ? 0.03 : 0.12;
+                    noiseGate.gain.setTargetAtTime(targetGain, this.audioContext.currentTime, ramp);
+                    stability.targetGain = targetGain;
+                }
+                if (Math.random() < 0.05) {
+                    console.log(`🎚️ [NoiseGate] ${participantId}`, {
+                        level: stability.smoothedLevel.toFixed(3),
+                        gain: stability.targetGain.toFixed(2),
+                    });
+                }
+            }
+            if (audioLevel < 1.0 && Math.random() < 0.2) {
                 console.warn(`⚠️ NO AUDIO DATA detected for ${participantId}! Track may be silent or not transmitting.`);
-                console.info(`💡 Check: 1) Is microphone unmuted? 2) Is correct mic selected? 3) Is mic working in system settings?`);
             }
-            // Check track status after 2 seconds
-            setTimeout(() => {
+            if (Date.now() - lastTrackLog > 2000) {
+                lastTrackLog = Date.now();
                 const track = stream.getAudioTracks()[0];
                 if (track) {
-                    console.log(`🔊 Audio track status after 2s for ${participantId}:`, {
+                    console.log(`🔊 Audio track status for ${participantId}:`, {
                         trackEnabled: track.enabled,
                         trackMuted: track.muted,
                         trackReadyState: track.readyState,
@@ -202,10 +386,23 @@ class SpatialAudioManager extends EventManager_1.EventManager {
                         },
                     });
                 }
-            }, 2000);
-        }, 2000); // Log every 2 seconds
+            }
+        }, 250); // Adaptive monitoring ~4x per second
         this.monitoringIntervals.set(participantId, interval);
     }
+    handleTrackStability(participantId, muted) {
+        if (!this.noiseGateEnabled) {
+            return;
+        }
+        const nodes = this.participantNodes.get(participantId);
+        if (!nodes)
+            return;
+        const stability = this.stabilityState.get(participantId);
+        if (stability) {
+            stability.networkMuted = muted;
+        }
+        nodes.noiseGate.gain.setTargetAtTime(muted ? 0 : 1, this.audioContext.currentTime, muted ? 0.05 : 0.2);
+    }
     /**
      * Update spatial audio position and orientation for a participant
      *
@@ -389,11 +586,18 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             nodes.panner.disconnect();
             nodes.analyser.disconnect();
             nodes.gain.disconnect();
+            nodes.noiseGate.disconnect();
             if (nodes.denoiseNode) {
                 nodes.denoiseNode.disconnect();
             }
+            const track = nodes.stream.getAudioTracks()[0];
+            if (track) {
+                track.onmute = null;
+                track.onunmute = null;
+            }
             nodes.stream.getTracks().forEach((track) => track.stop());
             this.participantNodes.delete(participantId);
+            this.stabilityState.delete(participantId);
             console.log(`🗑️ Removed participant ${participantId} from spatial audio.`);
         }
     }
@@ -476,11 +680,79 @@ class SpatialAudioManager extends EventManager_1.EventManager {
     isDenoiserEnabled() {
         return this.options.denoiser?.enabled !== false;
     }
-    async ensureDenoiseWorklet() {
+    async applyHardwareNoiseConstraints(track) {
+        try {
+            await track.applyConstraints({
+                echoCancellation: true,
+                noiseSuppression: true,
+                autoGainControl: true,
+                advanced: [
+                    {
+                        echoCancellation: true,
+                        noiseSuppression: true,
+                        autoGainControl: true,
+                        googEchoCancellation: true,
+                        googNoiseSuppression: true,
+                        googAutoGainControl: true,
+                        googHighpassFilter: true,
+                        googTypingNoiseDetection: true,
+                    },
+                ],
+            });
+        }
+        catch (error) {
+            console.warn("⚠️ Unable to apply hardware audio constraints", error);
+        }
+        track.contentHint = "speech";
+    }
+    startOutboundMonitor(processorId, analyser, gate) {
+        const dataArray = new Uint8Array(analyser.fftSize);
+        let smoothedLevel = 0;
+        return setInterval(() => {
+            analyser.getByteTimeDomainData(dataArray);
+            let sum = 0;
+            for (const value of dataArray) {
+                sum += Math.abs(value - 128);
+            }
+            const level = (sum / dataArray.length) / 128;
+            smoothedLevel = smoothedLevel * 0.7 + level * 0.3;
+            let targetGain = 1;
+            if (smoothedLevel < 0.02) {
+                targetGain = 0;
+            }
+            else if (smoothedLevel < 0.05) {
+                targetGain = 0.45;
+            }
+            else {
+                targetGain = 1;
+            }
+            gate.gain.setTargetAtTime(targetGain, gate.context.currentTime, targetGain > gate.gain.value ? 0.02 : 0.08);
+            if (Math.random() < 0.03) {
+                console.log("🎚️ [SDK] Outgoing gate", {
+                    processorId,
+                    level: smoothedLevel.toFixed(3),
+                    gain: targetGain.toFixed(2),
+                });
+            }
+        }, 200);
+    }
+    cleanupOutboundProcessor(processorId) {
+        const processor = this.outgoingProcessors.get(processorId);
+        if (!processor)
+            return;
+        clearInterval(processor.monitor);
+        processor.processedTrack.removeEventListener("ended", processor.cleanupListener);
+        processor.originalTrack.removeEventListener("ended", processor.cleanupListener);
+        processor.destinationStream.getTracks().forEach((t) => t.stop());
+        processor.sourceStream.getTracks().forEach((t) => t.stop());
+        processor.context.close();
+        this.outgoingProcessors.delete(processorId);
+    }
+    async ensureDenoiseWorklet(targetContext = this.audioContext) {
         if (!this.isDenoiserEnabled()) {
             return;
         }
-        if (!("audioWorklet" in this.audioContext)) {
+        if (!("audioWorklet" in targetContext)) {
             console.warn("⚠️ AudioWorklet not supported in this browser. Disabling denoiser.");
             this.options.denoiser = {
                 ...(this.options.denoiser || {}),
@@ -488,8 +760,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             };
             return;
         }
-        if (this.denoiseWorkletReady) {
-            return this.denoiseWorkletReady;
+        const existingPromise = this.denoiseContextPromises.get(targetContext);
+        if (existingPromise) {
+            return existingPromise;
         }
         const processorSource = `class OdysseyDenoiseProcessor extends AudioWorkletProcessor {
   constructor(options) {
@@ -546,11 +819,13 @@ class SpatialAudioManager extends EventManager_1.EventManager {
 
 registerProcessor('odyssey-denoise', OdysseyDenoiseProcessor);
 `;
-        const blob = new Blob([processorSource], {
-            type: "application/javascript",
-        });
-        this.denoiseWorkletUrl = URL.createObjectURL(blob);
-        this.denoiseWorkletReady = this.audioContext.audioWorklet
+        if (!this.denoiseWorkletUrl) {
+            const blob = new Blob([processorSource], {
+                type: "application/javascript",
+            });
+            this.denoiseWorkletUrl = URL.createObjectURL(blob);
+        }
+        const promise = targetContext.audioWorklet
             .addModule(this.denoiseWorkletUrl)
             .catch((error) => {
             console.error("❌ Failed to register denoise worklet", error);
@@ -560,7 +835,8 @@ registerProcessor('odyssey-denoise', OdysseyDenoiseProcessor);
             };
             throw error;
         });
-        return this.denoiseWorkletReady;
+        this.denoiseContextPromises.set(targetContext, promise);
+        return promise;
     }
     resolveOptions(options) {
         const distanceDefaults = {
@@ -575,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,
@@ -588,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/dist/index.d.ts

@@ -26,6 +26,7 @@ export declare class OdysseySpatialComms extends EventManager {
     }): Promise<Participant>;
     leaveRoom(): void;
     resumeAudio(): Promise<void>;
+    enhanceOutgoingAudioTrack(track: MediaStreamTrack): Promise<MediaStreamTrack>;
     getAudioContextState(): AudioContextState;
     produceTrack(track: MediaStreamTrack): Promise<any>;
     updatePosition(position: Position, direction: Direction, spatialData?: {

package/dist/index.js

@@ -121,6 +121,9 @@ class OdysseySpatialComms extends EventManager_1.EventManager {
     async resumeAudio() {
         await this.spatialAudioManager.resumeAudioContext();
     }
+    async enhanceOutgoingAudioTrack(track) {
+        return this.spatialAudioManager.enhanceOutgoingAudioTrack(track);
+    }
     getAudioContextState() {
         return this.spatialAudioManager.getAudioContextState();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newgameplusinc/odyssey-audio-video-sdk-dev",
-  "version": "1.0.11",
+  "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",