littlejsengine 1.19.3 → 1.20.0

package/src/engineAudio.js

@@ -15,17 +15,29 @@
 
 'use strict';
 
-/** Audio context used by the engine
+/** Audio context used by the engine, undefined outside a browser, where the engine runs headless
  *  @type {AudioContext}
  *  @memberof Audio */
-let audioContext = new AudioContext;
+let audioContext = typeof AudioContext == 'undefined' ? undefined : new AudioContext;
 
 /** Master gain node for all audio to pass through, made at load so effects can connect to it any time
  *  @type {GainNode}
  *  @memberof Audio */
-let audioMasterGain = audioContext.createGain();
-audioMasterGain.connect(audioContext.destination);
-audioMasterGain.gain.value = soundVolume; // set starting value
+let audioMasterGain = audioContext?.createGain();
+let audioMasterVolume; // the soundVolume the master gain was last set to
+if (audioMasterGain)
+{
+    audioMasterGain.connect(audioContext.destination);
+    audioMasterGain.gain.value = audioMasterVolume = soundVolume; // set starting value
+    audioContext.addEventListener?.('statechange', audioStateChange);
+}
+
+// soundVolume can be set directly, so the master gain follows it each frame
+function audioUpdateVolume()
+{
+    if (audioMasterGain && soundVolume !== audioMasterVolume)
+        audioMasterGain.gain.value = audioMasterVolume = soundVolume;
+}
 
 // the current master effect, kept so setAudioMasterEffect can undo the route it made,
 // and whether its output came from an effect, which gets its default route back
@@ -37,10 +49,10 @@ let audioMasterEffectInput, audioMasterEffectOutput, audioMasterEffectOutputIsEf
 const audioDefaultSampleRate = 44100;
 
 /** Check if the audio context is running and available for playback
- *  @return {boolean} - True if the audio context is running
+ *  @return {boolean} - True if the audio context is running, false when there is none
  *  @memberof Audio */
 function audioIsRunning()
-{ return audioContext.state === 'running'; }
+{ return audioContext?.state === 'running'; }
 
 function audioInit()
 {
@@ -67,6 +79,29 @@ function audioVisibilityChange()
     }
 }
 
+// sound instances whose start failed only because the context was not running, like music started in gameInit
+// before the first input, each with the time it tried; they start once the context runs unless paused or stopped
+// first, and a one shot drops out once it would have ended anyway, so a backlog of sounds can't all play at once
+const audioWaitingInstances = new Map;
+function audioWaitingPrune(now=performance.now())
+{
+    for (const [instance, startTime] of audioWaitingInstances)
+    {
+        const remaining = (instance.getDuration() - instance.pausedTime) / instance.rate;
+        if (!instance.loop && now - startTime > remaining * 1e3)
+            audioWaitingInstances.delete(instance);
+    }
+}
+function audioStateChange()
+{
+    if (!audioIsRunning()) return;
+    audioWaitingPrune();
+    const instances = [...audioWaitingInstances.keys()];
+    audioWaitingInstances.clear();
+    for (const instance of instances)
+        instance.resume();
+}
+
 /** Anything with input and output audio nodes, like an effect from the audio effects plugin
  *  @typedef {{input: AudioNode, output: AudioNode}} AudioEffectNodes
  *  @memberof Audio */
@@ -91,14 +126,20 @@ function setAudioMasterEffect(input, output)
     input = audioEffectNode(input, 'input');
     ASSERT(!input || typeof input.connect === 'function', 'input must be an AudioNode or an effect with input and output nodes');
     ASSERT(!output || typeof output.connect === 'function', 'output must be an AudioNode or an effect with input and output nodes');
+    if (!audioMasterGain) return; // no audio outside a browser, where the engine runs headless
 
-    // undo the current route, the master gain selectively so other taps on it survive,
-    // but the output node from everything since it only ever fed the speakers;
-    // an effect's output then goes back to the master gain, its default, so it still works for sounds
+    // undo the current route selectively so other taps survive; an effect's output that still feeds the speakers
+    // goes back to the master gain, its default, so it still works for sounds, but one that connect() already moved
+    // on, like the head of a longer chain being set now, stays where it was sent
     audioMasterGain.disconnect(audioMasterEffectInput || audioContext.destination);
