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

package/dist/utils/audio/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Audio utilities - Re-exports all audio utility 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("./clarity-score"), exports);
+__exportStar(require("./voice-filter"), exports);

package/dist/utils/audio/voice-filter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Voice Filter Calculations
+ *
+ * Functions for adaptive voice filtering
+ */
+/**
+ * Calculate adaptive highpass frequency based on voice characteristics
+ * Analyzes audio spectrum and returns optimal highpass cutoff (85-300Hz)
+ *
+ * @param frequencyData Frequency data from AnalyserNode
+ * @param sampleRate Audio sample rate
+ * @returns Optimal highpass frequency
+ */
+export declare function calculateAdaptiveHighpass(frequencyData: Uint8Array, sampleRate: number): number;
+/**
+ * Voice filter chain configuration
+ */
+export interface VoiceFilterChain {
+    highpass: BiquadFilterNode;
+    lowpass: BiquadFilterNode;
+    voiceBand: BiquadFilterNode;
+    dynamicLowpass: BiquadFilterNode;
+}
+/**
+ * Create a voice-optimized filter chain
+ *
+ * @param audioContext AudioContext
+ * @returns Filter chain nodes
+ */
+export declare function createVoiceFilterChain(audioContext: AudioContext): VoiceFilterChain;

package/dist/utils/audio/voice-filter.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Voice Filter Calculations
+ *
+ * Functions for adaptive voice filtering
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateAdaptiveHighpass = calculateAdaptiveHighpass;
+exports.createVoiceFilterChain = createVoiceFilterChain;
+/**
+ * Calculate adaptive highpass frequency based on voice characteristics
+ * Analyzes audio spectrum and returns optimal highpass cutoff (85-300Hz)
+ *
+ * @param frequencyData Frequency data from AnalyserNode
+ * @param sampleRate Audio sample rate
+ * @returns Optimal highpass frequency
+ */
+function calculateAdaptiveHighpass(frequencyData, sampleRate) {
+    const bufferLength = frequencyData.length;
+    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 = frequencyData[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)
+        return Math.max(85, Math.min(300, 85 + (centroid - 100) * 0.5));
+    }
+    // Default frequency if no significant energy
+    return 100;
+}
+/**
+ * Create a voice-optimized filter chain
+ *
+ * @param audioContext AudioContext
+ * @returns Filter chain nodes
+ */
+function createVoiceFilterChain(audioContext) {
+    // HIGHPASS FILTER: Remove low-frequency rumble and plosives
+    const highpass = audioContext.createBiquadFilter();
+    highpass.type = 'highpass';
+    highpass.frequency.value = 100; // Cut below 100Hz
+    highpass.Q.value = 0.5; // Gentle slope
+    // LOWPASS FILTER: Remove high-frequency hiss
+    const lowpass = audioContext.createBiquadFilter();
+    lowpass.type = 'lowpass';
+    lowpass.frequency.value = 10000; // Cut above 10kHz
+    lowpass.Q.value = 0.5;
+    // VOICE BAND EMPHASIS (disabled by default - can cause resonance)
+    const voiceBand = audioContext.createBiquadFilter();
+    voiceBand.type = 'peaking';
+    voiceBand.frequency.value = 180;
+    voiceBand.Q.value = 0.5;
+    voiceBand.gain.value = 0; // Disabled
+    // DYNAMIC LOWPASS for high-frequency control
+    const dynamicLowpass = audioContext.createBiquadFilter();
+    dynamicLowpass.type = 'lowpass';
+    dynamicLowpass.frequency.value = 12000;
+    dynamicLowpass.Q.value = 0.5;
+    return { highpass, lowpass, voiceBand, dynamicLowpass };
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Utils module - Re-exports all utility functions
+ */
+export * from './spatial';
+export * from './position';
+export * from './smoothing';
+export * from './audio';

package/dist/utils/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Utils module - Re-exports all utility 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("./spatial"), exports);
+__exportStar(require("./position"), exports);
+__exportStar(require("./smoothing"), exports);
+__exportStar(require("./audio"), exports);

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';