jsbeeb 1.20.2 → 1.21.0

package/README.md

@@ -289,11 +289,19 @@ sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
 - (mostly internal use) `logFdcCommands`, `logFdcStateChanges` - turn on logging in the disc controller.
 - `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.
+- `audioOutput` - what the sound chip is heard through: `speaker` (the default: the board's output stage and the
+  internal speaker and case, fitted to recordings of a Master 128), `board` (the board's output stage alone, as at
+  its line-level socket) or `off` (the chip resampled and nothing else). The top bar and the configuration dialog
+  have the same choice, and remember it. See [docs/audio-path.md](docs/audio-path.md) for the path, the Master's circuit and what a real
+  machine measures.
+- `speakerAmount` - how much of the speaker's character to apply, from 0 (the same as `board`) to 1 (as measured,
+  the default). The slider next to the sound output, on the top bar and in the configuration dialog, sets it live
+  and remembers it.
 - `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.
+  `audiofilterfreq=0` turns the whole output path 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)).
+  or `xbr` (an upscaler, see [docs/xbr-display-mode.md](docs/xbr-display-mode.md)). The top bar has the same choice, and remembers it.
 
 ### 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.20.2",
+  "version": "1.21.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/audio-output.js

@@ -0,0 +1,124 @@
+// The stages between the sound chip and the device, shared by the worklet and
+// by tools that replay the same path headlessly. Values and their sources are
+// in docs/audio-path.md.
+
+import { Biquad } from "./biquad.js";
+
+// 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 the resampler.
+export const OutputFilterHz = 7234;
+export const OutputFilterQ = 0.696;
+
+// The coupling capacitors after the filter, each a first-order high-pass:
+// C10 100nF into the LM386's 50K input, C79 330nF into 4K7 + 1K (Master only),
+// and C18 47uF into the 8 ohm speaker.
+export const BoardHighPassHz = [32, 85, 423];
+
+// The internal speaker and case, fitted to microphone captures of a Master 128
+// (the driver's resonance, a presence bump, and the roll-off above 6 kHz).
+export const SpeakerStages = [
+    { type: "highPass", frequency: 550, q: 1.56 },
+    { type: "peaking", frequency: 460, q: 3.5, gainDb: 16.5 },
+    { type: "peaking", frequency: 2750, q: 0.5, gainDb: 13.9 },
+    { type: "highShelf", frequency: 5600, q: 1.3, gainDb: -16.7 },
+    { type: "lowPass", frequency: 11700, q: 1.7 },
+];
+
+// The resampler's sinc is cut off below the output Nyquist so that its
+// transition band has finished before anything folds; sampled sound rides on
+// a 31 kHz or higher carrier that would otherwise land in the audible band.
+export const ResamplerCutoffOfOutputRate = 0.4;
+export const ResamplerTaps = 201;
+
+export const AudioOutputs = Object.freeze({
+    speaker: "speaker",
+    board: "board",
+    off: "off",
+});
+export const DefaultAudioOutput = AudioOutputs.speaker;
+
+export function isAudioOutput(value) {
+    return Object.values(AudioOutputs).includes(value);
+}
+
+const stageFactories = {
+    lowPass: (rate, s) => Biquad.lowPass(rate, s.frequency, s.q),
+    highPass: (rate, s) => Biquad.highPass(rate, s.frequency, s.q),
+    peaking: (rate, s) => Biquad.peaking(rate, s.frequency, s.q, s.gainDb),
+    highShelf: (rate, s) => Biquad.highShelf(rate, s.frequency, s.q, s.gainDb),
+};
+
+const GainProbeHz = [...Array(400).keys()].map((i) => 20 * 2 ** (i / 40));
+
+function chainMagnitude(stages, sampleRate, hz) {
+    return stages.reduce((gain, stage) => gain * stage.magnitudeAt(sampleRate, hz), 1);
+}
+
+const FlatQ = Math.SQRT1_2;
+const FlatHighPassHz = 20;
+const FlatLowPassHz = 20000;
+const lerp = (from, to, t) => from + (to - from) * t;
+const lerpLog = (from, to, t) => from * (to / from) ** t;
+
+// The fit scaled toward flat: gains shrink, the resonant Q falls to
+// Butterworth, and the band edges move out of the way.
+function scaledStage(stage, amount) {
+    switch (stage.type) {
+        case "peaking":
+        case "highShelf":
+            return { ...stage, gainDb: stage.gainDb * amount };
+        case "highPass":
+            return {
+                ...stage,
+                frequency: lerpLog(FlatHighPassHz, stage.frequency, amount),
+                q: lerp(FlatQ, stage.q, amount),
+            };
+        case "lowPass":
+            return {
+                ...stage,
+                frequency: lerpLog(FlatLowPassHz, stage.frequency, amount),
+                q: lerp(FlatQ, stage.q, amount),
+            };
+        default:
+            throw new Error(`Unknown stage type ${stage.type}`);
+    }
+}
+
+// The speaker's presence bump would push loud chords past full scale, so the
+// chain is scaled to peak at unity across the band.
+function speakerStages(sampleRate, amount) {
+    const stages = SpeakerStages.map((stage) => stageFactories[stage.type](sampleRate, scaledStage(stage, amount)));
+    const peak = Math.max(...GainProbeHz.map((hz) => chainMagnitude(stages, sampleRate, hz)));
+    return [...stages, Biquad.gain(1 / peak)];
+}
+
+// Zero turns the whole path off; a setting the biquad cannot realise
+// (non-finite, at or above Nyquist, non-positive Q) falls back to the board's
+// own values.
+function boardFilter(sampleRate, frequency = OutputFilterHz, q = OutputFilterQ) {
+    const usable = frequency < sampleRate / 2 && q > 0;
+    if (!usable) return Biquad.lowPass(sampleRate, OutputFilterHz, OutputFilterQ);
+    return Biquad.lowPass(sampleRate, frequency, q);
+}
+
+/**
+ * The filters to run on the chip's output, in order, for the chosen output.
+ *
+ * @param {number} sampleRate the chip's rate
+ * @param {string} output one of AudioOutputs
+ * @param {{filterHz?: number, filterQ?: number, speakerAmount?: number}} options overrides for the
+ *     board's low-pass, and how much of the speaker fit to apply (1 is the fit, 0 is flat)
+ * @returns {Biquad[]}
+ */
+export function outputStages(sampleRate, output, { filterHz, filterQ, speakerAmount = 1 } = {}) {
+    if (output === AudioOutputs.off || filterHz <= 0) return [];
+    const board = [
+        boardFilter(sampleRate, filterHz, filterQ),
+        ...BoardHighPassHz.map((hz) => Biquad.firstOrderHighPass(sampleRate, hz)),
+    ];
+    if (output === AudioOutputs.board) return board;
+    const amount = Number.isFinite(speakerAmount) ? Math.min(Math.max(speakerAmount, 0), 1) : 1;
+    return [...board, ...speakerStages(sampleRate, amount)];
+}

