@newgameplusinc/odyssey-audio-video-sdk-dev 1.0.257 → 1.0.259

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

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Angle Calculations
+ *
+ * Functions for computing angles between positions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeAzimuthFromPositions = computeAzimuthFromPositions;
+exports.calculateAngleToSource = calculateAngleToSource;
+/**
+ * Compute azimuth angle from listener to source
+ *
+ * @param listener Listener position
+ * @param source Source position
+ * @returns Angle in degrees (0-360), where 0° = forward (+Z), 90° = right (+X)
+ */
+function computeAzimuthFromPositions(listener, source) {
+    const vx = source.x - listener.x;
+    const vz = source.z - listener.z;
+    const angleRad = Math.atan2(vx, vz); // 0° = forward (Z+), 90° = right (X+)
+    const deg = (angleRad * 180) / Math.PI;
+    const normalized = (deg + 360) % 360;
+    return normalized;
+}
+/**
+ * Calculate angle between listener and sound source in degrees
+ * Takes into account listener's forward direction
+ *
+ * @param listenerPos Listener position
+ * @param sourcePos Source position
+ * @param listenerForward Listener's forward direction vector
+ * @returns Angle in degrees (0-360): 0° = front, 90° = right, 180° = back, 270° = left
+ */
+function calculateAngleToSource(listenerPos, sourcePos, listenerForward) {
+    // Use X/Z as the horizontal plane for 360° panning
+    const vx = sourcePos.x - listenerPos.x;
+    const vz = sourcePos.z - listenerPos.z;
+    // Project listener forward onto X/Z plane
+    let fx = listenerForward.x;
+    let fz = listenerForward.z;
+    const fLen = Math.hypot(fx, fz);
+    if (fLen < 1e-4) {
+        // Fallback: if forward is nearly vertical/invalid, assume world-forward
+        fx = 0;
+        fz = 1;
+    }
+    else {
+        fx /= fLen;
+        fz /= fLen;
+    }
+    const vLen = Math.hypot(vx, vz);
+    if (vLen < 1e-4) {
+        return 0;
+    }
+    const nx = vx / vLen;
+    const nz = vz / vLen;
+    // Signed angle from forward->source
+    const dot = fx * nx + fz * nz;
+    const cross = fx * nz - fz * nx;
+    let radians = Math.atan2(cross, dot);
+    // atan2 gives [-π, π]; map to [0, 2π)
+    if (radians < 0) {
+        radians += Math.PI * 2;
+    }
+    const degrees = (radians * 180) / Math.PI;
+    // Convert to convention where +90 is to the right
+    const angle = (360 - degrees) % 360;
+    return angle;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Distance Calculations
+ *
+ * Functions for calculating distances between positions in 3D space
+ */
+import { Position } from '../../types/position';
+/**
+ * Calculate 3D Euclidean distance between two positions
+ * distance = √(Δx² + Δy² + Δz²)
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Distance in the same units as input positions
+ */
+export declare function getDistanceBetween(a: Position, b: Position): number;
+/**
+ * Calculate horizontal distance (XZ plane only, ignoring Y/height)
+ * Useful for spatial audio where vertical distance matters less
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Horizontal distance
+ */
+export declare function getHorizontalDistance(a: Position, b: Position): number;
+/**
+ * Check if a position is within a certain range of another
+ *
+ * @param a First position
+ * @param b Second position
+ * @param maxDistance Maximum allowed distance
+ * @returns True if within range
+ */
+export declare function isWithinRange(a: Position, b: Position, maxDistance: number): boolean;

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

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Distance Calculations
+ *
+ * Functions for calculating distances between positions in 3D space
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDistanceBetween = getDistanceBetween;
+exports.getHorizontalDistance = getHorizontalDistance;
+exports.isWithinRange = isWithinRange;
+/**
+ * Calculate 3D Euclidean distance between two positions
+ * distance = √(Δx² + Δy² + Δz²)
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Distance in the same units as input positions
+ */
+function getDistanceBetween(a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const dz = b.z - a.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * Calculate horizontal distance (XZ plane only, ignoring Y/height)
+ * Useful for spatial audio where vertical distance matters less
+ *
+ * @param a First position
+ * @param b Second position
+ * @returns Horizontal distance
+ */
+function getHorizontalDistance(a, b) {
+    const dx = b.x - a.x;
+    const dz = b.z - a.z;
+    return Math.sqrt(dx * dx + dz * dz);
+}
+/**
+ * Check if a position is within a certain range of another
+ *
+ * @param a First position
+ * @param b Second position
+ * @param maxDistance Maximum allowed distance
+ * @returns True if within range
+ */
+function isWithinRange(a, b, maxDistance) {
+    return getDistanceBetween(a, b) <= maxDistance;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Gain Calculations
+ *
+ * Functions for calculating audio gain based on distance
+ */
+/**
+ * Gain calculation configuration
+ */
+export interface GainConfig {
+    minDistance?: number;
+    maxDistance?: number;
+    minGain?: number;
+    falloffRate?: number;
+}
+/**
+ * Default gain configuration
+ */
+export declare const DEFAULT_GAIN_CONFIG: Required<GainConfig>;
+/**
+ * Calculate gain based on distance using inverse-square law
+ *
+ * Uses inverse-square law (realistic sound propagation) with floor:
+ * Gain = 1 / (1 + k * distance²)
+ *
+ * Distance → Gain mapping (with defaults):
+ * - 0-1m → 100% (full volume, very close)
+ * - 2m → ~80%
+ * - 3m → ~55%
+ * - 5m → ~30%
+ * - 8m → ~15%
+ * - 10m+ → 5% (minimum, barely audible)
+ *
+ * @param distance Distance in meters
+ * @param config Optional gain configuration
+ * @returns Gain as percentage (0-100)
+ */
+export declare function calculateLogarithmicGain(distance: number, config?: GainConfig): number;

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

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Gain Calculations
+ *
+ * Functions for calculating audio gain based on distance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GAIN_CONFIG = void 0;
+exports.calculateLogarithmicGain = calculateLogarithmicGain;
+/**
+ * Default gain configuration
+ */
+exports.DEFAULT_GAIN_CONFIG = {
+    minDistance: 1.0, // Full volume at 1m or closer
+    maxDistance: 15.0, // Cannot hear beyond 15m
+    minGain: 5, // Minimum 5% at far distances
+    falloffRate: 0.15, // Controls how fast volume drops
+};
+/**
+ * Calculate gain based on distance using inverse-square law
+ *
+ * Uses inverse-square law (realistic sound propagation) with floor:
+ * Gain = 1 / (1 + k * distance²)
+ *
+ * Distance → Gain mapping (with defaults):
+ * - 0-1m → 100% (full volume, very close)
+ * - 2m → ~80%
+ * - 3m → ~55%
+ * - 5m → ~30%
+ * - 8m → ~15%
+ * - 10m+ → 5% (minimum, barely audible)
+ *
+ * @param distance Distance in meters
+ * @param config Optional gain configuration
+ * @returns Gain as percentage (0-100)
+ */
+function calculateLogarithmicGain(distance, config = {}) {
+    const { minDistance, maxDistance, minGain, falloffRate, } = { ...exports.DEFAULT_GAIN_CONFIG, ...config };
+    // Beyond max distance = minimum gain
+    if (distance >= maxDistance)
+        return minGain;
+    // Full volume within minimum distance
+    if (distance <= minDistance)
+        return 100;
+    // Inverse square falloff: gain = 1 / (1 + k * d²)
+    // This models realistic sound propagation in air
+    const effectiveDistance = distance - minDistance;
+    const attenuation = 1 / (1 + falloffRate * effectiveDistance * effectiveDistance);
+    // Scale to percentage range: minGain to 100
+    const gain = minGain + attenuation * (100 - minGain);
+    return Math.round(gain);
+}

package/dist/utils/spatial/head-position.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Head Position Calculations
+ *
+ * Functions for computing head/mouth position from body position
+ */
+import { Position } from '../../types/position';
+/**
+ * Compute estimated head/mouth position from body position
+ * Body position is typically at feet/base - add head height offset
+ *
+ * @param bodyPosition Body position (typically feet/base)
+ * @param headHeight Height offset to add (default: 1.6m)
+ * @returns Estimated head position
+ */
+export declare function computeHeadPosition(bodyPosition: Position, headHeight?: number): Position;
+/**
+ * Parse body height string to meters
+ * Handles various formats: "170", "170cm", "1.7m", etc.
+ *
+ * @param bodyHeightStr Body height string from participant data
+ * @param fallback Fallback height in meters (default: 1.6)
+ * @returns Height in meters
+ */
+export declare function parseBodyHeight(bodyHeightStr?: string, fallback?: number): number;
+/**
+ * Get vector from listener to target position
+ *
+ * @param listenerPosition Listener position
+ * @param targetPosition Target position
+ * @returns Vector from listener to target
+ */
+export declare function getVectorFromListener(listenerPosition: Position, targetPosition: Position): Position;

package/dist/utils/spatial/head-position.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Head Position Calculations
+ *
+ * Functions for computing head/mouth position from body position
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHeadPosition = computeHeadPosition;
+exports.parseBodyHeight = parseBodyHeight;
+exports.getVectorFromListener = getVectorFromListener;
+/**
+ * Default head height offset in meters
+ * Average human head height above body origin
+ */
+const DEFAULT_HEAD_HEIGHT = 1.6;
+/**
+ * Compute estimated head/mouth position from body position
+ * Body position is typically at feet/base - add head height offset
+ *
+ * @param bodyPosition Body position (typically feet/base)
+ * @param headHeight Height offset to add (default: 1.6m)
+ * @returns Estimated head position
+ */
+function computeHeadPosition(bodyPosition, headHeight = DEFAULT_HEAD_HEIGHT) {
+    return {
+        x: bodyPosition.x,
+        y: bodyPosition.y + headHeight,
+        z: bodyPosition.z,
+    };
+}
+/**
+ * Parse body height string to meters
+ * Handles various formats: "170", "170cm", "1.7m", etc.
+ *
+ * @param bodyHeightStr Body height string from participant data
+ * @param fallback Fallback height in meters (default: 1.6)
+ * @returns Height in meters
+ */
+function parseBodyHeight(bodyHeightStr, fallback = 1.6) {
+    if (!bodyHeightStr)
+        return fallback;
+    const str = bodyHeightStr.toLowerCase().trim();
+    // Try parsing as number with optional unit
+    const numMatch = str.match(/^([\d.]+)\s*(cm|m)?$/);
+    if (numMatch) {
+        const value = parseFloat(numMatch[1]);
+        const unit = numMatch[2];
+        if (isNaN(value))
+            return fallback;
+        if (unit === 'm') {
+            return value;
+        }
+        else if (unit === 'cm' || value > 10) {
+            // Assume centimeters if > 10 or explicitly cm
+            return value / 100;
+        }
+        else {
+            return value;
+        }
+    }
+    return fallback;
+}
+/**
+ * Get vector from listener to target position
+ *
+ * @param listenerPosition Listener position
+ * @param targetPosition Target position
+ * @returns Vector from listener to target
+ */
+function getVectorFromListener(listenerPosition, targetPosition) {
+    return {
+        x: targetPosition.x - listenerPosition.x,
+        y: targetPosition.y - listenerPosition.y,
+        z: targetPosition.z - listenerPosition.z,
+    };
+}

package/dist/utils/spatial/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Spatial utilities - Re-exports all spatial calculation functions
+ */
+export * from './distance-calc';
+export * from './gain-calc';
+export * from './pan-calc';
+export * from './head-position';
+export * from './listener-calc';
+export * from './angle-calc';

package/dist/utils/spatial/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Spatial utilities - Re-exports all spatial calculation functions
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./distance-calc"), exports);
+__exportStar(require("./gain-calc"), exports);
+__exportStar(require("./pan-calc"), exports);
+__exportStar(require("./head-position"), exports);
+__exportStar(require("./listener-calc"), exports);
+__exportStar(require("./angle-calc"), exports);

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

@@ -0,0 +1,28 @@
+/**
+ * Listener Orientation Calculations
+ *
+ * Functions for computing listener orientation vectors
+ */
+import { Position, ListenerRight, Rotation } from '../../types/position';
+/**
+ * Full listener orientation (forward and up vectors)
+ */
+export interface ListenerOrientation {
+    forward: Position;
+    up: Position;
+}
+/**
+ * Calculate listener's right-ear vector from rotation
+ *
+ * @param rot Rotation in degrees (pitch, yaw, roll)
+ * @returns Right-ear unit vector (XZ plane)
+ */
+export declare function getListenerRightFromRotation(rot?: Rotation): ListenerRight;
+/**
+ * Calculate full listener orientation from camera vectors
+ *
+ * @param cameraPos Camera position
+ * @param lookAtPos Look-at target position
+ * @returns Forward and up vectors for Web Audio API
+ */
+export declare function calculateListenerOrientation(cameraPos: Position, lookAtPos: Position): ListenerOrientation | null;

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

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Listener Orientation Calculations
+ *
+ * Functions for computing listener orientation vectors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getListenerRightFromRotation = getListenerRightFromRotation;
+exports.calculateListenerOrientation = calculateListenerOrientation;
+/**
+ * Calculate listener's right-ear vector from rotation
+ *
+ * @param rot Rotation in degrees (pitch, yaw, roll)
+ * @returns Right-ear unit vector (XZ plane)
+ */
+function getListenerRightFromRotation(rot) {
+    if (rot && typeof rot.y === 'number') {
+        const yawRad = (rot.y * Math.PI) / 180;
+        // Right ear vector - CLOCKWISE rotation (standard game engine convention)
+        // At yaw=0: facing +Z, right ear at +X → (1, 0)
+        // At yaw=90: facing +X, right ear at -Z → (0, -1)
+        return {
+            x: Math.cos(yawRad),
+            z: -Math.sin(yawRad),
+        };
+    }
+    // Fallback: assume facing forward with right ear to +X
+    return { x: 1, z: 0 };
+}
+/**
+ * Calculate full listener orientation from camera vectors
+ *
+ * @param cameraPos Camera position
+ * @param lookAtPos Look-at target position
+ * @returns Forward and up vectors for Web Audio API
+ */
+function calculateListenerOrientation(cameraPos, lookAtPos) {
+    // Calculate forward vector (from camera to look-at point)
+    const forwardX = lookAtPos.x - cameraPos.x;
+    const forwardY = lookAtPos.y - cameraPos.y;
+    const forwardZ = lookAtPos.z - cameraPos.z;
+    // Normalize forward vector
+    const forwardLen = Math.sqrt(forwardX * forwardX + forwardY * forwardY + forwardZ * forwardZ);
+    if (forwardLen < 0.001) {
+        return null;
+    }
+    const fwdX = forwardX / forwardLen;
+    const fwdY = forwardY / forwardLen;
+    const fwdZ = forwardZ / forwardLen;
+    // Calculate right vector (cross product of world up and forward)
+    const worldUp = { x: 0, y: 1, z: 0 };
+    const rightX = worldUp.y * fwdZ - worldUp.z * fwdY;
+    const rightY = worldUp.z * fwdX - worldUp.x * fwdZ;
+    const rightZ = worldUp.x * fwdY - worldUp.y * fwdX;
+    const rightLen = Math.sqrt(rightX * rightX + rightY * rightY + rightZ * rightZ);
+    if (rightLen < 0.001) {
+        // Forward is parallel to world up, use fallback
+        return {
+            forward: { x: fwdX, y: fwdY, z: fwdZ },
+            up: { x: 0, y: 1, z: 0 },
+        };
+    }
+    const rX = rightX / rightLen;
+    const rY = rightY / rightLen;
+    const rZ = rightZ / rightLen;
+    // Calculate true up vector (cross product of forward and right)
+    const upX = fwdY * rZ - fwdZ * rY;
+    const upY = fwdZ * rX - fwdX * rZ;
+    const upZ = fwdX * rY - fwdY * rX;
+    return {
+        forward: { x: fwdX, y: fwdY, z: fwdZ },
+        up: { x: upX, y: upY, z: upZ },
+    };
+}

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.257",
+  "version": "1.0.259",
   "description": "Odyssey Spatial Audio & Video SDK using MediaSoup for real-time communication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",