@codexo/exojs 0.6.12 → 0.7.12

package/dist/esm/audio/OscillatorSound.js

@@ -0,0 +1,342 @@
+import { clamp } from '../math/utils.js';
+import { AbstractMedia } from './AbstractMedia.js';
+import { isAudioContextReady, getAudioContext, onAudioContextReady } from './audio-context.js';
+import { getAudioManager } from './AudioManager.js';
+import { SoundPoolStrategy } from './Sound.js';
+
+/**
+ * Procedural tone generator — generates audio without an AudioBuffer asset.
+ * Useful for prototyping, game-jam SFX, retro-style sound effects, music
+ * apps that need synthesizer-style tones.
+ *
+ * Each `play()` creates a new OscillatorNode (oscillators are one-shot in
+ * Web Audio). Pool semantics match `Sound`: multiple concurrent voices
+ * up to `poolSize`, FIFO eviction by default.
+ *
+ *   const tone = new OscillatorSound({ frequency: 440, type: 'sine' });
+ *   tone.play();        // plays A4 sine wave
+ *   tone.frequency = 880;
+ *   tone.play();        // plays A5 (in addition to A4 if pool > 1)
+ *
+ * For musical applications, use `setNote(midi)`:
+ *
+ *   tone.setNote(69);   // MIDI 69 = A4
+ *   tone.setNote(60);   // C4 (middle C)
+ *
+ * With an envelope for smooth attack/release:
+ *
+ *   const synth = new OscillatorSound({
+ *       frequency: 440,
+ *       envelope: new Envelope({ attackMs: 50, decayMs: 100, sustainLevel: 0.7, releaseMs: 300 }),
+ *   });
+ *   synth.play();
+ *   // ... later
+ *   synth.pause();      // triggers release phase, stops after releaseMs
+ */
+class OscillatorSound extends AbstractMedia {
+    frequency;
+    detune;
+    type;
+    envelope;
+    poolSize;
+    poolStrategy;
+    priority;
+    _audioSetup = null;
+    _paused = true;
+    _pooledSources = [];
+    get paused() {
+        return this._paused;
+    }
+    set paused(paused) {
+        if (paused) {
+            this.pause();
+        }
+        else {
+            this.play();
+        }
+    }
+    get analyserTarget() {
+        return this._audioSetup?.gainNode ?? null;
+    }
+    constructor(options = {}) {
+        super({
+            duration: Infinity,
+            volume: clamp(options.volume ?? 1, 0, 2),
+            playbackRate: 1,
+            loop: false,
+            muted: options.muted ?? false,
+        });
+        this.frequency = options.frequency ?? 440;
+        this.type = options.type ?? 'sine';
+        this.detune = options.detune ?? 0;
+        this.envelope = options.envelope ?? null;
+        this.poolSize = Math.max(1, Math.floor(options.poolSize ?? 8));
+        this.poolStrategy = options.poolStrategy ?? SoundPoolStrategy.FirstInFirstOut;
+        this.priority = options.priority ?? 0;
+        if (options.loop !== undefined) {
+            this._loop = options.loop;
+        }
+        if (isAudioContextReady()) {
+            this._setupWithAudioContext(getAudioContext());
+        }
+        else {
+            onAudioContextReady.once(this._setupWithAudioContext, this);
+        }
+    }
+    play(options = {}) {
+        if (options.bus !== undefined) {
+            this.bus = options.bus;
+        }
+        if (options.volume !== undefined) {
+            this.setVolume(options.volume);
+        }
+        if (options.muted !== undefined) {
+            this.setMuted(options.muted);
+        }
+        if (options.replace) {
+            this._stopAllPooled();
+        }
+        const frequency = options.frequency ?? this.frequency;
+        const type = options.type ?? this.type;
+        const detune = options.detune ?? this.detune;
+        this._enqueuePooledPlay(frequency, type, detune);
+        this._paused = false;
+        this.onStart.dispatch();
+        return this;
+    }
+    pause() {
+        if (this._paused && this._pooledSources.length === 0) {
+            return this;
+        }
+        const wasPlaying = !this._paused || this._pooledSources.length > 0;
+        this._stopAllPooled();
+        this._paused = true;
+        if (wasPlaying) {
+            this.onStop.dispatch();
+        }
+        return this;
+    }
+    setVolume(value) {
+        const volume = clamp(value, 0, 2);
+        if (this._volume === volume) {
+            return this;
+        }
+        this._volume = volume;
+        if (this._audioSetup) {
+            const { gainNode, audioContext } = this._audioSetup;
+            gainNode.gain.setTargetAtTime(this.muted ? 0 : volume, audioContext.currentTime, 0.01);
+        }
+        return this;
+    }
+    setLoop(loop) {
+        this._loop = loop;
+        return this;
+    }
+    setPlaybackRate(value) {
+        this._playbackRate = clamp(value, 0.1, 20);
+        return this;
+    }
+    getTime() {
+        return 0;
+    }
+    setTime(_currentTime) {
+        return this;
+    }
+    setMuted(muted) {
+        this._muted = muted;
+        if (this._audioSetup) {
+            const { gainNode, audioContext } = this._audioSetup;
+            gainNode.gain.setTargetAtTime(muted ? 0 : this.volume, audioContext.currentTime, 0.01);
+        }
+        return this;
+    }
+    /** Set frequency from MIDI note number. midi 69 = A4 = 440Hz. */
+    setNote(midiNote) {
+        this.frequency = 440 * Math.pow(2, (midiNote - 69) / 12);
+        return this;
+    }
+    /** Returns frequency in Hz from MIDI note (without setting it). */
+    static midiToFrequency(midiNote) {
+        return 440 * Math.pow(2, (midiNote - 69) / 12);
+    }
+    destroy() {
+        super.destroy();
+        onAudioContextReady.clearByContext(this);
+        this._stopAllPooled();
+        this._audioSetup?.gainNode.disconnect();
+        this._audioSetup = null;
+    }
+    _getAudioSetup() {
+        return this._audioSetup;
+    }
+    _defaultBus() {
+        return getAudioManager().sound;
+    }
+    _disconnectFromBus() {
+        if (this._audioSetup) {
+            this._audioSetup.gainNode.disconnect();
+        }
+    }
+    _connectToBus() {
+        if (this._audioSetup) {
+            const inputNode = this.bus._getInputNode();
+            if (inputNode) {
+                this._audioSetup.gainNode.connect(inputNode);
+            }
+            else {
+                this._audioSetup.gainNode.connect(this._audioSetup.audioContext.destination);
+            }
+        }
+    }
+    _setupWithAudioContext(audioContext) {
+        const gainNode = audioContext.createGain();
+        gainNode.gain.setTargetAtTime(this.muted ? 0 : this.volume, audioContext.currentTime, 0.01);
+        const inputNode = this.bus._getInputNode();
+        if (inputNode) {
+            gainNode.connect(inputNode);
+        }
+        else {
+            gainNode.connect(audioContext.destination);
+        }
+        this._audioSetup = { audioContext, gainNode };
+    }
+    _enqueuePooledPlay(frequency, type, detune) {
+        if (!this._audioSetup) {
+            // AudioContext not yet ready; defer is not supported for oscillators
+            // since each play is ephemeral — silently ignore until context is ready.
+            return;
+        }
+        this._playPooledNow(frequency, type, detune);
+    }
+    _playPooledNow(frequency, type, detune) {
+        if (!this._audioSetup)
+            return;
+        const { audioContext, gainNode } = this._audioSetup;
+        // Create per-voice gain node (envelope target)
+        const voiceGain = audioContext.createGain();
+        const busInput = this.bus._getInputNode();
+        if (busInput) {
+            voiceGain.connect(busInput);
+        }
+        else {
+            voiceGain.connect(audioContext.destination);
+        }
+        // Apply volume/mute through the master gain node connection
+        // The voiceGain is the envelope target; the main gainNode handles bus-level volume
+        gainNode.connect(voiceGain);
+        const oscillator = audioContext.createOscillator();
+        oscillator.type = type;
+        oscillator.frequency.value = frequency;
+        oscillator.detune.value = detune;
+        oscillator.connect(voiceGain);
+        const now = audioContext.currentTime;
+        if (this.envelope) {
+            this.envelope.trigger(voiceGain.gain, now);
+        }
+        else {
+            voiceGain.gain.value = this.muted ? 0 : this._volume;
+        }
+        oscillator.start(now);
+        const pooledSource = {
+            oscillator,
+            gain: voiceGain,
+            startedAt: now,
+        };
+        oscillator.onended = () => {
+            const index = this._pooledSources.indexOf(pooledSource);
+            if (index !== -1) {
+                this._pooledSources.splice(index, 1);
+            }
+            oscillator.disconnect();
+            voiceGain.disconnect();
+            if (this._pooledSources.length === 0) {
+                this._paused = true;
+            }
+        };
+        this._pooledSources.push(pooledSource);
+        this._trimPooledSources();
+    }
+    _pickEvictionVictim() {
+        switch (this.poolStrategy) {
+            case SoundPoolStrategy.LeastRecentlyUsed: {
+                // Evict source closest to its natural end. Since oscillators
+                // are infinite by default, use oldest (smallest startedAt).
+                return this._pickOldestIndex();
+            }
+            case SoundPoolStrategy.LowestPriority:
+            // All pooled instances share the same priority, degenerates to FIFO.
+            // falls through
+            case SoundPoolStrategy.FirstInFirstOut:
+            default:
+                return 0; // oldest
+        }
+    }
+    _pickOldestIndex() {
+        let minTime = Infinity;
+        let minIndex = 0;
+        for (let i = 0; i < this._pooledSources.length; i++) {
+            const src = this._pooledSources[i];
+            if (src.startedAt < minTime) {
+                minTime = src.startedAt;
+                minIndex = i;
+            }
+        }
+        return minIndex;
+    }
+    _trimPooledSources() {
+        while (this._pooledSources.length > this.poolSize) {
+            const victimIndex = this._pickEvictionVictim();
+            const victim = this._pooledSources[victimIndex];
+            if (!victim)
+                break;
+            this._pooledSources.splice(victimIndex, 1);
+            victim.oscillator.onended = null;
+            this._stopSource(victim);
+        }
+    }
+    _stopAllPooled() {
+        for (const source of this._pooledSources) {
+            source.oscillator.onended = null;
+            this._stopSource(source);
+        }
+        this._pooledSources.length = 0;
+    }
+    _stopSource(source) {
+        if (!this._audioSetup) {
+            try {
+                source.oscillator.stop(0);
+            }
+            catch {
+                // already stopped
+            }
+            source.oscillator.disconnect();
+            source.gain.disconnect();
+            return;
+        }
+        const { audioContext } = this._audioSetup;
+        const now = audioContext.currentTime;
+        if (this.envelope) {
+            this.envelope.release(source.gain.gain, now);
+            const stopAt = now + this.envelope.releaseMs / 1000;
+            try {
+                source.oscillator.stop(stopAt);
+            }
+            catch {
+                // already stopped
+            }
+        }
+        else {
+            try {
+                source.oscillator.stop(now);
+            }
+            catch {
+                // already stopped
+            }
+            source.oscillator.disconnect();
+            source.gain.disconnect();
+        }
+    }
+}
+
+export { OscillatorSound };
+//# sourceMappingURL=OscillatorSound.js.map