-    audioMasterEffectOutput?.disconnect();
-    if (audioMasterEffectOutputIsEffect)
-        audioMasterEffectOutput.connect(audioMasterGain);
+    if (audioMasterEffectOutput)
+    {
+        let fedSpeakers = true;
+        try { audioMasterEffectOutput.disconnect(audioContext.destination); }
+        catch { fedSpeakers = false; }
+        if (audioMasterEffectOutputIsEffect && fedSpeakers)
+            audioMasterEffectOutput.connect(audioMasterGain);
+    }
     audioMasterEffectInput = input;
     audioMasterEffectOutput = output;
     audioMasterEffectOutputIsEffect = outputIsEffect;
@@ -117,7 +158,8 @@ function setAudioMasterEffect(input, output)
 // get one of an effect's nodes, or the thing itself when it is already a node
 /** @param {AudioNode|AudioEffectNodes|undefined} effectOrNode
  *  @param {'input'|'output'} key
- *  @return {AudioNode} */
+ *  @return {AudioNode}
+ *  @ignore */
 function audioEffectNode(effectOrNode, key)
 {
     if (effectOrNode && 'input' in effectOrNode)
@@ -125,8 +167,31 @@ function audioEffectNode(effectOrNode, key)
     return /** @type {AudioNode} */ (effectOrNode);
 }
 
