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

package/dist/utils/position/coordinates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Coordinate System Conversions
+ *
+ * Converts between Unreal Engine and Standard coordinate systems
+ *
+ * Unreal Engine: X=forward, Y=right, Z=up (centimeters)
+ * Standard/WebAudio: X=right, Y=up, Z=forward (meters)
+ */
+import { Position } from '../../types/position';
+/**
+ * Convert Unreal Engine coordinates to Standard coordinates
+ *
+ * Unreal: X=forward, Y=right, Z=up (centimeters)
+ * Standard: X=right, Y=up, Z=forward (meters)
+ *
+ * @param unreal Position in Unreal coordinates
+ * @returns Position in Standard coordinates (meters)
+ */
+export declare function unrealToStandard(unreal: Position): Position;
+/**
+ * Convert Standard coordinates to Unreal Engine coordinates
+ *
+ * Standard: X=right, Y=up, Z=forward (meters)
+ * Unreal: X=forward, Y=right, Z=up (centimeters)
+ *
+ * @param standard Position in Standard coordinates
+ * @returns Position in Unreal coordinates (centimeters)
+ */
+export declare function standardToUnreal(standard: Position): Position;
+/**
+ * Auto-detect and convert to Standard coordinates
+ * Assumes Unreal if values > 50 (likely centimeters)
+ *
+ * @param position Position to convert
+ * @returns Position in Standard coordinates (meters)
+ */
+export declare function autoConvertToStandard(position: Position): Position;

package/dist/utils/position/coordinates.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Coordinate System Conversions
+ *
+ * Converts between Unreal Engine and Standard coordinate systems
+ *
+ * Unreal Engine: X=forward, Y=right, Z=up (centimeters)
+ * Standard/WebAudio: X=right, Y=up, Z=forward (meters)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unrealToStandard = unrealToStandard;
+exports.standardToUnreal = standardToUnreal;
+exports.autoConvertToStandard = autoConvertToStandard;
+/**
+ * Convert Unreal Engine coordinates to Standard coordinates
+ *
+ * Unreal: X=forward, Y=right, Z=up (centimeters)
+ * Standard: X=right, Y=up, Z=forward (meters)
+ *
+ * @param unreal Position in Unreal coordinates
+ * @returns Position in Standard coordinates (meters)
+ */
+function unrealToStandard(unreal) {
+    return {
+        x: unreal.y / 100, // Unreal Y (right) → Standard X (right), cm → m
+        y: unreal.z / 100, // Unreal Z (up) → Standard Y (up), cm → m
+        z: unreal.x / 100, // Unreal X (forward) → Standard Z (forward), cm → m
+    };
+}
+/**
+ * Convert Standard coordinates to Unreal Engine coordinates
+ *
+ * Standard: X=right, Y=up, Z=forward (meters)
+ * Unreal: X=forward, Y=right, Z=up (centimeters)
+ *
+ * @param standard Position in Standard coordinates
+ * @returns Position in Unreal coordinates (centimeters)
+ */
+function standardToUnreal(standard) {
+    return {
+        x: standard.z * 100, // Standard Z (forward) → Unreal X (forward), m → cm
+        y: standard.x * 100, // Standard X (right) → Unreal Y (right), m → cm
+        z: standard.y * 100, // Standard Y (up) → Unreal Z (up), m → cm
+    };
+}
+/**
+ * Auto-detect and convert to Standard coordinates
+ * Assumes Unreal if values > 50 (likely centimeters)
+ *
+ * @param position Position to convert
+ * @returns Position in Standard coordinates (meters)
+ */
+function autoConvertToStandard(position) {
+    const maxAxis = Math.max(Math.abs(position.x), Math.abs(position.y), Math.abs(position.z));
+    if (maxAxis > 50) {
+        // Likely Unreal coordinates (centimeters)
+        return unrealToStandard(position);
+    }
+    // Already in meters, assume Standard
+    return { ...position };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Position utilities - Re-exports all position functions
+ */
+export * from './normalize';
+export * from './snap';
+export * from './coordinates';

package/dist/utils/position/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Position utilities - Re-exports all position 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("./normalize"), exports);
+__exportStar(require("./snap"), exports);
+__exportStar(require("./coordinates"), exports);