package/src/biquad.js

@@ -1,27 +1,100 @@
-// Coefficients from the RBJ Audio EQ Cookbook: the second-order prototype
+// Coefficients from the RBJ Audio EQ Cookbook: the second-order prototypes
 // 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;
+export class Biquad {
+    constructor(b0, b1, b2, a1, a2) {
+        this.b0 = b0;
+        this.b1 = b1;
+        this.b2 = b2;
+        this.a1 = a1;
+        this.a2 = a2;
         this.x1 = 0;
         this.x2 = 0;
         this.y1 = 0;
         this.y2 = 0;
     }
 
+    static _fromUnnormalised(b0, b1, b2, a0, a1, a2) {
+        return new Biquad(b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0);
+    }
+
+    static _prototype(sampleRate, frequency, q) {
+        const w0 = (2 * Math.PI * frequency) / sampleRate;
+        return { alpha: Math.sin(w0) / (2 * q), cosW0: Math.cos(w0) };
+    }
+
+    static lowPass(sampleRate, frequency, q) {
+        const { alpha, cosW0 } = Biquad._prototype(sampleRate, frequency, q);
+        return Biquad._fromUnnormalised((1 - cosW0) / 2, 1 - cosW0, (1 - cosW0) / 2, 1 + alpha, -2 * cosW0, 1 - alpha);
+    }
+
+    static highPass(sampleRate, frequency, q) {
+        const { alpha, cosW0 } = Biquad._prototype(sampleRate, frequency, q);
+        return Biquad._fromUnnormalised(
+            (1 + cosW0) / 2,
+            -(1 + cosW0),
+            (1 + cosW0) / 2,
+            1 + alpha,
+            -2 * cosW0,
+            1 - alpha,
+        );
+    }
+
+    /** A single RC high-pass: 6 dB per octave below the corner. */
+    static firstOrderHighPass(sampleRate, frequency) {
+        const k = Math.tan((Math.PI * frequency) / sampleRate);
+        return Biquad._fromUnnormalised(1, -1, 0, 1 + k, k - 1, 0);
+    }
+
+    static peaking(sampleRate, frequency, q, gainDb) {
+        const a = 10 ** (gainDb / 40);
+        const { alpha, cosW0 } = Biquad._prototype(sampleRate, frequency, q);
+        return Biquad._fromUnnormalised(
+            1 + alpha * a,
+            -2 * cosW0,
+            1 - alpha * a,
+            1 + alpha / a,
+            -2 * cosW0,
+            1 - alpha / a,
+        );
+    }
+
+    static highShelf(sampleRate, frequency, q, gainDb) {
+        const a = 10 ** (gainDb / 40);
+        const { alpha, cosW0 } = Biquad._prototype(sampleRate, frequency, q);
+        const root = 2 * Math.sqrt(a) * alpha;
+        return Biquad._fromUnnormalised(
+            a * (a + 1 + (a - 1) * cosW0 + root),
+            -2 * a * (a - 1 + (a + 1) * cosW0),
+            a * (a + 1 + (a - 1) * cosW0 - root),
+            a + 1 - (a - 1) * cosW0 + root,
+            2 * (a - 1 - (a + 1) * cosW0),
+            a + 1 - (a - 1) * cosW0 - root,
+        );
+    }
+
+    static gain(factor) {
+        return new Biquad(factor, 0, 0, 0, 0);
+    }
+
+    /** Magnitude response at `frequency`, as a linear factor. */
+    magnitudeAt(sampleRate, frequency) {
+        const w = (2 * Math.PI * frequency) / sampleRate;
+        const { b0, b1, b2, a1, a2 } = this;
+        const cos1 = Math.cos(w);
+        const sin1 = Math.sin(w);
+        const cos2 = Math.cos(2 * w);
+        const sin2 = Math.sin(2 * w);
+        const numerator = Math.hypot(b0 + b1 * cos1 + b2 * cos2, b1 * sin1 + b2 * sin2);
+        const denominator = Math.hypot(1 + a1 * cos1 + a2 * cos2, a1 * sin1 + a2 * sin2);
+        return numerator / denominator;
+    }
+
     process(buffer, offset, length) {
-        const { b0, b1, a1, a2 } = this;
+        const { b0, b1, b2, 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;
+            const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
             x2 = x1;
             x1 = x;
             y2 = y1;

package/src/config.js

@@ -1,6 +1,7 @@
 "use strict";
 import { allModels, findModel, tubeModelFor } from "./models.js";
 import { getFilterForMode } from "./canvas.js";
+import { AudioOutputs } from "./audio-output.js";
 
 const round = (value) => Number(value.toFixed(2));
 
@@ -128,7 +129,8 @@ export class Config extends EventTarget {
 
         for (const link of document.querySelectorAll(".keyboard-menu a")) {
             link.addEventListener("click", (e) => {
-                const keyLayout = e.target.dataset.target;
+                e.preventDefault();
+                const keyLayout = e.currentTarget.dataset.target;
                 this.changed.keyLayout = keyLayout;
                 this.setKeyLayout(keyLayout);
             });
@@ -136,16 +138,31 @@ export class Config extends EventTarget {
 
         for (const option of document.querySelectorAll(".mic-channel-option")) {
             option.addEventListener("click", (e) => {
-                const channelString = e.target.dataset.channel;
+                e.preventDefault();
+                const channelString = e.currentTarget.dataset.channel;
                 const channel = channelString === "" ? undefined : parseInt(channelString, 10);
                 this.changed.microphoneChannel = channel;
                 this.setMicrophoneChannel(channel);
             });
         }
 
+        for (const option of document.querySelectorAll(".audio-output-option")) {
+            option.addEventListener("click", (e) => {
+                e.preventDefault();
+                const audioOutput = e.currentTarget.dataset.output;
+                this.changed.audioOutput = audioOutput;
+                this.onChange({ audioOutput });
+            });
+        }
+
+        document.getElementById("speakerAmountSetting").addEventListener("input", (e) => {
+            this.onChange({ speakerAmount: parseFloat(e.currentTarget.value) });
+        });
+
         for (const option of document.querySelectorAll(".display-mode-option")) {
             option.addEventListener("click", (e) => {
-                const mode = e.target.dataset.mode;
+                e.preventDefault();
+                const mode = e.currentTarget.dataset.mode;
                 this.changed.displayMode = mode;
                 this.setDisplayMode(mode);
                 this.onChange({ displayMode: mode });
@@ -178,6 +195,14 @@ export class Config extends EventTarget {
         }
     }
 
+    setAudioOutput(audioOutput) {
+        const option = document.querySelector(`.audio-output-option[data-output="${audioOutput}"]`);
+        for (const el of document.querySelectorAll(".audio-output-text")) el.textContent = option.textContent;
+        document.getElementById("speakerAmountSetting").disabled = audioOutput !== AudioOutputs.speaker;
+    }
+    setSpeakerAmount(speakerAmount) {
+        document.getElementById("speakerAmountSetting").value = speakerAmount;
+    }
     setMicrophoneChannel(channel) {
         const text = channel !== undefined ? `Channel ${channel}` : "Disabled";
         for (const el of document.querySelectorAll(".mic-channel-text")) el.textContent = text;

package/src/main.js

@@ -23,6 +23,8 @@ import { Config } from "./config.js";
 import { DefaultModel, findModel, tubeModelFor } from "./models.js";
 import { initialise as electron } from "./app/electron.js";
 import { AudioHandler } from "./web/audio-handler.js";
+import { DefaultAudioOutput, isAudioOutput } from "./audio-output.js";
+import { QuickSettings } from "./web/quick-settings.js";
 import { Econet } from "./econet.js";
 import { DiscLayout, toSsdOrDsd } from "./disc.js";
 import { toHfe } from "./disc-hfe.js";
@@ -143,6 +145,7 @@ const paramTypes = {
     mouseJoystickEnabled: ParamTypes.BOOL,
     speechOutput: ParamTypes.BOOL,
     audioDebug: ParamTypes.BOOL,
+    audioOutput: ParamTypes.STRING,
 
     // Numeric parameters
     speed: ParamTypes.INT,
@@ -150,6 +153,7 @@ const paramTypes = {
     frameSkip: ParamTypes.INT,
     audiofilterfreq: ParamTypes.FLOAT,
     audiofilterq: ParamTypes.FLOAT,
+    speakerAmount: ParamTypes.FLOAT,
     audioLatencyMs: ParamTypes.FLOAT,
     cpuMultiplier: ParamTypes.FLOAT,
     tubeCpuMultiplier: ParamTypes.FLOAT,
@@ -248,14 +252,9 @@ setSpeechOutput(!!parsedQuery.speechOutput);
 
 const config = new Config(
     function onChange(changed) {
-        if (changed.displayMode) {
-            // swapCanvas settles displayModeFilter on whatever was really
-            // built, so take the picture from that rather than the request.
-            swapCanvas(getFilterForMode(changed.displayMode));
-            setCrtPic(displayModeFilter);
-            // Trigger window resize to recalculate layout with new dimensions
-            window.dispatchEvent(new Event("resize"));
-        }
+        if (changed.audioOutput) applyAudioOutput(changed.audioOutput);
+        if (changed.speakerAmount !== undefined) applySpeakerAmount(changed.speakerAmount);
+        if (changed.displayMode) applyDisplayMode(changed.displayMode);
     },
     function onClose(changed) {
         parsedQuery = Object.assign(parsedQuery, changed);
@@ -314,8 +313,41 @@ config.setCheckboxes({
     mouseJoystickEnabled: !!parsedQuery.mouseJoystickEnabled,
     speechOutput: speechOutput.enabled,
 });
-let displayMode = parsedQuery.displayMode || "rgb";
+const displayMode = parsedQuery.displayMode || window.localStorage.displayMode || "rgb";
 config.setDisplayMode(displayMode);
+const audioOutput =
+    [parsedQuery.audioOutput, window.localStorage.audioOutput].find(isAudioOutput) ?? DefaultAudioOutput;
+const speakerAmount =
+    [parsedQuery.speakerAmount, parseFloat(window.localStorage.speakerAmount)].find(Number.isFinite) ?? 1;
+
+config.setAudioOutput(audioOutput);
+config.setSpeakerAmount(speakerAmount);
+
+function applyAudioOutput(output) {
+    audioHandler.setAudioOutput(output);
+    config.setAudioOutput(output);
+    quickSettings?.showAudioOutput(output);
+    window.localStorage.audioOutput = output;
+}
+
+function applySpeakerAmount(amount) {
+    audioHandler.setSpeakerAmount(amount);
+    config.setSpeakerAmount(amount);
+    quickSettings?.showSpeakerAmount(amount);
+    window.localStorage.speakerAmount = amount;
+}
+
+function applyDisplayMode(mode) {
+    // swapCanvas settles displayModeFilter on whatever was really
+    // built, so take the picture from that rather than the request.
+    swapCanvas(getFilterForMode(mode));
+    setCrtPic(displayModeFilter);
+    // Trigger window resize to recalculate layout with new dimensions
+    window.dispatchEvent(new Event("resize"));
+    config.setDisplayMode(mode);
+    quickSettings?.showDisplayMode(mode);
+    window.localStorage.displayMode = mode;
+}
 
 model = config.model;
 
@@ -535,7 +567,7 @@ function createCanvasForFilter(filterClass) {
     return newCanvas;
 }
 
-let displayModeFilter = canvasLib.getFilterForMode(parsedQuery.displayMode || "rgb");
+let displayModeFilter = canvasLib.getFilterForMode(displayMode);
 function swapCanvas(newFilterClass) {
     // Everything but the filter is the same whatever the mode: the framebuffer
     // texture, the vertex buffers and fb32 all carry over untouched.
@@ -616,8 +648,10 @@ const audioStatsNode = parsedQuery.audioDebug ? audioStatsEl : null;
 const audioHandler = new AudioHandler({
     warningNode: document.getElementById("audio-warning"),
     statsNode: audioStatsNode,
+    audioOutput,
     audioFilterFreq: parsedQuery.audiofilterfreq,
     audioFilterQ: parsedQuery.audiofilterq,
+    speakerAmount,
     audioLatencyMs: parsedQuery.audioLatencyMs,
     noSeek,
     cpuSpeed,
@@ -628,6 +662,10 @@ const audioHandler = new AudioHandler({
 // start playing without user interaction, so we need to delay a
 // little to get a reliable indication.
 window.setTimeout(() => audioHandler.checkStatus(), 1000);
+const quickSettings = new QuickSettings(
+    { onAudioOutput: applyAudioOutput, onSpeakerAmount: applySpeakerAmount, onDisplayMode: applyDisplayMode },
+    { audioOutput, speakerAmount, displayMode },
+);
 
 for (const el of document.querySelectorAll(".initially-hidden")) el.classList.remove("initially-hidden");
 

package/src/soundchip.js

@@ -101,30 +101,34 @@ export class SoundChip {
             mute: () => {
                 this.catchUp();
                 this.sineOn = false;
-                this._emit({ sine: 0 });
+                this._emit("sine", 0);
             },
             tone: (freq) => {
                 this.catchUp();
                 this.sineOn = true;
                 this.sineStep = (freq / sampleRate) * this.sineTable.length;
-                this._emit({ sine: freq });
+                this._emit("sine", freq);
             },
         };
+
+        this.eventHandlers = {
+            progress: () => {},
+            poke: (value) => this.poke(value),
+            sine: (freq) => (freq ? this.toneGenerator.tone(freq) : this.toneGenerator.mute()),
+            state: (state) => this.restoreState(state),
+            reset: (hard) => this.reset(hard),
+        };
     }
 
-    _emit(event) {
-        if (this._onEvent) this._onEvent({ cycle: this.scheduler.epoch, ...event });
+    _emit(kind, value) {
+        if (this._onEvent) this._onEvent({ cycle: this.scheduler.epoch, kind, value });
     }
 
     /** 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);
+        const handler = this.eventHandlers[event.kind];
+        if (!handler) throw new Error(`Unknown sound event ${event.kind}`);
+        handler(event.value, event);
     }
 
     /** Renders `length` samples of output from `cycle`, for a chip that is driven by events. */
@@ -214,7 +218,7 @@ export class SoundChip {
         this.volume[2] = volumeTable[v2];
         this.volume[3] = volumeTable[v3];
         this.noisePoked();
-        this._emit({ state: this.snapshotState() });
+        this._emit("state", this.snapshotState());
     }
 
     generate(out, offset, length) {
@@ -255,7 +259,7 @@ export class SoundChip {
         });
         if (this._onEvent) {
             this.progressTask = this.scheduler.newTask(() => {
-                this._emit({ progress: true });
+                this._emit("progress", true);
                 this.progressTask.schedule(EventProgressCycles);
             });
             this.progressTask.schedule(EventProgressCycles);
@@ -312,7 +316,7 @@ export class SoundChip {
 
     poke(value) {
         this.catchUp();
-        this._emit({ poke: value });
+        this._emit("poke", value);
 
         let command;
         if (value & 0x80) {
@@ -394,12 +398,12 @@ export class SoundChip {
         this.dcPrevIn = state.dcPrevIn ?? 0;
         this.dcPrevOut = state.dcPrevOut ?? 0;
         this.progressTask?.ensureScheduled(true, EventProgressCycles);
-        this._emit({ state: this.snapshotState() });
+        this._emit("state", this.snapshotState());
     }
 
     reset(hard) {
         if (!hard) return;
-        this._emit({ reset: true });
+        this._emit("reset", true);
         for (let i = 0; i < 4; ++i) {
             this.counter[i] = 0;
             this.registers[i] = 0;
@@ -412,7 +416,6 @@ export class SoundChip {
 
     enable(e) {
         this.enabled = e;
-        this._emit({ enabled: e });
     }
 
     mute() {
@@ -457,6 +460,11 @@ export class AtomSoundChip extends SoundChip {
         this._speakerPrevIn = 0;
         this._speakerPrevOut = 0;
         this._speakerCycleOffset = 0;
+
+        Object.assign(this.eventHandlers, {
+            bit: (bit, { cycle }) => this.bitChange.push({ bit, cycles: cycle }),
+            speakerReset: () => this.speakerReset(),
+        });
     }
 
     reset(hard) {
@@ -470,19 +478,13 @@ 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._emit("speakerReset", true);
         this.bitChange = [];
         this.currentSpeakerBit = 0.0;
         this._speakerPrevIn = 0;
@@ -521,7 +523,7 @@ export class AtomSoundChip extends SoundChip {
     updateSpeaker(value, microCycle, seconds) {
         const cycles = microCycle + seconds / this.secondsPerCycle;
         const bit = value ? 1.0 : 0.0;
-        if (this._onEvent) this._onEvent({ cycle: cycles, bit });
+        if (this._onEvent) this._onEvent({ cycle: cycles, kind: "bit", value: bit });
         else this.bitChange.push({ bit, cycles });
     }
 }

package/src/web/audio-handler.js

@@ -21,8 +21,10 @@ export class AudioHandler {
     constructor({
         warningNode,
         statsNode,
+        audioOutput,
         audioFilterFreq,
         audioFilterQ,
+        speakerAmount,
         audioLatencyMs,
         noSeek,
         cpuSpeed,
@@ -51,7 +53,7 @@ export class AudioHandler {
         if (this.audioContext && this.audioContext.audioWorklet) {
             this.audioContext.onstatechange = () => this.checkStatus();
             const onEvent = (event) => {
-                if (event.progress) this.flushChipEvents();
+                if (event.kind === "progress") this.flushChipEvents();
                 else this._chipEvents.push(event);
             };
             this.soundChip = this.isAtom
@@ -62,7 +64,9 @@ export class AudioHandler {
             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({ audioOutput, audioFilterFreq, audioFilterQ, speakerAmount }).catch((error) =>
+                this._audioUnavailable(error),
+            );
         } else {
             if (this.audioContext && !this.audioContext.audioWorklet) {
                 this.audioContext = null;
@@ -127,18 +131,21 @@ export class AudioHandler {
         this.chart.streamTo(statsNode, 100);
     }
 
-    async _setup({ audioFilterFreq, audioFilterQ }) {
+    async _setup({ audioOutput, audioFilterFreq, audioFilterQ, speakerAmount }) {
         await this.audioContext.audioWorklet.addModule(rendererUrl);
         this._jsAudioNode = new AudioWorkletNode(this.audioContext, "sound-chip-processor", {
             processorOptions: {
                 targetLatencyMs: this._targetLatencyMs(),
                 isAtom: this.isAtom,
                 cpuSpeed: this.cpuSpeed,
+                audioOutput,
                 audioFilterFreq,
                 audioFilterQ,
+                speakerAmount,
             },
         });
         this._jsAudioNode.connect(this.audioContext.destination);
+        if (!this.soundChip.enabled) this._setEnabled(false);
         this._jsAudioNode.port.onmessage = (event) => {
             const now = Date.now();
             if (event.data.event) {
@@ -165,6 +172,18 @@ export class AudioHandler {
         return this.windowFocused ? this.audioLatencyMs : UnfocusedLatencyMs;
     }
 
+    _setEnabled(enabled) {
+        this._jsAudioNode?.port.postMessage({ command: "setEnabled", enabled });
+    }
+
+    setAudioOutput(audioOutput) {
+        this._jsAudioNode?.port.postMessage({ command: "setAudioOutput", audioOutput });
+    }
+
+    setSpeakerAmount(speakerAmount) {
+        this._jsAudioNode?.port.postMessage({ command: "setSpeakerAmount", speakerAmount });
+    }
+
     // Returns how far ahead of the sound the picture should now run, in ms.
     setWindowFocused(focused) {
         this.windowFocused = focused;
@@ -197,7 +216,11 @@ export class AudioHandler {
     // 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._jsAudioNode.port.postMessage({
+            command: "produced",
+            upTo: this.soundChip.scheduler.epoch,
+            events: this._chipEvents,
+        });
         this._chipEvents = [];
     }
 
@@ -231,15 +254,17 @@ export class AudioHandler {
         await this.relayNoise.initialise();
     }
 
-    // The emulator is stopping, so no tick will ship the change; send it now.
+    // The emulator is stopping, so no tick will ship its last writes; send them now.
     mute() {
         this.soundChip.mute();
+        this._setEnabled(false);
         this.flushChipEvents();
         if (this.masterGain) this.masterGain.gain.value = 0;
     }
 
     unmute() {
         this.soundChip.unmute();
+        this._setEnabled(true);
         this.flushChipEvents();
         if (this.masterGain) this.masterGain.gain.value = 1;
     }

package/src/web/audio-renderer.js

@@ -1,20 +1,13 @@
 /* global sampleRate, currentTime, registerProcessor, AudioWorkletProcessor */
 import { SoundChip, AtomSoundChip } from "../soundchip.js";
-import { LowPassBiquad } from "../biquad.js";
 import { PolyphaseResampler } from "../resampler.js";
-
-// 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 the resampler.
-const OutputFilterHz = 7234;
-const OutputFilterQ = 0.696;
-
-// The resampler's sinc is cut off below the output Nyquist so that its
-// transition band has finished before anything folds; sampled sound rides on
-// a 31 kHz or higher carrier that would otherwise land in the audible band.
-const ResamplerCutoffOfOutputRate = 0.4;
-const ResamplerTaps = 201;
+import {
+    AudioOutputs,
+    DefaultAudioOutput,
+    ResamplerCutoffOfOutputRate,
+    ResamplerTaps,
+    outputStages,
+} from "../audio-output.js";
 
 const DefaultTargetLatencyMs = 1000 * (1 / 50); // One frame
 const MaxTargetLatencyMs = 250;
@@ -26,7 +19,8 @@ const LeadSmoothingTau = 0.5;
 const ProportionalGain = 0.2;
 const MaxAdjustFraction = 0.0005;
 
-const isResync = (event) => event.state !== undefined || event.reset !== undefined;
+const ResyncKinds = new Set(["state", "reset"]);
+const isResync = (event) => ResyncKinds.has(event.kind);
 
 // Renders the chip from its timestamped state changes, so a producer that
 // falls behind leaves the chip sounding its current state (a stall) rather
@@ -38,13 +32,16 @@ class SoundChipProcessor extends AudioWorkletProcessor {
             isAtom = false,
             cpuSpeed = 1000000,
             targetLatencyMs,
+            audioOutput = DefaultAudioOutput,
             audioFilterFreq,
             audioFilterQ,
+            speakerAmount,
         } = 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.boardFilter = { filterHz: audioFilterFreq, filterQ: audioFilterQ, speakerAmount };
+        this.setAudioOutput(audioOutput);
         this.resampler = new PolyphaseResampler(this.inputSampleRate, ResamplerCutoffOfOutputRate * sampleRate, {
             taps: ResamplerTaps,
         });
@@ -61,20 +58,32 @@ class SoundChipProcessor extends AudioWorkletProcessor {
         this._phase = 0;
         this.smoothedLeadError = 0;
         this.setTargetLatency(targetLatencyMs);
-        this.port.onmessage = (event) => {
-            if (event.data.command === "setTargetLatency") this.setTargetLatency(event.data.targetLatencyMs);
-            else this.onProduced(event.data.upTo, event.data.events);
+        this.commands = {
+            produced: (m) => this.onProduced(m.upTo, m.events),
+            setEnabled: (m) => (this.chip.enabled = m.enabled),
+            setTargetLatency: (m) => this.setTargetLatency(m.targetLatencyMs),
+            setAudioOutput: (m) => this.setAudioOutput(m.audioOutput),
+            setSpeakerAmount: (m) => this.setSpeakerAmount(m.speakerAmount),
         };
+        this.port.onmessage = (event) => this.onMessage(event.data);
         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);
+    onMessage(message) {
+        const command = this.commands[message.command];
+        if (!command) throw new Error(`Unknown sound command ${message.command}`);
+        command(message);
+    }
+
+    setAudioOutput(audioOutput) {
+        this.audioOutput = audioOutput;
+        this.outputFilters = outputStages(this.inputSampleRate, audioOutput, this.boardFilter);
+    }
+
+    setSpeakerAmount(speakerAmount) {
+        if (speakerAmount === this.boardFilter.speakerAmount) return;
+        this.boardFilter.speakerAmount = speakerAmount;
+        if (this.audioOutput === AudioOutputs.speaker) this.setAudioOutput(this.audioOutput);
     }
 
     setTargetLatency(ms) {
@@ -224,7 +233,8 @@ class SoundChipProcessor extends AudioWorkletProcessor {
         const resampler = this.resampler;
         resampler.reserve(numInputSamples);
         this._renderInput(resampler.buffer, resampler.inputOffset, numInputSamples);
-        this.outputFilter?.process(resampler.buffer, resampler.inputOffset, numInputSamples);
+        for (const filter of this.outputFilters)
+            filter.process(resampler.buffer, resampler.inputOffset, numInputSamples);
         resampler.read(channel, this._phase, sampleRatio);
         resampler.commit();
         this._phase = end - numInputSamples;

package/src/web/quick-settings.js

@@ -0,0 +1,51 @@
+import { AudioOutputs } from "../audio-output.js";
+
+/**
+ * The sound output, speaker amount and display mode controls on the top bar.
+ * Choices go to the callbacks; what is shown follows the show methods, so the
+ * bar can be kept in step with the same settings elsewhere.
+ */
+export class QuickSettings {
+    constructor({ onAudioOutput, onSpeakerAmount, onDisplayMode }, { audioOutput, speakerAmount, displayMode }) {
+        this.output = document.getElementById("audio-output");
+        this.amount = document.getElementById("speaker-amount");
+        this.display = document.getElementById("display-mode");
+        if (!this.output || !this.amount || !this.display) return;
+
+        this.showAudioOutput(audioOutput);
+        this.showSpeakerAmount(speakerAmount);
+        this.showDisplayMode(displayMode);
+
+        this.output.addEventListener("click", (e) => {
+            const value = e.target.closest("[data-output]")?.dataset.output;
+            if (value) onAudioOutput(value);
+        });
+        this.amount.addEventListener("input", () => onSpeakerAmount(parseFloat(this.amount.value)));
+        this.display.addEventListener("click", (e) => {
+            const mode = e.target.closest("[data-mode]")?.dataset.mode;
+            if (mode) onDisplayMode(mode);
+        });
+    }
+
+    showAudioOutput(audioOutput) {
+        if (!this.output) return;
+        select(this.output.querySelectorAll("[data-output]"), (b) => b.dataset.output === audioOutput);
+        this.amount.disabled = audioOutput !== AudioOutputs.speaker;
+    }
+
+    showSpeakerAmount(speakerAmount) {
+        if (this.amount) this.amount.value = speakerAmount;
+    }
+
+    showDisplayMode(mode) {
+        if (this.display) select(this.display.querySelectorAll("[data-mode]"), (b) => b.dataset.mode === mode);
+    }
+}
+
+function select(buttons, isChosen) {
+    for (const button of buttons) {
+        const chosen = isChosen(button);
+        button.classList.toggle("active", chosen);
+        button.setAttribute("aria-pressed", chosen);
+    }
+}