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

package/README.md

@@ -1,7 +1,51 @@
 # Odyssey Audio/Video SDK (MediaSoup + Web Audio)
 
 This package exposes `OdysseySpatialComms`, a thin TypeScript client that glues together:
-
+## code structure:
+src/
+├── index.ts                    # Main SDK entry (OdysseySpatialComms class)
+├── types/                      # All TypeScript interfaces
+│   ├── position.ts            # Position, Direction, Rotation types
+│   ├── participant.ts         # Participant, MediaState types
+│   ├── events.ts              # All event types (OdysseyEvent, etc.)
+│   ├── room.ts                # Room-related types
+│   └── index.ts               # Re-exports all types
+├── utils/
+│   ├── spatial/               # Spatial audio calculations
+│   │   ├── distance-calc.ts   # Distance calculations
+│   │   ├── gain-calc.ts       # Logarithmic gain
+│   │   ├── pan-calc.ts        # Stereo panning
+│   │   ├── head-position.ts   # Head/body position
+│   │   ├── listener-calc.ts   # Listener orientation
+│   │   └── angle-calc.ts      # Azimuth/angle calculations
+│   ├── position/              # Position utilities
+│   │   ├── normalize.ts       # Unit normalization (cm/m)
+│   │   ├── snap.ts            # Position snapping cache
+│   │   └── coordinates.ts     # Unreal↔Standard conversion
+│   ├── smoothing/             # Audio smoothing
+│   │   ├── pan-smoothing.ts   # Pan interpolation
+│   │   └── gain-smoothing.ts  # Gain interpolation
+│   └── audio/                 # Audio quality
+│       ├── clarity-score.ts   # Voice clarity
+│       └── voice-filter.ts    # Voice filtering
+├── channels/
+│   ├── spatial/               # Spatial audio channel
+│   │   ├── SpatialAudioChannel.ts  # Main spatial processor
+│   │   └── SpatialAudioTypes.ts    # Channel-specific types
+│   └── huddle/                # Huddle/private channel
+│       ├── HuddleChannel.ts   # Huddle channel manager
+│       └── HuddleTypes.ts     # Huddle types
+├── audio/                     # Audio processing
+│   ├── AudioPipeline.ts       # Master audio chain
+│   ├── AudioNodeFactory.ts    # Web Audio node factory
+│   └── MLNoiseSuppressor.ts   # TensorFlow noise suppression
+├── core/                      # Core managers
+│   ├── EventManager.ts        # Event emitter base
+│   └── MediasoupManager.ts    # WebRTC transport manager
+└── sdk/
+    └── index.ts               # Public SDK exports
+
+    
 - **MediaSoup SFU** for ultra-low-latency audio/video routing
 - **Web Audio API** for Apple-like spatial mixing via `SpatialAudioManager`
 - **Socket telemetry** (position + direction) so every browser hears/sees everyone exactly where they are in the 3D world