+// ramp an audio param to a value, cancelling anything already scheduled so stacked calls don't fight;
+// returns when the ramp ends
+function audioParamRamp(param, value, fadeTime=0)
+{
+    ASSERT(fadeTime >= 0, 'fadeTime must be positive or zero');
+    const startTime = audioContext.currentTime;
+    param.cancelScheduledValues(startTime);
+    if (fadeTime)
+    {
+        param.setValueAtTime(param.value, startTime);
+        param.linearRampToValueAtTime(value, startTime + fadeTime);
+    }
+    else
+        param.value = value;
+    return startTime + fadeTime;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * @callback SoundLoadCallback - Function called when sound is loaded
+ * @param {Sound} sound
+ * @memberof Audio
+ */
+
 /**
  * Sound Object - Stores a sound for later
  * - this can be used to load and play wave, mp3, and ogg files
@@ -148,15 +213,9 @@ function audioEffectNode(effectOrNode, key)
  */
 class Sound
 {
-    /**
-     * @callback SoundLoadCallback - Function called when sound is loaded
-     * @param {Sound} sound
-     * @memberof Audio
-     */
-    
     /** Create a sound object and cache the audio for later use
-     *  @param {string|Array} [asset] - Filename of audio file or zzfx array
-     *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds the zzfx default is used if undefined
+     *  @param {string|URL|Array} [asset] - Filename or URL of an audio file, or a zzfx array
+     *  @param {number} [randomness] - How much to randomize frequency each time sound plays, for zzfx sounds it overrides the array's own randomness, which is used if undefined
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
      *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
@@ -175,26 +234,29 @@ class Sound
         this.range = range;
         /** @property {number} - At what percentage of range should it start tapering */
         this.taper = taper;
-        /** @property {number} - How much to randomize frequency each time sound plays */
+        /** @property {number} - How much to randomize frequency each time sound plays
+         *  @type {number} */
         this.randomness = randomness ?? 0;
         /** @property {number} - Sample rate for this sound */
         this.sampleRate = audioDefaultSampleRate;
         /** @property {number} - How many samples per channel this sound has */
         this.sampleLength = 0;
-        /** @property {AudioBuffer} - Decoded audio shared by every play of this sound
-         *  @type {AudioBuffer} */
+        /** @property {AudioBuffer|undefined} - Decoded audio shared by every play of this sound
+         *  @type {AudioBuffer|undefined} */
         this.sampleBuffer = undefined;
-        /** @private
-         *  @type {Array<Array<number>|Float32Array>} */
+        // internal, the 3D plugin reads it to know the sound has loaded
+        /** @ignore
+         *  @type {Array<Array<number>|Float32Array>|undefined} */
         this._sampleChannels = undefined;
         /** @property {number} - Percentage of this sound currently loaded, sounds
          *  fetched from a url stay at 0 until decoding completes */
         this.loadedPercent = 0;
-        /** @property {SoundLoadCallback} - function to call when sound is loaded */
+        /** @property {SoundLoadCallback|undefined} - function to call when sound is loaded
+         *  @type {SoundLoadCallback|undefined} */
         this.onloadCallback = onloadCallback;
-        /** @property {AudioNode|AudioEffectNodes} - Node or effect to route every play of this sound through instead of the master gain
+        /** @property {AudioNode|AudioEffectNodes|undefined} - Node or effect to route every play of this sound through instead of the master gain
          *  - Where this sound's audio goes, unlike AudioEffect.output which is an effect's own node, effects chain with connect()
-         *  @type {AudioNode|AudioEffectNodes} */
+         *  @type {AudioNode|AudioEffectNodes|undefined} */
         this.output = undefined;
 
         if (isArray(asset))
@@ -202,10 +264,9 @@ class Sound
             // generate zzfx sound — copy so we don't mutate the caller's array
             const zzfxSound = asset.slice();
 
-            // remove randomness so it can be applied on playback
-            const defaultRandomness = randomness ?? .05;
+            // remove randomness so it can be applied on playback, a value passed in wins over the array's
             const randomnessIndex = 1;
-            this.randomness = zzfxSound[randomnessIndex] ?? defaultRandomness;
+            this.randomness = randomness ?? zzfxSound[randomnessIndex] ?? .05;
             zzfxSound[randomnessIndex] = 0;
 
             // generate the zzfx samples, then hand them to an audio buffer so
@@ -215,11 +276,11 @@ class Sound
             this.loadedPercent = 1;
             onloadCallback?.(this);
         }
-        else if (typeof asset === 'string')
+        else if (asset)
         {
-            // load the audio file, report failures rather than leaving an
-            // unhandled rejection, the sound just stays unloaded and silent
-            const filename = asset;
+            // load the audio file, a URL object as bundlers give works like its string;
+            // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
+            const filename = asset + '';
             this.loadSound(filename).catch(e=>
                 LOG('Sound load failed for', filename, '-', e.message));
         }
@@ -229,7 +290,7 @@ class Sound
      *  Sounds keep their samples in an audio buffer, so reading this rebuilds
      *  the arrays from it and caches them. The copies are safe to hold onto,
      *  playing a sound detaches the buffer's own channel arrays.
-     *  @type {Array<Array<number>|Float32Array>} */
+     *  @return {Array<Array<number>|Float32Array>|undefined} */
     get sampleChannels()
     {
         const buffer = this.sampleBuffer;
@@ -265,14 +326,17 @@ class Sound
     }
 
     /** Play the sound
-     *  Sounds may not play until a user interaction occurs
+     *  - Browsers hold audio until the first user input, a sound played before it returns a paused instance
+     *    that starts on its own once audio runs, unless paused or stopped first; a one shot that would have
+     *    ended by then is dropped, and only the newest play of each sound waits, so a sound played every frame
+     *    starts once
      *  @param {Vector2} [pos] - World space position to play the sound if any
      *  @param {number}  [volume] - How much to scale volume by
      *  @param {number}  [pitch] - How much to scale pitch by
      *  @param {number}  [randomnessScale] - How much to scale pitch randomness
      *  @param {boolean} [loop] - Should the sound loop?
      *  @param {boolean} [paused] - Should the sound start paused
-     *  @return {SoundInstance} - The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode
+     *  @return {SoundInstance|undefined} - The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
      */
     play(pos, volume=1, pitch=1, randomnessScale=1, loop=false, paused=false)
     {
@@ -295,8 +359,11 @@ class Sound
                 if (lengthSquared > range*range)
                     return; // out of range
 
-                // attenuate volume by distance
-                volume *= percent(lengthSquared**.5, range, range*this.taper);
+                // attenuate volume by distance, full volume out to the taper and a fade past it,
+                // so a taper of 1 plays at full volume right up to the range
+                const distance = lengthSquared**.5, taperRange = range*this.taper;
+                if (distance > taperRange)
+                    volume *= percent(distance, range, taperRange);
             }
 
             // get pan from screen space coords
@@ -310,13 +377,13 @@ class Sound
         if (debug && debugSound && pos)
         {
             // visualize where positioned sounds play and their falloff range
-            debugCircle(pos, .5, '#0ff', .5, true);
+            debugCircle(pos, .5, '#0ff', .5, true, false);
             if (this.range)
             {
-                debugCircle(pos, 2*this.range, '#0ff', .5);            // silent radius
-                debugCircle(pos, 2*this.range*this.taper, '#0ff', .5); // full volume radius
+                debugCircle(pos, 2*this.range, '#0ff', .5, false, false);            // silent radius
+                debugCircle(pos, 2*this.range*this.taper, '#0ff', .5, false, false); // full volume radius
             }
-            debugText('vol '+volume.toFixed(2)+' pitch '+rate.toFixed(2), pos, .5, '#0ff', .5);
+            debugText('vol '+volume.toFixed(2)+' pitch '+rate.toFixed(2), pos, .5, '#0ff', .5, 0, 'monospace', false);
         }
 
         return instance;
@@ -328,7 +395,7 @@ class Sound
      *  @param {number}  [pitch] - How much to scale pitch by
      *  @param {number}  [randomnessScale] - How much to scale pitch randomness
      *  @param {boolean} [paused] - Should the sound start paused
-     *  @return {SoundInstance} - The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode */
+     *  @return {SoundInstance|undefined} - The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode */
     playLoop(pos, volume=1, pitch=1, randomnessScale=1, paused=false)
     { return this.play(pos, volume, pitch, randomnessScale, true, paused); }
 
@@ -336,7 +403,7 @@ class Sound
      *  @param {number} [volume] - Volume to play the music at
      *  @param {boolean} [loop] - Should the music loop?
      *  @param {boolean} [paused] - Should the music start paused
-     *  @return {SoundInstance} - The sound instance
+     *  @return {SoundInstance|undefined} - The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode
      */
     playMusic(volume=1, loop=true, paused=false)
     { return this.play(undefined, volume, 1, 0, loop, paused); }
@@ -346,7 +413,7 @@ class Sound
      *  @param {number}  [semitoneOffset] - How many semitones to offset pitch
      *  @param {Vector2} [pos] - World space position to play the sound if any
      *  @param {number}  [volume=1] - How much to scale volume by
-     *  @return {SoundInstance} - The sound instance
+     *  @return {SoundInstance|undefined} - The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
      */
     playNote(semitoneOffset=0, pos, volume)
     {
@@ -382,6 +449,7 @@ class Sound
         this.sampleRate = audioBuffer.sampleRate;
         this.sampleLength = audioBuffer.length;
         this.sampleBuffer = audioBuffer;
+        this._sampleChannels = undefined; // samples read from a sound loaded before are that sound's, not this one's
         this.loadedPercent = 1;
         this.onloadCallback?.(this);
     }
@@ -430,33 +498,49 @@ class SoundInstance
         this.pan = pan;
         /** @property {boolean} - Should the sound loop */
         this.loop = loop;
-        /** @property {number} - Timestamp for audio context when paused */
+        /** @property {number|undefined} - Where it is in the sound while not playing, in the sound's own seconds, undefined while playing
+         *  @type {number|undefined} */
         this.pausedTime = 0;
-        /** @property {number} - Timestamp for audio context when started */
+        /** @property {number} - Audio context time its place was last taken at, while playing
+         *  @type {number|undefined} */
         this.startTime = undefined;
-        /** @property {GainNode} - Gain node for the sound */
+        /** @property {number} - Where it was in the sound at startTime, in the sound's own seconds */
+        this.startOffset = 0;
+        /** @property {GainNode|undefined} - Gain node for the sound, undefined once it is stopped or paused
+         *  @type {GainNode|undefined} */
         this.gainNode = undefined;
-        /** @property {AudioBufferSourceNode} - Source node of the audio */
+        /** @property {StereoPannerNode|undefined} - Stereo panner for the sound, undefined once it is stopped or paused
+         *  @type {StereoPannerNode|undefined} */
+        this.pannerNode = undefined;
+        /** @property {AudioBufferSourceNode|undefined} - Source node of the audio, undefined while not playing
+         *  @type {AudioBufferSourceNode|undefined} */
         this.source = undefined;
-        /** @property {AudioNode|AudioEffectNodes} - Node or effect to route this instance through, copied from the sound
-         *  @type {AudioNode|AudioEffectNodes} */
+        /** @property {AudioNode|AudioEffectNodes|undefined} - Node or effect to route this instance through, copied from the sound
+         *  @type {AudioNode|AudioEffectNodes|undefined} */
         this.output = sound.output;
-        // setup end callback and start sound, a sound that ends is stopped, its time back at 0
-        this.onendedCallback = (source)=>
+        /** @property {AudioEndedCallback|undefined} - Called when this instance plays to its end, not when it is stopped
+         *  or paused; it is read when the sound ends, so it can be set at any time
+         *  @type {AudioEndedCallback|undefined} */
+        this.onendedCallback = undefined;
+        /** A playback that ends on its own leaves the instance stopped, its time back at 0; the ended event of one
+         *  stopped or replaced since is too late to change anything
+         *  @private */
+        this.sourceEnded = (source)=>
         {
-            if (source === this.source)
-            {
-                this.source = undefined;
-                this.startTime = undefined;
-                this.pausedTime = 0;
-            }
+            if (source !== this.source) return;
+            this.source = this.gainNode = this.pannerNode = undefined;
+            this.startTime = undefined;
+            this.pausedTime = 0;
+            this.onendedCallback?.(source);
         };
+
+        // start sound
         if (!paused)
             this.start();
     }
 
