@williamzujkowski/live-coding-music-mcp 4.0.0 → 4.1.0

package/dist/AudioAnalyzer.js

@@ -1,14 +1,232 @@
+import { Logger } from './utils/Logger.js';
+const DEFAULT_FFT_SIZE = 1024;
+const DEFAULT_SMOOTHING = 0.8;
+const MIN_FFT_SIZE = 32;
+const MAX_FFT_SIZE = 32768;
+/**
+ * True if `n` is a power of two within the Web Audio AnalyserNode range
+ * (32-32768). Web Audio rejects anything else with an InvalidStateError.
+ */
+function isValidFftSize(n) {
+    return (typeof n === 'number' &&
+        Number.isInteger(n) &&
+        n >= MIN_FFT_SIZE &&
+        n <= MAX_FFT_SIZE &&
+        (n & (n - 1)) === 0);
+}
+/** Timestamps, whichever shape was passed. */
+export function onsetTimes(onsets) {
+    return onsets.map(onset => (typeof onset === 'number' ? onset : onset.t));
+}
+/** Strengths, or an empty array when the caller had none to give. */
+function onsetStrengths(onsets) {
+    if (onsets.length === 0 || typeof onsets[0] === 'number')
+        return [];
+    return onsets.map(onset => onset.strength);
+}
 export class AudioAnalyzer {
     _analysisCache = null;
     _cacheTimestamp = 0;
     ANALYSIS_CACHE_TTL = 50; // milliseconds
     // Advanced analysis tracking
+    /**
+     * Detected onsets, with the flux that produced each one (#352). Bare
+     * timestamps would throw away the only signal that distinguishes a
+     * kick from a hi-hat.
+     */
     _onsetHistory = [];
+    /**
+     * The tempo we have committed to, and the one still on probation.
+     *
+     * `detectTempo` used to answer from scratch every poll, so the answer
+     * moved while the onset window filled. Measured on unchanging audio:
+     * the amen break read 167, 83, 83, 83 across four polls, and
+     * `gen/intelligent_dnb` read 130, 130, 86, 130 (#374, #501).
+     *
+     * At most one of 167 and 83 is a measurement. The other is an
+     * artifact of how much history had accumulated — and a caller has no
+     * way to tell which poll it is holding.
+     *
+     * So a reading has to be seen twice, from two different windows,
+     * before it is reported; and once reported it is not displaced until
+     * some other reading has cleared the same bar. Cleared by
+     * `resetTempoHistory`, which is the pattern-change boundary.
+     */
+    _confirmedTempo = null;
+    _unconfirmedBpm = null;
+    /**
+     * What the onsets looked like at the previous poll.
+     *
+     * Confirmation has to mean two readings from DIFFERENT evidence.
+     * `detectTempo` drains the page's flux buffer, so calling it twice in
+     * a row sees the identical onset history and trivially agrees with
+     * itself — which would confirm a first reading rather than test it.
+     *
+     * Count alone is not enough: the history is capped at
+     * MAX_HISTORY_LENGTH, so a full window slides without the count
+     * changing. The newest onset's timestamp catches that.
+     *
+     * `null` means no poll has happened yet.
+     */
+    _lastOnsetSignature = null;
     _spectralFluxHistory = [];
     _previousMagnitudes = null;
     _chromaHistory = [];
+    /**
+     * Fixed onset threshold. Retained only as a floor — see
+     * `isOnset`, which decides adaptively.
+     *
+     * As an absolute threshold this was unreachable. Flux is normalized
+     * by bin count AND by 255, so 0.3 demands an average jump of +76/255
+     * across EVERY bin. A realistic kick transient (low bins 30->240,
+     * mids 90->120) measures 0.057 — five times under. Only a
+     * silence-to-full-scale transition fired it (#322).
+     */
     ONSET_THRESHOLD = 0.3;
+    /**
+     * Recent flux values, for the adaptive threshold.
+     *
+     * Picking a smaller constant would just be a different guess: what
+     * counts as a transient depends on the material, and a dense mix has
+     * a higher flux floor than a sparse one. So an onset is a local
+     * OUTLIER — median plus a multiple of the deviation — which is how
+     * onset detection is normally done and which needs no magic number
+     * tuned to one corpus.
+     */
+    _fluxHistory = [];
+    FLUX_WINDOW = 32;
+    /**
+     * Multiplier applied to the RAW median absolute deviation, not to sigma
+     * (#414 item 1).
+     *
+     * The distinction matters because the two are not the same unit. For
+     * Gaussian noise MAD is about 0.6745 sigma, so this 2.5 is roughly
+     * **1.69 sigma**, not two and a half. The previous name and doc comment
+     * ("deviations above the median") read as sigmas and were wrong by a
+     * factor of 1.4826.
+     *
+     * The VALUE is not known to be wrong. It was arrived at empirically in
+     * #350 and the resulting onset behaviour was measured against real
+     * playback in #366, so it is tuned for this signal whatever unit it is
+     * expressed in. Do not "correct" it to 2.5 sigma (i.e. 3.71 MAD) on the
+     * strength of the arithmetic alone — that is a real sensitivity change
+     * and needs re-measuring against the #366 corpus first.
+     */
+    ONSET_MAD_MULTIPLIER = 2.5;
+    /** Flux below this is silence, whatever the local statistics say. */
+    FLUX_NOISE_FLOOR = 0.004;
     MAX_HISTORY_LENGTH = 100;
+    /**
+     * How long after a detected transient further frames are treated as
+     * part of it rather than as new onsets.
+     *
+     * The reasoning for the original 50ms was right and the number was
+     * too small to deliver it. "Not shattering every kick into four" is
+     * exactly the goal; 50ms did not reach it, because the AnalyserNode
+     * runs with `smoothingTimeConstant = 0.8`, which spreads one
+     * transient over three or four frames of positive flux — 60 to 100ms.
+     * A refractory shorter than the tail of the hit it is suppressing
+     * suppresses nothing, so one kick became two onsets ~60ms apart.
+     *
+     * Measured: ambient had 7 of 33 inter-onset intervals at 100ms or
+     * less, where aubio on the same audio had none, and only 59% of our
+     * onsets landed on the beat grid against aubio's 89%. Those doubles
+     * inflate the inter-onset CV, which is what `tempoFromOnsets` turns
+     * into confidence — so a correct 130.4 BPM estimate was scored below
+     * MIN_TEMPO_CONFIDENCE and thrown away (#502).
+     *
+     * Swept against captured flux from six real patterns. The knee is
+     * sharp and it is at 65ms:
+     *
+     *     refractory   ambient      techno       dnb
+     *     50-60ms      65 @ 0.12    130 @ 0.49   65 @ 0.15
+     *     65-80ms      65 @ 0.19    130 @ 0.94   65 @ 0.42
+     *     90-100ms     65 @ 0.37    130 @ 0.94   65 @ 0.50
+     *     125ms        65 @ 0.48    130 @ 0.94   65 @ 0.52
+     *
+     * Not a trade: the material that already worked improves most, since
+     * techno was carrying the same doubles.
+     *
+     * 70 rather than 65, to sit past the knee rather than on it, and
+     * rather than the 90ms that scores better still: 16th notes at
+     * 200 BPM are 75ms apart, and the original comment was right to want
+     * headroom there. 125ms takes `intelligent_dnb` from 130 to 65, which
+     * is the far edge of this making things worse.
+     */
+    static ONSET_REFRACTORY_MS = 70;
+    /**
+     * How much a candidate's octave relatives count toward its score,
+     * relative to the candidate itself.
+     *
+     * 0.25, measured, not chosen. At 0.5 a 90 BPM shuffle (667ms beat with
+     * a 2:1 swing putting a hit at 444ms) read 135, because the swung
+     * offbeat gives a spurious relative real correlation. Cross-model
+     * review predicted that exact number before I measured it.
+     *
+     * Enough to break a near-tie the prior would otherwise decide the
+     * wrong way; not enough to let a relative carry a candidate.
+     */
+    static FAMILY_CORROBORATION = 0.25;
+    /**
+     * Below this, `detectTempo` reports no tempo instead of a number.
+     *
+     * A BPM with confidence 0.00 is not a weak measurement, it is the
+     * tempo prior's centre with a measurement's face on. Reporting zero
+     * lets a caller tell "I could not hear a pulse" from "the pulse is
+     * 120", which is the distinction #366 turned on.
+     */
+    static MIN_TEMPO_CONFIDENCE = 0.1;
+    /**
+     * How far two readings may differ and still count as the same answer.
+     *
+     * 2%, with a one-BPM floor applied at the comparison. Wide enough for
+     * the 83/82 wobble adjacent polls produce on identical audio, narrow
+     * enough that 130 and 86 — a 2:3 cross-rhythm, and the pair that
+     * flipped in #501 — are never mistaken for each other.
+     */
+    static TEMPO_AGREEMENT_RATIO = 0.02;
+    /**
+     * Floor for the autocorrelation branch, on its own scale.
+     *
+     * `corr(beat)/corr(0)` is not the interval-spread number
+     * MIN_TEMPO_CONFIDENCE was calibrated against, so it does not
+     * inherit that threshold. Measured: deliberate negatives — intervals
+     * drawn flat, onsets scattered through the window — score 0.088 to
+     * 0.160, and the weakest genuine reading scores 0.303. 0.25 sits in
+     * the gap (#506).
+     */
+    static MIN_PERIODICITY_CONFIDENCE = 0.25;
+    /**
+     * How much of the past a tempo reading may be built from.
+     *
+     * `MAX_HISTORY_LENGTH` bounds the COUNT, which is not the same thing:
+     * 100 onsets can span ten seconds of one pattern or five minutes
+     * across four. Age is what matters to a tempo.
+     *
+     * 12s rather than 6s, measured. A 6s window reads dnb correctly about
+     * half the time and then flips (174, 115, 115, 174) and drags trap
+     * down to 70 on later polls; 12s gives the same answer every poll for
+     * every pattern. The reported failure in #352 was a SPREAD, so
+     * stability is the property worth buying — even though it costs the
+     * occasional lucky-correct reading a short window produces.
+     */
+    static MAX_ONSET_AGE_MS = 12_000;
+    /**
+     * A gap this large between the newest kept onset and the oldest new
+     * one means the audio stopped — a different pattern, a stop/play, or
+     * an agent that went away and came back.
+     *
+     * Measured, this is not theoretical: playing dnb at 174 and then house
+     * at 125, the FIRST house reading came back 174. The previous
+     * pattern's onsets were still in the history and outnumbered the new
+     * ones. Every wrong first reading in that run was the pattern before
+     * it (#366).
+     */
+    static ONSET_CONTINUITY_GAP_MS = 1_500;
+    // Per-instance analyser config (wired through from config.audio_analysis
+    // in config.json). #195.
+    fftSize;
+    smoothing;
     // Pitch classes for key detection
     PITCH_CLASSES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
     // Krumhansl-Schmuckler scale profiles
@@ -21,19 +239,135 @@ export class AudioAnalyzer {
         mixolydian: [6.0, 2.5, 3.5, 2.5, 4.5, 4.0, 2.5, 5.0, 3.5, 2.5, 3.5, 3.0],
         locrian: [6.0, 3.0, 2.5, 4.0, 3.0, 3.0, 3.5, 4.0, 3.0, 3.5, 4.0, 2.5]
     };
+    /**
+     * @param options.fftSize - power of 2 in [32, 32768]. Default 1024.
+     * @param options.smoothing - value in [0, 1]. Default 0.8.
+     *
+     * Invalid values fall back to defaults with a warning rather than
+     * throwing; bad config in `config.json` shouldn't crash the server.
+     */
+    constructor(options) {
+        const logger = new Logger();
+        if (options?.fftSize !== undefined && !isValidFftSize(options.fftSize)) {
+            logger.warn(`AudioAnalyzer: invalid fftSize ${String(options.fftSize)} — must be a power of 2 in [${MIN_FFT_SIZE}, ${MAX_FFT_SIZE}]. Falling back to ${DEFAULT_FFT_SIZE}.`);
+            this.fftSize = DEFAULT_FFT_SIZE;
+        }
+        else {
+            this.fftSize = options?.fftSize ?? DEFAULT_FFT_SIZE;
+        }
+        if (options?.smoothing !== undefined &&
+            (typeof options.smoothing !== 'number' ||
+                Number.isNaN(options.smoothing) ||
+                options.smoothing < 0 ||
+                options.smoothing > 1)) {
+            logger.warn(`AudioAnalyzer: invalid smoothing ${String(options.smoothing)} — must be in [0, 1]. Falling back to ${DEFAULT_SMOOTHING}.`);
+            this.smoothing = DEFAULT_SMOOTHING;
+        }
+        else {
+            this.smoothing = options?.smoothing ?? DEFAULT_SMOOTHING;
+        }
+    }
+    /** Configured FFT size (read-only). Test/debug helper. */
+    getFftSize() {
+        return this.fftSize;
+    }
+    /** Configured smoothing constant (read-only). Test/debug helper. */
+    getSmoothing() {
+        return this.smoothing;
+    }
     /**
      * Injects audio analysis code into the Strudel page
      * @param page - Playwright page instance to inject into
      */
     async inject(page) {
+        const cfg = { fftSize: this.fftSize, smoothing: this.smoothing };
         /* istanbul ignore next -- browser-injected IIFE, covered by integration tests */
-        await page.evaluate(() => {
+        await page.evaluate(/* istanbul ignore next */ (cfg) => {
+            // Stop the previous collector before replacing the object it
+            // belongs to.
+            //
+            // This assignment overwrites `strudelAudioAnalyzer` outright, and
+            // the old object's 20ms interval does not stop just because
+            // nothing points at it any more. It kept sampling into an
+            // orphaned array and held the old AnalyserNode — and through it
+            // the old AudioContext — reachable for the life of the page.
+            // Measured in real Chromium: 16 samples in 300ms after a second
+            // inject (#479).
+            //
+            // This is also `stopFluxTracking`'s first production caller. It
+            // was written in #322 and never invoked, so the collector had no
+            // way to stop at all.
+            window.strudelAudioAnalyzer?.stopFluxTracking?.();
             window.strudelAudioAnalyzer = {
                 analyser: null,
                 dataArray: null,
                 isConnected: false,
                 lastAnalysis: null,
                 lastAnalysisTime: 0,
+                /**
+                 * Real hardware sample rate, read from the AudioContext.
+                 *
+                 * 44100 was assumed throughout, and 22050 was hardcoded as the
+                 * Nyquist. The AudioContext rate follows the hardware and is
+                 * commonly 48000 (typical on Linux/Chrome), where every reported
+                 * frequency came out 8.8% low — 1.47 semitones, enough to label
+                 * a real C as B or A# (#321/#323).
+                 */
+                sampleRate: 44100,
+                /**
+                 * Rolling flux samples, timestamped, collected continuously.
+                 *
+                 * detectTempo used to sample the spectrum ONCE per call and push
+                 * at most one onset, and four are needed before a BPM is
+                 * reported — so the inter-onset intervals were the gaps between
+                 * TOOL CALLS and the answer was a function of how often the
+                 * agent polled (#322).
+                 *
+                 * The page records raw flux here; the ONSET DECISION stays on
+                 * the server, so the adaptive detector is not duplicated into a
+                 * copy that would drift.
+                 */
+                fluxSamples: [],
+                fluxTimer: null,
+                previousMagnitudes: null,
+                MAX_FLUX_SAMPLES: 512,
+                /** Starts continuous flux sampling. Idempotent. */
+                startFluxTracking(intervalMs) {
+                    if (this.fluxTimer !== null)
+                        return;
+                    this.fluxTimer = setInterval(() => {
+                        if (!this.analyser || !this.dataArray)
+                            return;
+                        this.analyser.getByteFrequencyData(this.dataArray);
+                        const current = Array.from(this.dataArray);
+                        if (this.previousMagnitudes) {
+                            let flux = 0;
+                            for (let i = 0; i < current.length; i++) {
+                                const diff = current[i] - this.previousMagnitudes[i];
+                                if (diff > 0)
+                                    flux += diff;
+                            }
+                            this.fluxSamples.push({
+                                t: Date.now(),
+                                flux: flux / current.length / 255,
+                            });
+                            if (this.fluxSamples.length > this.MAX_FLUX_SAMPLES)
+                                this.fluxSamples.shift();
+                        }
+                        this.previousMagnitudes = current;
+                    }, intervalMs);
+                },
+                stopFluxTracking() {
+                    if (this.fluxTimer !== null) {
+                        clearInterval(this.fluxTimer);
+                        this.fluxTimer = null;
+                    }
+                },
+                takeFluxSamples() {
+                    const samples = this.fluxSamples;
+                    this.fluxSamples = [];
+                    return samples;
+                },
                 connect() {
                     const originalGainConnect = GainNode.prototype.connect;
                     let intercepted = false;
@@ -41,14 +375,18 @@ export class AudioAnalyzer {
                         if (!intercepted && args[0] && args[0].context) {
                             intercepted = true;
                             const ctx = args[0].context;
+                            window.strudelAudioAnalyzer.sampleRate = ctx.sampleRate;
                             window.strudelAudioAnalyzer.analyser = ctx.createAnalyser();
-                            // Reduced FFT size for better performance
-                            window.strudelAudioAnalyzer.analyser.fftSize = 1024;
-                            window.strudelAudioAnalyzer.analyser.smoothingTimeConstant = 0.8;
+                            // Configurable via config.audio_analysis in config.json (#195).
+                            window.strudelAudioAnalyzer.analyser.fftSize = cfg.fftSize;
+                            window.strudelAudioAnalyzer.analyser.smoothingTimeConstant = cfg.smoothing;
                             window.strudelAudioAnalyzer.dataArray = new Uint8Array(window.strudelAudioAnalyzer.analyser.frequencyBinCount);
                             const result = originalGainConnect.apply(this, args);
                             originalGainConnect.call(this, window.strudelAudioAnalyzer.analyser);
                             window.strudelAudioAnalyzer.isConnected = true;
+                            // Sample every 20ms — fine enough to resolve 16ths at
+                            // 200 BPM (75ms apart) without flooding the buffer.
+                            window.strudelAudioAnalyzer.startFluxTracking(20);
                             return result;
                         }
                         return originalGainConnect.apply(this, args);
@@ -70,6 +408,17 @@ export class AudioAnalyzer {
                     // Optimized analysis using typed array operations
                     const dataArray = this.dataArray;
                     const length = dataArray.length;
+                    // Frequency-band boundaries scaled to the actual `length`.
+                    // Reference values are bin indices that worked at fftSize=1024
+                    // (length=512): bass<4, lowMid<16, mid<64, highMid<128,
+                    // treble<256. Scaling by `length / 512` keeps each band over
+                    // the same Hz range when fftSize changes (#195).
+                    const scale = length / 512;
+                    const bassEnd = Math.max(1, Math.round(4 * scale));
+                    const lowMidEnd = Math.max(bassEnd + 1, Math.round(16 * scale));
+                    const midEnd = Math.max(lowMidEnd + 1, Math.round(64 * scale));
+                    const highMidEnd = Math.max(midEnd + 1, Math.round(128 * scale));
+                    const trebleEnd = Math.max(highMidEnd + 1, Math.round(256 * scale));
                     // Single-pass computation for better performance
                     let sum = 0;
                     let peak = 0;
@@ -85,26 +434,37 @@ export class AudioAnalyzer {
                             peak = value;
                             peakIndex = i;
                         }
-                        // Frequency bands (adjusted for 1024 FFT)
-                        if (i < 4)
+                        // Frequency-band boundaries are derived from the bin indices
+                        // that worked well at fftSize=1024 (length=512): 4, 16, 64,
+                        // 128, 256. Scaling by `length / 512` preserves the Hz-range
+                        // each band covers when fftSize changes (#195).
+                        if (i < bassEnd)
                             bassSum += value;
-                        else if (i < 16)
+                        else if (i < lowMidEnd)
                             lowMidSum += value;
-                        else if (i < 64)
+                        else if (i < midEnd)
                             midSum += value;
-                        else if (i < 128)
+                        else if (i < highMidEnd)
                             highMidSum += value;
-                        else if (i < 256)
+                        else if (i < trebleEnd)
                             trebleSum += value;
                     }
                     const average = sum / length;
-                    const centroid = sum > 0 ? weightedSum / sum : 0;
-                    const peakFreq = (peakIndex / length) * 22050;
-                    const bass = bassSum / 4;
-                    const lowMid = lowMidSum / 12;
-                    const mid = midSum / 48;
-                    const highMid = highMidSum / 64;
-                    const treble = trebleSum / 128;
+                    // Hz per bin. `weightedSum` accumulates `i * value`, so the
+                    // raw centroid is a BIN INDEX; comparing it against Hz-scale
+                    // thresholds made "bright" need bin 500 of 512, i.e. 21.5 kHz
+                    // out of a 22 kHz maximum — unreachable — and made the answer
+                    // depend on fftSize (#323).
+                    const nyquist = this.sampleRate / 2;
+                    const hzPerBin = nyquist / length;
+                    const centroidBin = sum > 0 ? weightedSum / sum : 0;
+                    const centroid = centroidBin * hzPerBin;
+                    const peakFreq = peakIndex * hzPerBin;
+                    const bass = bassSum / Math.max(1, bassEnd);
+                    const lowMid = lowMidSum / Math.max(1, lowMidEnd - bassEnd);
+                    const mid = midSum / Math.max(1, midEnd - lowMidEnd);
+                    const highMid = highMidSum / Math.max(1, highMidEnd - midEnd);
+                    const treble = trebleSum / Math.max(1, trebleEnd - highMidEnd);
                     const result = {
                         connected: true,
                         timestamp: now,
@@ -121,7 +481,10 @@ export class AudioAnalyzer {
                             isPlaying: average > 5,
                             isSilent: average < 1,
                             bassToTrebleRatio: treble > 0 ? (bass / treble).toFixed(2) : 'N/A',
-                            brightness: centroid > 500 ? 'bright' : centroid > 200 ? 'balanced' : 'dark'
+                            // Hz now, and reachable. Roughly: mostly-bass content
+                            // sits under 1.5 kHz, a full mix lands 1.5-4 kHz, and
+                            // hat/cymbal-dominated material runs above.
+                            brightness: centroid > 4000 ? 'bright' : centroid > 1500 ? 'balanced' : 'dark'
                         }
                     };
                     // Cache result
@@ -131,7 +494,7 @@ export class AudioAnalyzer {
                 }
             };
             window.strudelAudioAnalyzer.connect();
-        });
+        }, cfg);
     }
     /**
      * Retrieves audio analysis data from the page
@@ -185,6 +548,217 @@ export class AudioAnalyzer {
     /**
      * Calculate spectral flux (rate of change in frequency spectrum)
      */
+    /**
+     * Whether a flux value is an onset, judged against recent history.
+     *
+     * @param flux - Current spectral flux, 0-1
+     * @returns True if this is a local outlier and above the noise floor
+     * @example
+     * // A steady 0.05 background with a 0.2 spike: only the spike fires.
+     */
+    /**
+     * Turns a timestamped flux series into onset timestamps.
+     *
+     * The page samples flux continuously; this applies the same adaptive
+     * decision to the whole series at once. Keeping the decision here
+     * rather than in the injected script means the detector is not
+     * duplicated into a browser copy that would drift from this one — the
+     * failure mode #341 found in the style resource (#322).
+     *
+     * Returns the flux value alongside the timestamp, because a kick and a
+     * hi-hat are not equally good evidence of where the beat is, and the
+     * autocorrelation needs to be able to tell them apart (#352).
+     *
+     * @param samples - Timestamped flux values, oldest first
+     * @returns Each detected onset, with the flux that triggered it
+     * @example
+     * analyzer.onsetsFromFlux([{ t: 0, flux: 0.01 }, { t: 20, flux: 0.4 }]);
+     */
+    onsetsFromFlux(samples, continueStream = false) {
+        return AudioAnalyzer.collapseToPeaks(this.onsetCandidatesFromFlux(samples, continueStream));
+    }
+    /**
+     * Every frame that crossed the threshold, before collapsing.
+     *
+     * The buffered path needs these rather than the collapsed peaks,
+     * because collapsing per buffer and then collapsing the boundary
+     * again is not the same operation as collapsing the whole stream
+     * once. The first candidates of a buffer get merged among themselves
+     * before they can be compared with what the previous buffer kept, and
+     * a frame the whole-series pass would have chosen as the peak can be
+     * discarded before the boundary merge ever sees it.
+     *
+     * That was the residual left open in #370 — one onset in 45 at an
+     * adversarial 1745ms boundary — and it grew to two as soon as
+     * ONSET_REFRACTORY_MS was widened to cover the smoothing tail (#502),
+     * because a wider window puts more frames in each run.
+     *
+     * @param samples - Timestamped flux values, oldest first
+     * @param continueStream - True when this buffer continues one already in progress
+     * @returns Every frame judged an onset, uncollapsed, oldest first
+     */
+    onsetCandidatesFromFlux(samples, continueStream = false) {
+        // Resetting between buffers of ONE performance makes every boundary
+        // a discontinuity: the first samples of each buffer fall back to the
+        // fixed threshold instead of the adaptive one the stream had already
+        // learned. Detecting the same audio whole and in 5s pieces then
+        // gives different onsets, which is #370. A genuinely new capture
+        // still resets — via resetTempoHistory, on pattern change and stop.
+        if (!continueStream)
+            this.resetOnsetDetection();
+        const candidates = [];
+        for (const sample of samples) {
+            if (this.isOnset(sample.flux))
+                candidates.push({ t: sample.t, strength: sample.flux });
+        }
+        return candidates;
+    }
+    /**
+     * Collapses a run of adjacent detections into the one transient it is.
+     *
+     * A drum hit is not instantaneous. Its flux stays above the adaptive
+     * threshold for several consecutive 20ms frames, and without this every
+     * frame of it became a separate "onset" — measured on real playback,
+     * the median inter-onset interval was 20ms, exactly one sampling step,
+     * for dnb, techno and house alike. An envelope of solid blocks has no
+     * periodicity to find, the autocorrelation came out flat, and the
+     * tempo prior answered on its own: 120 BPM for every pattern, at
+     * confidence 0.00 (#366).
+     *
+     * Keeps the loudest frame of each run, which is also the one whose
+     * strength should weight the correlation.
+     *
+     * @param candidates - Every frame that crossed the threshold, in order
+     * @param refractoryMs - Frames closer than this belong to one transient
+     * @returns One observation per transient
+     */
+    static collapseToPeaks(candidates, refractoryMs = AudioAnalyzer.ONSET_REFRACTORY_MS) {
+        const peaks = [];
+        for (const candidate of candidates) {
+            const previous = peaks[peaks.length - 1];
+            if (previous !== undefined && candidate.t - previous.t < refractoryMs) {
+                // Same transient. Keep the louder frame, and its time with it —
+                // the peak is a better estimate of when the hit landed than the
+                // first frame that happened to cross.
+                if (candidate.strength > previous.strength)
+                    peaks[peaks.length - 1] = candidate;
+                continue;
+            }
+            peaks.push(candidate);
+        }
+        return peaks;
+    }
+    /**
+     * Folds newly detected onsets into the history, dropping what no
+     * longer belongs to the same performance.
+     *
+     * @param detected - Onsets from the latest buffer, oldest first
+     */
+    mergeOnsetHistory(detected) {
+        const newest = this._onsetHistory[this._onsetHistory.length - 1];
+        const first = detected[0];
+        // A silence longer than a bar is a different performance. Keeping
+        // the old onsets across it does not add data, it mixes two tempos
+        // and puts a multi-second interval between them.
+        if (newest !== undefined && first !== undefined &&
+            first.t - newest.t > AudioAnalyzer.ONSET_CONTINUITY_GAP_MS) {
+            this._onsetHistory = [];
+        }
+        // A transient that straddles a buffer boundary arrives as the tail of
+        // one detection and the head of the next. `collapseToPeaks` merges
+        // within a single call and cannot see across one, so one kick counts
+        // twice, every buffer.
+        //
+        // Collapsing `[last kept onset, ...incoming]` rather than special-
+        // casing the first element is what makes this EXACTLY the same
+        // operation the whole-series path performs. A hand-rolled boundary
+        // merge got it nearly right and dropped one onset in 45: it decided
+        // the first incoming onset, then pushed the rest unchanged, so an
+        // onset that became adjacent to the retained peak was never
+        // reconsidered.
+        const previous = this._onsetHistory.pop();
+        const joined = previous === undefined ? detected : [previous, ...detected];
+        this._onsetHistory.push(...AudioAnalyzer.collapseToPeaks(joined));
+        const latest = this._onsetHistory[this._onsetHistory.length - 1];
+        if (latest !== undefined) {
+            const cutoff = latest.t - AudioAnalyzer.MAX_ONSET_AGE_MS;
+            // Bound by age first: a count bound alone let a reading span
+            // minutes of unrelated audio.
+            while (this._onsetHistory.length > 0 && this._onsetHistory[0].t < cutoff) {
+                this._onsetHistory.shift();
+            }
+        }
+        while (this._onsetHistory.length > this.MAX_HISTORY_LENGTH) {
+            this._onsetHistory.shift();
+        }
+    }
+    /**
+     * Forgets every onset collected so far.
+     *
+     * Called when the pattern changes or the transport stops: the next
+     * reading must describe the next performance, not average it with the
+     * last one.
+     */
+    async resetTempoHistory(page) {
+        this._onsetHistory = [];
+        // The stable reading belongs to the pattern that produced it (#374).
+        this._confirmedTempo = null;
+        this._unconfirmedBpm = null;
+        this._lastOnsetSignature = null;
+        this.resetOnsetDetection();
+        // The PAGE keeps its own flux buffer, and clearing only the Node
+        // side left up to ten seconds of the previous pattern's samples
+        // waiting to be drained into the fresh history on the next call.
+        // Cross-model review found this: the reset looked complete because
+        // everything it could see was cleared, and the contamination lived
+        // one process away (#374).
+        //
+        // Draining and discarding reuses the existing accessor rather than
+        // adding a second way to empty the same array.
+        if (page !== undefined) {
+            try {
+                await page.evaluate(/* istanbul ignore next */ () => {
+                    window.strudelAudioAnalyzer?.takeFluxSamples?.();
+                });
+            }
+            catch {
+                // The page may be gone — a reset that cannot reach it has
+                // nothing to contaminate anyway.
+            }
+        }
+    }
+    isOnset(flux) {
+        const history = this._fluxHistory;
+        history.push(flux);
+        if (history.length > this.FLUX_WINDOW)
+            history.shift();
+        // Below the noise floor is silence regardless of what the window
+        // says — otherwise a completely quiet passage generates onsets from
+        // its own rounding.
+        if (flux < this.FLUX_NOISE_FLOOR)
+            return false;
+        // Not enough history yet: fall back to the fixed threshold rather
+        // than firing on the first sample of anything.
+        if (history.length < 8)
+            return flux > this.ONSET_THRESHOLD;
+        const sorted = [...history].sort((a, b) => a - b);
+        const median = sorted[Math.floor(sorted.length / 2)];
+        // Median absolute deviation — robust to the very spikes we are
+        // looking for, unlike a standard deviation.
+        const deviations = sorted.map(v => Math.abs(v - median)).sort((a, b) => a - b);
+        const mad = deviations[Math.floor(deviations.length / 2)];
+        // A perfectly steady signal has mad 0; require a real rise over the
+        // median rather than dividing by zero.
+        const threshold = mad > 0
+            ? median + this.ONSET_MAD_MULTIPLIER * mad
+            : median * 1.5 + this.FLUX_NOISE_FLOOR;
+        return flux > threshold;
+    }
+    /** Clears the flux window, so a new capture does not inherit one. */
+    resetOnsetDetection() {
+        this._fluxHistory = [];
+        this._previousMagnitudes = null;
+    }
     calculateSpectralFlux(currentMagnitudes) {
         if (!this._previousMagnitudes) {
             this._previousMagnitudes = Array.from(currentMagnitudes);
@@ -216,16 +790,77 @@ export class AudioAnalyzer {
     /**
      * Extract chroma features (12-dimensional pitch class profile) from FFT data
      */
-    extractChroma(fftData) {
+    /**
+     * Mean in-range bin magnitude below which a spectrum carries no key.
+     *
+     * On the 0-255 byte scale `getByteFrequencyData` produces, so this is
+     * roughly one part in 255 of full scale, averaged over the 20-4000 Hz
+     * bins — far below anything audible.
+     *
+     * Measured against live playback (#412), mean in-range magnitude:
+     *
+     *     stopped                          0
+     *     note("<c3 e3 g3>").s("sine")    14.7   <- quietest content tried
+     *     s("bd*4")                       18.9
+     *     s("bd*4, ~ cp ~ cp, hh*8")     151.1
+     *
+     * Silence reads exactly 0 and the quietest musical content read 14.7,
+     * so 1 sits in an empty gap an order of magnitude wide on either side.
+     *
+     * Three patterns on one machine in one browser, which is not a survey
+     * — but the gap is wide enough that the exact figure does not matter,
+     * and the guard's job is to separate "nothing" from "something".
+     */
+    static CHROMA_NOISE_FLOOR = 1;
+    /**
+     * Mean magnitude of the bins `extractChroma` will actually use.
+     *
+     * Read before normalization, which is the whole point: the chroma
+     * vector sums to 1 for a single non-zero bin exactly as it does for a
+     * full mix, so nothing downstream of `extractChroma` can tell silence
+     * from music.
+     *
+     * @param fftData - Byte frequency data
+     * @param sampleRate - The rate the AudioContext reported
+     * @returns Mean magnitude over the 20-4000 Hz bins, 0 if none
+     */
+    meanInRangeMagnitude(fftData, sampleRate) {
+        let sum = 0;
+        let count = 0;
+        for (let i = 0; i < fftData.length; i++) {
+            const freq = (i / fftData.length) * (sampleRate / 2);
+            if (freq < 20 || freq > 4000)
+                continue;
+            sum += fftData[i];
+            count++;
+        }
+        return count > 0 ? sum / count : 0;
+    }
+    extractChroma(fftData, sampleRate = 44100) {
         const chroma = new Array(12).fill(0);
+        // How many FFT bins landed in each pitch class. Linear-frequency
+        // bins do not divide evenly among twelve logarithmic pitch classes:
+        // at fftSize=1024 only 92 of 512 bins fall inside 20-4000 Hz, and
+        // they are distributed 4 to 12 per class — A gets 12, C# and D# get
+        // 4. Summing raw magnitudes therefore made the classes with more
+        // bins louder no matter what the audio was, and flat white noise
+        // detected as F major with confidence 0.849 (#321).
+        const binCounts = new Array(12).fill(0);
         const fftSize = fftData.length;
-        const sampleRate = 44100;
         for (let i = 0; i < fftSize; i++) {
             const freq = (i / fftSize) * (sampleRate / 2);
             if (freq < 20 || freq > 4000)
                 continue; // Focus on musical range
             const pitchClass = this.frequencyToPitchClass(freq);
             chroma[pitchClass] += fftData[i];
+            binCounts[pitchClass]++;
+        }
+        // Mean magnitude per class, not total. This is the whole fix: a
+        // class with 12 bins is now compared on equal terms with one that
+        // has 4.
+        for (let pc = 0; pc < 12; pc++) {
+            if (binCounts[pc] > 0)
+                chroma[pc] /= binCounts[pc];
         }
         // Normalize
         const sum = chroma.reduce((a, b) => a + b, 0);
@@ -273,17 +908,6 @@ export class AudioAnalyzer {
         const magnitude = Math.sqrt(magX * magY);
         return magnitude === 0 ? 0 : dotProduct / magnitude;
     }
-    /**
-     * Rotate a profile array by a given number of steps
-     * For tonic N, rotate the profile so that position N gets the tonic weight
-     */
-    rotateProfile(profile, steps) {
-        const rotated = new Array(12);
-        for (let i = 0; i < 12; i++) {
-            rotated[i] = profile[(i - steps + 12) % 12];
-        }
-        return rotated;
-    }
     /**
      * Calculate intervals between consecutive values
      */
@@ -346,8 +970,8 @@ export class AudioAnalyzer {
                 }
                 const fftData = new Uint8Array(analyzer.dataArray);
                 const flux = this.calculateSpectralFlux(fftData);
-                if (flux > this.ONSET_THRESHOLD) {
-                    this._onsetHistory.push(Date.now());
+                if (this.isOnset(flux)) {
+                    this._onsetHistory.push({ t: Date.now(), strength: flux });
                     if (this._onsetHistory.length > this.MAX_HISTORY_LENGTH) {
                         this._onsetHistory.shift();
                     }
@@ -356,47 +980,540 @@ export class AudioAnalyzer {
             }
         }
         else {
-            // No analyze function, use real-time detection
+            // Prefer the page's continuous buffer.
+            //
+            // Sampling once per call gave at most one onset per tool call, so
+            // the intervals measured were the gaps between CALLS. The page
+            // samples every 20ms; this reads what it collected and applies the
+            // onset decision to the whole series (#322).
+            const buffered = await this.takeBufferedFlux(page);
+            if (buffered.length >= 8) {
+                // Continuing the same stream: the previous buffer's threshold
+                // state is what makes this buffer's first samples comparable.
+                // Candidates, not peaks: `mergeOnsetHistory` collapses them
+                // together with what the previous buffer kept, so the collapse
+                // happens exactly once over the concatenated stream — which is
+                // what makes the buffered path equal the whole-series one
+                // (#370, #502).
+                const detected = this.onsetCandidatesFromFlux(buffered, this._onsetHistory.length > 0);
+                this.mergeOnsetHistory(detected);
+                const history = [...this._onsetHistory];
+                return this.stabilise(this.tempoFromOnsets(history), history);
+            }
+            // Fall back to the single-sample path when the page has no buffer
+            // — an older injected script, or a capture that just started.
             if (!analyzer.dataArray) {
                 throw new Error('Invalid audio data');
             }
             const fftData = new Uint8Array(analyzer.dataArray);
             const flux = this.calculateSpectralFlux(fftData);
-            if (flux > this.ONSET_THRESHOLD) {
-                this._onsetHistory.push(Date.now());
+            if (this.isOnset(flux)) {
+                this._onsetHistory.push({ t: Date.now(), strength: flux });
                 if (this._onsetHistory.length > this.MAX_HISTORY_LENGTH) {
                     this._onsetHistory.shift();
                 }
             }
             onsets = [...this._onsetHistory];
         }
+        return this.stabilise(this.tempoFromOnsets(onsets), onsets);
+    }
+    /**
+     * Whether two readings describe the same pulse.
+     *
+     * Not equality: consecutive readings of the same audio wobble by a
+     * BPM, and the amen break read 83 then 82 on adjacent polls. A
+     * proportional tolerance with a one-BPM floor treats that as the same
+     * answer and still separates 130 from 86.
+     *
+     * @param a - One reading, in BPM
+     * @param b - The other
+     * @returns True when the two agree within tolerance
+     */
+    static readingsAgree(a, b) {
+        if (a <= 0 || b <= 0)
+            return false;
+        return Math.abs(a - b) <= Math.max(1, a * AudioAnalyzer.TEMPO_AGREEMENT_RATIO);
+    }
+    /**
+     * A fingerprint of the onsets a reading was taken from.
+     *
+     * @param onsets - The series the reading came from
+     * @returns A string that changes when the window does
+     */
+    static onsetSignature(onsets) {
+        const times = onsetTimes(onsets);
+        const newest = times.length > 0 ? times[times.length - 1] : 0;
+        return `${String(times.length)}:${String(newest)}`;
+    }
+    /**
+     * Holds a reading back until a second window agrees with it.
+     *
+     * The rule, in full:
+     *
+     *  - A window that has not changed since the last poll cannot produce
+     *    a different answer, so its reading is final and reported at
+     *    once. This is the mock and fixture case, and the real case after
+     *    the audio stops.
+     *  - A reading that agrees with the confirmed one refreshes it. The
+     *    confirmed BPM is reported rather than the new one, so the number
+     *    does not wobble by a BPM between polls; confidence stays live,
+     *    because that is a live property of the evidence.
+     *  - A reading that agrees with the previous unconfirmed one is
+     *    promoted and reported.
+     *  - Anything else is held. If something is already confirmed it
+     *    keeps being reported, so one deviant poll cannot flip the
+     *    answer — the deviant has to be seen twice, like every other
+     *    reading. That is what stops 130, 130, 86, 130.
+     *  - `bpm: 0` is not a competing reading, it is the absence of one.
+     *    It never displaces a confirmed answer and never counts as
+     *    corroboration.
+     *
+     * A held reading returns `bpm: 0` with its measured confidence and
+     * method, matching what the MIN_TEMPO_CONFIDENCE gate already does —
+     * the caller reads `bpm === 0` as "no answer yet" either way.
+     *
+     * @param reading - What this poll measured
+     * @param onsets - The onsets it measured from
+     * @returns The reading to report
+     */
+    stabilise(reading, onsets) {
+        const signature = AudioAnalyzer.onsetSignature(onsets);
+        const windowMoved = this._lastOnsetSignature !== signature;
+        const firstPoll = this._lastOnsetSignature === null;
+        this._lastOnsetSignature = signature;
+        if (reading.bpm === 0) {
+            // No reading to corroborate, and none to contradict. Whatever was
+            // confirmed still stands until the pattern changes.
+            return this._confirmedTempo === null
+                ? reading
+                : { ...this._confirmedTempo, confidence: reading.confidence };
+        }
+        if (!windowMoved && !firstPoll) {
+            // Nothing new can arrive, so waiting cannot improve this answer.
+            this._confirmedTempo = reading;
+            this._unconfirmedBpm = null;
+            return reading;
+        }
+        if (this._confirmedTempo !== null
+            && AudioAnalyzer.readingsAgree(this._confirmedTempo.bpm, reading.bpm)) {
+            this._unconfirmedBpm = null;
+            return { ...this._confirmedTempo, confidence: reading.confidence };
+        }
+        if (this._unconfirmedBpm !== null
+            && AudioAnalyzer.readingsAgree(this._unconfirmedBpm, reading.bpm)) {
+            this._confirmedTempo = reading;
+            this._unconfirmedBpm = null;
+            return reading;
+        }
+        this._unconfirmedBpm = reading.bpm;
+        // `settling`, so the caller is not told to check whether audio is
+        // playing while it is playing and a candidate is already in hand.
+        return this._confirmedTempo === null
+            ? { ...reading, bpm: 0, alternatives: undefined, settling: true }
+            : { ...this._confirmedTempo, confidence: reading.confidence };
+    }
+    /**
+     * Halves or doubles a tempo until it lands in the musical range.
+     *
+     * Out-of-range readings used to be discarded outright, which threw
+     * away recoverable answers: 174 BPM drum & bass with onsets on 8ths
+     * reads as 348 and returned bpm 0, on 16ths as 696 and returned 0,
+     * and a 70 BPM tune whose onsets land on half notes reads as 35 and
+     * returned 0. Onset detection lands on whatever subdivision is
+     * loudest, so this is the common case, not the edge case (#322).
+     *
+     * @param bpm - Raw tempo from the median inter-onset interval
+     * @returns A tempo within [40, 200], or null if it cannot be folded there
+     * @example
+     * AudioAnalyzer.foldIntoTempoRange(348); // 174
+     * AudioAnalyzer.foldIntoTempoRange(35);  // 70
+     */
+    static foldIntoTempoRange(bpm) {
+        if (!Number.isFinite(bpm) || bpm <= 0)
+            return null;
+        const MIN = 40;
+        const MAX = 200;
+        let folded = bpm;
+        // Three octaves each way. That covers every real case — onsets on
+        // 8ths is one octave, on 16ths is two — while refusing to invent a
+        // tempo from noise: 5000 BPM means onsets 12ms apart, and folding
+        // that five times to a plausible-looking 156 would be a fabrication,
+        // not a measurement.
+        const MAX_OCTAVES = 3;
+        for (let i = 0; i < MAX_OCTAVES && folded > MAX; i++)
+            folded /= 2;
+        for (let i = 0; i < MAX_OCTAVES && folded < MIN; i++)
+            folded *= 2;
+        return folded >= MIN && folded <= MAX ? folded : null;
+    }
+    // ============================================================================
+    // KEY DETECTION
+    // ============================================================================
+    /**
+     * Reads and clears the page's continuous flux buffer.
+     *
+     * @param page - Playwright page with the analyser injected
+     * @returns Timestamped flux samples, oldest first
+     */
+    async takeBufferedFlux(page) {
+        try {
+            const samples = await page.evaluate(/* istanbul ignore next */ () => {
+                const a = window.strudelAudioAnalyzer;
+                return typeof a?.takeFluxSamples === 'function' ? a.takeFluxSamples() : [];
+            });
+            return Array.isArray(samples) ? samples : [];
+        }
+        catch {
+            // An older injected script, or a page that went away mid-call.
+            // The caller falls back to single-sample detection.
+            return [];
+        }
+    }
+    /**
+     * Derives a tempo from onset timestamps.
+     *
+     * @param onsets - Onset times in milliseconds, oldest first
+     * @returns Tempo analysis, or bpm 0 when there is not enough to go on
+     */
+    /**
+     * Finds the beat period by autocorrelating the onset series.
+     *
+     * A central inter-onset interval measures whatever subdivision the
+     * onsets happen to land on, not the pulse. A 174 BPM track with hits
+     * on 8ths has a 172ms median interval, and the fold-into-range step
+     * then picks whichever octave it lands in first — which is why the
+     * liquid-dnb example read 108, 117 and 190 across runs (#352).
+     *
+     * Autocorrelation asks a different question: at what lag does the
+     * whole series repeat? Hits on 8ths correlate at 172ms AND at 345ms,
+     * and a preference weight centred on 120 BPM breaks the octave tie
+     * the way a listener does.
+     *
+     * @param onsets - Onset times in milliseconds, oldest first
+     * @returns Beat period in ms, or null when no periodicity is clear
+     * @example
+     * // onsets every 172ms from a 174 BPM track -> ~345
+     */
+    /**
+     * How strongly a candidate's whole octave family correlates, not just
+     * the candidate.
+     *
+     * Measured on a real 174 BPM reading, the raw correlation favoured 174
+     * over 115 (.0041 against .0039) and the 120-centred prior overturned
+     * it: 174 weighs 0.866, 115 weighs 0.998, and 13% was enough. 115 is
+     * then a trap — it sits near the prior's centre AND its double, 230
+     * BPM, is outside the 40-200 window, so the half-time walk has nowhere
+     * to go and the reading can never be corrected.
+     *
+     * 115 is not an octave of 174 at all. It is a cross-rhythm: six
+     * sixteenths where the beat is four.
+     *
+     * Families separate them on evidence rather than on where the prior's
+     * centre was guessed. 43.5 / 87 / 174 all correlate strongly; 115's
+     * family is 57.5 / 115 / 230, one weak and one out of range. Whether a
+     * tempo's halves and doubles also correlate is a property of the
+     * music.
+     *
+     * Members outside the reportable BPM range still count as evidence —
+     * 230 BPM is not an answer this returns, but its correlation says
+     * something about whether 115 is real.
+     *
+     * @param correlation - Autocorrelation of the onset envelope
+     * @param lag - Candidate lag, in bins
+     * @returns Summed correlation across the candidate's octave family
+     */
+    static familyStrength(correlation, lag) {
+        const own = lag > 0 && lag < correlation.length ? correlation[lag] : 0;
+        let relatives = 0;
+        for (const multiple of [0.25, 0.5, 2, 4]) {
+            const member = Math.round(lag * multiple);
+            if (member > 0 && member < correlation.length)
+                relatives += correlation[member];
+        }
+        // The candidate leads; its family corroborates. A plain sum makes
+        // every member of a family score alike and lets a strong relative
+        // carry a weak candidate, which broke a pure 90 BPM train (read as
+        // 120) and a triplet fixture.
+        return own + AudioAnalyzer.FAMILY_CORROBORATION * relatives;
+    }
+    beatPeriodFromOnsets(onsets) {
+        const times = onsetTimes(onsets);
+        const strengths = onsetStrengths(onsets);
+        // Autocorrelation needs a series long enough to show periodicity.
+        // With 8 onsets over 1.2 seconds it reported 117 for a 174 BPM
+        // train — the correlation simply has too few overlapping terms at
+        // the lags that matter. Below this the median path is better, and
+        // the caller falls through to it (#352).
+        const MIN_ONSETS_FOR_AUTOCORRELATION = 12;
+        if (times.length < MIN_ONSETS_FOR_AUTOCORRELATION)
+            return null;
+        // Impulse train at 10ms resolution — finer than the 20ms flux
+        // sampling, so quantization here adds nothing.
+        const RESOLUTION_MS = 5;
+        const span = times[times.length - 1] - times[0];
+        if (span <= 0)
+            return null;
+        const length = Math.floor(span / RESOLUTION_MS) + 1;
+        if (length < 8)
+            return null;
+        // Weighted by flux, not a binary impulse train.
+        //
+        // A dnb pattern fires onsets on kicks, snares AND hats, and an
+        // unweighted train says they are equally likely to be the beat. They
+        // are not — measured on a synthetic 174 BPM mix with 16th hats, the
+        // unweighted correlation reads 115 BPM, because the 120 BPM prior
+        // tips a near-tie between the beat lag and a six-sixteenth lag. With
+        // the kick contributing ~2.5x what a hat does, the tie disappears.
+        //
+        // Normalized so the loudest onset is 1: flux magnitudes are relative
+        // to whatever the mix is doing, and only the ratios matter here.
+        const loudest = strengths.length > 0 ? Math.max(...strengths) : 1;
+        const scale = loudest > 0 ? 1 / loudest : 1;
+        const envelope = new Array(length).fill(0);
+        // Each onset is spread over a small triangular kernel rather than
+        // written to one bin.
+        //
+        // The flux series is sampled every 20ms, so every onset time is a
+        // multiple of 20ms — and most tempos do not divide into it. A 345ms
+        // beat (174 BPM) lands alternately on 340 and 360, and a bare
+        // impulse train has NO lag that matches both. Measured, tempos whose
+        // period is an exact multiple of the sampling step read correctly
+        // (120 from 500ms, 100 from 600ms) and tempos that are not read
+        // wrong (174, 140) — which is the quantization, not the music.
+        //
+        // A kernel one sampling step wide either side lets a jittered onset
+        // still correlate with the lag it belongs to.
+        // Only for flux-derived onsets. The jitter this corrects is an
+        // artifact of the 20ms sampling, so an input that was not sampled —
+        // exact timestamps from a test, or the mock path — has none, and
+        // smearing it only blurs a peak that was already sharp. Measured:
+        // applying the kernel to an exact 174 BPM 8th-note train moved it
+        // to 117.
+        const KERNEL_BINS = strengths.length > 0 ? Math.max(1, Math.round(20 / RESOLUTION_MS)) : 0;
+        for (let i = 0; i < times.length; i++) {
+            const centre = Math.round((times[i] - times[0]) / RESOLUTION_MS);
+            const weight = strengths.length > 0 ? strengths[i] * scale : 1;
+            for (let d = -KERNEL_BINS; d <= KERNEL_BINS; d++) {
+                const index = centre + d;
+                if (index < 0 || index >= length)
+                    continue;
+                const taper = 1 - Math.abs(d) / (KERNEL_BINS + 1);
+                // Keep the strongest contribution rather than summing: two hats
+                // quantized together must not outweigh one kick.
+                envelope[index] = Math.max(envelope[index], weight * taper);
+            }
+        }
+        const correlation = this.autocorrelate(envelope);
+        // Lags corresponding to 40-200 BPM.
+        const minLag = Math.floor((60000 / 200) / RESOLUTION_MS);
+        const maxLag = Math.ceil((60000 / 40) / RESOLUTION_MS);
+        let bestLag = 0;
+        let bestScore = 0;
+        for (let lag = minLag; lag <= maxLag && lag < correlation.length; lag++) {
+            const bpm = 60000 / (lag * RESOLUTION_MS);
+            // Preference weight in log-tempo space, centred on 120 BPM. This
+            // is what resolves the octave ambiguity: 172ms and 345ms both
+            // correlate, and a listener hears the slower one as the beat.
+            const octaves = Math.log2(bpm / 120);
+            const weight = Math.exp(-(octaves * octaves) / 2);
+            const score = AudioAnalyzer.familyStrength(correlation, lag) * weight;
+            if (score > bestScore) {
+                bestScore = score;
+                bestLag = lag;
+            }
+        }
+        if (bestLag === 0 || bestScore <= 0)
+            return null;
+        // Prefer the faster reading when it also correlates.
+        //
+        // The autocorrelation of an impulse train peaks at the period AND
+        // at every multiple, and the normalization by (n - lag) slightly
+        // favours the longer one — so a 174 BPM series scored highest at
+        // 690ms and reported 87. Half-time is a real reading of dnb, but
+        // 174 is the one its producer would give, and five existing tests
+        // asserted 174.
+        //
+        // So: if halving the winning lag still correlates substantially,
+        // take the halved one. A 120 BPM series on the beat has no
+        // correlation at 250ms and keeps 500ms; one on 8ths does, and
+        // halves to 250ms — which folds back to 120 anyway.
+        // How strongly the halved lag must correlate before it is preferred.
+        //
+        // Two regimes, because the two inputs carry different information.
+        // With flux strengths the loudest onsets mark the beat, the peak is
+        // trustworthy, and halving should need a near-tie to win — at 0.4 a
+        // 90 BPM pattern with 8th-note hats reads 179. Without strengths
+        // every onset looks alike and a train on 8ths is genuinely
+        // ambiguous: 172.5ms and 345ms are both perfectly periodic, and 174
+        // is a convention rather than a measurement. There, leaning on the
+        // halving is what recovers the number a producer would give.
+        const HALF_TIME_RATIO = strengths.length > 0 ? 0.8 : 0.4;
+        let lag = bestLag;
+        for (let i = 0; i < 3; i++) {
+            const half = Math.round(lag / 2);
+            if (half < minLag || half >= correlation.length)
+                break;
+            if (correlation[half] < correlation[lag] * HALF_TIME_RATIO)
+                break;
+            lag = half;
+        }
+        // The share of the envelope's self-similarity that survives at the
+        // reported period — `corr(beat) / corr(0)`. This is what the
+        // caller uses for confidence, and it is the quantity the answer
+        // was actually derived from (#506).
+        const periodicity = correlation[0] > 0
+            ? Math.min(1, correlation[lag] / correlation[0])
+            : 0;
+        return { periodMs: lag * RESOLUTION_MS, periodicity };
+    }
+    /**
+     * Tempos an octave either side of a detected one, within range.
+     *
+     * Half and double time are the SAME onset series — 345ms and 690ms
+     * impulse trains are indistinguishable from timing alone, and
+     * separating them needs onset strength or spectral cues this detector
+     * does not have. Measured at four envelope resolutions from 1ms to
+     * 10ms: the ranking never changed, so it is not a quantization
+     * artefact.
+     *
+     * Rather than pick silently, the alternatives are reported. A dnb
+     * track detected at 87 lists 174, which is the reading its producer
+     * would give (#352).
+     *
+     * @param bpm - The detected tempo
+     * @returns Octave-related tempos inside 40-200, nearest first
+     */
+    static tempoOctaves(bpm) {
+        const out = [];
+        for (const factor of [2, 0.5, 4, 0.25]) {
+            const candidate = Math.round(bpm * factor);
+            if (candidate >= 40 && candidate <= 200)
+                out.push(candidate);
+        }
+        return out;
+    }
+    tempoFromOnsets(onsets) {
+        const times = onsetTimes(onsets);
         // Need at least 4 onsets for reliable tempo detection
-        if (onsets.length < 4) {
+        if (times.length < 4) {
             return { bpm: 0, confidence: 0, method: 'onset' };
         }
         // Calculate inter-onset intervals (IOIs)
-        const intervals = this.calculateIntervals(onsets);
-        // Calculate mean interval and derive BPM
-        const meanInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
-        const bpm = 60000 / meanInterval;
-        // Validate BPM range
-        if (bpm < 40 || bpm > 200) {
+        const intervals = this.calculateIntervals(times);
+        // Autocorrelation first: it asks at what lag the whole series
+        // repeats, rather than measuring whatever subdivision the onsets
+        // happen to land on. A central inter-onset interval read the
+        // liquid-dnb example as 108, 117 and 190 across runs, because the
+        // fold-into-range step picked whichever octave the subdivision
+        // landed in first (#352).
+        const beatPeriod = this.beatPeriodFromOnsets(onsets);
+        if (beatPeriod !== null && beatPeriod.periodMs > 0) {
+            const rawBpm = 60000 / beatPeriod.periodMs;
+            const folded = AudioAnalyzer.foldIntoTempoRange(rawBpm);
+            if (folded !== null) {
+                const bpm = Math.round(folded);
+                // Confidence from the correlation that produced this number,
+                // not from the spread of the inter-onset intervals.
+                //
+                // The old measure asked "were the detected onsets evenly
+                // spaced?" and was read as "how sure are you about this
+                // tempo?". Those come apart exactly where it matters: the
+                // autocorrelation returned 130.4 BPM in seven of seven
+                // six-second ambient windows while interval CV drifted across
+                // the floor, so a correct answer was reported in four of them
+                // and discarded in three — on a statistic the correlation had
+                // never consulted (#506).
+                //
+                // Measured across real captures and deliberate negatives, the
+                // two quantities rank the cases differently and only one of
+                // them ranks them correctly:
+                //
+                //                        interval CV   corr(beat)/corr(0)
+                //   random intervals        0.45            0.11
+                //   scattered onsets        0.00            0.09
+                //   ambient (correct)       0.19            0.71
+                //   amen break              0.39            0.56
+                //   techno                  0.94            0.95
+                //
+                // The old measure puts a pulseless series ABOVE real ambient.
+                // The new one separates every negative from every positive
+                // with no overlap — 0.16 against 0.30 at the boundary.
+                const confidence = beatPeriod.periodicity;
+                // Below the floor, say nothing rather than say 120.
+                //
+                // The correlation always has a highest lag, and the tempo prior
+                // is centred on 120 — so when the onsets carry no periodicity
+                // the answer is the prior's centre, dressed as a measurement.
+                // Measured on real playback before #366's onset fix: 120 BPM for
+                // dnb, techno and house alike, every run, at confidence 0.00.
+                // The code already knew; nothing was reading it.
+                // Its own floor, because it is its own scale. The negatives
+                // measured top out at 0.16 and the weakest true reading is
+                // 0.30, so 0.25 sits in the gap rather than on either side of
+                // it. MIN_TEMPO_CONFIDENCE still governs the median branch,
+                // where confidence is still interval-based.
+                if (confidence < AudioAnalyzer.MIN_PERIODICITY_CONFIDENCE) {
+                    return { bpm: 0, confidence, method: 'autocorrelation' };
+                }
+                return {
+                    bpm,
+                    confidence,
+                    method: 'autocorrelation',
+                    alternatives: AudioAnalyzer.tempoOctaves(bpm),
+                };
+            }
+        }
+        // Median, not mean.
+        //
+        // A single dropped or ghosted onset moved the answer badly: a steady
+        // 120 BPM grid with one missed onset reported 105, and with one
+        // extra reported 135. The median is unmoved by either, and onset
+        // detection misses and doubles constantly (#322).
+        const sorted = [...intervals].sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        const medianInterval = sorted.length % 2 === 0
+            ? (sorted[mid - 1] + sorted[mid]) / 2
+            : sorted[mid];
+        if (medianInterval <= 0) {
             return { bpm: 0, confidence: 0, method: 'onset' };
         }
-        // Calculate confidence from interval consistency
-        const variance = this.calculateVariance(intervals, meanInterval);
-        const coefficientOfVariation = Math.sqrt(variance) / meanInterval;
+        const rawBpm = 60000 / medianInterval;
+        const bpm = AudioAnalyzer.foldIntoTempoRange(rawBpm);
+        // Unfoldable — more than a few octaves outside the range, so the
+        // onsets are not a tempo at all.
+        if (bpm === null) {
+            return { bpm: 0, confidence: 0, method: 'onset' };
+        }
+        // Confidence still comes from interval consistency, but measured
+        // against the median so one outlier does not inflate the spread it
+        // is being compared to.
+        const variance = this.calculateVariance(intervals, medianInterval);
+        const coefficientOfVariation = Math.sqrt(variance) / medianInterval;
         // More aggressive penalty for variation
-        const confidence = Math.max(0, 1 - coefficientOfVariation * 1.5);
+        let confidence = Math.max(0, 1 - coefficientOfVariation * 1.5);
+        // A folded reading is a weaker claim than a direct one: we inferred
+        // the beat is half or double what the onsets literally say.
+        if (Math.abs(rawBpm - bpm) > 1) {
+            confidence *= 0.8;
+        }
+        // The same floor the autocorrelation branch applies, which this
+        // branch never had.
+        //
+        // It is the one that let `gen/ambient` report 184 BPM at confidence
+        // 0.000 and `gen/jungle` report 184 at 0.000 — a number with nothing
+        // behind it, in the shape of a measurement. The reasoning on
+        // MIN_TEMPO_CONFIDENCE applies here unchanged; it was simply only
+        // written on one of the two exits (#419).
+        const finalConfidence = Math.min(1, confidence);
+        if (finalConfidence < AudioAnalyzer.MIN_TEMPO_CONFIDENCE) {
+            return { bpm: 0, confidence: finalConfidence, method: 'onset' };
+        }
         return {
             bpm: Math.round(bpm),
-            confidence: Math.min(1, confidence),
+            confidence: finalConfidence,
             method: 'onset'
         };
     }
-    // ============================================================================
-    // KEY DETECTION
-    // ============================================================================
     /**
      * Detect musical key using Krumhansl-Schmuckler algorithm
      */
@@ -409,6 +1526,9 @@ export class AudioAnalyzer {
             throw new Error('Audio analyzer not connected');
         }
         let chroma;
+        // Mean in-range bin magnitude before normalization, or null when the
+        // chroma came from a mock and there is no spectrum behind it.
+        let rawMagnitude = null;
         // Check if this is a mock with pre-calculated chroma vector (for testing)
         if (typeof analyzer.analyze === 'function') {
             const analysis = analyzer.analyze();
@@ -421,7 +1541,8 @@ export class AudioAnalyzer {
                     throw new Error('Invalid audio data');
                 }
                 const fftData = new Uint8Array(analyzer.dataArray);
-                chroma = this.extractChroma(fftData);
+                rawMagnitude = this.meanInRangeMagnitude(fftData, analyzer.sampleRate ?? 44100);
+                chroma = this.extractChroma(fftData, analyzer.sampleRate ?? 44100);
             }
         }
         else {
@@ -430,18 +1551,61 @@ export class AudioAnalyzer {
                 throw new Error('Invalid audio data');
             }
             const fftData = new Uint8Array(analyzer.dataArray);
-            chroma = this.extractChroma(fftData);
+            // The rate the AudioContext actually reported, captured at
+            // connect time. 44100 was assumed; the real rate is commonly
+            // 48000, where every frequency came out 8.8% low — 1.47
+            // semitones, enough to put a note in the wrong pitch class (#321).
+            rawMagnitude = this.meanInRangeMagnitude(fftData, analyzer.sampleRate ?? 44100);
+            chroma = this.extractChroma(fftData, analyzer.sampleRate ?? 44100);
+        }
+        // Check for sufficient energy.
+        //
+        // This used to sum the chroma vector and compare against 0.1 — a
+        // test that could never fail, because `extractChroma` normalizes to
+        // sum 1 whenever any bin is non-zero. Measured: an FFT with a single
+        // bin at magnitude 1 out of 1024, which is silence, normalized to
+        // sum 1.000 and came back "C locrian, confidence 0.793". Only an
+        // exactly all-zero spectrum could trip the guard.
+        //
+        // The magnitude has to be read before normalization throws it away.
+        if (rawMagnitude !== null && rawMagnitude < AudioAnalyzer.CHROMA_NOISE_FLOOR) {
+            return { key: 'C', scale: 'major', confidence: 0 };
         }
-        // Check for sufficient energy
-        const totalEnergy = chroma.reduce((sum, val) => sum + val, 0);
-        if (totalEnergy < 0.1) {
-            return { key: 'C', scale: 'major', confidence: 0.1 };
+        // The mock path supplies a chroma directly and has no spectrum to
+        // measure, so it keeps a chroma-side check — meaningful there
+        // because a mock is not required to be normalized.
+        if (rawMagnitude === null && chroma.reduce((sum, val) => sum + val, 0) <= 0) {
+            return { key: 'C', scale: 'major', confidence: 0 };
         }
+        return this.detectKeyFromChroma(chroma);
+    }
+    /**
+     * Scores a chroma vector against every key/scale profile.
+     *
+     * Extracted from `detectKey` so it can be tested at all. The scoring
+     * used to be inline in a method that needs a live Playwright page, so
+     * nothing could feed it a known chroma and check the answer — which
+     * is how it came to return "dorian" for all twelve canonical minor
+     * profiles without anyone noticing (#320).
+     *
+     * @param chroma - 12-element pitch class profile, any scale
+     * @returns Best key/scale with confidence and alternatives
+     * @example
+     * analyzer.detectKeyFromChroma(KRUMHANSL_MINOR); // C minor
+     */
+    detectKeyFromChroma(chroma) {
         // Correlate with all key/scale combinations
         const scores = [];
         for (const scale of Object.keys(this.SCALE_PROFILES)) {
             // Normalize profile to sum to 1
-            const rawProfile = this.SCALE_PROFILES[scale];
+            // Key comes from Object.keys(this.SCALE_PROFILES) directly above,
+            // so it is always an own property; hasOwn keeps it that way if the
+            // loop is ever rewritten (#318).
+            const rawProfile = Object.hasOwn(this.SCALE_PROFILES, scale)
+                ? this.SCALE_PROFILES[scale]
+                : undefined;
+            if (!rawProfile)
+                continue;
             const profileSum = rawProfile.reduce((a, b) => a + b, 0);
             const profile = rawProfile.map(v => v / profileSum);
             for (let tonic = 0; tonic < 12; tonic++) {
@@ -451,8 +1615,17 @@ export class AudioAnalyzer {
                 for (let i = 0; i < 12; i++) {
                     rotatedChroma[i] = chroma[(i + tonic) % 12];
                 }
-                // Use cosine similarity for correlation
-                const correlation = this.cosineSimilarity(rotatedChroma, profile);
+                // Pearson, which is what Krumhansl-Schmuckler is defined with.
+                //
+                // Cosine was used instead, and `pearsonCorrelation` sat right
+                // beside it, implemented and unit-tested and never called.
+                // Cosine is not mean-centered, so all 24 scores bunch near 1:
+                // for a C-major input the full range was 0.804-1.000, a spread
+                // of 0.196, where Pearson gives -0.683-1.000. The top-1-vs-top-2
+                // gap under cosine was 0.0048 — smaller than the mode boosts
+                // below, which is how those boosts came to decide every
+                // answer (#320).
+                const correlation = this.pearsonCorrelation(rotatedChroma, profile);
                 scores.push({
                     key: this.PITCH_CLASSES[tonic],
                     scale,
@@ -464,42 +1637,64 @@ export class AudioAnalyzer {
         const chromaWithIndices = chroma.map((v, i) => ({ value: v, index: i }));
         chromaWithIndices.sort((a, b) => b.value - a.value);
         const topPitches = chromaWithIndices.slice(0, 3).map(x => this.PITCH_CLASSES[x.index]);
-        // Apply bias boosts to resolve ambiguous cases
+        // The mode boosts are gone.
+        //
+        // `dorian *= 1.015` was larger than the margin cosine left between
+        // minor and dorian (0.0078), so it flipped EVERY minor key: fed the
+        // exact canonical K-S minor profile for all 12 minor keys, detection
+        // answered "dorian" 12 out of 12 — right tonic, wrong mode, every
+        // time. A thumb on the scale heavier than the scale itself is not a
+        // tie-breaker, it is the decision (#320).
+        //
+        // The tonic boost stays, reduced and applied only to the single
+        // loudest pitch class rather than the top three (boosting all three
+        // by the same 1.075 meant it discriminated nothing between them).
+        // Pearson's spread is wide enough that a nudge this size can only
+        // break a genuine near-tie.
+        //
+        // Applied only to a positive score. Multiplying is a boost above
+        // zero and a PENALTY below it: a candidate at -0.4 becomes -0.408,
+        // pushed down by the nudge that exists to lift it. That only bites
+        // when nothing correlates well, which is exactly where a tonic hint
+        // was supposed to help.
+        const TONIC_NUDGE = 1.02;
         for (const s of scores) {
-            // Boost keys that match one of the top 3 loudest pitches
-            // (any of these could plausibly be the tonic)
-            const pitchBoost = topPitches.indexOf(s.key);
-            if (pitchBoost >= 0) {
-                // Slightly favor 2nd pitch to handle dominant/mediant being louder than tonic
-                const boosts = [1.075, 1.075, 1.075];
-                s.score *= boosts[pitchBoost];
-            }
-            // Boost for common scales
-            if (s.scale === 'major') {
-                s.score *= 1.03; // 3% boost for major scales (most common)
-            }
-            else if (s.scale === 'dorian') {
-                s.score *= 1.015; // 1.5% boost for dorian (common modal scale)
+            if (s.key === topPitches[0] && s.score > 0) {
+                s.score *= TONIC_NUDGE;
             }
         }
         // Sort by score (after applying biases)
         scores.sort((a, b) => b.score - a.score);
-        // Calculate confidence
         const best = scores[0];
         const secondBest = scores[1];
-        // Confidence based on score strength (cosine similarity 0-1) and separation
-        // Increased separation weight to better differentiate close matches
-        const strength = best.score;
-        const separation = Math.min(1, Math.max(0, (best.score - secondBest.score) * 10));
-        const confidence = Math.min(1, strength * 0.75 + separation * 0.25);
+        // Confidence is about discrimination, not similarity.
+        //
+        // It used to be 0.75 * the raw cosine score, which is >= 0.9 for
+        // essentially any non-negative chroma — a flat, zero-information
+        // input returned confidence 0.787. Pearson on a flat chroma is 0
+        // (no correlation with anything), so `strength` now collapses on
+        // exactly the inputs that carry no information, and `separation`
+        // asks whether the winner actually beat the runner-up.
+        const STRENGTH_WEIGHT = 0.6;
+        const SEPARATION_WEIGHT = 0.4;
+        const strength = Math.max(0, best.score);
+        const separation = Math.min(1, Math.max(0, (best.score - secondBest.score) * 5));
+        const confidence = Math.min(1, Math.max(0, strength * STRENGTH_WEIGHT + separation * SEPARATION_WEIGHT));
         return {
             key: best.key,
             scale: best.scale,
             confidence,
+            // Alternatives are scored the same WAY as the headline, not just
+            // clamped to the same range. Reporting their raw correlation put
+            // them on a different scale entirely — an A-minor input answered
+            // with confidence 0.801 while listing "A dorian 0.926" beneath
+            // it, an alternative apparently more confident than the answer.
+            // A non-winner earns no separation term, by definition: it did
+            // not separate from anything (#320).
             alternatives: scores.slice(1, 4).map(s => ({
                 key: s.key,
                 scale: s.scale,
-                confidence: Math.max(0, s.score)
+                confidence: Math.min(1, Math.max(0, s.score) * STRENGTH_WEIGHT)
             }))
         };
     }
@@ -538,26 +1733,26 @@ export class AudioAnalyzer {
                 // No mock data, use real-time detection
                 const fftData = new Uint8Array(analyzer.dataArray);
                 const flux = this.calculateSpectralFlux(fftData);
-                if (flux > this.ONSET_THRESHOLD) {
-                    this._onsetHistory.push(Date.now());
+                if (this.isOnset(flux)) {
+                    this._onsetHistory.push({ t: Date.now(), strength: flux });
                     if (this._onsetHistory.length > this.MAX_HISTORY_LENGTH) {
                         this._onsetHistory.shift();
                     }
                 }
-                onsets = [...this._onsetHistory];
+                onsets = onsetTimes(this._onsetHistory);
             }
         }
         else {
             // No analyze function, use real-time detection
             const fftData = new Uint8Array(analyzer.dataArray);
             const flux = this.calculateSpectralFlux(fftData);
-            if (flux > this.ONSET_THRESHOLD) {
-                this._onsetHistory.push(Date.now());
+            if (this.isOnset(flux)) {
+                this._onsetHistory.push({ t: Date.now(), strength: flux });
                 if (this._onsetHistory.length > this.MAX_HISTORY_LENGTH) {
                     this._onsetHistory.shift();
                 }
             }
-            onsets = [...this._onsetHistory];
+            onsets = onsetTimes(this._onsetHistory);
         }
         // Need at least 2 onsets for rhythm analysis
         if (onsets.length < 2) {
@@ -625,7 +1820,14 @@ export class AudioAnalyzer {
             return 0;
         let syncopationScore = 0;
         for (let i = 1; i < onsets.length; i++) {
-            const phase = (onsets[i] % (meanInterval * 4)) / meanInterval;
+            // Relative to the first onset, not to the Unix epoch.
+            // `onsets[i]` is a Date.now() value, so this modulo used to depend
+            // on what time of day it was: the same nine onsets 500ms apart
+            // scored 0.000 at one epoch offset and 1.000 at another, and a
+            // perfectly regular grid reported maximum syncopation roughly
+            // three-quarters of the time (#323).
+            const elapsed = onsets[i] - onsets[0];
+            const phase = (elapsed % (meanInterval * 4)) / meanInterval;
             // Check if onset is on an off-beat (not on 0, 1, 2, 3)
             const nearestBeat = Math.round(phase);
             const beatDistance = Math.abs(phase - nearestBeat);
@@ -646,7 +1848,8 @@ export class AudioAnalyzer {
         const patternLength = 16;
         const pattern = new Array(patternLength).fill('.');
         for (const onset of onsets) {
-            const position = Math.round((onset % (meanInterval * patternLength)) / meanInterval);
+            // Same epoch bug as detectSyncopation: relative to the first onset.
+            const position = Math.round(((onset - onsets[0]) % (meanInterval * patternLength)) / meanInterval);
             if (position < patternLength) {
                 pattern[position] = 'X';
             }