@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.61 → 1.0.63

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;
@@ -137,12 +147,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,32 @@ 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 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 = 85; // Conservative value to preserve male voice depth
-        highpassFilter.Q.value = 1.0; // Quality factor
+        highpassFilter.frequency.value = 80; // Cut frequencies below 80Hz (removes rumble/pops)
+        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
         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: Subtle boost 80-300Hz fundamental range for clarity
+        // This emphasizes the base pitch without affecting harmonics
+        // 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 = 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 = 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
@@ -167,13 +182,27 @@ class SpatialAudioManager extends EventManager_1.EventManager {
         panner.coneOuterGain = 0.3; // Some sound even outside cone
         // Configure gain for individual participant volume control
         gain.gain.value = 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 = -24; // Start compressing at -24dB
+        participantCompressor.knee.value = 10; // Smooth knee for natural sound
+        participantCompressor.ratio.value = 3; // 3:1 compression ratio
+        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 -> compressor -> [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) {
@@ -194,8 +223,10 @@ class SpatialAudioManager extends EventManager_1.EventManager {
             analyser,
             gain,
             proximityGain,
+            compressor: participantCompressor,
             highpassFilter,
             lowpassFilter,
+            voiceBandFilter,
             dynamicLowpass,
             denoiseNode,
             stream,
@@ -282,35 +313,39 @@ 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; // This is HEAD position (from setListenerFromLSD)
+            // Calculate distance (in meters) - from HEAD to source
+            const distance = this.getDistanceBetween(listenerPos, normalizedPosition);
+            // 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);
+            // 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
+            // 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 (was 50ms - increased for gentler onset)
+            // Ensure we never ramp to exactly 0 (causes issues)
+            const targetGain = Math.max(0.001, gainValue);
+            nodes.gain.gain.setTargetAtTime(targetGain, currentTime, rampTime);
+            nodes.proximityGain.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);
+            // 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)}%`);
             }
-            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);
         }
     }
     /**
@@ -330,17 +365,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)
@@ -535,9 +581,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);
@@ -581,6 +663,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/package.json

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