-    /** Start playing the sound instance from the offset time
-     *  @param {number} [offset] - Offset in seconds to start playback from 
+    /** Start playing the sound instance from a place in the sound
+     *  @param {number} [offset] - Where to start in the sound, in its own seconds whatever the rate
      */
     start(offset=0)
     {
@@ -464,22 +548,34 @@ class SoundInstance
         if (this.isPlaying())
             this.stop();
         this.gainNode = audioContext.createGain();
+        this.pannerNode = new StereoPannerNode(audioContext, {'pan':clamp(this.pan, -1, 1)});
 
         // build the shared buffer if it was not made at load time, then play it
         this.sound.buildSampleBuffer();
         this.source = this.sound.sampleBuffer ?
-            playAudioBuffer(this.sound.sampleBuffer, this.volume, this.rate, this.pan, this.loop, this.gainNode, offset, this.onendedCallback, this.output) :
-            playSamples(this.sound.sampleChannels, this.volume, this.rate, this.pan, this.loop, this.sound.sampleRate, this.gainNode, offset, this.onendedCallback, this.output);
+            playAudioBuffer(this.sound.sampleBuffer, this.volume, this.rate, this.pan, this.loop, this.gainNode, offset, this.sourceEnded, this.output, this.pannerNode) :
+            playSamples(this.sound.sampleChannels, this.volume, this.rate, this.pan, this.loop, this.sound.sampleRate, this.gainNode, offset, this.sourceEnded, this.output, this.pannerNode);
+        audioWaitingInstances.delete(this);
         if (this.source)
         {
-            this.startTime = audioContext.currentTime - offset;
+            this.startTime = audioContext.currentTime;
+            this.startOffset = offset;
             this.pausedTime = undefined;
         }
         else
         {
-            // the sound could not start, keep the place so a later resume picks it up
-            this.startTime = undefined;
+            // the sound could not start, keep the place so a later resume picks it up,
+            // which happens on its own when it failed only because audio is not running yet
+            this.startTime = this.gainNode = this.pannerNode = undefined;
             this.pausedTime = offset;
+            if (!audioIsRunning())
+            {
+                // only the newest of each sound waits, a loop a game plays again each frame is one loop
+                audioWaitingPrune();
+                for (const other of audioWaitingInstances.keys())
+                    other.sound === this.sound && audioWaitingInstances.delete(other);
+                audioWaitingInstances.set(this, performance.now());
+            }
         }
     }
 