package/dist/audio/AudioNodeFactory.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Audio Node Factory
+ *
+ * Factory functions for creating Web Audio API nodes
+ * with optimal configurations for voice communication
+ */
+/**
+ * PannerNode configuration for spatial audio
+ */
+export interface PannerConfig {
+    refDistance?: number;
+    maxDistance?: number;
+    rolloffFactor?: number;
+    panningModel?: PanningModelType;
+    distanceModel?: DistanceModelType;
+    coneInnerAngle?: number;
+    coneOuterAngle?: number;
+    coneOuterGain?: number;
+}
+/**
+ * Default panner configuration for voice
+ */
+export declare const DEFAULT_PANNER_CONFIG: Required<PannerConfig>;
+/**
+ * Create configured PannerNode for 3D spatial audio
+ *
+ * @param audioContext AudioContext
+ * @param config Optional panner configuration
+ * @returns Configured PannerNode
+ */
+export declare function createPanner(audioContext: AudioContext, config?: PannerConfig): PannerNode;
+/**
+ * Create StereoPannerNode for left/right panning
+ *
+ * @param audioContext AudioContext
+ * @param initialPan Initial pan value (-1 to +1)
+ * @returns StereoPannerNode
+ */
+export declare function createStereoPanner(audioContext: AudioContext, initialPan?: number): StereoPannerNode;
+/**
+ * Create GainNode with initial value
+ *
+ * @param audioContext AudioContext
+ * @param initialGain Initial gain value
+ * @returns GainNode
+ */
+export declare function createGain(audioContext: AudioContext, initialGain?: number): GainNode;
+/**
+ * Create AnalyserNode for audio visualization/monitoring
+ *
+ * @param audioContext AudioContext
+ * @param fftSize FFT size (default: 2048)
+ * @returns AnalyserNode
+ */
+export declare function createAnalyser(audioContext: AudioContext, fftSize?: number): AnalyserNode;
+/**
+ * Highpass filter configuration
+ */
+export interface HighpassConfig {
+    frequency?: number;
+    Q?: number;
+}
+/**
+ * Create highpass filter for removing low-frequency rumble
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+export declare function createHighpassFilter(audioContext: AudioContext, config?: HighpassConfig): BiquadFilterNode;
+/**
+ * Lowpass filter configuration
+ */
+export interface LowpassConfig {
+    frequency?: number;
+    Q?: number;
+}
+/**
+ * Create lowpass filter for removing high-frequency hiss
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+export declare function createLowpassFilter(audioContext: AudioContext, config?: LowpassConfig): BiquadFilterNode;
+/**
+ * Peaking filter configuration
+ */
+export interface PeakingConfig {
+    frequency?: number;
+    Q?: number;
+    gain?: number;
+}
+/**
+ * Create peaking filter for frequency emphasis
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+export declare function createPeakingFilter(audioContext: AudioContext, config?: PeakingConfig): BiquadFilterNode;
+/**
+ * Compressor configuration
+ */
+export interface CompressorConfig {
+    threshold?: number;
+    knee?: number;
+    ratio?: number;
+    attack?: number;
+    release?: number;
+}
+/**
+ * Create DynamicsCompressorNode with configuration
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns DynamicsCompressorNode
+ */
+export declare function createCompressor(audioContext: AudioContext, config?: CompressorConfig): DynamicsCompressorNode;
+/**
+ * Create MediaStreamAudioSourceNode from track
+ *
+ * @param audioContext AudioContext
+ * @param track MediaStreamTrack (audio)
+ * @returns MediaStreamAudioSourceNode and MediaStream
+ */
+export declare function createMediaStreamSource(audioContext: AudioContext, track: MediaStreamTrack): {
+    source: MediaStreamAudioSourceNode;
+    stream: MediaStream;
+};

