@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.258 → 1.0.260

package/dist/utils/spatial/pan-calc.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pan Calculations
+ *
+ * Functions for calculating stereo panning based on listener/source positions
+ */
+import { Position, ListenerRight } from '../../types/position';
+/**
+ * Panning values for left/right channels
+ */
+export interface Panning {
+    left: number;
+    right: number;
+}
+/**
+ * Calculate listener's right-ear vector from yaw rotation
+ *
+ * COORDINATE SYSTEM: X=right, Y=up, Z=forward (datum at 0,0,0)
+ *
+ * Rotation convention (right-hand rule around Y-axis):
+ *   yaw = 0°   → facing +Z (forward), right ear points to +X
+ *   yaw = 90°  → facing +X (right),   right ear points to -Z
+ *   yaw = 180° → facing -Z (backward), right ear points to -X
+ *   yaw = 270° → facing -X (left),    right ear points to +Z
+ *
+ * @param yawDegrees Yaw rotation in degrees
+ * @returns Unit vector pointing to listener's right ear
+ */
+export declare function calculateListenerRight(yawDegrees: number): ListenerRight;
+/**
+ * Calculate pan value from listener and source positions
+ *
+ * Uses dot product projection onto listener's right-ear axis:
+ * dxLocal = vecToSource · listenerRight
+ *
+ * @param listenerPos Listener position
+ * @param sourcePos Sound source position
+ * @param listenerRight Listener's right-ear unit vector
+ * @returns Pan value from -1 (full left) to +1 (full right)
+ */
+export declare function calculatePanFromPositions(listenerPos: Position, sourcePos: Position, listenerRight: ListenerRight): number;
+/**
+ * Convert pan value (-1 to +1) to left/right channel percentages
+ *
+ * @param pan Pan value from -1 (full left) to +1 (full right)
+ * @param dxLocal Optional dxLocal value (unused, for compatibility)
+ * @returns Panning percentages for left and right channels
+ */
+export declare function panValueToPanning(pan: number, dxLocal?: number): Panning;

package/dist/utils/spatial/pan-calc.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Pan Calculations
+ *
+ * Functions for calculating stereo panning based on listener/source positions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateListenerRight = calculateListenerRight;
+exports.calculatePanFromPositions = calculatePanFromPositions;
+exports.panValueToPanning = panValueToPanning;
+/**
+ * Calculate listener's right-ear vector from yaw rotation
+ *
+ * COORDINATE SYSTEM: X=right, Y=up, Z=forward (datum at 0,0,0)
+ *
+ * Rotation convention (right-hand rule around Y-axis):
+ *   yaw = 0°   → facing +Z (forward), right ear points to +X
+ *   yaw = 90°  → facing +X (right),   right ear points to -Z
+ *   yaw = 180° → facing -Z (backward), right ear points to -X
+ *   yaw = 270° → facing -X (left),    right ear points to +Z
+ *
+ * @param yawDegrees Yaw rotation in degrees
+ * @returns Unit vector pointing to listener's right ear
+ */
+function calculateListenerRight(yawDegrees) {
+    const yawRad = (yawDegrees * Math.PI) / 180;
+    // Right ear vector - CLOCKWISE rotation (standard game engine convention)
+    return {
+        x: Math.cos(yawRad),
+        z: -Math.sin(yawRad), // NEGATIVE for clockwise rotation
+    };
+}
+/**
+ * Calculate pan value from listener and source positions
+ *
+ * Uses dot product projection onto listener's right-ear axis:
+ * dxLocal = vecToSource · listenerRight
+ *
+ * @param listenerPos Listener position
+ * @param sourcePos Sound source position
+ * @param listenerRight Listener's right-ear unit vector
+ * @returns Pan value from -1 (full left) to +1 (full right)
+ */
+function calculatePanFromPositions(listenerPos, sourcePos, listenerRight) {
+    // Calculate relative vector (speaker relative to listener)
+    const vecToSource = {
+        x: sourcePos.x - listenerPos.x,
+        z: sourcePos.z - listenerPos.z,
+    };
+    // Project onto listener's right-ear axis using dot product
+    // Positive = sound is to the RIGHT of listener
+    // Negative = sound is to the LEFT of listener
+    const dxLocal = vecToSource.x * listenerRight.x + vecToSource.z * listenerRight.z;
+    // Calculate dzLocal (forward/back component)
+    // For CLOCKWISE rotation: Forward = right rotated 90° CW: (x,z) -> (-z,x)
+    const listenerForward = { x: -listenerRight.z, z: listenerRight.x };
+    const dzLocal = vecToSource.x * listenerForward.x + vecToSource.z * listenerForward.z;
+    // TRUE 360° SPATIAL AUDIO PANNING
+    // Calculate angle from listener to source using atan2
+    const angleToSource = Math.atan2(dxLocal, dzLocal); // Radians: -π to +π
+    const rawPanValue = Math.sin(angleToSource); // -1 to +1
+    return rawPanValue;
+}
+/**
+ * Convert pan value (-1 to +1) to left/right channel percentages
+ *
+ * @param pan Pan value from -1 (full left) to +1 (full right)
+ * @param dxLocal Optional dxLocal value (unused, for compatibility)
+ * @returns Panning percentages for left and right channels
+ */
+function panValueToPanning(pan, dxLocal) {
+    const clamped = Math.max(-1, Math.min(1, pan));
+    // Map pan to asymmetric gains while keeping center at 100/100
+    const left = 100 * (1 - Math.max(0, clamped));
+    const right = 100 * (1 + Math.min(0, clamped));
+    return {
+        left: Math.max(0, Math.min(100, left)),
+        right: Math.max(0, Math.min(100, right)),
+    };
+}

