jsbeeb 1.19.3 → 1.20.1

package/src/web/audio-handler.js

@@ -6,19 +6,39 @@ import { createAudioContext } from "../audio-utils.js";
 import { toggle, fadeIn, fadeOut } from "../dom-utils.js";
 import { toast } from "./toast.js";
 
-// Using this approach means when jsbeeb is embedded in other projects, vite doesn't have a fit.
-// See https://github.com/vitejs/vite/discussions/6459
-const rendererUrl = new URL("./audio-renderer.js", import.meta.url).href;
-const music5000WorkletUrl = new URL("../music5000-worklet.js", import.meta.url).href;
+import rendererUrl from "./audio-renderer.js?worker&url";
+import music5000WorkletUrl from "../music5000-worklet.js?worker&url";
+
+// Skips plot as the milliseconds skipped, on the lead scale; stalls as a fixed spike.
+const StallSpikeHeight = 20;
+
+// Nobody is watching an unfocused window, so its sound can run far behind
+// the picture, deep enough to ride out the browser starving the tab.
+export const UnfocusedLatencyMs = 200;
+export const DefaultLatencyMs = 20;
 
 export class AudioHandler {
-    constructor({ warningNode, statsNode, audioFilterFreq, audioFilterQ, noSeek, cpuSpeed, isAtom } = {}) {
+    constructor({
+        warningNode,
+        statsNode,
+        audioFilterFreq,
+        audioFilterQ,
+        audioLatencyMs,
+        noSeek,
+        cpuSpeed,
+        isAtom,
+        hasMusic5000,
+    } = {}) {
         this.cpuSpeed = cpuSpeed;
         this.isAtom = isAtom;
+        this.audioLatencyMs = audioLatencyMs ?? DefaultLatencyMs;
+        this.windowFocused = document.hasFocus();
         this.warningNode = warningNode;
         this.noAudio = false;
         toggle(this.warningNode, false);
         this.stats = {};
+        this.eventCounts = { stall: 0, skip: 0, leadMinMs: Infinity };
+        this._chipEvents = [];
         if (statsNode) {
             this._initStats(statsNode).catch((error) => {
                 console.error("Unable to initialise audio stats", error);
@@ -30,16 +50,19 @@ export class AudioHandler {
         this._jsAudioNode = null;
         if (this.audioContext && this.audioContext.audioWorklet) {
             this.audioContext.onstatechange = () => this.checkStatus();
-            const onBuffer = (buffer, time) => this._onBuffer(buffer, time);
+            const onEvent = (event) => {
+                if (event.progress) this.flushChipEvents();
+                else this._chipEvents.push(event);
+            };
             this.soundChip = this.isAtom
-                ? new AtomSoundChip(onBuffer, { cpuSpeed: this.cpuSpeed })
-                : new SoundChip(onBuffer);
+                ? new AtomSoundChip(null, { cpuSpeed: this.cpuSpeed, onEvent })
+                : new SoundChip(null, { onEvent });
             // Master gain node for all sample-based audio (disc, relay, etc.).
             this.masterGain = this.audioContext.createGain();
             this.masterGain.connect(this.audioContext.destination);
             this.ddNoise = noSeek ? new FakeDdNoise() : new DdNoise(this.audioContext, this.masterGain);
             this.relayNoise = new RelayNoise(this.audioContext, this.masterGain);
-            this._setup(audioFilterFreq, audioFilterQ).catch((error) => this._audioUnavailable(error));
+            this._setup({ audioFilterFreq, audioFilterQ }).catch((error) => this._audioUnavailable(error));
         } else {
             if (this.audioContext && !this.audioContext.audioWorklet) {
                 this.audioContext = null;
@@ -60,31 +83,31 @@ export class AudioHandler {
 
         this.warningNode.addEventListener("mousedown", () => this.tryResume());
 
-        // Initialise Music 5000 audio context
-        this.audioContextM5000 = createAudioContext({ sampleRate: 46875 });
-
-        if (this.audioContextM5000 && this.audioContextM5000.audioWorklet) {
-            this.audioContextM5000.onstatechange = () => this.checkStatus();
-            this.music5000 = new Music5000((buffer) => this._onBufferMusic5000(buffer));
-
-            this.audioContextM5000.audioWorklet
-                .addModule(music5000WorkletUrl)
-                .then(() => {
-                    this._music5000workletnode = new AudioWorkletNode(this.audioContextM5000, "music5000", {
-                        outputChannelCount: [2],
-                    });
-                    this._music5000workletnode.connect(this.audioContextM5000.destination);
-                })
-                .catch((error) => {
-                    console.error("Unable to initialise Music 5000 audio", error);
-                    toast(
-                        `The Music 5000 will be silent: its audio could not be started (${error?.message ?? error}). Reloading the page may help.`,
-                        { title: "Music 5000", quietKey: "quietMusic5000Audio" },
-                    );
-                });
-        } else {
-            this.music5000 = new FakeMusic5000();
-        }
+        this.audioContextM5000 = null;
+        this._music5000workletnode = null;
+        this.music5000 = hasMusic5000 ? this._createMusic5000() : new FakeMusic5000();
+    }
+
+    // The Music 5000 gets its own context, running at the board's own sample rate.
+    _createMusic5000() {
+        if (!this.audioContext?.audioWorklet) return new FakeMusic5000();
+        const context = createAudioContext({ sampleRate: 46875 });
+        this.audioContextM5000 = context;
+        context.onstatechange = () => this.checkStatus();
+        context.audioWorklet
+            .addModule(music5000WorkletUrl)
+            .then(() => {
+                this._music5000workletnode = new AudioWorkletNode(context, "music5000", { outputChannelCount: [2] });
+                this._music5000workletnode.connect(context.destination);
+            })
+            .catch((error) => {
+                console.error("Unable to initialise Music 5000 audio", error);
+                toast(
+                    `The Music 5000 will be silent: its audio could not be started (${error?.message ?? error}). Reloading the page may help.`,
+                    { title: "Music 5000", quietKey: "quietMusic5000Audio" },
+                );
+            });
+        return new Music5000((buffer) => this._onBufferMusic5000(buffer));
     }
 
     // Lazily load smoothie and set up the audio stats chart.
@@ -98,34 +121,64 @@ export class AudioHandler {
                 return { min: 0, max: range.max };
             },
         });
-        this._addStat("queueSize", { strokeStyle: "rgb(51,126,108)" });
-        this._addStat("queueAge", { strokeStyle: "rgb(162,119,22)" });
+        this._addStat("leadMs", { strokeStyle: "rgb(51,126,108)" });
+        this._addStat("stall", { strokeStyle: "rgb(220,50,50)", lineWidth: 2 });
+        this._addStat("skip", { strokeStyle: "rgb(120,80,200)", lineWidth: 2 });
         this.chart.streamTo(statsNode, 100);
     }
 
-    async _setup(audioFilterFreq, audioFilterQ) {
+    async _setup({ audioFilterFreq, audioFilterQ }) {
         await this.audioContext.audioWorklet.addModule(rendererUrl);
-        if (audioFilterFreq !== 0) {
-            const filterNode = this.audioContext.createBiquadFilter();
-            filterNode.type = "lowpass";
-            filterNode.frequency.value = audioFilterFreq;
-            filterNode.Q.value = audioFilterQ;
-            this._audioDestination = filterNode;
-            filterNode.connect(this.audioContext.destination);
-        } else {
-            this._audioDestination = this.audioContext.destination;
-        }
-
-        this._jsAudioNode = new AudioWorkletNode(this.audioContext, "sound-chip-processor");
-        this._jsAudioNode.connect(this._audioDestination);
+        this._jsAudioNode = new AudioWorkletNode(this.audioContext, "sound-chip-processor", {
+            processorOptions: {
+                targetLatencyMs: this._targetLatencyMs(),
+                isAtom: this.isAtom,
+                cpuSpeed: this.cpuSpeed,
+                audioFilterFreq,
+                audioFilterQ,
+            },
+        });
+        this._jsAudioNode.connect(this.audioContext.destination);
         this._jsAudioNode.port.onmessage = (event) => {
             const now = Date.now();
+            if (event.data.event) {
+                this._onAudioEvent(now, event.data);
+                return;
+            }
+            this.eventCounts.leadMinMs = Math.min(this.eventCounts.leadMinMs, event.data.leadMinMs);
             for (const stat of Object.keys(event.data)) {
                 if (this.stats[stat]) this.stats[stat].append(now, event.data[stat]);
             }
         };
     }
 
+    _onAudioEvent(now, { event, count }) {
+        this.eventCounts[event] += count;
+        const series = this.stats[event];
+        if (!series) return;
+        series.append(now - 1, 0);
+        series.append(now, event === "stall" ? StallSpikeHeight : count);
+        series.append(now + 1, 0);
+    }
+
+    _targetLatencyMs() {
+        return this.windowFocused ? this.audioLatencyMs : UnfocusedLatencyMs;
+    }
+
+    // Returns how far ahead of the sound the picture should now run, in ms.
+    setWindowFocused(focused) {
+        this.windowFocused = focused;
+        const targetLatencyMs = this._targetLatencyMs();
+        this._jsAudioNode?.port.postMessage({ command: "setTargetLatency", targetLatencyMs });
+        return targetLatencyMs - this.audioLatencyMs;
+    }
+
+    takeEventCounts() {
+        const counts = this.eventCounts;
+        this.eventCounts = { stall: 0, skip: 0, leadMinMs: Infinity };
+        return counts;
+    }
+
     _audioUnavailable(error) {
         console.error("Unable to initialise audio", error);
         this.noAudio = true;
@@ -140,11 +193,12 @@ export class AudioHandler {
         this.chart.addTimeSeries(timeSeries, info);
     }
 
-    _onBuffer(buffer) {
-        // No transfer list, deliberately: the chip reuses this buffer, and
-        // transferring would detach it and trip crbug.com/537801199. The clone
-        // costs little (512 floats per 1.024ms of chip output, ~2MB/s).
-        if (this._jsAudioNode) this._jsAudioNode.port.postMessage({ time: Date.now(), buffer });
+    // Ships the chip's state changes since the last call, and how far the
+    // emulator has got, so the worklet knows its lead even when nothing changed.
+    flushChipEvents() {
+        if (!this._jsAudioNode) return;
+        this._jsAudioNode.port.postMessage({ upTo: this.soundChip.scheduler.epoch, events: this._chipEvents });
+        this._chipEvents = [];
     }
 
     // Recent browsers, particularly Safari and Chrome, require a user interaction in order to enable sound playback.
@@ -177,13 +231,16 @@ export class AudioHandler {
         await this.relayNoise.initialise();
     }
 
+    // The emulator is stopping, so no tick will ship the change; send it now.
     mute() {
         this.soundChip.mute();
+        this.flushChipEvents();
         if (this.masterGain) this.masterGain.gain.value = 0;
     }
 
     unmute() {
         this.soundChip.unmute();
+        this.flushChipEvents();
         if (this.masterGain) this.masterGain.gain.value = 1;
     }
 }

package/src/web/audio-renderer.js

@@ -1,122 +1,213 @@
 /* global sampleRate, currentTime, registerProcessor, AudioWorkletProcessor */
+import { SoundChip, AtomSoundChip } from "../soundchip.js";
+import { LowPassBiquad } from "../biquad.js";
 
-const lowPassFilterFreq = sampleRate / 2;
-const RC = 1 / (2 * Math.PI * lowPassFilterFreq);
+// The board's output filter is an equal-component Sallen-Key (Service Manual
+// section 3.8: 10K and 2n2 twice, gain K = 1 + 22/39): f0 = 1/(2*pi*RC) = 7234 Hz,
+// Q = 1/(3 - K) = 0.696, below 1/sqrt(2), so no resonant peak. Run at the chip
+// rate, ahead of decimation, it is also the anti-alias filter.
+const OutputFilterHz = 7234;
+const OutputFilterQ = 0.696;
 
-const InputSampleRate = 4000000.0 / 8;
-const MaxQueuedMs = 250;
+const DefaultTargetLatencyMs = 1000 * (1 / 50); // One frame
+const MaxTargetLatencyMs = 250;
 
-const samplesFor = (ms) => (InputSampleRate * ms) / 1000;
-
-// Smoothing rejects the producer's per-frame bursts; proportional only, as
-// occupancy already integrates rate error; 0.05% authority covers clock skew
+// Smoothing rejects the producer's per-tick bursts; proportional only, as
+// lead already integrates rate error; 0.05% authority covers clock skew
 // without audibly bending pitch.
-const OccupancySmoothingTau = 0.5;
+const LeadSmoothingTau = 0.5;
 const ProportionalGain = 0.2;
-const MaxAdjust = InputSampleRate * 0.0005;
+const MaxAdjustFraction = 0.0005;
 
-class SoundChipProcessor extends AudioWorkletProcessor {
-    constructor(...args) {
-        super(...args);
+const isResync = (event) => event.state !== undefined || event.reset !== undefined;
 
-        this.inputSampleRate = InputSampleRate;
-        this._lastSample = 0;
-        this._lastFilteredOutput = 0;
+// Renders the chip from its timestamped state changes, so a producer that
+// falls behind leaves the chip sounding its current state (a stall) rather
+// than silent; the missed time is skipped once the producer is ahead again.
+class SoundChipProcessor extends AudioWorkletProcessor {
+    constructor(options) {
+        super(options);
+        const {
+            isAtom = false,
+            cpuSpeed = 1000000,
+            targetLatencyMs,
+            audioFilterFreq,
+            audioFilterQ,
+        } = options?.processorOptions ?? {};
+        this.chip = isAtom ? new AtomSoundChip(null, { cpuSpeed }) : new SoundChip(null);
+        this.inputSampleRate = this.chip.soundchipFreq;
+        this.samplesPerCycle = this.chip.samplesPerCycle;
+        this.outputFilter = this._makeOutputFilter(audioFilterFreq, audioFilterQ);
+
+        this.events = [];
+        this.eventsHead = 0;
+        this.clock = 0;
+        this.upTo = 0;
+        this.stalled = true;
+        this.stalls = 0;
+        this.skippedMs = 0;
+        this.minLeadMs = Infinity;
+
+        this._lastInputSample = 0;
         this._phase = 0;
         this._source = new Float32Array(0);
-        this.queue = [];
-        this._queueSizeSamples = 0;
-        this.dropped = 0;
-        this.underruns = 0;
-        this.targetLatencyMs = 1000 * (1 / 50); // One frame
-        this.startQueueSizeSamples = samplesFor(this.targetLatencyMs);
-        this.smoothedOccupancyError = 0;
-        this.running = false;
-        this.maxQueueSizeSamples = samplesFor(MaxQueuedMs);
+        this.smoothedLeadError = 0;
+        this.setTargetLatency(targetLatencyMs);
         this.port.onmessage = (event) => {
-            // TODO: even better than this, send over register settings/catch up and run the audio work _here_
-            this.onBuffer(event.data.time, event.data.buffer);
+            if (event.data.command === "setTargetLatency") this.setTargetLatency(event.data.targetLatencyMs);
+            else this.onProduced(event.data.upTo, event.data.events);
         };
         this.nextStats = 0;
     }
 
+    // Zero turns it off; a setting the biquad cannot realise (non-finite, at or
+    // above Nyquist, non-positive Q) falls back to the board's own values.
+    _makeOutputFilter(frequency = OutputFilterHz, q = OutputFilterQ) {
+        if (frequency <= 0) return null;
+        const usable = frequency < this.inputSampleRate / 2 && q > 0;
+        if (!usable) return new LowPassBiquad(this.inputSampleRate, OutputFilterHz, OutputFilterQ);
+        return new LowPassBiquad(this.inputSampleRate, frequency, q);
+    }
+
+    setTargetLatency(ms) {
+        const valid = Number.isFinite(ms) && ms > 0;
+        this.targetLatencyMs = valid ? Math.min(ms, MaxTargetLatencyMs) : DefaultTargetLatencyMs;
+        this.targetLeadCycles = this._cycles(this.targetLatencyMs);
+        this.smoothedLeadError = 0;
+    }
+
+    _cycles(ms) {
+        return ((ms / 1000) * this.inputSampleRate) / this.samplesPerCycle;
+    }
+
+    _ms(cycles) {
+        return (1000 * cycles * this.samplesPerCycle) / this.inputSampleRate;
+    }
+
+    leadMs() {
+        return this._ms(this.upTo - this.clock);
+    }
+
+    // A resync (restore or reset) starts a new timeline; anything queued
+    // before it belongs to the old one.
+    onProduced(upTo, events) {
+        let from = 0;
+        for (let i = events.length - 1; i >= 0; --i) {
+            if (isResync(events[i])) {
+                from = i;
+                this.events = [];
+                this.eventsHead = 0;
+                break;
+            }
+        }
+        if (this.eventsHead > 0) {
+            this.events = this.events.slice(this.eventsHead);
+            this.eventsHead = 0;
+        }
+        for (let i = from; i < events.length; ++i) this.events.push(events[i]);
+        this.upTo = upTo;
+    }
+
     stats(sampleRatio) {
         if (currentTime < this.nextStats) return;
         this.nextStats = currentTime + 0.25;
         this.port.postMessage({
             sampleRate: sampleRate,
             inputSampleRate: this.inputSampleRate,
-            dropped: this.dropped,
-            underruns: this.underruns,
-            queueSize: this.queue.length,
-            queueAge: this._queueAge(),
+            stalls: this.stalls,
+            skippedMs: this.skippedMs,
+            leadMs: this.leadMs(),
+            leadMinMs: this.minLeadMs,
+            queuedEvents: this.events.length - this.eventsHead,
             sampleRatio: sampleRatio,
         });
+        this.minLeadMs = Infinity;
     }
 
-    _queueAge() {
-        if (this.queue.length === 0) return 0;
-        const timeInBufferMs = 1000 * (this.queue[0].offset / this.inputSampleRate) + this.queue[0].time;
-        return Date.now() - timeInBufferMs;
+    _notify(event, count) {
+        this.port.postMessage({ event, count });
     }
 
-    _occupancySamples() {
-        return this._queueSizeSamples - (this.queue.length ? this.queue[0].offset : 0);
+    _effectiveSampleRate(dtSeconds) {
+        const error = this.upTo - this.clock - this.targetLeadCycles;
+        const alpha = Math.min(1, dtSeconds / LeadSmoothingTau);
+        this.smoothedLeadError += alpha * (error - this.smoothedLeadError);
+        const adjustment = ProportionalGain * this.smoothedLeadError * this.samplesPerCycle;
+        const maxAdjust = this.inputSampleRate * MaxAdjustFraction;
+        return this.inputSampleRate + Math.min(maxAdjust, Math.max(-maxAdjust, adjustment));
     }
 
-    _effectiveSampleRate(dtSeconds) {
-        const error = this._occupancySamples() - this.startQueueSizeSamples;
-        const alpha = Math.min(1, dtSeconds / OccupancySmoothingTau);
-        this.smoothedOccupancyError += alpha * (error - this.smoothedOccupancyError);
-        const adjustment = ProportionalGain * this.smoothedOccupancyError;
-        return this.inputSampleRate + Math.min(MaxAdjust, Math.max(-MaxAdjust, adjustment));
+    _applyHead() {
+        this.chip.applyEvent(this.events[this.eventsHead++]);
     }
 
-    onBuffer(time, buffer) {
-        this.queue.push({ offset: 0, time, buffer });
-        this._queueSizeSamples += buffer.length;
-        this.cleanQueue();
-        if (!this.running && this._queueSizeSamples >= this.startQueueSizeSamples) this.running = true;
+    // Applies every queued change up to `cycle` at once and moves the clock
+    // there, so the sound continues from the producer's state without a gap.
+    _skipTo(cycle) {
+        while (this.eventsHead < this.events.length && this.events[this.eventsHead].cycle <= cycle) this._applyHead();
+        this.skippedMs += this._ms(cycle - this.clock);
+        this.clock = cycle;
     }
 
-    _shift() {
-        const dropped = this.queue.shift();
-        this._queueSizeSamples -= dropped.buffer.length;
+    _restart() {
+        const skipTo = this.upTo - this.targetLeadCycles;
+        if (skipTo > this.clock) {
+            this._notify("skip", this._ms(skipTo - this.clock));
+            this._skipTo(skipTo);
+        }
+        this.stalled = false;
     }
 
-    cleanQueue() {
-        const maxLatency = this.targetLatencyMs * 2;
-        while (this._queueSizeSamples > this.maxQueueSizeSamples || this._queueAge() > maxLatency) {
-            this._shift();
-            this.dropped++;
+    _stall(out, offset, length) {
+        if (!this.stalled) {
+            this.stalled = true;
+            this.stalls++;
+            this._notify("stall", 1);
         }
+        this.chip.renderAt(this.clock, out, offset, length);
+    }
+
+    // Input samples before the next change of state: the head event, or
+    // the producer's position, whichever the clock reaches first. A resync
+    // takes effect at once, since it starts a new timeline.
+    _samplesUntilNextChange() {
+        const head = this.events[this.eventsHead];
+        if (head !== undefined && isResync(head)) return 0;
+        const boundary = head === undefined ? this.upTo : Math.min(head.cycle, this.upTo);
+        return Math.floor((boundary - this.clock) * this.samplesPerCycle);
     }
 
-    nextSample() {
-        if (this.running && this.queue.length) {
-            const queueElement = this.queue[0];
-            this._lastSample = queueElement.buffer[queueElement.offset];
-            if (++queueElement.offset === queueElement.buffer.length) this._shift();
-        } else {
-            this.underruns++;
-            this.running = false;
+    _renderInput(out, offset, length) {
+        if (this.stalled) {
+            this._stall(out, offset, length);
+            return;
+        }
+        while (length > 0) {
+            const n = Math.min(length, this._samplesUntilNextChange());
+            if (n > 0) {
+                this.chip.renderAt(this.clock, out, offset, n);
+                this.clock += n / this.samplesPerCycle;
+                offset += n;
+                length -= n;
+                continue;
+            }
+            const head = this.events[this.eventsHead];
+            if (head === undefined) {
+                this._stall(out, offset, length);
+                return;
+            }
+            if (isResync(head)) this.clock = head.cycle;
+            this._applyHead();
         }
-        return this._lastSample;
     }
 
     process(inputs, outputs) {
-        this.cleanQueue();
-        if (this.queue.length === 0) return true;
+        if (this.stalled && this.upTo - this.clock >= this.targetLeadCycles) this._restart();
 
-        // I looked into using https://www.npmjs.com/package/@alexanderolsen/libsamplerate-js or similar (the full API),
-        // but we fiddle the sample rate here to catch up with the target latency, which is harder to do with that API.
         const channel = outputs[0][0];
         const effectiveSampleRate = this._effectiveSampleRate(channel.length / sampleRate);
         const sampleRatio = effectiveSampleRate / sampleRate;
 
-        const dt = 1 / effectiveSampleRate;
-        const filterAlpha = dt / (RC + dt);
-
         // The fractional read position carries across quanta, so consumption
         // averages exactly sampleRatio and the pitch never steps at a rounding
         // boundary. source[0] is the last input sample of the previous quantum.
@@ -124,13 +215,10 @@ class SoundChipProcessor extends AudioWorkletProcessor {
         const numInputSamples = Math.floor(end);
         if (this._source.length <= numInputSamples) this._source = new Float32Array(numInputSamples * 2);
         const source = this._source;
-        source[0] = this._lastFilteredOutput;
-        let prevSample = this._lastFilteredOutput;
-        for (let i = 1; i <= numInputSamples; ++i) {
-            prevSample += filterAlpha * (this.nextSample() - prevSample);
-            source[i] = prevSample;
-        }
-        this._lastFilteredOutput = prevSample;
+        source[0] = this._lastInputSample;
+        this._renderInput(source, 1, numInputSamples);
+        this.outputFilter?.process(source, 1, numInputSamples);
+        this._lastInputSample = source[numInputSamples];
         for (let i = 0; i < channel.length; i++) {
             const pos = this._phase + i * sampleRatio;
             const loc = Math.floor(pos);
@@ -138,6 +226,7 @@ class SoundChipProcessor extends AudioWorkletProcessor {
             channel[i] = source[loc] * (1 - alpha) + source[loc + 1] * alpha;
         }
         this._phase = end - numInputSamples;
+        this.minLeadMs = Math.min(this.minLeadMs, this.leadMs());
         this.stats(sampleRatio);
         return true;
     }