package/dist/audio/AudioNodeFactory.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Audio Node Factory
+ *
+ * Factory functions for creating Web Audio API nodes
+ * with optimal configurations for voice communication
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PANNER_CONFIG = void 0;
+exports.createPanner = createPanner;
+exports.createStereoPanner = createStereoPanner;
+exports.createGain = createGain;
+exports.createAnalyser = createAnalyser;
+exports.createHighpassFilter = createHighpassFilter;
+exports.createLowpassFilter = createLowpassFilter;
+exports.createPeakingFilter = createPeakingFilter;
+exports.createCompressor = createCompressor;
+exports.createMediaStreamSource = createMediaStreamSource;
+/**
+ * Default panner configuration for voice
+ */
+exports.DEFAULT_PANNER_CONFIG = {
+    refDistance: 1.2,
+    maxDistance: 15,
+    rolloffFactor: 1.35,
+    panningModel: 'HRTF',
+    distanceModel: 'inverse',
+    coneInnerAngle: 360,
+    coneOuterAngle: 360,
+    coneOuterGain: 0.3,
+};
+/**
+ * Create configured PannerNode for 3D spatial audio
+ *
+ * @param audioContext AudioContext
+ * @param config Optional panner configuration
+ * @returns Configured PannerNode
+ */
+function createPanner(audioContext, config = {}) {
+    const panner = audioContext.createPanner();
+    const cfg = { ...exports.DEFAULT_PANNER_CONFIG, ...config };
+    panner.panningModel = cfg.panningModel;
+    panner.distanceModel = cfg.distanceModel;
+    panner.refDistance = cfg.refDistance;
+    panner.maxDistance = cfg.maxDistance;
+    panner.rolloffFactor = cfg.rolloffFactor;
+    panner.coneInnerAngle = cfg.coneInnerAngle;
+    panner.coneOuterAngle = cfg.coneOuterAngle;
+    panner.coneOuterGain = cfg.coneOuterGain;
+    return panner;
+}
+/**
+ * Create StereoPannerNode for left/right panning
+ *
+ * @param audioContext AudioContext
+ * @param initialPan Initial pan value (-1 to +1)
+ * @returns StereoPannerNode
+ */
+function createStereoPanner(audioContext, initialPan = 0) {
+    const panner = audioContext.createStereoPanner();
+    panner.pan.value = initialPan;
+    return panner;
+}
+/**
+ * Create GainNode with initial value
+ *
+ * @param audioContext AudioContext
+ * @param initialGain Initial gain value
+ * @returns GainNode
+ */
+function createGain(audioContext, initialGain = 1.0) {
+    const gain = audioContext.createGain();
+    gain.gain.value = initialGain;
+    return gain;
+}
+/**
+ * Create AnalyserNode for audio visualization/monitoring
+ *
+ * @param audioContext AudioContext
+ * @param fftSize FFT size (default: 2048)
+ * @returns AnalyserNode
+ */
+function createAnalyser(audioContext, fftSize = 2048) {
+    const analyser = audioContext.createAnalyser();
+    analyser.fftSize = fftSize;
+    return analyser;
+}
+/**
+ * Create highpass filter for removing low-frequency rumble
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+function createHighpassFilter(audioContext, config = {}) {
+    const filter = audioContext.createBiquadFilter();
+    filter.type = 'highpass';
+    filter.frequency.value = config.frequency ?? 100;
+    filter.Q.value = config.Q ?? 0.5;
+    return filter;
+}
+/**
+ * Create lowpass filter for removing high-frequency hiss
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+function createLowpassFilter(audioContext, config = {}) {
+    const filter = audioContext.createBiquadFilter();
+    filter.type = 'lowpass';
+    filter.frequency.value = config.frequency ?? 10000;
+    filter.Q.value = config.Q ?? 0.5;
+    return filter;
+}
+/**
+ * Create peaking filter for frequency emphasis
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns BiquadFilterNode
+ */
+function createPeakingFilter(audioContext, config = {}) {
+    const filter = audioContext.createBiquadFilter();
+    filter.type = 'peaking';
+    filter.frequency.value = config.frequency ?? 180;
+    filter.Q.value = config.Q ?? 0.5;
+    filter.gain.value = config.gain ?? 0;
+    return filter;
+}
+/**
+ * Create DynamicsCompressorNode with configuration
+ *
+ * @param audioContext AudioContext
+ * @param config Optional configuration
+ * @returns DynamicsCompressorNode
+ */
+function createCompressor(audioContext, config = {}) {
+    const compressor = audioContext.createDynamicsCompressor();
+    compressor.threshold.value = config.threshold ?? -24;
+    compressor.knee.value = config.knee ?? 30;
+    compressor.ratio.value = config.ratio ?? 12;
+    compressor.attack.value = config.attack ?? 0.003;
+    compressor.release.value = config.release ?? 0.25;
+    return compressor;
+}
+/**
+ * Create MediaStreamAudioSourceNode from track
+ *
+ * @param audioContext AudioContext
+ * @param track MediaStreamTrack (audio)
+ * @returns MediaStreamAudioSourceNode and MediaStream
+ */
+function createMediaStreamSource(audioContext, track) {
+    const stream = new MediaStream([track]);
+    const source = audioContext.createMediaStreamSource(stream);
+    return { source, stream };
+}

