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

package/dist/SpatialAudioManager.d.ts

@@ -74,6 +74,12 @@ export declare class SpatialAudioManager extends EventManager {
      */
     setupSpatialAudioForParticipant(participantId: string, track: MediaStreamTrack, bypassSpatialization?: boolean): Promise<void>;
     private startMonitoring;
+    /**
+     * Toggle spatialization for a participant (for huddle/spatial switching)
+     * @param participantId The participant to update
+     * @param enableSpatialization True for spatial audio, false for non-spatial (huddle)
+     */
+    setParticipantSpatialization(participantId: string, enableSpatialization: boolean): void;
     /**
      * Update spatial audio position and orientation for a participant
      *
@@ -131,12 +137,49 @@ export declare class SpatialAudioManager extends EventManager {
     private normalizePositionUnits;
     private getVectorFromListener;
     private applyDirectionalSuppression;
+    /**
+     * Dynamically adjust highpass filter based on voice characteristics
+     * Analyzes audio spectrum and sets filter between 85-300Hz
+     */
+    private adjustVoiceAdaptiveFilter;
     private calculateClarityScore;
     private calculateProximityWeight;
     private calculateDirectionFocus;
     private normalizeVector;
     private clamp;
     private isDenoiserEnabled;
+    /**
+     * Calculate angle between listener and sound source in degrees (0-360)
+     * 0° = front, 90° = right, 180° = back, 270° = left
+     */
+    private calculateAngle;
+    /**
+     * Calculate stereo panning based on angle (0-360°)
+     * Returns { left: 0-100, right: 0-100 }
+     *
+     * Reference angles:
+     * 0° (front): L100, R100
+     * 45° (front-right): L50, R100
+     * 90° (right): L0, R100
+     * 135° (back-right): L0, R50
+     * 180° (back): L50, R50
+     * 225° (back-left): L50, R0
+     * 270° (left): L100, R0
+     * 315° (front-left): L100, R50
+     */
+    private calculatePanning;
+    /**
+     * Calculate gain based on distance using logarithmic scale
+     * Distance range: 0.5m to 5m
+     * Gain range: 100% to 0%
+     * Uses quadratic equation for human ear perception
+     */
+    private calculateLogarithmicGain;
+    /**
+     * Apply stereo panning to participant audio
+     * Converts panning percentages to StereoPanner values
+     */
+    private applyStereoPanning;
     private ensureDenoiseWorklet;
     private resolveOptions;
 }

package/dist/SpatialAudioManager.js

@@ -142,17 +142,31 @@ 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)
+        // Human voice fundamental: 80-300Hz, harmonics: 300Hz-8kHz
+        // This cuts BELOW voice range while preserving full voice spectrum
         const highpassFilter = this.audioContext.createBiquadFilter();
         highpassFilter.type = "highpass";
-        highpassFilter.frequency.value = 85; // Conservative value to preserve male voice depth
+        highpassFilter.frequency.value = 80; // Cut frequencies below 80Hz (removes rumble/pops)
         highpassFilter.Q.value = 1.0; // Quality factor
+        // 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
         const lowpassFilter = this.audioContext.createBiquadFilter();
         lowpassFilter.type = "lowpass";
-        lowpassFilter.frequency.value = 7500; // Below 8kHz to avoid flat/muffled sound
+        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
+        // This emphasizes the base pitch without affecting harmonics
+        // Helps reduce the "pop" when someone starts speaking
+        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
         const dynamicLowpass = this.audioContext.createBiquadFilter();
         dynamicLowpass.type = "lowpass";
-        dynamicLowpass.frequency.value = 7600;
+        dynamicLowpass.frequency.value = 7500; // Fixed for all angles
         dynamicLowpass.Q.value = 0.8;
         proximityGain.gain.value = 1.0;
         // Configure Panner for realistic 3D spatial audio
@@ -172,8 +186,11 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             currentNode.connect(denoiseNode);
             currentNode = denoiseNode;
         }
+        // Audio chain with voice optimization filters
+        // Chain: source -> [denoise] -> highpass -> voiceBand -> lowpass -> dynamicLowpass -> proximityGain -> panner -> analyser -> gain -> masterGain
         currentNode.connect(highpassFilter);
-        highpassFilter.connect(lowpassFilter);
+        highpassFilter.connect(voiceBandFilter);
+        voiceBandFilter.connect(lowpassFilter);
         lowpassFilter.connect(dynamicLowpass);
         dynamicLowpass.connect(proximityGain);
         if (bypassSpatialization) {
@@ -196,6 +213,7 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             proximityGain,
             highpassFilter,
             lowpassFilter,
+            voiceBandFilter,
             dynamicLowpass,
             denoiseNode,
             stream,
@@ -225,6 +243,40 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         }, 2000); // Check every 2 seconds
         this.monitoringIntervals.set(participantId, interval);
     }