package/package.json

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

package/dist/SpatialAudioManager.d.ts

@@ -1,271 +0,0 @@
-import { EventManager } from "./EventManager";
-import { Position } from "./types";
-type SpatialAudioDistanceConfig = {
-    refDistance?: number;
-    maxDistance?: number;
-    rolloffFactor?: number;
-    unit?: "auto" | "meters" | "centimeters";
-};
-type DenoiserOptions = {
-    enabled?: boolean;
-    threshold?: number;
-    noiseFloor?: number;
-    release?: number;
-    attack?: number;
-    holdMs?: number;
-    maxReduction?: number;
-    hissCut?: number;
-    expansionRatio?: number;
-    learnRate?: number;
-    voiceBoost?: number;
-    voiceSensitivity?: number;
-    voiceEnhancement?: boolean;
-    silenceFloor?: number;
-    silenceHoldMs?: number;
-    silenceReleaseMs?: number;
-    speechBoost?: number;
-    highBandGate?: number;
-    highBandAttack?: number;
-    highBandRelease?: number;
-};
-export type SpatialAudioOptions = {
-    distance?: SpatialAudioDistanceConfig;
-    denoiser?: DenoiserOptions;
-};
-export declare class SpatialAudioManager extends EventManager {
-    private static readonly BUILD_STAMP;
-    private audioContext;
-    private participantNodes;
-    private masterGainNode;
-    private monitoringIntervals;
-    private compressor;
-    private options;
-    private denoiseWorkletReady;
-    private denoiseWorkletUrl?;
-    private listenerPosition;
-    private listenerInitialized;
-    private listenerDirection;
-    private listenerRight;
-    private lastLogTime?;
-    private localParticipantId;
-    private isMasterMuted;
-    private smoothedPanValues;
-    private lastPanValue;
-    private lastSpatialUpdateTime;
-    private _spatialDebugTimes;
-    private panSmoothingFactor;
-    private panChangeThreshold;
-    private panCenterDeadZone;
-    private cachedSpeakerPositions;
-    private cachedListenerPosition;
-    private listenerPositionInitialized;
-    private positionSnapThreshold;
-    private _listenerDebugLogTime?;
-    private mlSuppressor;
-    private mlModelReady;
-    constructor(options?: SpatialAudioOptions);
-    getAudioContext(): AudioContext;
-    /**
-     * Initialize ML-based noise suppression (TensorFlow.js)
-     * Falls back to AudioWorklet denoiser if ML initialization fails
-     */
-    initializeMLNoiseSuppression(modelUrl: string): Promise<void>;
-    /**
-     * Get current noise suppression mode
-     */
-    getNoiseSuppressionMode(): 'ml' | 'audioworklet' | 'none';
-    /**
-     * True if the TFJS model assets were loaded and the model is ready.
-     * This does NOT mean it is currently processing the live WebAudio stream.
-     */
-    isMLModelLoaded(): boolean;
-    /**
-     * Setup spatial audio for a participant
-     *
-     * CRITICAL: Each participant gets their OWN audio processing chain:
-     * Stream -> Source -> Panner -> Analyser -> Gain -> Compressor -> Output
-     *
-     * This ensures:
-     * - Each voice is positioned independently in 3D space
-     * - No server-side mixing required
-     * - Scalable to unlimited participants (browser handles the mixing)
-     *
-     * @param participantId Unique ID for this participant
-     * @param track Audio track from MediaSoup consumer
-     * @param bypassSpatialization For testing - bypasses 3D positioning
-     */
-    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
-     *
-     * This is called every time we receive position/direction updates from the server.
-     *
-     * Position: Where the participant is in 3D space (their location)
-     * Direction: Which way they're facing (their forward vector)
-     *
-     * Example:
-     * - Position: (x: -200, y: 0, z: 100) = 2m to your left
-     * - Direction: (x: 0, y: 1, z: 0) = facing forward (away from you)
-     * - Result: Sound comes from your left, oriented as if speaking away
-     *
-     * The Web Audio API's PannerNode uses HRTF to create realistic 3D audio
-     * based on these parameters plus the listener's position/orientation.
-     *
-     * @param participantId Who to update
-     * @param position Where they are (from socket data)
-     * @param direction Which way they're facing (from socket data)
-     */
-    updateSpatialAudio(participantId: string, position: Position, direction?: {
-        x: number;
-        y: number;
-        z: number;
-    }, _spatialMeta?: {
-        pan?: number;
-        dxLocal?: number;
-    }): void;
-    /**
-     * Mute or unmute a participant's audio
-     * Used for channel-based audio routing (huddle vs spatial)
-     * @param participantId The participant to mute/unmute
-     * @param muted True to mute, false to unmute
-     */
-    setParticipantMuted(participantId: string, muted: boolean): void;
-    /**
-     * Master mute/unmute for ALL audio output
-     * Use this to prevent audio from playing until user explicitly joins the space.
-     * @param muted True to mute all audio, false to unmute
-     */
-    setMasterMuted(muted: boolean): void;
-    /**
-     * Get current master mute state
-     * @returns True if master mute is enabled
-     */
-    getMasterMuted(): boolean;
-    /**
-     * 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;
-        forwardZ: number;
-        upX: number;
-        upY: number;
-        upZ: number;
-    }): void;
-    /**
-     * POSITION-ONLY MODE: Set listener HEAD position (no direction needed)
-     * 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) - stored but not used for panning
-     * @param rot Rotation data (pitch, yaw, roll) - stored but not used for panning
-     */
-    setListenerFromLSD(listenerPos: Position, cameraPos: Position, lookAtPos: Position, rot?: {
-        x: number;
-        y: number;
-        z: number;
-    }, localParticipantId?: string): void;
-    private applyListenerTransform;
-    removeParticipant(participantId: string): void;
-    resumeAudioContext(): Promise<void>;
-    getAudioContextState(): AudioContextState;
-    private getDistanceConfig;
-    private applySpatialBoostIfNeeded;
-    private getDistanceBetween;
-    private calculateDistanceGain;
-    private normalizePositionUnits;
-    /**
-     * Snap position to grid to prevent jitter from micro-movements
-     * If the position hasn't changed significantly, return the cached position
-     * This prevents gain/pan fluctuation when users are "stationary"
-     *
-     * @param position New incoming position
-     * @param participantId Participant ID for caching (use 'listener' for listener)
-     * @returns Snapped position (either new or cached)
-     */
-    private snapPosition;
-    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;
-    /**
-     * Compute estimated head/mouth position from body position
-     * Body position is typically at feet/base - add head height offset
-     * Average human head height: 1.6m (adjustable based on avatar)
-     */
-    private computeHeadPosition;
-    private calculatePanning;
-    private panningFromPanValue;
-    /**
-     * SMOOTH PAN VALUE to prevent random left/right jumping
-     * Uses exponential moving average (EMA) to smooth out jittery position data
-     * With SNAP behavior for large direction changes (e.g., turning around)
-     * With DEAD-ZONE around center to prevent face-to-face oscillation
-     * @param participantId The participant to smooth pan for
-     * @param newPanValue The new calculated pan value (-1 to +1)
-     * @returns Smoothed pan value
-     */
-    private smoothPanValue;
-    private computeAzimuthFromPositions;
-    /**
-     * OLD METHOD - Kept for reference but not used in position-only mode
-     * Calculate angle between listener and sound source in degrees (0-360)
-     * 0° = front, 90° = right, 180° = back, 270° = left
-     */
-    private calculateAngle;
-    /**
-     * Calculate gain based on distance using logarithmic scale
-     * Distance range: 0.5m to 15m
-     * Gain range: 100% to 20% (reduced minimum for audibility at distance)
-     * Uses smoother curve for more consistent audio across distances
-     *
-     * TUNED FOR CONSISTENT VOICE CLARITY:
-     * - Near range (0-3m): Full volume for clear conversation
-     * - Medium range (3-8m): Gradual falloff, still easily audible
-     * - Far range (8-15m): Soft but still present
-     */
-    /**
-     * Calculate gain based on distance - AGGRESSIVE FALLOFF
-     *
-     * Uses inverse-square law (realistic sound propagation) with floor:
-     * Gain = 1 / (1 + k * distance²)
-     *
-     * Distance → Gain mapping:
-     * - 0-1m → 100% (full volume, very close)
-     * - 2m → ~80%
-     * - 3m → ~55%
-     * - 5m → ~30%
-     * - 8m → ~15%
-     * - 10m+ → 5% (minimum, barely audible)
-     */
-    private calculateLogarithmicGain;
-    /**
-     * Apply stereo panning to participant audio using StereoPannerNode
-     * This provides STABLE left-right panning without jitter
-     */
-    private applyStereoPanning;
-    private ensureDenoiseWorklet;
-    private resolveOptions;
-}
-export {};