@weasel-js/audio 1.15.1 → 1.16.0

package/dist/index.d.ts

@@ -228,11 +228,15 @@ interface SoundCache {
  *  between concurrent loads of it; a failed load is not cached. */
 declare function createSoundCache(ctx: AudioContext, fetchFn?: typeof fetch): SoundCache;
 
-/** A 2D world position, in the consumer's own units. */
-interface Vec2 {
+/** A world position or direction, in the consumer's own units. `z` is absent
+ *  in a 2D scene and read as 0. */
+interface SpatialPoint {
     x: number;
     y: number;
+    z?: number;
 }
+/** @deprecated Use `SpatialPoint`, which also takes an optional `z`. */
+type Vec2 = SpatialPoint;
 /** Distance and pan model for `spatialize`, in the same units as the
  *  positions. */
 interface SpatialOptions {
@@ -246,15 +250,20 @@ interface SpatialOptions {
     rolloff?: 'inverse' | 'linear';
     /** How sharply gain falls. Default 1. */
     rolloffFactor?: number;
-    /** Horizontal distance mapping to full left/right. Default 500. */
+    /** Offset along `right` mapping to full left/right. Default 500. */
     panWidth?: number;
+    /** The listener's right, as a direction; its length is ignored. Default
+     *  `{ x: 1, y: 0, z: 0 }`. Pan is the source's offset along it. */
+    right?: SpatialPoint;
 }
 /**
  * Map a source position to a gain and a stereo pan, relative to the listener.
+ * Gain falls with the full 3D distance; pan is the offset along the listener's
+ * right, over `panWidth`.
  *
  * Pure — no Web Audio, no state. This is the whole spatial model.
  */
-declare function spatialize(source: Vec2, listener: Vec2, opts?: SpatialOptions): {
+declare function spatialize(source: SpatialPoint, listener: SpatialPoint, opts?: SpatialOptions): {
     gain: number;
     pan: number;
 };
@@ -362,7 +371,7 @@ interface PlayOptions {
     /** Explicit stereo pan, -1..1. Ignored when `position` is given. */
     pan?: number;
     /** World position; spatialized against the engine listener. */
-    position?: Vec2;
+    position?: SpatialPoint;
     /** Engine time in ms (see `engine.now()`). Default: as soon as possible. */
     when?: number;
     /** `stopKey(key)` stops every voice sharing this key. */
@@ -402,7 +411,7 @@ interface VoiceHandle {
     setDetune(cents: number): void;
     /** Explicit stereo pan. Stops the voice tracking a `position`. */
     setPan(value: number): void;
-    setPosition(p: Vec2): void;
+    setPosition(p: SpatialPoint): void;
     isPlaying(): boolean;
 }
 /** One sine partial of an inharmonic voice. */
@@ -606,7 +615,7 @@ interface AudioEngine {
     analyser(busName?: string, opts?: AnalyserTapOptions): AnalyserTap;
     /** A graph feeding `bus`'s input (default: the first bus). Disposed with the engine. */
     graph(bus?: string): AudioGraph;
-    setListener(p: Vec2, opts?: SpatialOptions): void;
+    setListener(p: SpatialPoint, opts?: SpatialOptions): void;
     dispose(): void;
 }
 /**
@@ -1166,4 +1175,4 @@ declare function reverbNode(ctx: BaseAudioContext, opts?: ReverbNodeOptions): Gr
 /** A graph node over a compressor insert: port `in`; params `threshold`, `knee`, `ratio`, `attack` (ms), `release` (ms), `makeup`. */
 declare function compressorNode(ctx: BaseAudioContext, opts?: CompressorEffectOptions): GraphNodeDef;
 
-export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type AudioGraph, type AudioGraphOptions, type BiquadCoefficients, type BusGraph, type BusGraphOptions, type BusHandle, type CompressorEffect, type CompressorEffectOptions, type DelayEffect, type DelayEffectOptions, type Envelope, type EnvelopePoint, type FileSourceNodeOptions, type FilterEffect, type FilterEffectOptions, type Glide, type GraphNodeDef, type GraphPatch, type GraphTarget, type ImpulseResponseOptions, type Inharmonic, type InsertAddOptions, type InsertChain, type InsertChainOptions, type InsertEffect, type InsertSlot, type KernelNoise, type KernelNote, type NoiseColor, type NoiseNodeOptions, type NoiseOptions, type NoisePatch, type NoteOptions, type OscillatorNodeOptions, type OscillatorWave, type PatternDetune, type PatternEvent, type PatternHit, type PatternLoadOptions, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, type ReverbNodeOptions, SCORE_BAR_STEPS, type Scheduler, type SchedulerOptions, type Score, type ScoreBarOptions, type ScoreCue, type ScoreCueName, type ScoreCueReading, type ScoreMode, type ScoreMood, type ScoreOptions, type ScoreParams, type ScoreState, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceDropReason, type VoiceFilter, type VoiceHandle, type VoiceKernel, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, biquadCoefficients, biquadResponseDb, compressorNode, createAnalyserTap, createAudioEngine, createAudioGraph, createBusGraph, createCompressorEffect, createDelayEffect, createFileSourceNode, createFilterEffect, createGainNode, createMixNode, createNoiseKernel, createNoiseNode, createNoteKernel, createOscillatorNode, createPanNode, createPatternPlayer, createReverbEffect, createScheduler, createScore, createSoundCache, createTickTimer, createVoicePool, delayNode, envelopeLevel, envelopePoints, filterNode, impulseResponse, insertNode, midiToFrequency, noiseSamples, noteToMidi, partialPresets, patternLength, patternVoicePeaks, readScoreCue, renderNoise, renderNote, resolveEnvelope, reverbNode, scoreBar, scoreChord, scoreCues, scoreModes, scoreParams, spatialize, toFrequency };
+export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type AudioGraph, type AudioGraphOptions, type BiquadCoefficients, type BusGraph, type BusGraphOptions, type BusHandle, type CompressorEffect, type CompressorEffectOptions, type DelayEffect, type DelayEffectOptions, type Envelope, type EnvelopePoint, type FileSourceNodeOptions, type FilterEffect, type FilterEffectOptions, type Glide, type GraphNodeDef, type GraphPatch, type GraphTarget, type ImpulseResponseOptions, type Inharmonic, type InsertAddOptions, type InsertChain, type InsertChainOptions, type InsertEffect, type InsertSlot, type KernelNoise, type KernelNote, type NoiseColor, type NoiseNodeOptions, type NoiseOptions, type NoisePatch, type NoteOptions, type OscillatorNodeOptions, type OscillatorWave, type PatternDetune, type PatternEvent, type PatternHit, type PatternLoadOptions, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, type ReverbNodeOptions, SCORE_BAR_STEPS, type Scheduler, type SchedulerOptions, type Score, type ScoreBarOptions, type ScoreCue, type ScoreCueName, type ScoreCueReading, type ScoreMode, type ScoreMood, type ScoreOptions, type ScoreParams, type ScoreState, type SoundCache, type SoundHandle, type SpatialOptions, type SpatialPoint, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceDropReason, type VoiceFilter, type VoiceHandle, type VoiceKernel, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, biquadCoefficients, biquadResponseDb, compressorNode, createAnalyserTap, createAudioEngine, createAudioGraph, createBusGraph, createCompressorEffect, createDelayEffect, createFileSourceNode, createFilterEffect, createGainNode, createMixNode, createNoiseKernel, createNoiseNode, createNoteKernel, createOscillatorNode, createPanNode, createPatternPlayer, createReverbEffect, createScheduler, createScore, createSoundCache, createTickTimer, createVoicePool, delayNode, envelopeLevel, envelopePoints, filterNode, impulseResponse, insertNode, midiToFrequency, noiseSamples, noteToMidi, partialPresets, patternLength, patternVoicePeaks, readScoreCue, renderNoise, renderNote, resolveEnvelope, reverbNode, scoreBar, scoreChord, scoreCues, scoreModes, scoreParams, spatialize, toFrequency };

package/dist/index.js

@@ -1883,7 +1883,8 @@ function spatialize(source, listener, opts = {}) {
   const panWidth = opts.panWidth ?? 500;
   const dx = source.x - listener.x;
   const dy = source.y - listener.y;
-  const distance = Math.hypot(dx, dy);
+  const dz = (source.z ?? 0) - (listener.z ?? 0);
+  const distance = dz === 0 ? Math.hypot(dx, dy) : Math.hypot(dx, dy, dz);
   let gain;
   if (distance <= refDistance) {
     gain = 1;
@@ -1894,9 +1895,17 @@ function spatialize(source, listener, opts = {}) {
     gain = refDistance / (refDistance + rolloffFactor * (distance - refDistance));
   }
   gain = Math.min(1, Math.max(0, gain));
-  const pan = panWidth <= 0 ? 0 : Math.min(1, Math.max(-1, dx / panWidth));
+  const lateral = lateralOffset(dx, dy, dz, opts.right);
+  const pan = panWidth <= 0 ? 0 : Math.min(1, Math.max(-1, lateral / panWidth));
   return { gain, pan };
 }
+function lateralOffset(dx, dy, dz, right) {
+  if (!right) return dx;
+  const rz = right.z ?? 0;
+  const len = Math.hypot(right.x, right.y, rz);
+  if (len === 0) return 0;
+  return (dx * right.x + dy * right.y + dz * rz) / len;
+}
 
 // src/voices.ts
 var dropped = (id) => ({