+    /**
+     * Toggle spatialization for a participant (for huddle/spatial switching)
+     * @param participantId The participant to update
+     * @param enableSpatialization True for spatial audio, false for non-spatial (huddle)
+     */
+    setParticipantSpatialization(participantId, enableSpatialization) {
+        const nodes = this.participantNodes.get(participantId);
+        if (!nodes) {
+            console.warn(`[SpatialAudio] No nodes found for participant ${participantId}`);
+            return;
+        }
+        // Disconnect and reconnect audio chain
+        try {
+            // Disconnect from current destination
+            nodes.proximityGain.disconnect();
+            if (enableSpatialization) {
+                // Connect through panner for 3D spatial audio
+                nodes.proximityGain.connect(nodes.panner);
+                nodes.panner.connect(nodes.analyser);
+                console.log(`🎯 [SpatialAudio] Enabled spatialization for ${participantId.substring(0, 8)}`);
+            }
+            else {
+                // Bypass panner for non-spatial (huddle) audio
+                nodes.proximityGain.connect(nodes.analyser);
+                console.log(`🔊 [SpatialAudio] Disabled spatialization (huddle mode) for ${participantId.substring(0, 8)}`);
+            }
+            // Rest of the chain remains the same
+            nodes.analyser.connect(nodes.gain);
+            nodes.gain.connect(this.masterGainNode);
+        }
+        catch (error) {
+            console.error(`[SpatialAudio] Error toggling spatialization for ${participantId}:`, error);
+        }
+    }
     /**
      * Update spatial audio position and orientation for a participant
      *
@@ -248,35 +300,35 @@ class SpatialAudioManager extends EventManager_1.EventManager {
     updateSpatialAudio(participantId, position, direction) {
         const nodes = this.participantNodes.get(participantId);
         if (nodes?.panner) {
-            const distanceConfig = this.getDistanceConfig();
             const normalizedPosition = this.normalizePositionUnits(position);
-            const targetPosition = this.applySpatialBoostIfNeeded(normalizedPosition);
-            // 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);
-            nodes.panner.positionZ.setValueAtTime(targetPosition.z, this.audioContext.currentTime);
-            // 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 listenerPos = this.listenerPosition;
-            const vectorToSource = this.getVectorFromListener(targetPosition);
-            const distance = this.getDistanceBetween(listenerPos, targetPosition);
-            this.applyDirectionalSuppression(participantId, distance, vectorToSource);
-            const distanceGain = this.calculateDistanceGain(distanceConfig, distance);
-            nodes.gain.gain.setTargetAtTime(distanceGain, this.audioContext.currentTime, 0.05);
+            // Calculate distance (in meters)
+            const distance = this.getDistanceBetween(listenerPos, normalizedPosition);
+            // Calculate angle between listener and source
+            const angle = this.calculateAngle(listenerPos, normalizedPosition, this.listenerDirection.forward);
+            // Calculate stereo panning based on angle
+            const panning = this.calculatePanning(angle);
+            // Calculate logarithmic gain based on distance
+            const gain = this.calculateLogarithmicGain(distance);
+            // Apply panning
+            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);
+            // 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);
+            // Log for debugging (remove in production)
+            if (Math.random() < 0.01) { // Log 1% of updates to avoid spam
+                console.log(`[Spatial Audio] Participant: ${participantId}`);
+                console.log(`  Distance: ${distance.toFixed(2)}m`);
+                console.log(`  Angle: ${angle.toFixed(1)}°`);
+                console.log(`  Panning: L${panning.left.toFixed(0)}% R${panning.right.toFixed(0)}%`);
+                console.log(`  Gain: ${gain.toFixed(0)}%`);
+            }
         }
     }
     /**
@@ -322,7 +374,9 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         const fwdY = forwardY / forwardLen;
         const fwdZ = forwardZ / forwardLen;
         // Calculate right vector (cross product of world up and forward)
-        const worldUp = { x: 0, y: 0, z: 1 }; // Unreal Z-up
+        // Web Audio API uses Y-up coordinate system, Unreal uses Z-up
+        // We need to transform: Unreal (X,Y,Z) -> WebAudio (X,Z,-Y)
+        const worldUp = { x: 0, y: 1, z: 0 }; // Web Audio Y-up
         const rightX = worldUp.y * fwdZ - worldUp.z * fwdY;
         const rightY = worldUp.z * fwdX - worldUp.x * fwdZ;
         const rightZ = worldUp.x * fwdY - worldUp.y * fwdX;
@@ -334,8 +388,8 @@ class SpatialAudioManager extends EventManager_1.EventManager {
                 forwardY: fwdY,
                 forwardZ: fwdZ,
                 upX: 0,
-                upY: 0,
-                upZ: 1,
+                upY: 1,
+                upZ: 0,
             });
             return;
         }
@@ -499,9 +553,45 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         }
         const clarityScore = this.calculateClarityScore(distance, vectorToSource);
         const targetGain = 0.48 + clarityScore * 0.72; // 0.48 → 1.20
-        const targetLowpass = 3600 + clarityScore * 4600; // 3.6kHz → ~8.2kHz
+        // Only adjust gain based on angle, not frequency
         nodes.proximityGain.gain.setTargetAtTime(targetGain, this.audioContext.currentTime, 0.08);
-        nodes.dynamicLowpass.frequency.setTargetAtTime(targetLowpass, this.audioContext.currentTime, 0.12);
+        // Analyze voice and adjust highpass filter dynamically (85-300Hz)
+        this.adjustVoiceAdaptiveFilter(participantId);
+    }
+    /**
+     * Dynamically adjust highpass filter based on voice characteristics
+     * Analyzes audio spectrum and sets filter between 85-300Hz
+     */
+    adjustVoiceAdaptiveFilter(participantId) {
+        const nodes = this.participantNodes.get(participantId);
+        if (!nodes?.analyser) {
+            return;
+        }
+        const bufferLength = nodes.analyser.frequencyBinCount;
+        const dataArray = new Uint8Array(bufferLength);
+        nodes.analyser.getByteFrequencyData(dataArray);
+        // Calculate spectral centroid in low frequency range (0-500Hz)
+        const sampleRate = this.audioContext.sampleRate;
+        const nyquist = sampleRate / 2;
+        const binWidth = nyquist / bufferLength;
+        let weightedSum = 0;
+        let totalEnergy = 0;
+        const maxBin = Math.floor(500 / binWidth); // Only analyze up to 500Hz
+        for (let i = 0; i < Math.min(maxBin, bufferLength); i++) {
+            const frequency = i * binWidth;
+            const magnitude = dataArray[i] / 255.0;
+            weightedSum += frequency * magnitude;
+            totalEnergy += magnitude;
+        }
+        if (totalEnergy > 0.01) {
+            const centroid = weightedSum / totalEnergy;
+            // Map centroid to highpass frequency (85-300Hz)
+            // Lower centroid = deeper voice = use lower highpass (preserve bass)
+            // Higher centroid = higher voice = use higher highpass (remove mud)
+            const targetFreq = Math.max(85, Math.min(300, 85 + (centroid - 100) * 0.5));
+            nodes.highpassFilter.frequency.setTargetAtTime(targetFreq, this.audioContext.currentTime, 0.15 // Smooth transition
+            );
+        }
     }
     calculateClarityScore(distance, vectorToSource) {
         const proximityWeight = this.calculateProximityWeight(distance);
@@ -545,6 +635,132 @@ class SpatialAudioManager extends EventManager_1.EventManager {
     isDenoiserEnabled() {
         return this.options.denoiser?.enabled !== false;
     }
+    /**
+     * Calculate angle between listener and sound source in degrees (0-360)
+     * 0° = front, 90° = right, 180° = back, 270° = left
+     */
+    calculateAngle(listenerPos, sourcePos, listenerForward) {
+        // Vector from listener to source
+        const dx = sourcePos.x - listenerPos.x;
+        const dy = sourcePos.y - listenerPos.y;
+        // Project onto horizontal plane (assuming Z is up)
+        // Use listener's forward direction to determine angle
+        const forwardX = listenerForward.x;
+        const forwardY = listenerForward.y;
+        // Calculate angle using atan2
+        const angleToSource = Math.atan2(dy, dx);
+        const forwardAngle = Math.atan2(forwardY, forwardX);
+        // Relative angle in radians
+        let relativeAngle = angleToSource - forwardAngle;
+        // Normalize to 0-2π
+        while (relativeAngle < 0)
+            relativeAngle += Math.PI * 2;
+        while (relativeAngle >= Math.PI * 2)
+            relativeAngle -= Math.PI * 2;
+        // Convert to degrees (0-360)
+        return (relativeAngle * 180 / Math.PI);
+    }
+    /**
+     * Calculate stereo panning based on angle (0-360°)
+     * Returns { left: 0-100, right: 0-100 }
+     *
+     * Reference angles:
+     * 0° (front): L100, R100
+     * 45° (front-right): L50, R100
+     * 90° (right): L0, R100
+     * 135° (back-right): L0, R50
+     * 180° (back): L50, R50
+     * 225° (back-left): L50, R0
+     * 270° (left): L100, R0
+     * 315° (front-left): L100, R50
+     */
+    calculatePanning(angle) {
+        // Normalize angle to 0-360
+        while (angle < 0)
+            angle += 360;
+        while (angle >= 360)
+            angle -= 360;
+        let left = 100;
+        let right = 100;
+        if (angle <= 90) {
+            // Front-right quadrant (0° to 90°)
+            // Left decreases from 100 to 0
+            // Right stays at 100
+            left = 100 * (1 - angle / 90);
+            right = 100;
+        }
+        else if (angle <= 180) {
+            // Back-right quadrant (90° to 180°)
+            // Left stays at 0
+            // Right decreases from 100 to 50
+            left = 0;
+            right = 100 - 50 * ((angle - 90) / 90);
+        }
+        else if (angle <= 270) {
+            // Back-left quadrant (180° to 270°)
+            // Left increases from 0 to 100
+            // Right decreases from 50 to 0
+            const progress = (angle - 180) / 90;
+            left = 50 + 50 * progress;
+            right = 50 * (1 - progress);
+        }
+        else {
+            // Front-left quadrant (270° to 360°)
+            // Left stays at 100
+            // Right increases from 0 to 100
+            left = 100;
+            right = 100 * ((angle - 270) / 90);
+        }
+        return {
+            left: Math.max(0, Math.min(100, left)),
+            right: Math.max(0, Math.min(100, right))
+        };
+    }
+    /**
+     * Calculate gain based on distance using logarithmic scale
+     * Distance range: 0.5m to 5m
+     * Gain range: 100% to 0%
+     * Uses quadratic equation for human ear perception
+     */
+    calculateLogarithmicGain(distance) {
+        const minDistance = 0.5; // meters
+        const maxDistance = 5.0; // meters
+        // Clamp distance
+        if (distance <= minDistance)
+            return 100;
+        if (distance >= maxDistance)
+            return 0;
+        // 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
+        const gain = 100 * Math.pow(1 - normalizedDistance, 2);
+        return Math.max(0, Math.min(100, gain));
+    }
+    /**
+     * Apply stereo panning to participant audio
+     * Converts panning percentages to StereoPanner values
+     */
+    applyStereoPanning(participantId, panning) {
+        const nodes = this.participantNodes.get(participantId);
+        if (!nodes?.panner)
+            return;
+        // Convert left/right percentages to pan value (-1 to +1)
+        // If left=100, right=0 → pan = -1 (full left)
+        // If left=0, right=100 → pan = +1 (full right)
+        // If left=100, right=100 → pan = 0 (center)
+        const leftRatio = panning.left / 100;
+        const rightRatio = panning.right / 100;
+        // Calculate pan position
+        let panValue = 0;
+        if (leftRatio + rightRatio > 0) {
+            panValue = (rightRatio - leftRatio);
+        }
+        // Adjust X position for left-right panning (-1 = left, +1 = right)
+        const currentTime = this.audioContext.currentTime;
+        nodes.panner.positionX.setTargetAtTime(panValue * 5, currentTime, 0.05);
+    }
     async ensureDenoiseWorklet() {
         if (!this.isDenoiserEnabled()) {
             return;

package/dist/index.js

@@ -383,11 +383,16 @@ class OdysseySpatialComms extends EventManager_1.EventManager {
                         return; // Exit early to prevent any audio processing
                     }
                     else {
-                        // Setup spatial audio with full 3D positioning
-                        await this.spatialAudioManager.setupSpatialAudioForParticipant(participant.participantId, track, false // Always enable spatial audio
+                        // Check if participant is in a huddle (non-spatial channel)
+                        const participantChannel = participant.currentChannel || "spatial";
+                        const isInHuddle = participantChannel !== "spatial";
+                        // Setup spatial audio - bypass 3D positioning for huddle members
+                        await this.spatialAudioManager.setupSpatialAudioForParticipant(participant.participantId, track, isInHuddle // Bypass spatialization if in huddle
                         );
-                        // Update spatial audio position
-                        this.spatialAudioManager.updateSpatialAudio(participant.participantId, data.position);
+                        // Only update spatial position if in spatial channel
+                        if (!isInHuddle) {
+                            this.spatialAudioManager.updateSpatialAudio(participant.participantId, data.position);
+                        }
                     }
                     // NOW resume the consumer after audio pipeline is ready
                     this.mediasoupManager
@@ -496,6 +501,9 @@ class OdysseySpatialComms extends EventManager_1.EventManager {
             const participant = this.room?.participants.get(data.participantId);
             if (participant) {
                 participant.currentChannel = data.channelId;
+                // Update spatialization based on channel
+                const isInSpatialChannel = data.channelId === "spatial";
+                this.spatialAudioManager.setParticipantSpatialization(data.participantId, isInSpatialChannel);
                 // If this participant is now in a different channel from us, clear their screenshare
                 const myChannel = this.localParticipant?.currentChannel || "spatial";
                 const theirChannel = data.channelId || "spatial";

package/package.json

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