package/dist/esm/audio/OscillatorSound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OscillatorSound.js","sources":["../../../../src/audio/OscillatorSound.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/audio/Sound.d.ts

@@ -1,14 +1,74 @@
+import { Vector } from '@/math/Vector';
 import type { PlaybackOptions } from '@/core/types';
 import { AbstractMedia } from '@/audio/AbstractMedia';
+import type { AudioBus } from '@/audio/AudioBus';
+/**
+ * Eviction strategy used when the pool is full and a new play is requested.
+ *
+ * At the per-Sound level all pooled instances share the same priority, so
+ * `LowestPriority` degenerates to `FirstInFirstOut` in V1. The enum is
+ * forward-compatible with a future global voice manager that culls across
+ * multiple Sound instances.
+ */
+export declare enum SoundPoolStrategy {
+    /** Evict the oldest (first-started) source. Default. */
+    FirstInFirstOut = "fifo",
+    /** Evict the source closest to its natural end (shortest remaining time). */
+    LeastRecentlyUsed = "lru",
+    /**
+     * Evict the source with the lowest priority.
+     * Within a single Sound all instances share the same priority, so this
+     * degenerates to FirstInFirstOut in V1.
+     */
+    LowestPriority = "priority"
+}
+/**
+ * Named sub-region of an {@link AudioBuffer} used as an audio sprite sheet.
+ * `start` / `end` are seconds into the buffer; `loop` makes
+ * {@link Sound.playSprite} loop the sprite indefinitely.
+ */
 export interface AudioSpriteClip {
     start: number;
     end: number;
     loop?: boolean;
 }