@@ -492,32 +588,33 @@ class SoundInstance
         ASSERT(volume >= 0, 'Sound volume must be positive or zero');
         ASSERT(fadeTime >= 0, 'Sound fade time must be positive or zero');
         this.volume = volume;
-        if (!this.gainNode) return;
-
-        // drop any fade still scheduled so stacked calls don't fight,
-        // then ramp from wherever the gain is now or jump straight there
-        const gain = this.gainNode.gain;
-        const startFade = audioContext.currentTime;
-        gain.cancelScheduledValues(startFade);
-        if (fadeTime)
-        {
-            gain.setValueAtTime(gain.value, startFade);
-            gain.linearRampToValueAtTime(volume, startFade + fadeTime);
-        }
-        else
-            gain.value = volume;
+        this.gainNode && audioParamRamp(this.gainNode.gain, volume, fadeTime);
+    }
+
+    /** Set the stereo pan of this sound instance, while it plays too
+     *  - A looping sound can follow its source across the screen this way
+     *  @param {number} pan - -1 is left, 0 is center, 1 is right, clamped to that range */
+    setPan(pan)
+    {
+        ASSERT(isNumber(pan), 'Sound pan must be a number');
+        this.pan = pan;
+        if (this.pannerNode)
+            this.pannerNode.pan.value = clamp(pan, -1, 1);
     }
 
     /** Set the playback rate of this sound instance, its speed and pitch, while it plays
      *  - A looping sound can follow something smoothly this way, like an engine with the speed
-     *  - A rate of 0 freezes the sound in place, its current time is not tracked until it moves again
+     *  - A rate of 0 freezes the sound in place, and it carries on from there when the rate comes back
      *  @param {number} rate - 1 is normal, 2 is twice as fast and an octave up */
     setRate(rate)
     {
         ASSERT(rate >= 0, 'Sound rate must be positive or zero');
-        // keep the place in the sound, only the speed changes from here, so the current time stays true
-        if (this.isPlaying() && rate)
-            this.startTime = audioContext.currentTime - this.getCurrentTime() * this.rate / rate;
+        // keep the place in the sound, only the speed changes from here
+        if (this.isPlaying())
+        {
+            this.startOffset = this.getCurrentTime();
+            this.startTime = audioContext.currentTime;
+        }
         this.rate = rate;
         if (this.source)
             this.source.playbackRate.value = rate;
@@ -528,6 +625,7 @@ class SoundInstance
     stop(fadeTime=0)
     {
         ASSERT(fadeTime >= 0, 'Sound fade time must be positive or zero');
+        audioWaitingInstances.delete(this); // a sound waiting for audio to run no longer starts
         if (this.isPlaying())
         {
             if (fadeTime)
@@ -535,15 +633,8 @@ class SoundInstance
                 // ramp off gain from where it is now (not 1, or low-volume
                 // instances would jump back up before fading, and a volume
                 // fade in flight carries on down from its current point);
-                // cancel any prior scheduling so stacked stop calls don't
-                // re-anchor partway through a previous fade
-                const gain = this.gainNode.gain;
-                const startFade = audioContext.currentTime;
-                const endFade = startFade + fadeTime;
-                gain.cancelScheduledValues(startFade);
-                gain.setValueAtTime(gain.value, startFade);
-                gain.linearRampToValueAtTime(0, endFade);
-                this.source.stop(endFade);
+                // the ramp and the stop share one end time
+                this.source.stop(audioParamRamp(this.gainNode.gain, 0, fadeTime));
             }
             else
                 this.source.stop();
@@ -551,11 +642,16 @@ class SoundInstance
         this.pausedTime = 0;
         this.source = undefined;
         this.startTime = undefined;
+        // let go of the gain node so a later setVolume can't cancel the fade out, the ended listener disconnects
+        // it, and start makes a new one
+        this.gainNode = undefined;
+        this.pannerNode = undefined;
     }
 
     /** Pause this sound instance */
     pause()
     {
+        audioWaitingInstances.delete(this); // a sound waiting for audio to run no longer starts
         if (this.isPaused()) return;
 
         // save current time and stop sound
@@ -563,6 +659,8 @@ class SoundInstance
         this.source.stop();
         this.source = undefined;
         this.startTime = undefined;
+        this.gainNode = undefined; // resume starts with a new one at the volume set meanwhile
+        this.pannerNode = undefined;
     }
 
     /** Resume this sound instance */
@@ -584,24 +682,25 @@ class SoundInstance
      */
     isPaused() { return !this.isPlaying(); }
 
-    /** Get the current playback time in seconds
-     *  @return {number} - Current playback time
+    /** Get where it is in the sound, in the sound's own seconds: at a rate of 2 it moves two seconds for each one
+     *  that passes, and at 0 it stays put
+     *  @return {number} - Seconds into the sound
      */
     getCurrentTime()
     {
         if (!this.isPlaying()) return this.pausedTime;
         const duration = this.getDuration();
-        // guard mod against 0 duration (rate=0 or sound not loaded)
-        return duration ? mod(audioContext.currentTime - this.startTime, duration) : 0;
+        const place = this.startOffset + (audioContext.currentTime - this.startTime) * this.rate;
+        return duration ? mod(place, duration) : 0; // a sound still loading has no length yet
     }
 
-    /** Get the total duration of this sound
-     *  @return {number} - Total duration in seconds (0 if loading)
+    /** Get the length of the sound in its own seconds, the same at any rate; divide by the rate for how long it takes to play
+     *  @return {number} - Length in seconds (0 if loading)
      */
-    getDuration() { return this.rate ? this.sound.getDuration() / this.rate : 0; }
+    getDuration() { return this.sound.getDuration(); }
 
     /** Get source of this sound instance
-     *  @return {AudioBufferSourceNode}
+     *  @return {AudioBufferSourceNode|undefined} - The source, or undefined while not playing
      */
     getSource() { return this.source; }
 }
