note-listener 1.1.2 → 1.1.3

package/README.md

@@ -1,18 +1,18 @@
 # note-listener
 
-A lightweight JavaScript/TypeScript library for detecting pitch from any audio input. Works in the browser and supports selecting specific microphones or sound cards. Perfect for guitar practice, music apps, or live pitch detection.
+A lightweight JavaScript/TypeScript library for real-time musical note detection from microphone audio in the browser.
+Ideal for guitar practice, tuners, music apps, and live pitch visualization.
 
----
+`note-listener` listens to audio input, detects the dominant pitch, and continuously emits the corresponding musical note.
 
 ## Features
 
-* Detect musical notes (C0–B8) in real-time.
-* Smooths out note jitter with a configurable buffer.
-* Supports multiple audio inputs and allows choosing a specific device.
-* Pure browser-based — no backend required.
-* Minimal dependencies (`pitchy`).
-
----
+-  Real-time musical note detection (C0–B8)
+-  Works with any microphone or sound card
+-  Smooths jitter using internal buffering
+-  Configurable frequency range and clarity threshold
+-  Pure browser-based (Web Audio API)
+-  Minimal dependencies ([pitchy](https://github.com/ianprime0509/pitchy))
 
 ## Installation
 
@@ -22,37 +22,99 @@ npm install note-listener
 yarn add note-listener
 ```
 
+## How it works
+
+This library is **event-based**, not return-based.
+
+1. You start listening to the microphone
+2. The library continuously detects notes
+3. Each detected note is sent to you via a callback
+4. Listening continues until you explicitly stop it
+
+There is no "single return value" — notes are streamed over time.
+
 ## Usage
 
-### Plain JavaScript
+### 1. List available audio inputs (optional)
 
 ```js
-import { listAudioInputs, createPitchListener } from "note-listener";
+import { listAudioInputs } from "note-listener"
 
-// List all available audio inputs
-const inputs = await listAudioInputs();
-console.log(inputs); // [{ deviceId, label }, ...]
+const inputs = await listAudioInputs()
+console.log(inputs)
+// [{ deviceId: "...", label: "Built-in Microphone" }, ...]
+```
+
+> **Note:** Browsers require microphone permission before device labels appear:
+> ```js
+> await navigator.mediaDevices.getUserMedia({ audio: true })
+> ```
+
+### 2. Create a pitch listener
+
+```js
+import { createPitchListener } from "note-listener"
 
 const listener = await createPitchListener({
-  deviceId: inputs[0].deviceId, // select a device
+  deviceId: inputs[0].deviceId,
   minEnergy: 0.03,
-  onNote: (note, freq, clarity) => {
-    console.log(`Detected note: ${note} (${freq.toFixed(2)} Hz), clarity: ${clarity.toFixed(2)}`);
+  onNote: (note, frequency, clarity) => {
+    console.log(
+      `${note} (${frequency.toFixed(2)} Hz, clarity ${clarity.toFixed(2)})`
+    )
+  },
+})
+```
+
+At this point, the microphone is **not yet active** and no audio is being analyzed. You are just configuring the listener.
+
+### 3. Start listening
+
+```js
+listener.start()
+```
+
+When `start()` is called, the browser activates the selected microphone, audio is analyzed in real time, and detected notes are emitted via `onNote`.
+
+### 4. Stop listening
+
+```js
+listener.stop()
+```
+
+This stops the microphone stream, disconnects audio nodes, and frees system resources. You should always call `stop()` when done.
+
+## Examples
+
+### Plain JavaScript
+
+```js
+import { listAudioInputs, createPitchListener } from "note-listener"
+
+await navigator.mediaDevices.getUserMedia({ audio: true })
+
+const inputs = await listAudioInputs()
+
+const listener = await createPitchListener({
+  deviceId: inputs[0].deviceId,
+  onNote(note, freq) {
+    console.log(`Current note: ${note} (${freq.toFixed(1)} Hz)`)
   },
-});
+})
 
-listener.start();
+listener.start()
 
-// Stop when needed
-// listener.stop();
+// Later...
+// listener.stop()
 ```
 
-### Vue 3 Example
+### Vue 3
 
 ```vue
 <template>
   <div>
-    <h2>Select audio input</h2>
+    <h3>Select audio input</h3>
+
     <select v-model="selectedId">
       <option disabled value="">-- choose input --</option>
       <option v-for="d in inputs" :key="d.deviceId" :value="d.deviceId">
@@ -60,7 +122,9 @@ listener.start();
       </option>
     </select>
 
-    <button @click="start" :disabled="!selectedId">Start listening</button>
+    <button @click="start" :disabled="!selectedId">Start</button>
+    <button @click="stop">Stop</button>
+
     <p>Last note: {{ lastNote || "—" }}</p>
   </div>
 </template>
@@ -84,33 +148,57 @@ async function start() {
 
   listener = await createPitchListener({
     deviceId: selectedId.value,
-    minEnergy: 0.03,
     onNote(note) {
       lastNote.value = note
-      console.log("🎵", note)
     },
   })
 
   listener.start()
 }
 
-onBeforeUnmount(() => {
+function stop() {
   if (listener) listener.stop()
-})
+}
+
+onBeforeUnmount(stop)
 </script>
 ```
 
-## Options
+## API
+
+### `createPitchListener(options)`
+
+| Option             | Type       | Default     | Description                              |
+| ------------------ | ---------- | ----------- | ---------------------------------------- |
+| `deviceId`         | `string`   | `undefined` | Audio input device ID                    |
+| `minEnergy`        | `number`   | `0.03`      | Minimum RMS energy required              |
+| `clarityThreshold` | `number`   | `0.88`      | Minimum pitch clarity                    |
+| `minFreq`          | `number`   | `82`        | Minimum frequency (Hz)                   |
+| `maxFreq`          | `number`   | `1319`      | Maximum frequency (Hz)                   |
+| `onNote`           | `function` | required    | Called when a note is detected           |
+
+### `onNote` callback
+
+```ts
+(note: string, frequency: number, clarity: number) => void
+```
+
+Called continuously while audio is being analyzed. `note` is a string like `"A4"`, `frequency` is in Hz, and `clarity` is a value between 0 and 1 indicating pitch confidence.
+
+### `listAudioInputs()`
+
+Returns a promise resolving to an array of available audio input devices:
+
+```ts
+[{ deviceId: string, label: string }]
+```
+
+## Browser support
 
-| Option           | Type     | Default   | Description                                                         |
-| ---------------- | -------- | --------- | ------------------------------------------------------------------- |
-| deviceId         | string   | undefined | Audio input device ID to use.                                       |
-| minEnergy        | number   | 0.03      | Minimum RMS energy to consider a signal as valid.                   |
-| clarityThreshold | number   | 0.88      | Minimum clarity from pitchy to register a note.                     |
-| minFreq          | number   | 82        | Minimum frequency to detect (Hz).                                   |
-| maxFreq          | number   | 1319      | Maximum frequency to detect (Hz).                                   |
-| onNote           | function | required  | Callback when a new note is detected: `(note, freq, clarity) => {}` |
+- Works in modern Chromium, Firefox, and Safari
+- Requires user interaction to initiate microphone access
+- Not supported in Node.js or server-side environments
 
 ## License
 
-MIT © Donald Edwin
+MIT © Donald Edwin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "note-listener",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "simple pitch detection library for instruments using pitchy",
   "main": "src/index.js",
   "scripts": {
@@ -23,4 +23,3 @@
     "pitchy": "^4.1.0"
   }
 }
-

package/src/index.js

@@ -1,168 +1,385 @@
 import { PitchDetector } from "pitchy";
 
-export async function listAudioInputs() {
-  const devices = await navigator.mediaDevices.enumerateDevices();
-  return devices.filter((d) => d.kind === "audioinput");
+  //  AUDIO WORKLET PROCESSOR (inlined as a Blob)
+  //  Runs on the audio thread, posts raw PCM frames
+
+const WORKLET_CODE =`
+class PitchProcessorNode extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this._buf = [];
+    this._frameSize = 2048;
+  }
+
+  process(inputs) {
+    const ch = inputs[0]?.[0];
+    if (!ch) return true;
+
+    for (let i = 0; i < ch.length; i++) this._buf.push(ch[i]);
+
+    while (this._buf.length >= this._frameSize) {
+      const frame = new Float32Array(this._buf.splice(0, this._frameSize));
+      this.port.postMessage(frame, [frame.buffer]);
+    }
+    return true;
+  }
 }