package/dist/audio/AudioPipeline.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Audio Pipeline - Web Audio Node Chain Setup
+ *
+ * Creates and connects audio processing nodes for participant audio
+ */
+/**
+ * Audio pipeline configuration
+ */
+export interface AudioPipelineConfig {
+    sampleRate?: number;
+    enableCompressor?: boolean;
+    enableFilters?: boolean;
+    enableDenoiser?: boolean;
+}
+/**
+ * Default audio pipeline configuration
+ */
+export declare const DEFAULT_PIPELINE_CONFIG: Required<AudioPipelineConfig>;
+/**
+ * Master audio output chain
+ */
+export interface MasterAudioChain {
+    masterGain: GainNode;
+    compressor: DynamicsCompressorNode;
+}
+/**
+ * Create master audio output chain
+ *
+ * @param audioContext AudioContext
+ * @returns Master gain and compressor nodes
+ */
+export declare function createMasterChain(audioContext: AudioContext): MasterAudioChain;
+/**
+ * Participant audio filter chain
+ */
+export interface ParticipantFilterChain {
+    highpass: BiquadFilterNode;
+    lowpass: BiquadFilterNode;
+    voiceBand: BiquadFilterNode;
+    dynamicLowpass: BiquadFilterNode;
+}
+/**
+ * Create participant filter chain for voice optimization
+ *
+ * @param audioContext AudioContext
+ * @returns Filter nodes
+ */
+export declare function createFilterChain(audioContext: AudioContext): ParticipantFilterChain;
+/**
+ * Connect filter chain in series
+ *
+ * @param filters Filter chain
+ * @returns Input and output nodes
+ */
+export declare function connectFilterChain(filters: ParticipantFilterChain): {
+    input: BiquadFilterNode;
+    output: BiquadFilterNode;
+};
+/**
+ * Create limiter (peak prevention compressor)
+ *
+ * @param audioContext AudioContext
+ * @returns DynamicsCompressorNode configured as limiter
+ */
+export declare function createLimiter(audioContext: AudioContext): DynamicsCompressorNode;
+/**
+ * Mono downmix chain for stable stereo panning
+ */
+export interface MonoDownmixChain {
+    splitter: ChannelSplitterNode;
+    gainL: GainNode;
+    gainR: GainNode;
+    merger: ChannelMergerNode;
+    stereoUpmixer: ChannelMergerNode;
+}
+/**
+ * Create mono downmix chain
+ * Forces predictable mono signal before StereoPanner
+ *
+ * @param audioContext AudioContext
+ * @returns Mono downmix nodes
+ */
+export declare function createMonoDownmixChain(audioContext: AudioContext): MonoDownmixChain;
+/**
+ * Connect mono downmix chain
+ *
+ * @param chain Mono downmix chain
+ */
+export declare function connectMonoDownmixChain(chain: MonoDownmixChain): void;