package/dist/utils/position/normalize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Position Normalization
+ *
+ * Functions for normalizing position units (cm to meters, etc.)
+ */
+import { Position } from '../../types/position';
+/**
+ * Normalize position units to meters
+ * Detects if values are likely in centimeters and converts
+ *
+ * @param position Position to normalize
+ * @param unit Force unit interpretation: 'auto' | 'meters' | 'centimeters'
+ * @returns Position in meters
+ */
+export declare function normalizePositionUnits(position: Position, unit?: 'auto' | 'meters' | 'centimeters'): Position;
+/**
+ * Convert meters to centimeters
+ *
+ * @param position Position in meters
+ * @returns Position in centimeters
+ */
+export declare function metersToCentimeters(position: Position): Position;
+/**
+ * Convert centimeters to meters
+ *
+ * @param position Position in centimeters
+ * @returns Position in meters
+ */
+export declare function centimetersToMeters(position: Position): Position;
+/**
+ * Check if position values are likely in centimeters
+ *
+ * @param position Position to check
+ * @param threshold Threshold for detection (default: 50)
+ * @returns True if likely centimeters
+ */
+export declare function isLikelyCentimeters(position: Position, threshold?: number): boolean;

package/dist/utils/position/normalize.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Position Normalization
+ *
+ * Functions for normalizing position units (cm to meters, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePositionUnits = normalizePositionUnits;
+exports.metersToCentimeters = metersToCentimeters;
+exports.centimetersToMeters = centimetersToMeters;
+exports.isLikelyCentimeters = isLikelyCentimeters;
+/**
+ * Normalize position units to meters
+ * Detects if values are likely in centimeters and converts
+ *
+ * @param position Position to normalize
+ * @param unit Force unit interpretation: 'auto' | 'meters' | 'centimeters'
+ * @returns Position in meters
+ */
+function normalizePositionUnits(position, unit = 'auto') {
+    if (unit === 'meters') {
+        return { ...position };
+    }
+    if (unit === 'centimeters') {
+        return {
+            x: position.x / 100,
+            y: position.y / 100,
+            z: position.z / 100,
+        };
+    }
+    // Auto-detect: if any axis > 50, likely centimeters
+    const maxAxis = Math.max(Math.abs(position.x), Math.abs(position.y), Math.abs(position.z));
+    if (maxAxis > 50) {
+        return {
+            x: position.x / 100,
+            y: position.y / 100,
+            z: position.z / 100,
+        };
+    }
+    return { ...position };
+}
+/**
+ * Convert meters to centimeters
+ *
+ * @param position Position in meters
+ * @returns Position in centimeters
+ */
+function metersToCentimeters(position) {
+    return {
+        x: position.x * 100,
+        y: position.y * 100,
+        z: position.z * 100,
+    };
+}
+/**
+ * Convert centimeters to meters
+ *
+ * @param position Position in centimeters
+ * @returns Position in meters
+ */
+function centimetersToMeters(position) {
+    return {
+        x: position.x / 100,
+        y: position.y / 100,
+        z: position.z / 100,
+    };
+}
+/**
+ * Check if position values are likely in centimeters
+ *
+ * @param position Position to check
+ * @param threshold Threshold for detection (default: 50)
+ * @returns True if likely centimeters
+ */
+function isLikelyCentimeters(position, threshold = 50) {
+    const maxAxis = Math.max(Math.abs(position.x), Math.abs(position.y), Math.abs(position.z));
+    return maxAxis > threshold;
+}

package/dist/utils/position/snap.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Position Snapping
+ *
+ * Functions for reducing position jitter by snapping to a grid
+ */
+import { Position } from '../../types/position';
+/**
+ * Snap configuration
+ */
+export interface SnapConfig {
+    threshold: number;
+}
+/**
+ * Default snap configuration
+ * 0.30m = 30cm - ignores pixel streaming jitter, physics wobble, breathing
+ */
+export declare const SNAP_CONFIG: SnapConfig;
+/**
+ * Position snap cache for reducing jitter
+ */
+export declare class PositionSnapCache {
+    private cache;
+    private threshold;
+    constructor(threshold?: number);
+    /**
+     * Snap position to reduce jitter
+     * Returns cached position if movement is below threshold
+     *
+     * @param position New position
+     * @param id Identifier for this position (participantId or 'listener')
+     * @returns Snapped position
+     */
+    snap(position: Position, id: string): Position;
+    /**
+     * Clear cached position for an ID
+     */
+    clear(id: string): void;
+    /**
+     * Clear all cached positions
+     */
+    clearAll(): void;
+}
+/**
+ * Simple position snap without caching
+ * Snaps to grid based on threshold
+ *
+ * @param position Position to snap
+ * @param gridSize Grid size for snapping
+ * @returns Snapped position
+ */
+export declare function snapPositionSimple(position: Position, gridSize?: number): Position;

package/dist/utils/position/snap.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Position Snapping
+ *
+ * Functions for reducing position jitter by snapping to a grid
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PositionSnapCache = exports.SNAP_CONFIG = void 0;
+exports.snapPositionSimple = snapPositionSimple;
+/**
+ * Default snap configuration
+ * 0.30m = 30cm - ignores pixel streaming jitter, physics wobble, breathing
+ */
+exports.SNAP_CONFIG = {
+    threshold: 0.30,
+};
+/**
+ * Position snap cache for reducing jitter
+ */
+class PositionSnapCache {
+    constructor(threshold = exports.SNAP_CONFIG.threshold) {
+        this.cache = new Map();
+        this.threshold = threshold;
+    }
+    /**
+     * Snap position to reduce jitter
+     * Returns cached position if movement is below threshold
+     *
+     * @param position New position
+     * @param id Identifier for this position (participantId or 'listener')
+     * @returns Snapped position
+     */
+    snap(position, id) {
+        const cached = this.cache.get(id);
+        // If no cached position, use this one as baseline
+        if (!cached || (cached.x === 0 && cached.y === 0 && cached.z === 0)) {
+            this.cache.set(id, { ...position });
+            return position;
+        }
+        // Calculate movement distance
+        const dx = position.x - cached.x;
+        const dy = position.y - cached.y;
+        const dz = position.z - cached.z;
+        const movedDistance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        // If moved more than threshold, update cache and use new position
+        if (movedDistance > this.threshold) {
+            this.cache.set(id, { ...position });
+            return position;
+        }
+        // Position hasn't changed significantly - return cached
+        return cached;
+    }
+    /**
+     * Clear cached position for an ID
+     */
+    clear(id) {
+        this.cache.delete(id);
+    }
+    /**
+     * Clear all cached positions
+     */
+    clearAll() {
+        this.cache.clear();
+    }
+}
+exports.PositionSnapCache = PositionSnapCache;
+/**
+ * Simple position snap without caching
+ * Snaps to grid based on threshold
+ *
+ * @param position Position to snap
+ * @param gridSize Grid size for snapping
+ * @returns Snapped position
+ */
+function snapPositionSimple(position, gridSize = 0.1) {
+    return {
+        x: Math.round(position.x / gridSize) * gridSize,
+        y: Math.round(position.y / gridSize) * gridSize,
+        z: Math.round(position.z / gridSize) * gridSize,
+    };
+}

package/dist/utils/smoothing/gain-smoothing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Gain Smoothing
+ *
+ * Functions for smoothing audio gain changes to prevent clicks/pops
+ */
+/**
+ * Apply smooth gain transition using Web Audio API's setTargetAtTime
+ *
+ * @param gainNode The GainNode to modify
+ * @param targetGain Target gain value (0-1)
+ * @param audioContext AudioContext for timing
+ * @param timeConstant Time constant for transition (default: 0.1 = ~300ms to settle)
+ */
+export declare function applyGainSmooth(gainNode: GainNode, targetGain: number, audioContext: AudioContext, timeConstant?: number): void;
+/**
+ * Gain tracker for managing gain values per participant
+ */
+export declare class GainTracker {
+    private lastValues;
+    /**
+     * Get last gain value for a participant
+     */
+    get(participantId: string): number | undefined;
+    /**
+     * Set last gain value for a participant
+     */
+    set(participantId: string, value: number): void;
+    /**
+     * Clear gain value for a participant
+     */
+    clear(participantId: string): void;
+    /**
+     * Clear all gain values
+     */
+    clearAll(): void;
+}
+/**
+ * Apply smooth stereo pan transition
+ *
+ * @param stereoPanner The StereoPannerNode to modify
+ * @param panValue Target pan value (-1 to +1)
+ * @param audioContext AudioContext for timing
+ * @param timeConstant Time constant for transition (default: 0.05 = ~150ms)
+ */
+export declare function applyStereoPanSmooth(stereoPanner: StereoPannerNode, panValue: number, audioContext: AudioContext, timeConstant?: number): void;

package/dist/utils/smoothing/gain-smoothing.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Gain Smoothing
+ *
+ * Functions for smoothing audio gain changes to prevent clicks/pops
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GainTracker = void 0;
+exports.applyGainSmooth = applyGainSmooth;
+exports.applyStereoPanSmooth = applyStereoPanSmooth;
+/**
+ * Apply smooth gain transition using Web Audio API's setTargetAtTime
+ *
+ * @param gainNode The GainNode to modify
+ * @param targetGain Target gain value (0-1)
+ * @param audioContext AudioContext for timing
+ * @param timeConstant Time constant for transition (default: 0.1 = ~300ms to settle)
+ */
+function applyGainSmooth(gainNode, targetGain, audioContext, timeConstant = 0.1) {
+    try {
+        gainNode.gain.setTargetAtTime(targetGain, audioContext.currentTime, timeConstant);
+    }
+    catch (err) {
+        // Fallback: set value directly
+        gainNode.gain.value = targetGain;
+    }
+}
+/**
+ * Gain tracker for managing gain values per participant
+ */
+class GainTracker {
+    constructor() {
+        this.lastValues = new Map();
+    }
+    /**
+     * Get last gain value for a participant
+     */
+    get(participantId) {
+        return this.lastValues.get(participantId);
+    }
+    /**
+     * Set last gain value for a participant
+     */
+    set(participantId, value) {
+        this.lastValues.set(participantId, value);
+    }
+    /**
+     * Clear gain value for a participant
+     */
+    clear(participantId) {
+        this.lastValues.delete(participantId);
+    }
+    /**
+     * Clear all gain values
+     */
+    clearAll() {
+        this.lastValues.clear();
+    }
+}
+exports.GainTracker = GainTracker;
+/**
+ * Apply smooth stereo pan transition
+ *
+ * @param stereoPanner The StereoPannerNode to modify
+ * @param panValue Target pan value (-1 to +1)
+ * @param audioContext AudioContext for timing
+ * @param timeConstant Time constant for transition (default: 0.05 = ~150ms)
+ */
+function applyStereoPanSmooth(stereoPanner, panValue, audioContext, timeConstant = 0.05) {
+    try {
+        stereoPanner.pan.setTargetAtTime(panValue, audioContext.currentTime, timeConstant);
+    }
+    catch (err) {
+        // Fallback: set value directly
+        stereoPanner.pan.value = panValue;
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Smoothing utilities - Re-exports all smoothing functions
+ */
+export * from './pan-smoothing';
+export * from './gain-smoothing';

package/dist/utils/smoothing/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Smoothing utilities - Re-exports all smoothing 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("./pan-smoothing"), exports);
+__exportStar(require("./gain-smoothing"), exports);

package/dist/utils/smoothing/pan-smoothing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pan Smoothing
+ *
+ * Classes and functions for smoothing stereo panning values
+ * to prevent audio jitter and rapid left/right jumping
+ */
+/**
+ * Pan smoother configuration
+ */
+export interface PanSmootherOptions {
+    smoothingFactor?: number;
+    changeThreshold?: number;
+    centerDeadZone?: number;
+}
+/**
+ * Default pan smoother options
+ */
+export declare const DEFAULT_PAN_SMOOTHER_OPTIONS: Required<PanSmootherOptions>;
+/**
+ * Pan smoother class
+ * Smooths pan values using EMA with dead-zone and threshold
+ */
+export declare class PanSmoother {
+    private smoothedValues;
+    private options;
+    constructor(options?: PanSmootherOptions);
+    /**
+     * Smooth a pan value for a participant
+     *
+     * @param participantId Participant ID
+     * @param newPanValue New pan value (-1 to +1)
+     * @returns Smoothed pan value
+     */
+    smooth(participantId: string, newPanValue: number): number;
+    /**
+     * Clear smoothed value for a participant
+     */
+    clear(participantId: string): void;
+    /**
+     * Clear all smoothed values
+     */
+    clearAll(): void;
+}

package/dist/utils/smoothing/pan-smoothing.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Pan Smoothing
+ *
+ * Classes and functions for smoothing stereo panning values
+ * to prevent audio jitter and rapid left/right jumping
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PanSmoother = exports.DEFAULT_PAN_SMOOTHER_OPTIONS = void 0;
+/**
+ * Default pan smoother options
+ */
+exports.DEFAULT_PAN_SMOOTHER_OPTIONS = {
+    smoothingFactor: 0.35,
+    changeThreshold: 0.02,
+    centerDeadZone: 0.03,
+};
+/**
+ * Pan smoother class
+ * Smooths pan values using EMA with dead-zone and threshold
+ */
+class PanSmoother {
+    constructor(options = {}) {
+        this.smoothedValues = new Map();
+        this.options = { ...exports.DEFAULT_PAN_SMOOTHER_OPTIONS, ...options };
+    }
+    /**
+     * Smooth a pan value for a participant
+     *
+     * @param participantId Participant ID
+     * @param newPanValue New pan value (-1 to +1)
+     * @returns Smoothed pan value
+     */
+    smooth(participantId, newPanValue) {
+        const previousPan = this.smoothedValues.get(participantId);
+        // DEAD-ZONE: If new pan is very close to center, snap to exactly 0
+        let targetPan = newPanValue;
+        if (Math.abs(newPanValue) < this.options.centerDeadZone) {
+            targetPan = 0;
+        }
+        // If no previous value, initialize with current value
+        if (previousPan === undefined) {
+            this.smoothedValues.set(participantId, targetPan);
+            return targetPan;
+        }
+        // Calculate the change from previous pan
+        const panChange = Math.abs(targetPan - previousPan);
+        // If change is below threshold, keep previous value (prevents micro-jitter)
+        if (panChange < this.options.changeThreshold) {
+            return previousPan;
+        }
+        // Determine effective smoothing factor based on change magnitude
+        let effectiveSmoothingFactor = 0.7; // High smoothing = slow but stable
+        const signFlipped = (previousPan > 0 && targetPan < 0) || (previousPan < 0 && targetPan > 0);
+        const bothNearCenter = Math.abs(previousPan) < 0.2 && Math.abs(targetPan) < 0.2;
+        if (bothNearCenter) {
+            // Near center - use moderate smoothing
+            effectiveSmoothingFactor = 0.5;
+        }
+        else if (signFlipped && panChange > 1.0) {
+            // Full flip - likely jitter, use HEAVY smoothing
+            effectiveSmoothingFactor = 0.85;
+        }
+        // Apply exponential moving average smoothing
+        const smoothedPan = previousPan * effectiveSmoothingFactor + targetPan * (1 - effectiveSmoothingFactor);
+        // Apply dead-zone to final smoothed value
+        const finalPan = Math.abs(smoothedPan) < this.options.centerDeadZone ? 0 : smoothedPan;
+        // Store for next update
+        this.smoothedValues.set(participantId, finalPan);
+        return finalPan;
+    }
+    /**
+     * Clear smoothed value for a participant
+     */
+    clear(participantId) {
+        this.smoothedValues.delete(participantId);
+    }
+    /**
+     * Clear all smoothed values
+     */
+    clearAll() {
+        this.smoothedValues.clear();
+    }
+}
+exports.PanSmoother = PanSmoother;

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

@@ -0,0 +1,24 @@
+/**
+ * Angle Calculations
+ *
+ * Functions for computing angles between positions
+ */
+import { Position } from '../../types/position';
+/**
+ * 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)
+ */
+export declare function computeAzimuthFromPositions(listener: Position, source: Position): number;
+/**
+ * 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
+ */
+export declare function calculateAngleToSource(listenerPos: Position, sourcePos: Position, listenerForward: Position): number;