@@ -668,24 +767,27 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
  *  @param {number}   [sampleRate=44100] - Sample rate for the sound
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
- *  @param {number}   [offset] - Offset in seconds to start playback from
+ *  @param {number}   [offset] - Where to start in the sound, in its own seconds whatever the rate
  *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
  *  @param {AudioNode|AudioEffectNodes} [output] - Node or effect to connect the gain to instead of the master gain
- *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
+ *  @param {StereoPannerNode} [pannerNode] - Optional stereo panner for panning while playing, its pan already set (disconnected when the sound ends)
+ *  @return {AudioBufferSourceNode|undefined} - The source node of the sound played, undefined if play fails
  *  @memberof Audio */
-function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended, output)
+function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended, output, pannerNode)
 {
     if (!soundEnable || headlessMode) return;
 
     if (!audioIsRunning())
     {
-        // fix stalled audio, don't build a buffer that can't be played
-        audioContext.resume();
+        // fix stalled audio, don't build a buffer that can't be played;
+        // but a context suspended because the page is hidden stays suspended until it shows
+        if (!audioSuspendedWhenHidden)
+            audioContext.resume();
         return;
     }
 
     const buffer = createAudioBuffer(sampleChannels, sampleRate);
-    return playAudioBuffer(buffer, volume, rate, pan, loop, gainNode, offset, onended, output);
+    return playAudioBuffer(buffer, volume, rate, pan, loop, gainNode, offset, onended, output, pannerNode);
 }
 
 /** Copy arrays of samples into a new audio buffer
@@ -710,19 +812,22 @@ function createAudioBuffer(sampleChannels, sampleRate=audioDefaultSampleRate)
  *  @param {number}   [pan] - How much to apply stereo panning
  *  @param {boolean}  [loop] - True if the sound should loop when it reaches the end
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
- *  @param {number}   [offset] - Offset in seconds to start playback from
+ *  @param {number}   [offset] - Where to start in the sound, in its own seconds whatever the rate
  *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
  *  @param {AudioNode|AudioEffectNodes} [output] - Node or effect to connect the gain to instead of the master gain
- *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
+ *  @param {StereoPannerNode} [pannerNode] - Optional stereo panner for panning while playing, its pan already set (disconnected when the sound ends)
+ *  @return {AudioBufferSourceNode|undefined} - The source node of the sound played, undefined if play fails
  *  @memberof Audio */