+/** Construction options for {@link Sound}. */
 export interface SoundOptions extends Partial<PlaybackOptions> {
     poolSize?: number;
+    poolStrategy?: SoundPoolStrategy;
+    priority?: number;
     sprites?: Readonly<Record<string, AudioSpriteClip>>;
 }
+/** Per-call overrides for {@link Sound.play} and {@link Sound.playSprite}. */
+export interface PlayOptions extends Partial<PlaybackOptions> {
+    bus?: AudioBus;
+    /**
+     * When `true`, all currently-playing instances of this sound are stopped
+     * before the new one starts (singleton-replace mode). Useful for
+     * non-overlapping playback such as UI confirmation chimes.
+     *
+     * Default: `false` (multi-instance / pooled mode).
+     */
+    replace?: boolean;
+}
+/**
+ * Pre-decoded short audio clip backed by an `AudioBuffer`. Each
+ * {@link Sound.play} call grabs a free `AudioBufferSourceNode` from the
+ * pool (default size 8) so the same sound can overlap itself; when the
+ * pool is full the configured {@link SoundPoolStrategy} decides which
+ * source to evict.
+ *
+ * Supports audio-sprite playback via {@link Sound.playSprite} — name a
+ * sub-region in the {@link AudioSpriteClip} options and trigger by name.
+ *
+ * Routes through any {@link AudioBus}; defaults to the engine's `sound`
+ * bus. Calling {@link Sound.makeSpatial} attaches a panner so the sound
+ * follows a {@link SceneNode} or world-space target with distance
+ * attenuation handled by Web Audio.
+ *
+ * Use {@link Music} for long-form streaming audio (single source, decoded
+ * lazily) — `Sound` is best for short, frequently-triggered clips.
+ */
 export declare class Sound extends AbstractMedia {
     private readonly _audioBuffer;
     private readonly _pooledSources;
@@ -16,15 +76,40 @@ export declare class Sound extends AbstractMedia {
     private readonly _sprites;
     private _audioSetup;
     private _paused;
-    private _startTime;
-    private _currentTime;
-    private _sourceNode;
     private _poolSize;
+    private _poolStrategy;
+    private _priority;
+    private _position;
+    private _velocity;
+    private _pannerNode;
     get paused(): boolean;
     set paused(paused: boolean);
     get analyserTarget(): GainNode | null;
     get poolSize(): number;
     set poolSize(poolSize: number);
+    /**
+     * The eviction strategy used when the pool is at capacity.
+     * @default SoundPoolStrategy.FirstInFirstOut
+     */
+    get poolStrategy(): SoundPoolStrategy;
+    set poolStrategy(strategy: SoundPoolStrategy);
+    /**
+     * Sound priority. Used by the `LowestPriority` pool strategy.
+     * Higher values indicate higher priority (less likely to be evicted).
+     * @default 0
+     */
+    get priority(): number;
+    set priority(value: number);
+    get position(): Vector | null;
+    set position(value: {
+        x: number;
+        y: number;
+    } | Vector | null);
+    get velocity(): Vector | null;
+    set velocity(value: {
+        x: number;
+        y: number;
+    } | Vector | null);
     constructor(audioBuffer: AudioBuffer, options?: SoundOptions);
     setVolume(value: number): this;
     setLoop(loop: boolean): this;
@@ -37,20 +122,45 @@ export declare class Sound extends AbstractMedia {
     defineSprite(name: string, clip: AudioSpriteClip): this;
     hasSprite(name: string): boolean;
     removeSprite(name: string): this;
-    play(options?: Partial<PlaybackOptions>): this;
-    playPooled(options?: Partial<PlaybackOptions>): this;
+    /**
+     * Play this sound. By default, creates a new pooled instance allowing
+     * multiple concurrent plays up to `poolSize`. Pass `{ replace: true }` to
+     * stop all prior instances of this sound before starting a new one
+     * (singleton-replace mode — useful for non-overlapping playback like UI
+     * confirmation chimes).
+     */
+    play(options?: PlayOptions): this;
     playSprite(name: string, options?: Partial<PlaybackOptions>): this;
-    stopPooled(): this;
     pause(options?: Partial<PlaybackOptions>): this;
+    protected _getAudioSetup(): {
+        audioContext: AudioContext;
+        gainNode: GainNode;
+    } | null;
+    protected _defaultBus(): AudioBus;
+    protected _disconnectFromBus(): void;
+    protected _connectToBus(): void;
     destroy(): void;
-    private createSourceNode;
+    /** Internal: called by AudioManager.update() once per frame for spatial sounds. */
+    _tickSpatial(): void;
+    private _setupSpatial;
+    private _teardownSpatial;
     private setupWithAudioContext;
     private _enqueuePooledPlay;
     private _flushQueuedPooledPlays;
     private _playPooledNow;
+    /**
+     * Pick the index within `_pooledSources` of the source to evict.
+     * The returned index is always valid (0 .. length-1).
+     */
+    private _pickEvictionVictim;
+    /**
+     * Returns the index of the source with the smallest remaining playback
+     * time (i.e. closest to its natural end). Used for `LeastRecentlyUsed`.
+     */
+    private _pickClosestToEnd;
     private _trimPooledSources;
-    private _stopPrimarySource;
-    private _stopPooledSources;
+    /** Stop all pooled sources immediately (used by `replace: true` and `pause()`). */
+    private _stopAllPooled;
     private _stopSourceNode;
     private _createBufferSourceNode;
 }