jsbeeb 1.19.3 → 1.20.1

package/README.md

@@ -287,7 +287,13 @@ 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.
+- `audiofilterfreq` / `audiofilterq` - the corner frequency in Hz and the Q of the lowpass modelling the board's output
+  filter, applied to the sound chip before it is resampled. The defaults, 7234 and 0.696, are the Beeb's own.
+  `audiofilterfreq=0` turns the filter off.
+- `displayMode=X` - picks the display: `rgb` (the default, a plain monitor), `pal` (a television fed by the Beeb's UHF modulator)
+  or `xbr` (an upscaler, see [docs/xbr-display-mode.md](docs/xbr-display-mode.md)).
 
 ### 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.3",
+  "version": "1.20.1",
   "//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/acia.js

@@ -4,8 +4,9 @@
 // https://books.google.com/books?id=wUecAQAAQBAJ&pg=PA431&lpg=PA431&dq=acia+tdre&source=bl&ots=mp-yF-mK-P&sig=e6aXkFRfiIOb57WZmrvdIGsCooI&hl=en&sa=X&ei=0g2fVdDyFIXT-QG8-JD4BA&ved=0CCwQ6AEwAw#v=onepage&q=acia%20tdre&f=false
 // http://www.classiccmp.org/dunfield/r/6850.pdf
 
-export class Acia {
+export class Acia extends EventTarget {
     constructor(cpu, toneGen, scheduler, relayNoise) {
+        super();
         this.cpu = cpu;
         this.toneGen = toneGen;
         this.rs423Handler = null;
@@ -20,6 +21,7 @@ export class Acia {
         this.tapeCarrierCount = 0;
         this.tapeDcdLineLevel = false;
         this.hadDcdHigh = false;
+        this.saidOverrun = false;
         this.serialReceiveRate = 0;
         this.serialReceiveCyclesPerByte = 0;
         this.serialTransmitRate = 0;
@@ -200,8 +202,8 @@ export class Acia {
             // TODO: this doesn't match the datasheet:
             // "The Overrun does not occur in the Status Register until the
             // valid character prior to Overrun has been read."
-            console.log("Serial overrun");
             this.sr |= 0xa0;
+            this.noteOverrun();
         } else {
             // If bit 7 contains parity, mask it off.
             this.dr = byte & (this.cr & 0x10 ? 0xff : 0x7f);
@@ -210,6 +212,22 @@ export class Acia {
         this.updateIrq();
     }
 
+    noteOverrun() {
+        if (this.saidOverrun) return;
+        this.saidOverrun = true;
+        this.dispatchEvent(
+            new CustomEvent("notice", {
+                detail: {
+                    message:
+                        "A serial byte arrived before the previous one was read, so it was lost. " +
+                        "A tape load that stops with Data? is usually this.",
+                    title: "Serial",
+                    quietKey: "quietSerialOverrun",
+                },
+            }),
+        );
+    }
+
     snapshotState() {
         const scheduler = this.txCompleteTask.scheduler;
         return {

package/src/biquad.js

@@ -0,0 +1,36 @@
+// Coefficients from the RBJ Audio EQ Cookbook: the second-order prototype
+// under a bilinear transform prewarped so the corner lands on `frequency`.
+export class LowPassBiquad {
+    constructor(sampleRate, frequency, q) {
+        const w0 = (2 * Math.PI * frequency) / sampleRate;
+        const alpha = Math.sin(w0) / (2 * q);
+        const cosW0 = Math.cos(w0);
+        const a0 = 1 + alpha;
+        this.b0 = (1 - cosW0) / (2 * a0);
+        this.b1 = (1 - cosW0) / a0;
+        this.a1 = (-2 * cosW0) / a0;
+        this.a2 = (1 - alpha) / a0;
+        this.x1 = 0;
+        this.x2 = 0;
+        this.y1 = 0;
+        this.y2 = 0;
+    }
+
+    process(buffer, offset, length) {
+        const { b0, b1, a1, a2 } = this;
+        let { x1, x2, y1, y2 } = this;
+        for (let i = offset; i < offset + length; ++i) {
+            const x = buffer[i];
+            const y = b0 * x + b1 * x1 + b0 * x2 - a1 * y1 - a2 * y2;
+            x2 = x1;
+            x1 = x;
+            y2 = y1;
+            y1 = y;
+            buffer[i] = y;
+        }
+        this.x1 = x1;
+        this.x2 = x2;
+        this.y1 = y1;
+        this.y2 = y2;
+    }
+}

package/src/canvas.js

@@ -240,7 +240,8 @@ export class GlCanvas {
         this.filter.setUniforms({
             width,
             height,
-            frameCount: frame.frameCount,
+            lineBaseEven: frame.lineBaseEven,
+            lineBaseOdd: frame.lineBaseOdd,
             lineGrid: frame.lineGrid,
             // How much of the framebuffer each output pixel covers, which sets
             // how wide an edge-smoothing ramp should be. `extent` holds texel

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

@@ -89,6 +89,11 @@ function stringToMachineKeys(text) {
 }
 
 const gamepad = new GamePad();
+if (!window.isSecureContext)
+    toast("Gamepads only work over https, so any joystick plugged in here is not seen.", {
+        title: "Gamepads",
+        quietKey: "quietInsecureGamepads",
+    });
 const availableImages = [
     {
         name: "Elite",
@@ -145,6 +150,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,12 +180,6 @@ const cpuMultiplier = parsedQuery.cpuMultiplier ?? 1;
 let fastAsPossible = false;
 let fastTape = false;
 let noSeek;
-// 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;
 
@@ -208,8 +208,6 @@ if (parsedQuery.embed) {
 fastTape = !!parsedQuery.fasttape;
 noSeek = !!parsedQuery.noseek;
 
-if (parsedQuery.audiofilterfreq !== undefined) audioFilterFreq = parsedQuery.audiofilterfreq;
-if (parsedQuery.audiofilterq !== undefined) audioFilterQ = parsedQuery.audiofilterq;
 if (parsedQuery.stationId !== undefined) stationId = parsedQuery.stationId;
 if (parsedQuery.frameSkip !== undefined) frameSkip = parsedQuery.frameSkip;
 
@@ -238,7 +236,15 @@ const userPort = {
 // Speech output: initialised from URL param; can be toggled at runtime via the Settings panel.
 // Must be created before Config so the onClose callback and the initial checkbox state can reference it.
 const speechOutput = new SpeechOutput();
-speechOutput.enabled = !!parsedQuery.speechOutput;
+
+function setSpeechOutput(enabled) {
+    speechOutput.enabled = enabled;
+    if (enabled && typeof speechSynthesis === "undefined")
+        toast("This browser has no speech synthesis, so speech output has nothing to speak with.", {
+            title: "Speech",
+        });
+}
+setSpeechOutput(!!parsedQuery.speechOutput);
 
 const config = new Config(
     function onChange(changed) {
@@ -265,9 +271,7 @@ const config = new Config(
                 setupMicrophone();
             }
         }
-        if (changed.speechOutput !== undefined) {
-            speechOutput.enabled = !!changed.speechOutput;
-        }
+        if (changed.speechOutput !== undefined) setSpeechOutput(!!changed.speechOutput);
         if (changed.tubeCpuMultiplier !== undefined) {
             emulationConfig.tubeCpuMultiplier = changed.tubeCpuMultiplier;
             config.setTubeCpuMultiplier(changed.tubeCpuMultiplier);
@@ -372,7 +376,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) {
@@ -552,14 +556,55 @@ 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,
+    lineBaseEven: 0,
+    lineBaseOdd: 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,
+            lineBaseEven: this.lineBaseEven,
+            lineBaseOdd: this.lineBaseOdd,
+        });
+        paintMsThisTick += performance.now() - start;
+        if (!presentScheduled) {
+            presentScheduled = true;
+            window.requestAnimationFrame(present);
+        }
     },
     { isAtom: model.isAtom },
 );
@@ -571,11 +616,13 @@ const audioStatsNode = parsedQuery.audioDebug ? audioStatsEl : null;
 const audioHandler = new AudioHandler({
     warningNode: document.getElementById("audio-warning"),
     statsNode: audioStatsNode,
-    audioFilterFreq,
-    audioFilterQ,
+    audioFilterFreq: parsedQuery.audiofilterfreq,
+    audioFilterQ: parsedQuery.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
@@ -675,8 +722,10 @@ pastetext.addEventListener("drop", async function (event) {
         } else if (file.name.toLowerCase().endsWith(".uef")) {
             // Regular UEF tape image (not a BeebEm save state)
             setProcessorTape(await loadTapeFromData(file.name, new Uint8Array(arrayBuffer), model));
+            toast(`Loaded ${file.name} as the tape.`, { title: "Dropped" });
         } else {
             await loadHTMLFile(file);
+            toast(`Loaded ${file.name} into drive 0.`, { title: "Dropped" });
         }
     } catch (error) {
         reportLoadFailure(file.name, error);
@@ -724,12 +773,23 @@ 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();
-    event.preventDefault();
-});
+const fullscreenItem = document.getElementById("fs");
+if (document.fullscreenEnabled) {
+    fullscreenItem.addEventListener("click", async (event) => {
+        event.preventDefault();
+        try {
+            await screenCanvas.requestFullscreen();
+        } catch (error) {
+            toast(`Could not go fullscreen: ${errorText(error)}`, { title: "Fullscreen" });
+        }
+    });
+} else {
+    fullscreenItem.closest("li").hidden = true;
+}
 
 let keyboard; // This will be initialised after the processor is created
 
@@ -817,6 +877,7 @@ processor = new CpuClass(model, {
 printer.attach(processor.uservia);
 
 processor.teletextAdaptor?.addEventListener("notice", showNotice);
+processor.acia.addEventListener("notice", showNotice);
 
 // Create input sources
 const gamepadSource = new GamepadSource(emulationConfig.getGamepads);
@@ -1661,12 +1722,6 @@ document.querySelector("#google-drive-auth form").addEventListener("submit", asy
 });
 
 async function gdLoad(cat, layout) {
-    // TODO: have a onclose flush event, handle errors
-    /*
-     $(window).bind("beforeunload", function() {
-     return confirm("Do you really want to close?");
-     });
-     */
     popupLoading("Loading '" + cat.name + "' from Google Drive");
     try {
         const available = await googleDrive.initialise();
@@ -1687,6 +1742,12 @@ async function gdLoad(cat, layout) {
         const ssd = await googleDrive.load(processor.fdc, cat.id, layout);
         console.log("Google Drive loading finished");
         loadingFinished();
+        if (!ssd.savesChanges) {
+            toast(`${cat.name} is read only on Google Drive, so changes to it are not written back.`, {
+                title: "Google Drive",
+                quietKey: "quietDriveReadOnly",
+            });
+        }
         return ssd;
     } catch (error) {
         console.error("Google Drive loading error:", error);
@@ -1694,20 +1755,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();
@@ -2248,6 +2305,7 @@ function profileVideo(arg) {
 }
 
 let last = 0;
+let lastEnd = 0;
 
 function VirtualSpeedUpdater() {
     this.cycles = 0;
@@ -2281,8 +2339,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,
@@ -2315,21 +2416,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
@@ -2338,25 +2449,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;
         }
@@ -2365,14 +2467,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);
@@ -2383,11 +2491,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;