jsbeeb 1.19.2 → 1.20.0

package/README.md

@@ -287,7 +287,8 @@ sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
   Doesn't support the sth: pseudo URL unlike `disc` and `tape`, but if given a ZIP file will attempt to use the `.rom`
   file assumed to be within.
 - (mostly internal use) `logFdcCommands`, `logFdcStateChanges` - turn on logging in the disc controller.
-- `audioDebug` - show audio queue stats chart.
+- `audioDebug` - show the audio lead chart, and log one console line per second in which the emulator tick ran late or the sound stalled or skipped.
+- `audioLatencyMs` - how far the sound runs behind the emulator, in milliseconds (default 20). Raising it lets the sound ride out longer stalls of the emulator, at the cost of lagging the picture by that much.
 
 ### Atom-specific parameters
 

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.19.2",
+  "version": "1.20.0",
   "//engines": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": ">=24.15.0"

package/src/google-drive.js

@@ -23,7 +23,17 @@ export class GoogleDriveLoader {
         this.driveClient = undefined;
     }
 
-    async initialise() {
+    initialise() {
+        if (!this._initialising) {
+            this._initialising = this._initialise().catch((error) => {
+                this._initialising = undefined;
+                throw error;
+            });
+        }
+        return this._initialising;
+    }
+
+    async _initialise() {
         console.log("Creating GAPI");
         await this._loadScript("https://apis.google.com/js/api.js");
         console.log("Got GAPI, creating token client");

package/src/main.js

@@ -145,6 +145,7 @@ const paramTypes = {
     frameSkip: ParamTypes.INT,
     audiofilterfreq: ParamTypes.FLOAT,
     audiofilterq: ParamTypes.FLOAT,
+    audioLatencyMs: ParamTypes.FLOAT,
     cpuMultiplier: ParamTypes.FLOAT,
     tubeCpuMultiplier: ParamTypes.FLOAT,
     microphoneChannel: ParamTypes.INT,
@@ -174,8 +175,12 @@ const cpuMultiplier = parsedQuery.cpuMultiplier ?? 1;
 let fastAsPossible = false;
 let fastTape = false;
 let noSeek;
-let audioFilterFreq = 7000;
-let audioFilterQ = 5;
+// The board's output filter is an equal-component Sallen-Key (Service Manual
+// section 3.8: 10K and 2n2 twice, gain 1 + 22/39): f0 = 1/(2*pi*RC) = 7234 Hz,
+// Q = 1/(3 - K) = 0.696, below 1/sqrt(2), so no resonant peak. BiquadFilterNode
+// takes lowpass Q in decibels: 20*log10(0.696) = -3.15.
+let audioFilterFreq = 7234;
+let audioFilterQ = -3.15;
 let stationId = 101;
 let econet = null;
 
@@ -368,7 +373,7 @@ sbBind(document.querySelector(".sidebar.bottom"), parsedQuery.sbBottom, function
 if (cpuMultiplier !== 1) console.log(`CPU multiplier set to ${cpuMultiplier}`);
 const cpuSpeed = model.cyclesPerSecond;
 const clocksPerSecond = (cpuMultiplier * cpuSpeed) | 0;
-const MaxCyclesPerFrame = clocksPerSecond / 10;
+const MaxCyclesPerTick = clocksPerSecond / 10;
 
 let tryGl = true;
 if (parsedQuery.glEnabled !== undefined) {
@@ -548,14 +553,40 @@ function swapCanvas(newFilterClass) {
 const canvas = createCanvasForFilter(displayModeFilter);
 displayModeFilter = canvas.filterClass;
 
+// The emulator paints into its own framebuffer; flyback copies the finished
+// frame into the canvas and an animation frame presents it, so a stalled
+// display holds up the picture and not the emulation (issue #885).
+const videoFb32 = new Uint32Array(canvas.fb32.length);
+const pendingFrame = { minx: 0, miny: 0, maxx: 0, maxy: 0, frameCount: 0, lineGrid: new Uint8Array(0) };
+let presentScheduled = false;
+let paintMsThisTick = 0;
+let presentMsMax = 0;
+
+function present() {
+    presentScheduled = false;
+    const start = performance.now();
+    canvas.paint(pendingFrame.minx, pendingFrame.miny, pendingFrame.maxx, pendingFrame.maxy, pendingFrame);
+    presentMsMax = Math.max(presentMsMax, performance.now() - start);
+}
+
 video = new Video(
     model.isMaster,
-    canvas.fb32,
+    videoFb32,
     function paint(minx, miny, maxx, maxy) {
         frames++;
         if (frames < frameSkip) return;
         frames = 0;
-        canvas.paint(minx, miny, maxx, maxy, { frameCount: this.frameCount, lineGrid: this.lineGrid });
+        const start = performance.now();
+        canvas.fb32.set(videoFb32.subarray(miny * 1024, maxy * 1024), miny * 1024);
+        if (pendingFrame.lineGrid.length !== this.lineGrid.length)
+            pendingFrame.lineGrid = new Uint8Array(this.lineGrid.length);
+        pendingFrame.lineGrid.set(this.lineGrid);
+        Object.assign(pendingFrame, { minx, miny, maxx, maxy, frameCount: this.frameCount });
+        paintMsThisTick += performance.now() - start;
+        if (!presentScheduled) {
+            presentScheduled = true;
+            window.requestAnimationFrame(present);
+        }
     },
     { isAtom: model.isAtom },
 );
@@ -569,9 +600,11 @@ const audioHandler = new AudioHandler({
     statsNode: audioStatsNode,
     audioFilterFreq,
     audioFilterQ,
+    audioLatencyMs: parsedQuery.audioLatencyMs,
     noSeek,
     cpuSpeed,
     isAtom: model.isAtom,
+    hasMusic5000: config.hasMusic5000,
 });
 // Firefox will report that audio is suspended even when it will
 // start playing without user interaction, so we need to delay a
@@ -720,7 +753,9 @@ setCrtPic(displayModeFilter);
 
 window.addEventListener("blur", function () {
     keyboard.clearKeys();
+    setEmulationLead(audioHandler.setWindowFocused(false));
 });
+window.addEventListener("focus", () => setEmulationLead(audioHandler.setWindowFocused(true)));
 
 document.getElementById("fs").addEventListener("click", function (event) {
     screenCanvas.requestFullscreen();
@@ -1690,20 +1725,16 @@ async function gdLoad(cat, layout) {
     }
 }
 
-for (const el of document.querySelectorAll(".if-drive-available")) el.style.display = "none";
-(async () => {
+const googleDriveModal = new bootstrap.Modal(googleDriveEl);
+// Loading the Google client holds the main thread for ~100ms, so it waits for
+// someone to ask for Drive.
+document.getElementById("open-drive-link").addEventListener("click", async function () {
     try {
-        const available = await googleDrive.initialise();
-        if (available) {
-            for (const el of document.querySelectorAll(".if-drive-available")) el.style.display = "";
-            await gdAuth(true);
-        }
+        await googleDrive.initialise();
     } catch (error) {
-        console.log(`Google Drive is unavailable: ${errorText(error)}`);
+        toast(`Google Drive is unavailable: ${errorText(error)}`, { title: "Google Drive" });
+        return false;
     }
-})();
-const googleDriveModal = new bootstrap.Modal(googleDriveEl);
-document.getElementById("open-drive-link").addEventListener("click", async function () {
     const authed = await gdAuth(false);
     if (authed) {
         googleDriveModal.show();
@@ -2244,6 +2275,7 @@ function profileVideo(arg) {
 }
 
 let last = 0;
+let lastEnd = 0;
 
 function VirtualSpeedUpdater() {
     this.cycles = 0;
@@ -2277,8 +2309,51 @@ function VirtualSpeedUpdater() {
 const virtualSpeedUpdater = new VirtualSpeedUpdater();
 
 const rewindBuffer = new RewindBuffer(30);
-let rewindFrameCounter = 0;
-const RewindCaptureInterval = 50; // ~1 second at 50fps
+let rewindCycleCounter = 0;
+const RewindCaptureInterval = 50; // emulated frames, ~1 second
+const RewindCaptureCycles = (RewindCaptureInterval * clocksPerSecond) / 50;
+
+// Under ?audioDebug, one console line per second in which the emulator sat
+// idle between ticks or a tick ran long, or the audio queue underran or
+// dropped, so a click can be matched to a cause. The sound chip posts samples
+// throughout execute(), so only the idle time starves the audio queue.
+const AudioDebugLogIntervalMs = 1000;
+const AudioDebugSlowTickMs = 30;
+const audioDebugLog = { start: 0, ticks: 0, cycles: 0, maxIdle: 0, maxExecute: 0, maxPaint: 0, maxSnapshot: 0 };
+const AudioDebugSlowPresentMs = 30;
+
+function logAudioDebugTick(now, cycles, idleMs, executeMs, paintMs, snapshotMs) {
+    const log = audioDebugLog;
+    if (log.start === 0) log.start = now;
+    log.ticks++;
+    log.cycles += cycles;
+    log.maxIdle = Math.max(log.maxIdle, idleMs);
+    log.maxExecute = Math.max(log.maxExecute, executeMs);
+    log.maxPaint = Math.max(log.maxPaint, paintMs);
+    log.maxSnapshot = Math.max(log.maxSnapshot, snapshotMs);
+    if (now - log.start < AudioDebugLogIntervalMs) return;
+    const audio = audioHandler.takeEventCounts();
+    const present = presentMsMax;
+    presentMsMax = 0;
+    const leadMin = Number.isFinite(audio.leadMinMs) ? `${audio.leadMinMs.toFixed(1)}ms` : "(no stats)";
+    if (
+        log.maxIdle > AudioDebugSlowTickMs ||
+        log.maxExecute > AudioDebugSlowTickMs ||
+        present > AudioDebugSlowPresentMs ||
+        audio.stall ||
+        audio.skip
+    ) {
+        console.log(
+            `${(now / 1000).toFixed(0)}s: ${log.ticks} ticks emulating ${((1000 * log.cycles) / clocksPerSecond).toFixed(0)}ms, ` +
+                `idle max ${log.maxIdle.toFixed(0)}ms, ` +
+                `execute max ${log.maxExecute.toFixed(0)}ms (paint ${log.maxPaint.toFixed(1)}ms), ` +
+                `present max ${present.toFixed(0)}ms, snapshot ${log.maxSnapshot.toFixed(1)}ms; ` +
+                `audio lead min ${leadMin}, stalls ${audio.stall}, skipped ${audio.skip.toFixed(0)}ms`,
+        );
+    }
+    log.start = now;
+    log.ticks = log.cycles = log.maxIdle = log.maxExecute = log.maxPaint = log.maxSnapshot = 0;
+}
 
 rewindUI = new RewindUI({
     rewindBuffer,
@@ -2311,21 +2386,31 @@ for (const item of document.querySelectorAll(".drive-tracks")) {
     if (drive) showDriveTracks(driveIndex);
 }
 
-function draw(now) {
+// A timer, not requestAnimationFrame: a display presentation stall withholds
+// animation frames, and with them the sound chip's samples (issue #885).
+const TickMs = 10;
+let tickToken = null;
+
+// A user-blocking task runs ahead of rendering and ordinary timers, so a stuck
+// compositor does not hold the tick off too.
+function scheduleTick(delayMs) {
+    const token = (tickToken = {});
+    const fire = () => {
+        if (tickToken === token) tick();
+    };
+    if (window.scheduler?.postTask) window.scheduler.postTask(fire, { delay: delayMs, priority: "user-blocking" });
+    else window.setTimeout(fire, delayMs);
+}
+
+function tick() {
     if (!running) {
         last = 0;
         return;
     }
-    // If we got here via setTimeout, we don't get passed the time.
-    if (now === undefined) {
-        now = window.performance.now();
-    }
+    const now = performance.now();
 
     const motorOn = processor.acia.motorOn;
-    const discOn = processor.fdc.motorOn[0] || processor.fdc.motorOn[1];
     const speedy = fastAsPossible || (fastTape && motorOn);
-    const useTimeout = speedy || motorOn || discOn;
-    const timeout = speedy ? 0 : 1000.0 / 50;
 
     // In speedy mode, we still run all the state machines accurately
     // but we paint less often because painting is the most expensive
@@ -2334,25 +2419,16 @@ function draw(now) {
     // modes, i.e. MODE 7, still look ok.
     video.frameSkipCount = speedy ? 9 : 0;
 
-    // We use setTimeout instead of requestAnimationFrame in two cases:
-    // a) We're trying to run as fast as possible.
-    // b) Tape is playing, normal speed but backgrounded tab should run.
-    if (useTimeout) {
-        window.setTimeout(draw, timeout);
-    } else {
-        window.requestAnimationFrame(draw);
-    }
+    scheduleTick(speedy ? 0 : TickMs);
 
-    audioHandler.soundChip.catchUp();
     gamepad.update(processor.sysvia);
     syncLights();
     if (last !== 0) {
         let cycles;
         if (!speedy) {
-            // Now and last are DOMHighResTimeStamp, just a double.
-            const sinceLast = now - last;
+            const sinceLast = Math.max(0, now - last);
             cycles = (sinceLast * clocksPerSecond) / 1000;
-            cycles = Math.min(cycles, MaxCyclesPerFrame);
+            cycles = Math.min(cycles, MaxCyclesPerTick);
         } else {
             cycles = clocksPerSecond / 50;
         }
@@ -2361,14 +2437,20 @@ function draw(now) {
             if (!processor.execute(cycles)) {
                 stop(true);
             }
+            audioHandler.flushChipEvents();
             const end = performance.now();
             virtualSpeedUpdater.update(cycles, end - now, speedy);
-            // Capture rewind snapshot periodically
-            if (++rewindFrameCounter >= RewindCaptureInterval) {
-                rewindFrameCounter = 0;
+            let snapshotMs = 0;
+            rewindCycleCounter += cycles;
+            if (rewindCycleCounter >= RewindCaptureCycles) {
+                rewindCycleCounter -= RewindCaptureCycles;
                 rewindBuffer.push(processor.snapshotState());
                 rewindUI.updateButtonState();
+                snapshotMs = performance.now() - end;
             }
+            if (audioStatsNode)
+                logAudioDebugTick(now, cycles, speedy ? 0 : now - lastEnd, end - now, paintMsThisTick, snapshotMs);
+            paintMsThisTick = 0;
         } catch (e) {
             running = false;
             utils.noteEvent("exception", "thrown", e.stack);
@@ -2379,11 +2461,29 @@ function draw(now) {
             stop(false);
         }
     }
-    last = now;
+    last = Math.max(last, now);
+    lastEnd = performance.now();
 }
 
 function run() {
-    window.requestAnimationFrame(draw);
+    scheduleTick(0);
+}
+
+// A change of audio buffer depth is taken by the picture, not the sound:
+// gaining lead emulates ahead at once; losing it moves `last` forward so the
+// ticks emulate nothing until the queue has drained by that much.
+let emulationLeadMs = 0;
+
+function setEmulationLead(leadMs) {
+    if (!running) return;
+    const aheadMs = leadMs - emulationLeadMs;
+    emulationLeadMs = leadMs;
+    if (aheadMs > 0) {
+        if (!processor.execute((aheadMs * clocksPerSecond) / 1000)) stop(true);
+        audioHandler.flushChipEvents();
+    } else {
+        last -= aheadMs;
+    }
 }
 
 let wasPreviouslyRunning = false;

package/src/soundchip.js

@@ -5,6 +5,17 @@ const speakerVolume = 0.5;
 // Samples per output chunk handed to the onBuffer callback.
 export const SoundBufferSamples = 512;
 
+// The BBC's DC restoration circuit (Service Manual section 3.8: R8 10K, C2
+// 4u7) cancels the SN76489's unipolar pedestal. Modelled as a first-order DC
+// blocker with the same corner, 1/(2*pi*R*C). The generators must stay
+// unipolar: sampled speech is amplitude modulation of a 125 kHz carrier's
+// mean level, which a zero-mean output would silence (see issue #863).
+const DcRestoreCornerHz = 1 / (2 * Math.PI * 10e3 * 4.7e-6);
+
+// A chip with an event sink reports progress this often, so its events can
+// stream through a long execute() rather than all arriving at its end.
+const EventProgressCycles = 4000;
+
 const volumeTable = new Float32Array(16);
 (() => {
     let f = 1.0;
@@ -28,9 +39,15 @@ export class SoundChip {
      * @param {function(Float32Array): void} onBuffer called with each full
      *     SoundBufferSamples-sized buffer of output. Receives the same buffer
      *     every call, overwritten afterwards: copy the contents if they are kept.
+     * @param {object} [options]
+     * @param {function(object): void} [options.onEvent] called with each
+     *     change to the chip's state, stamped with the cycle it takes effect at.
+     *     A chip with an event sink does not render; something else renders
+     *     from the events (see audio-renderer.js).
      */
-    constructor(onBuffer) {
+    constructor(onBuffer, { onEvent = null } = {}) {
         this._onBuffer = onBuffer;
+        this._onEvent = onEvent;
         // 4MHz input signal. Internal divide-by-8
         this.soundchipFreq = 4000000.0 / 8;
         const sampleRate = this.soundchipFreq;
@@ -72,6 +89,10 @@ export class SoundChip {
         this.position = 0;
         this.buffer = new Float32Array(SoundBufferSamples);
 
+        this.dcAlpha = 1 - (2 * Math.PI * DcRestoreCornerHz) / sampleRate;
+        this.dcPrevIn = 0;
+        this.dcPrevOut = 0;
+
         this.latchedRegister = 0;
         this.slowDataBus = 0;
         this.active = false;
@@ -80,15 +101,38 @@ export class SoundChip {
             mute: () => {
                 this.catchUp();
                 this.sineOn = false;
+                this._emit({ sine: 0 });
             },
             tone: (freq) => {
                 this.catchUp();
                 this.sineOn = true;
                 this.sineStep = (freq / sampleRate) * this.sineTable.length;
+                this._emit({ sine: freq });
             },
         };
     }
 
+    _emit(event) {
+        if (this._onEvent) this._onEvent({ cycle: this.scheduler.epoch, ...event });
+    }
+
+    /** Applies an event from another chip's onEvent, at the cycle this chip is rendering. */
+    applyEvent(event) {
+        if (event.poke !== undefined) this.poke(event.poke);
+        else if (event.sine !== undefined) {
+            if (event.sine) this.toneGenerator.tone(event.sine);
+            else this.toneGenerator.mute();
+        } else if (event.enabled !== undefined) this.enabled = event.enabled;
+        else if (event.state !== undefined) this.restoreState(event.state);
+        else if (event.reset !== undefined) this.reset(event.reset);
+    }
+
+    /** Renders `length` samples of output from `cycle`, for a chip that is driven by events. */
+    renderAt(cycle, out, offset, length) {
+        this.scheduler.epoch = this.lastRunEpoch = cycle;
+        this.generate(out, offset, length);
+    }
+
     sineChannel(channel, out, offset, length) {
         if (!this.sineOn) return;
 
@@ -170,6 +214,7 @@ export class SoundChip {
         this.volume[2] = volumeTable[v2];
         this.volume[3] = volumeTable[v3];
         this.noisePoked();
+        this._emit({ state: this.snapshotState() });
     }
 
     generate(out, offset, length) {
@@ -178,10 +223,22 @@ export class SoundChip {
         for (let i = 0; i < length; ++i) {
             out[i + offset] = 0.0;
         }
-        if (!this.enabled) return;
-        for (let i = 0; i < this.generators.length; ++i) {
-            this.generators[i](i, out, offset, length);
+        if (this.enabled) {
+            for (let i = 0; i < this.generators.length; ++i) {
+                this.generators[i](i, out, offset, length);
+            }
         }
+        const alpha = this.dcAlpha;
+        let prevIn = this.dcPrevIn;
+        let prevOut = this.dcPrevOut;
+        for (let i = 0; i < length; ++i) {
+            const x = out[i + offset];
+            prevOut = x - prevIn + alpha * prevOut;
+            prevIn = x;
+            out[i + offset] = prevOut;
+        }
+        this.dcPrevIn = prevIn;
+        this.dcPrevOut = prevOut;
     }
 
     catchUp() {
@@ -196,6 +253,13 @@ export class SoundChip {
         this.activeTask = this.scheduler.newTask(() => {
             if (this.active) this.poke(this.slowDataBus);
         });
+        if (this._onEvent) {
+            this.progressTask = this.scheduler.newTask(() => {
+                this._emit({ progress: true });
+                this.progressTask.schedule(EventProgressCycles);
+            });
+            this.progressTask.schedule(EventProgressCycles);
+        }
     }
 
     render(out, offset, length) {
@@ -216,6 +280,7 @@ export class SoundChip {
     }
 
     advance(cycles) {
+        if (this._onEvent) return;
         const num = cycles * this.samplesPerCycle + this.residual;
         let rounded = num | 0;
         this.residual = num - rounded;
@@ -247,6 +312,7 @@ export class SoundChip {
 
     poke(value) {
         this.catchUp();
+        this._emit({ poke: value });
 
         let command;
         if (value & 0x80) {
@@ -297,6 +363,8 @@ export class SoundChip {
             sineOn: this.sineOn,
             sineStep: this.sineStep,
             sineTime: this.sineTime,
+            dcPrevIn: this.dcPrevIn,
+            dcPrevOut: this.dcPrevOut,
         };
     }
 
@@ -322,10 +390,16 @@ export class SoundChip {
         // Reset output buffer
         this.position = 0;
         this.buffer.fill(0);
+        // Older snapshots predate the DC blocker
+        this.dcPrevIn = state.dcPrevIn ?? 0;
+        this.dcPrevOut = state.dcPrevOut ?? 0;
+        this.progressTask?.ensureScheduled(true, EventProgressCycles);
+        this._emit({ state: this.snapshotState() });
     }
 
     reset(hard) {
         if (!hard) return;
+        this._emit({ reset: true });
         for (let i = 0; i < 4; ++i) {
             this.counter[i] = 0;
             this.registers[i] = 0;
@@ -338,14 +412,15 @@ export class SoundChip {
 
     enable(e) {
         this.enabled = e;
+        this._emit({ enabled: e });
     }
 
     mute() {
-        this.enabled = false;
+        this.enable(false);
     }
 
     unmute() {
-        this.enabled = true;
+        this.enable(true);
     }
 }
 
@@ -355,8 +430,8 @@ export class SoundChip {
  * channel with DC-blocking filter.
  */
 export class AtomSoundChip extends SoundChip {
-    constructor(onBuffer, { cpuSpeed = 1000000 } = {}) {
-        super(onBuffer);
+    constructor(onBuffer, { cpuSpeed = 1000000, onEvent = null } = {}) {
+        super(onBuffer, { onEvent });
         this.samplesPerCycle = this.soundchipFreq / cpuSpeed;
         this.secondsPerCycle = 1 / cpuSpeed;
 
@@ -395,7 +470,19 @@ export class AtomSoundChip extends SoundChip {
         this._speakerCycleOffset = 0;
     }
 
+    applyEvent(event) {
+        if (event.bit !== undefined) this.bitChange.push({ bit: event.bit, cycles: event.cycle });
+        else if (event.speakerReset !== undefined) this.speakerReset();
+        else super.applyEvent(event);
+    }
+
+    renderAt(cycle, out, offset, length) {
+        this._speakerCycleOffset = 0;
+        super.renderAt(cycle, out, offset, length);
+    }
+
     speakerReset() {
+        this._emit({ speakerReset: true });
         this.bitChange = [];
         this.currentSpeakerBit = 0.0;
         this._speakerPrevIn = 0;
@@ -433,7 +520,9 @@ export class AtomSoundChip extends SoundChip {
 
     updateSpeaker(value, microCycle, seconds) {
         const cycles = microCycle + seconds / this.secondsPerCycle;
-        this.bitChange.push({ bit: value ? 1.0 : 0.0, cycles });
+        const bit = value ? 1.0 : 0.0;
+        if (this._onEvent) this._onEvent({ cycle: cycles, bit });
+        else this.bitChange.push({ bit, cycles });
     }
 }
 

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,10 +50,13 @@ 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);
@@ -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,8 +121,9 @@ 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);
     }
 
@@ -116,16 +140,54 @@ export class AudioHandler {
             this._audioDestination = this.audioContext.destination;
         }
 
-        this._jsAudioNode = new AudioWorkletNode(this.audioContext, "sound-chip-processor");
+        this._jsAudioNode = new AudioWorkletNode(this.audioContext, "sound-chip-processor", {
+            processorOptions: {
+                targetLatencyMs: this._targetLatencyMs(),
+                isAtom: this.isAtom,
+                cpuSpeed: this.cpuSpeed,
+            },
+        });
         this._jsAudioNode.connect(this._audioDestination);
         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 +202,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 +240,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,117 +1,224 @@
 /* global sampleRate, currentTime, registerProcessor, AudioWorkletProcessor */
+import { SoundChip, AtomSoundChip } from "../soundchip.js";
 
 const lowPassFilterFreq = sampleRate / 2;
 const RC = 1 / (2 * Math.PI * lowPassFilterFreq);
 
-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-tick bursts; proportional only, as
+// lead already integrates rate error; 0.05% authority covers clock skew
+// without audibly bending pitch.
+const LeadSmoothingTau = 0.5;
+const ProportionalGain = 0.2;
+const MaxAdjustFraction = 0.0005;
 
+const isResync = (event) => event.state !== undefined || event.reset !== undefined;
+
+// 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(...args) {
-        super(...args);
+    constructor(options) {
+        super(options);
+        const { isAtom = false, cpuSpeed = 1000000, targetLatencyMs } = options?.processorOptions ?? {};
+        this.chip = isAtom ? new AtomSoundChip(null, { cpuSpeed }) : new SoundChip(null);
+        this.inputSampleRate = this.chip.soundchipFreq;
+        this.samplesPerCycle = this.chip.samplesPerCycle;
+
+        this.events = [];
+        this.eventsHead = 0;
+        this.clock = 0;
+        this.upTo = 0;
+        this.stalled = true;
+        this.stalls = 0;
+        this.skippedMs = 0;
+        this.minLeadMs = Infinity;
 
-        this.inputSampleRate = InputSampleRate;
-        this._lastSample = 0;
         this._lastFilteredOutput = 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.running = false;
-        this.maxQueueSizeSamples = samplesFor(MaxQueuedMs);
+        this._phase = 0;
+        this._source = new Float32Array(0);
+        this._rendered = new Float32Array(0);
+        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;
     }
 
+    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 });
     }
 
-    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;
+    _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));
     }
 
-    _shift() {
-        const dropped = this.queue.shift();
-        this._queueSizeSamples -= dropped.buffer.length;
+    _applyHead() {
+        this.chip.applyEvent(this.events[this.eventsHead++]);
     }
 
-    cleanQueue() {
-        const maxLatency = this.targetLatencyMs * 2;
-        while (this._queueSizeSamples > this.maxQueueSizeSamples || this._queueAge() > maxLatency) {
-            this._shift();
-            this.dropped++;
+    // 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;
+    }
+
+    _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;
+    }
+
+    _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, length) {
+        if (this.stalled) {
+            this._stall(out, 0, length);
+            return;
+        }
+        let offset = 0;
+        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;
-
-        // 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 outByMs = this._queueAge() - this.targetLatencyMs;
-        const maxAdjust = this.inputSampleRate * 0.01;
-        const adjustment = Math.min(maxAdjust, Math.max(-maxAdjust, outByMs * 100));
-        const effectiveSampleRate = this.inputSampleRate + adjustment;
-        const sampleRatio = effectiveSampleRate / sampleRate;
+        if (this.stalled && this.upTo - this.clock >= this.targetLeadCycles) this._restart();
 
         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);
 
-        const numInputSamples = Math.round(sampleRatio * channel.length);
-        const source = new Float32Array(numInputSamples);
+        // 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.
+        const end = this._phase + channel.length * sampleRatio;
+        const numInputSamples = Math.floor(end);
+        if (this._source.length <= numInputSamples) {
+            this._source = new Float32Array(numInputSamples * 2);
+            this._rendered = new Float32Array(numInputSamples * 2);
+        }
+        const source = this._source;
+        const rendered = this._rendered;
+        this._renderInput(rendered, numInputSamples);
+        source[0] = this._lastFilteredOutput;
         let prevSample = this._lastFilteredOutput;
-        for (let i = 0; i < numInputSamples; ++i) {
-            prevSample += filterAlpha * (this.nextSample() - prevSample);
+        for (let i = 1; i <= numInputSamples; ++i) {
+            prevSample += filterAlpha * (rendered[i - 1] - prevSample);
             source[i] = prevSample;
         }
         this._lastFilteredOutput = prevSample;
         for (let i = 0; i < channel.length; i++) {
-            const pos = (i + 0.5) * sampleRatio;
+            const pos = this._phase + i * sampleRatio;
             const loc = Math.floor(pos);
             const alpha = pos - loc;
             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;
     }