-function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode, offset=0, onended, output)
+function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode, offset=0, onended, output, pannerNode)
 {
     if (!soundEnable || headlessMode) return;
 
     if (!audioIsRunning())
     {
-        // fix stalled audio, this sound won't be able to play
-        audioContext.resume();
+        // fix stalled audio, this sound won't be able to play;
+        // but a context suspended because the page is hidden stays suspended until it shows
+        if (!audioSuspendedWhenHidden)
+            audioContext.resume();
         return;
     }
 
@@ -740,21 +845,20 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
     gainNode.connect(outputNode);
 
     // connect source to stereo panner and gain
-    const pannerNode = new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)});
-    source.connect(pannerNode).connect(gainNode);
+    const panner = pannerNode || new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)});
+    source.connect(panner).connect(gainNode);
 
     // disconnect nodes when the sound ends so the audio graph doesn't grow
     // unbounded across many play() calls (source.stop() also fires 'ended')
     source.addEventListener('ended', ()=>
     {
         gainNode.disconnect();
-        pannerNode.disconnect();
+        panner.disconnect();
         if (onended) onended(source);
     });
 
-    // play and return sound
-    const startOffset = offset * rate;
-    source.start(0, startOffset);
+    // play and return sound, the offset is a place in the buffer whatever the rate
+    source.start(0, offset);
 
     if (debug && debugSound)
         LOG('sound', 'vol', volume.toFixed(2), 'rate', rate.toFixed(2), 'pan', pan.toFixed(2), loop ? 'loop' : '');