package/dist/audio/AudioPipeline.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Audio Pipeline - Web Audio Node Chain Setup
+ *
+ * Creates and connects audio processing nodes for participant audio
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PIPELINE_CONFIG = void 0;
+exports.createMasterChain = createMasterChain;
+exports.createFilterChain = createFilterChain;
+exports.connectFilterChain = connectFilterChain;
+exports.createLimiter = createLimiter;
+exports.createMonoDownmixChain = createMonoDownmixChain;
+exports.connectMonoDownmixChain = connectMonoDownmixChain;
+/**
+ * Default audio pipeline configuration
+ */
+exports.DEFAULT_PIPELINE_CONFIG = {
+    sampleRate: 48000,
+    enableCompressor: true,
+    enableFilters: true,
+    enableDenoiser: false,
+};
+/**
+ * Create master audio output chain
+ *
+ * @param audioContext AudioContext
+ * @returns Master gain and compressor nodes
+ */
+function createMasterChain(audioContext) {
+    // Master gain - unity gain for clean audio
+    const masterGain = audioContext.createGain();
+    masterGain.gain.value = 1.0;
+    // Master compressor - gentle dynamic range control
+    const compressor = audioContext.createDynamicsCompressor();
+    compressor.threshold.value = -15;
+    compressor.knee.value = 40;
+    compressor.ratio.value = 2.5;
+    compressor.attack.value = 0.02;
+    compressor.release.value = 0.25;
+    // Connect: masterGain → compressor → destination
+    masterGain.connect(compressor);
+    compressor.connect(audioContext.destination);
+    return { masterGain, compressor };
+}
+/**
+ * Create participant filter chain for voice optimization
+ *
+ * @param audioContext AudioContext
+ * @returns Filter nodes
+ */
+function createFilterChain(audioContext) {
+    // Highpass: Remove low-frequency rumble (< 100Hz)
+    const highpass = audioContext.createBiquadFilter();
+    highpass.type = 'highpass';
+    highpass.frequency.value = 100;
+    highpass.Q.value = 0.5;
+    // Lowpass: Remove high-frequency hiss (> 10kHz)
+    const lowpass = audioContext.createBiquadFilter();
+    lowpass.type = 'lowpass';
+    lowpass.frequency.value = 10000;
+    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;
+    // 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 };
+}
+/**
+ * Connect filter chain in series
+ *
+ * @param filters Filter chain
+ * @returns Input and output nodes
+ */
+function connectFilterChain(filters) {
+    filters.highpass.connect(filters.voiceBand);
+    filters.voiceBand.connect(filters.lowpass);
+    filters.lowpass.connect(filters.dynamicLowpass);
+    return {
+        input: filters.highpass,
+        output: filters.dynamicLowpass,
+    };
+}
+/**
+ * Create limiter (peak prevention compressor)
+ *
+ * @param audioContext AudioContext
+ * @returns DynamicsCompressorNode configured as limiter
+ */
+function createLimiter(audioContext) {
+    const limiter = audioContext.createDynamicsCompressor();
+    limiter.threshold.value = -6; // Only activate near clipping
+    limiter.knee.value = 3; // Hard knee = limiter behavior
+    limiter.ratio.value = 20; // High ratio = limiter
+    limiter.attack.value = 0.001; // 1ms - catch peaks fast
+    limiter.release.value = 0.05; // 50ms - fast release
+    return limiter;
+}
+/**
+ * Create mono downmix chain
+ * Forces predictable mono signal before StereoPanner
+ *
+ * @param audioContext AudioContext
+ * @returns Mono downmix nodes
+ */
+function createMonoDownmixChain(audioContext) {
+    const splitter = audioContext.createChannelSplitter(2);
+    const gainL = audioContext.createGain();
+    const gainR = audioContext.createGain();
+    const merger = audioContext.createChannelMerger(1);
+    const stereoUpmixer = audioContext.createChannelMerger(2);
+    gainL.gain.value = 0.5;
+    gainR.gain.value = 0.5;
+    return { splitter, gainL, gainR, merger, stereoUpmixer };
+}
+/**
+ * Connect mono downmix chain
+ *
+ * @param chain Mono downmix chain
+ */
+function connectMonoDownmixChain(chain) {
+    // Split stereo input
+    chain.splitter.connect(chain.gainL, 0);
+    chain.splitter.connect(chain.gainR, 1);
+    // Mix to mono
+    chain.gainL.connect(chain.merger, 0, 0);
+    chain.gainR.connect(chain.merger, 0, 0);
+    // Upmix mono to stereo (same signal both channels)
+    chain.merger.connect(chain.stereoUpmixer, 0, 0);
+    chain.merger.connect(chain.stereoUpmixer, 0, 1);
+}

package/dist/{MLNoiseSuppressor.d.ts → audio/MLNoiseSuppressor.d.ts}

@@ -1,6 +1,8 @@
 /**
  * ML Noise Suppressor - TensorFlow.js-based Real-Time Audio Enhancement
- * Integrates trained ML model for noise suppression with fallback to traditional DSP
+ *
+ * Integrates trained ML model for noise suppression
+ * Falls back to traditional DSP if ML is unavailable
  */
 export declare class MLNoiseSuppressor {
     private model;
@@ -18,12 +20,10 @@ export declare class MLNoiseSuppressor {
     initialize(modelUrl: string): Promise<void>;
     /**
      * Process audio buffer through ML model
-     * @param inputBuffer Audio samples to process
-     * @returns Denoised audio samples
      */
     processAudio(inputBuffer: Float32Array): Promise<Float32Array>;
     /**
-     * Extract audio features (simplified mel-spectrogram approximation)
+     * Extract audio features
      */
     private extractFeatures;
     /**
@@ -31,15 +31,15 @@ export declare class MLNoiseSuppressor {
      */
     private createSequences;
     /**
-     * Apply temporal smoothing to mask (prevents "musical noise")
+     * Apply temporal smoothing to mask
      */
     private applyTemporalSmoothing;
     /**
-     * Apply noise suppression mask to audio with voice preservation
+     * Apply noise suppression mask to audio
      */
     private applyMaskToAudio;
     /**
-     * Reset processing state (call when switching audio streams)
+     * Reset processing state
      */
     reset(): void;
     /**