+registerProcessor("pitch-processor", PitchProcessorNode);
+`;
+
+/* ─────────────────────────────────────────────
+   CONSTANTS
+   ───────────────────────────────────────────── */
+const A4 = 440;
+const NOTE_NAMES = ["C","C#","D","D#","E","F","F#","G","G#","A","A#","B"];
+const FRAME_SIZE = 2048;
 
+// Guitar band splits: [label, lowHz, highHz]
+const BANDS = [
+  ["bass",   82,   200],
+  ["mid",   200,   500],
+  ["treble",500,  1319],
+];
+
+/* ─────────────────────────────────────────────
+   UTILITIES
+   ───────────────────────────────────────────── */
+export function listAudioInputs() {
+  return navigator.mediaDevices
+    .enumerateDevices()
+    .then((d) => d.filter((x) => x.kind === "audioinput"));
+}
+
+function freqToMidi(freq) {
+  return Math.round(12 * Math.log2(freq / A4) + 69);
+}
+
+function midiToNote(midi) {
+  return NOTE_NAMES[midi % 12] + (Math.floor(midi / 12) - 1);
+}
 
-/* ====== Utilities ====== */
 function freqToNote(freq) {
-  const A4 = 440;
-  const notes = [
-    "C",
-    "C#",
-    "D",
-    "D#",
-    "E",
-    "F",
-    "F#",
-    "G",
-    "G#",
-    "A",
-    "A#",
-    "B",
-  ];
-
-  const n = Math.round(12 * Math.log2(freq / A4) + 69);
-  const name = notes[n % 12];
-  const octave = Math.floor(n / 12) - 1;
-
-  return name + octave;
+  return midiToNote(freqToMidi(freq));
 }
 
-function rms(buffer) {
-  let sum = 0;
-  for (let i = 0; i < buffer.length; i++) {
-    sum += buffer[i] * buffer[i];
+/** Cents sharp (+) or flat (-) relative to the nearest equal-tempered pitch */
+function centDeviation(freq) {
+  const midi = 12 * Math.log2(freq / A4) + 69;
+  const nearest = Math.round(midi);
+  return Math.round((midi - nearest) * 100);
+}
+
+function rms(buf) {
+  let s = 0;
+  for (let i = 0; i < buf.length; i++) s += buf[i] * buf[i];
+  return Math.sqrt(s / buf.length);
+}
+
+function mostCommon(arr) {
+  const c = {};
+  arr.forEach((n) => (c[n] = (c[n] || 0) + 1));
+  let max = 0, winner = null;
+  for (const n in c) if (c[n] > max) { max = c[n]; winner = n; }
+  return winner;
+}
+
+/* ─────────────────────────────────────────────
+   FFT PEAK PICKING WITH HARMONIC VALIDATION
+   ───────────────────────────────────────────── */
+
+/**
+ * Finds candidate fundamental frequencies in a magnitude spectrum
+ * by locating spectral peaks and validating that their harmonics
+ * (2f, 3f, 4f) also carry significant energy.
+ *
+ * @param {Float32Array} freqData   - getFloatFrequencyData() output (dBFS)
+ * @param {number}       sampleRate
+ * @param {object}       opts
+ * @returns {Array<{freq, note, cents}>}
+ */
+function fftPeakNotes(freqData, sampleRate, {
+  minFreq      = 82,
+  maxFreq      = 1319,
+  noiseFloor   = -60,   // dBFS below which we ignore bins
+  peakDelta    = 6,     // dB above neighbours to count as peak
+  harmonics    = 3,     // how many harmonics to validate
+  harmonicGain = -18,   // harmonic must be within XdB of fundamental
+} = {}) {
+  const binHz = sampleRate / (2 * (freqData.length - 1));
+  const results = [];
+
+  const minBin = Math.ceil(minFreq / binHz);
+  const maxBin = Math.floor(maxFreq / binHz);
+
+  for (let i = minBin; i <= maxBin; i++) {
+    const mag = freqData[i];
+    if (mag < noiseFloor) continue;
+    // local peak check
+    if (mag <= freqData[i - 1] || mag <= freqData[i + 1]) continue;
+    if (mag - freqData[i - 1] < peakDelta && mag - freqData[i + 1] < peakDelta) continue;
+
+    const freq = i * binHz;
+
+    // harmonic validation
+    let harmonicScore = 0;
+    for (let h = 2; h <= harmonics + 1; h++) {
+      const hBin = Math.round((freq * h) / binHz);
+      if (hBin >= freqData.length) break;
+      if (freqData[hBin] > noiseFloor && freqData[hBin] >= mag + harmonicGain) {
+        harmonicScore++;
+      }
+    }
+    // require at least half of the harmonics to be present
+    if (harmonicScore < Math.floor(harmonics / 2)) continue;
+
+    results.push({
+      freq,
+      note: freqToNote(freq),
+      cents: centDeviation(freq),
+    });
   }
-  return Math.sqrt(sum / buffer.length);
+
+  return results;
 }
 
-function getGuitar(deviceId) {
-  return navigator.mediaDevices.getUserMedia({
-    audio: {
-      ...(deviceId ? { deviceId: { exact: deviceId } } : {}),
-      echoCancellation: false,
-      autoGainControl: false,
-      noiseSuppression: false,
-      latency: 0,
-    },
+/* ─────────────────────────────────────────────
+   BAND-SPLIT + PARALLEL PITCHY DETECTORS
+   ───────────────────────────────────────────── */
+
+/**
+ * Runs the McLeod (pitchy) detector on each frequency band independently.
+ * Each band has its own smoothing buffer and lastNote for hysteresis.
+ */
+function createBandDetectors(clarityThreshold, bufferSize) {
+  return BANDS.map(([label, lo, hi]) => {
+    const detector  = PitchDetector.forFloat32Array(FRAME_SIZE);
+    const noteBuffer = [];
+    let lastNote    = null;
+    let lastEnergy  = 0;
+
+    return { label, lo, hi, detector, noteBuffer, lastNote, lastEnergy, bufferSize, clarityThreshold };
   });
 }
 
-/* ====== PUBLIC API ====== */
+/**
+ * Applies a simple software bandpass via frequency masking on a copy of
+ * the time-domain buffer before running pitchy.  (A proper approach would
+ * use biquad-filtered streams, but this avoids extra Web Audio nodes and
+ * works well enough given pitchy's built-in autocorrelation windowing.)
+ *
+ * We apply a rectangular window in the frequency domain then IFFT via
+ * the AnalyserNode — but since we only have time-domain data here, we do
+ * the simpler thing: trust that pitchy's autocorrelation naturally weights
+ * the dominant frequency, and use the [lo, hi] range to gate the result.
+ */
+function runBandDetector(band, frame, sampleRate, minEnergy, hysteresisRatio) {
+  const energy = rms(frame);
 
-export async function createPitchListener({
-  onNote,
-  deviceId,
-  minEnergy = 0.03,
-  clarityThreshold = 0.88,
-  minFreq = 82,
-  maxFreq = 1319,
-} = {}) {
-  if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
-    throw new Error("Browser does not support microphone access.");
+  // Silence hysteresis: note-on at minEnergy, note-off at minEnergy * hysteresisRatio
+  const onThreshold  = minEnergy;
+  const offThreshold = minEnergy * hysteresisRatio;
+
+  if (energy < offThreshold) {
+    band.lastNote   = null;
+    band.lastEnergy = energy;
+    return null;
   }
-  if (!window.AudioContext && !window.webkitAudioContext) {
-    throw new Error("Browser does not support Web Audio API.");
+
+  if (energy < onThreshold && band.lastNote === null) {
+    band.lastEnergy = energy;
+    return null;
   }
 
-  const context = new AudioContext();
-  let guitar;
-  try {
-    guitar = await getGuitar(deviceId);
-  } catch (e) {
-    console.warn("Microphone access not granted:", e.message);
+  const [freq, clarity] = band.detector.findPitch(frame, sampleRate);
+
+  if (clarity < band.clarityThreshold || freq < band.lo || freq > band.hi) {
+    band.lastEnergy = energy;
+    return null;
+  }
+
+  const note = freqToNote(freq);
+  band.noteBuffer.push(note);
+  if (band.noteBuffer.length > band.bufferSize) band.noteBuffer.shift();
+
+  const smoothed = mostCommon(band.noteBuffer);
+
+  // Onset detection: did we just cross the energy threshold from below?
+  const isOnset = band.lastEnergy < onThreshold && energy >= onThreshold;
+  const noteChanged = smoothed !== band.lastNote;
+
+  band.lastNote   = smoothed;
+  band.lastEnergy = energy;
+
+  if (noteChanged || isOnset) {
     return {
-      start() {
-        console.warn("Cannot start, no mic access.");
-      },
-      stop() {},
+      source:   "band:" + band.label,
+      note:     smoothed,
+      freq,
+      clarity,
+      cents:    centDeviation(freq),
+      isOnset,
+      energy,
     };
   }
+  return null;
+}
+
+/* ─────────────────────────────────────────────
+   MERGE & DEDUPLICATE DETECTIONS
+   ───────────────────────────────────────────── */
+
+/**
+ * Merges notes from band detectors and FFT peak picker.
+ * Deduplicates by MIDI pitch (within ±1 semitone).
+ */
+function mergeNotes(bandNotes, fftNotes, activeNotes, minEnergy) {
+  const all = [...bandNotes];
 
-  if (context.state === "suspended") {
-    await context.resume();
+  for (const fn of fftNotes) {
+    const midi = freqToMidi(fn.freq);
+    const dup  = all.some((n) => Math.abs(freqToMidi(n.freq) - midi) <= 1);
+    if (!dup) all.push({ source: "fft", isOnset: !activeNotes.has(fn.note), ...fn });
   }
 
-  const source = context.createMediaStreamSource(guitar);
+  return all;
+}
 
-  const filter = context.createBiquadFilter();
-  filter.type = "highpass";
-  filter.frequency.value = 70;
+/* ─────────────────────────────────────────────
+   PUBLIC API
+   ───────────────────────────────────────────── */
 
-  const analyser = context.createAnalyser();
-  analyser.fftSize = 2048;
+/**
+ * Creates a polyphonic pitch listener.
+ *
+ * @param {object} opts
+ * @param {function} opts.onNotes          - Called with an array of detected note objects
+ * @param {function} [opts.onOnset]        - Called when a new note onset is detected
+ * @param {string}  [opts.deviceId]        - Specific audio input device
+ * @param {number}  [opts.minEnergy]       - RMS energy threshold for note-on  (default 0.03)
+ * @param {number}  [opts.hysteresisRatio] - note-off = minEnergy * ratio       (default 0.6)
+ * @param {number}  [opts.clarityThreshold]- pitchy clarity gate               (default 0.88)
+ * @param {number}  [opts.minFreq]         - lowest frequency to track Hz       (default 82)
+ * @param {number}  [opts.maxFreq]         - highest frequency to track Hz      (default 1319)
+ * @param {number}  [opts.smoothing]       - band detector smoothing buffer len (default 5)
+ *
+ * Each note object passed to onNotes:
+ * {
+ *   note:    string,   // e.g. "E2"
+ *   freq:    number,   // Hz
+ *   cents:   number,   // deviation from equal temperament (-50..+50)
+ *   clarity: number,   // pitchy confidence 0-1 (band notes only)
+ *   isOnset: boolean,  // true on first frame of a new note
+ *   source:  string,   // "band:bass" | "band:mid" | "band:treble" | "fft"
+ *   energy:  number,   // RMS energy of this frame
+ * }
+ *
+ * @returns {Promise<{start, stop}>}
+ */
+export async function createPitchListener({
+  onNotes,
+  onOnset,
+  deviceId,
+  minEnergy        = 0.03,
+  hysteresisRatio  = 0.6,
+  clarityThreshold = 0.88,
+  minFreq          = 82,
+  maxFreq          = 1319,
+  smoothing        = 5,
+} = {}) {
+  if (!navigator.mediaDevices?.getUserMedia) throw new Error("Browser does not support microphone access.");
+  const ACtx = window.AudioContext ?? window.webkitAudioContext;
+  if (!ACtx) throw new Error("Browser does not support Web Audio API.");
 
-  source.connect(filter);
-  filter.connect(analyser);
+  /* -- AudioContext --------------------------------------------------- */
+  const context = new ACtx();
 
-  const buffer = new Float32Array(analyser.fftSize);
-  const detector = PitchDetector.forFloat32Array(analyser.fftSize);
+  /* -- Microphone stream --------------------------------------------- */
+  let stream;
+  try {
+    stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        ...(deviceId ? { deviceId: { exact: deviceId } } : {}),
+        echoCancellation: false,
+        autoGainControl:  false,
+        noiseSuppression: false,
+        latency: 0,
+      },
+    });
+  } catch (e) {
+    console.warn("Microphone access denied:", e.message);
+    return { start() {}, stop() {} };
+  }
 
-  // variables for control and smoothing
+  if (context.state === "suspended") await context.resume();
 
-  const noteBuffer = [];
-  const bufferSize = 5;
-  let lastNote = null;
-  let running = false;
+  /* -- AudioWorklet --------------------------------------------------- */
+  const blob    = new Blob([WORKLET_CODE], { type: "application/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  await context.audioWorklet.addModule(blobUrl);
+  URL.revokeObjectURL(blobUrl);
 
-  //  helper function for smoothing
+  const source    = context.createMediaStreamSource(stream);
+  const worklet   = new AudioWorkletNode(context, "pitch-processor");
 
-  function mostCommon(arr) {
-    const counts = {};
-    arr.forEach((n) => (counts[n] = (counts[n] || 0) + 1));
-    let max = 0,
-      winner = null;
-    for (const n in counts) {
-      if (counts[n] > max) {
-        max = counts[n];
-        winner = n;
-      }
-    }
-    return winner;
-  }
+  /* -- AnalyserNode for FFT ------------------------------------------ */
+  const analyser       = context.createAnalyser();
+  analyser.fftSize     = 8192;  // high resolution for FFT peak picker
+  analyser.smoothingTimeConstant = 0.5;
+  const fftBuf         = new Float32Array(analyser.frequencyBinCount);
 
-  function read() {
-    if (!running) return;
+  /* -- Highpass filter ------------------------------------------------ */
+  const hpf            = context.createBiquadFilter();
+  hpf.type             = "highpass";
+  hpf.frequency.value  = 70;
 
-    analyser.getFloatTimeDomainData(buffer);
+  source.connect(hpf);
+  hpf.connect(analyser);
+  hpf.connect(worklet);   // worklet gets filtered signal too
 
-    const energy = rms(buffer);
-    if (energy >= minEnergy) {
-      const [freq, clarity] = detector.findPitch(buffer, context.sampleRate);
+  /* -- Band detectors ------------------------------------------------- */
+  const bands      = createBandDetectors(clarityThreshold, smoothing);
+  const activeNotes = new Set();   // currently sounding notes (for onset tracking)
 
-      if (clarity >= clarityThreshold && freq >= minFreq && freq <= maxFreq) {
-        const note = freqToNote(freq);
+  /* -- Main processing handler --------------------------------------- */
+  worklet.port.onmessage = ({ data: frame }) => {
+    // --- Band-split detections ---
+    const bandNotes = bands
+      .map((band) => runBandDetector(band, frame, context.sampleRate, minEnergy, hysteresisRatio))
+      .filter(Boolean);
 
-        noteBuffer.push(note);
-        if (noteBuffer.length > bufferSize) noteBuffer.shift();
+    // --- FFT peak detections ---
+    analyser.getFloatFrequencyData(fftBuf);
+    const fftNotes = fftPeakNotes(fftBuf, context.sampleRate, { minFreq, maxFreq });
 
-        const smoothedNote = mostCommon(noteBuffer);
+    // --- Merge & deduplicate ---
+    const detected = mergeNotes(bandNotes, fftNotes, activeNotes);
 
-        if (smoothedNote !== lastNote) {
-          lastNote = smoothedNote;
-          onNote(smoothedNote, freq, clarity);
-        }
-      }
-    }
+    if (detected.length === 0) return;
 
-    requestAnimationFrame(read);
-  }
+    // Update active note set
+    detected.forEach(({ note }) => activeNotes.add(note));
+
+    // Fire callbacks
+    if (onNotes) onNotes(detected);
+
+    const onsets = detected.filter((n) => n.isOnset);
+    if (onsets.length && onOnset) onOnset(onsets);
+  };
+
+  let connected = false;
 
   return {
     start() {
-      running = true;
-      read();
+      if (connected) return;
+      connected = true;
+      worklet.connect(context.destination);  // worklet needs to be in the graph to run
     },
+
     stop() {
-      running = false;
-      if (context && context.state !== "closed") {
-        context
-          .close()
-          .catch((err) => console.warn("Error closing audio context:", err));
-      }
+      connected = false;
+      worklet.disconnect();
+      stream.getTracks().forEach((t) => t.stop());
+      context.close().catch(() => {});
     },
   };
-}
+}