@@ -769,7 +873,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
  *
  *  <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
  *  @param {Array} zzfxSound - Array of ZzFX parameters, ex. [.5,.5]
- *  @return {AudioBufferSourceNode} - The audio node of the sound played
+ *  @return {AudioBufferSourceNode|undefined} - The audio node of the sound played, undefined if play fails
  *  @memberof Audio */
 function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
 
@@ -840,7 +944,7 @@ function zzfxG
         f,             // wave frequency
 
         // biquad LP/HP filter
-        quality = 2, w = PI2 * abs(filter) * 2 / sampleRate,
+        quality = 2, w = PI2 * min(abs(filter), sampleRate/4 - 1) * 2 / sampleRate, // stable below a quarter rate
         cosw = cos(w), alpha = sin(w) / 2 / quality,
         a0 = 1 + alpha, a1 = -2*cosw / a0, a2 = (1 - alpha) / a0,
         b0 = (1 + sign(filter) * cosw) / 2 / a0,
@@ -890,7 +994,7 @@ function zzfxG
 
             s = delay ? s/2 + (delay > i ? 0 :           // delay
                 (i<length-delay? 1 : (length-i)/delay) * // release delay
-                b[i-delay|0]/2/volume) : s;              // sample delay
+                b[i-delay|0]/2/(volume||1)) : s;         // sample delay, stored samples are 0 at volume 0
 
             if (filter)                                  // apply filter
                 s = y1 = b2*x2 + b1*(x2=x1) + b0*(x1=s) - a2*y2 - a1*(y2=y1);