tuner-core 2026.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuner contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# tuner-core
+
+Pitch detection (**YIN**, **pYIN / HMM**, **MPM / McLeod**, **autocorrelation**) and a small **tuner session** API (smoothing, confidence gating, note / cents, tunings registry). Made for browsers, Node, or native shells by injecting an `AudioProvider`.
+
+## Requirements
+
+- **Node.js 20+**
+- **ESM only** (`import`, not `require`). CommonJS callers must use dynamic `import()`.
+
+## Install
+
+```bash
+npm install tuner-core
+```
+
+## Why several detectors?
+
+Different algorithms trade off **latency**, **stability**, **CPU cost**, and **robustness** to noise, vibrato, and false subharmonics. Shipping multiple implementations lets you **benchmark under real rooms and instruments**, A/B in your UI, and fall back when one misbehaves on a given platform.
+
+**YIN** is the **default** in `DEFAULT_TUNER_SETTINGS**: a direct **cumulative mean normalized difference (CMND)** detector with **`yinThreshold`** as the main knob. **Predictive YIN (pYIN)** uses the same observations with a small HMM for a steadier monophonic track—pick it when that trade-off suits your app. **MPM** and **autocorrelation** stay in the box for comparison and platform-specific behavior.
+
+## Using `TunerSession` and reading results
+
+You bring an **`AudioProvider`** (mic / `AudioWorklet` / native capture): it exposes sample rate, registers a frame callback, and implements `start()` / `stop()`. **`TunerSession`** wires that stream to a **`PitchDetector`**, applies median smoothing and confidence gating, then emits **`TunerResult`** on each analyzed frame.
+
+```ts
+import {
+  TunerSession,
+  createPitchDetector,
+  mergeTunerSettings,
+  findTuning,
+  type AudioProvider,
+  type TunerResult,
+} from 'tuner-core'
+
+const settings = mergeTunerSettings({
+  pitchDetector: 'yin', // or 'pyin' | 'mpm' | 'autocorrelation'
+  medianWindowSize: 7,
+  minConfidence: 0.28,
+})
+
+const audio: AudioProvider = {
+  /* your implementation: getSampleRate, onFrame, start, stop */
+}
+const detector = createPitchDetector(settings)
+const session = new TunerSession(audio, detector, settings)
+
+// Optional: guitar / bass context for string dots and in-tune hints
+const tuning = findTuning('guitar', 'guitar-standard')
+session.setTuning(tuning ?? null)
+session.applyPreferences({ centsThreshold: 5 })
+
+session.on('started', () => {
+  console.log('capture started')
+})
+session.on('stopped', () => {
+  console.log('capture stopped')
+})
+session.on('error', (err) => {
+  console.error(err.message)
+})
+
+session.on('result', (r: TunerResult) => {
+  // Smoothed display pitch (Hz); may hold last confident value if current frame is weak
+  console.log(r.frequency)
+
+  // Nearest chromatic note
+  console.log(r.note, r.octave) // e.g. "A", 4
+
+  // Cents from that semitone (-50 … +50 after rounding in core helpers)
+  console.log(r.cents)
+
+  // If setTuning() was used: nearest string, how far in cents, and in-tune vs prefs
+  if (r.closestString) {
+    console.log(
+      r.closestString.name,
+      r.closestString.centsOff,
+      r.closestString.inTune,
+    )
+  }
+
+  // Copy of open strings for UI pills / labels, or null if no tuning selected
+  console.log(r.tuningStrings)
+})
+
+await session.start()
+// … later …
+session.stop()
+```
+
+Each **`result`** event is one synthesis of the pipeline: **raw detector output → median window → confidence gate (hold last good pitch when unsure) → MIDI / note / cents / optional string math**.
+
+## More
+
+Source and CLI: [github.com/mducharme/Tuner](https://github.com/mducharme/Tuner).
+
+## Publish (maintainers)
+
+From the monorepo root (with a clean build and tests green):
+
+```bash
+pnpm --filter tuner-core build
+pnpm --filter tuner-core run package:assert
+pnpm --filter tuner-core publish --access public
+```
+
+Prefer **npm provenance** via GitHub Actions (see `.github/workflows/publish.yml`) and [trusted publishers](https://docs.npmjs.com/trusted-publishers).
+
+`prepublishOnly` runs `tsc`, `publint --strict`, and **Are The Types Wrong?** (`attw --pack . --profile esm-only`).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/detectors/autocorrelation.d.ts

@@ -0,0 +1,19 @@
+import type { PitchDetection, PitchDetector } from '../types.js';
+/**
+ * Autocorrelation-based pitch detector.
+ * Fast and simple — good enough for v1, swappable for YIN/McLeod later.
+ */
+export declare class AutocorrelationDetector implements PitchDetector {
+    private readonly minFrequency;
+    private readonly maxFrequency;
+    private readonly clarityThreshold;
+    constructor({ minFrequency, // ~B1, covers bass guitar low B
+    maxFrequency, // covers most instruments
+    clarityThreshold, }?: {
+        minFrequency?: number | undefined;
+        maxFrequency?: number | undefined;
+        clarityThreshold?: number | undefined;
+    });
+    detect(samples: Float32Array, sampleRate: number): PitchDetection;
+}
+//# sourceMappingURL=autocorrelation.d.ts.map

package/dist/detectors/autocorrelation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocorrelation.d.ts","sourceRoot":"","sources":["../../src/detectors/autocorrelation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhE;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;gBAE7B,EACV,YAAiB,EAAE,gCAAgC;IACnD,YAAmB,EAAE,0BAA0B;IAE/C,gBAAsB,GACvB;;;;KAAK;IAMN,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc;CAkDlE"}

package/dist/detectors/autocorrelation.js

@@ -0,0 +1,60 @@
+/**
+ * Autocorrelation-based pitch detector.
+ * Fast and simple — good enough for v1, swappable for YIN/McLeod later.
+ */
+export class AutocorrelationDetector {
+    minFrequency;
+    maxFrequency;
+    clarityThreshold;
+    constructor({ minFrequency = 60, // ~B1, covers bass guitar low B
+    maxFrequency = 1400, // covers most instruments
+    // Mic + room noise yields much lower "clarity" than synthetic sines; 0.9 rejected almost all real input.
+    clarityThreshold = 0.2, } = {}) {
+        this.minFrequency = minFrequency;
+        this.maxFrequency = maxFrequency;
+        this.clarityThreshold = clarityThreshold;
+    }
+    detect(samples, sampleRate) {
+        const minPeriod = Math.ceil(sampleRate / this.maxFrequency);
+        const maxPeriod = Math.floor(sampleRate / this.minFrequency);
+        const n = samples.length;
+        let bestPeriod = -1;
+        let bestCorrelation = 0;
+        let rms = 0;
+        for (let i = 0; i < n; i++) {
+            rms += (samples[i] ?? 0) * (samples[i] ?? 0);
+        }
+        rms = Math.sqrt(rms / n);
+        if (rms < 0.01) {
+            return { frequency: null, confidence: 0 };
+        }
+        for (let period = minPeriod; period <= maxPeriod; period++) {
+            let correlation = 0;
+            for (let i = 0; i < n - period; i++) {
+                correlation += (samples[i] ?? 0) * (samples[i + period] ?? 0);
+            }
+            correlation /= n - period;
+            if (correlation > bestCorrelation) {
+                bestCorrelation = correlation;
+                bestPeriod = period;
+            }
+        }
+        if (bestPeriod === -1) {
+            return { frequency: null, confidence: 0 };
+        }
+        let maxValue = 0;
+        for (let i = 0; i < n; i++) {
+            maxValue = Math.max(maxValue, Math.abs(samples[i] ?? 0));
+        }
+        const clarity = maxValue > 0 ? bestCorrelation / (maxValue * maxValue) : 0;
+        const confidence = Math.min(1, Math.max(0, clarity));
+        if (clarity < this.clarityThreshold) {
+            return { frequency: null, confidence };
+        }
+        return {
+            frequency: sampleRate / bestPeriod,
+            confidence,
+        };
+    }
+}
+//# sourceMappingURL=autocorrelation.js.map

package/dist/detectors/autocorrelation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocorrelation.js","sourceRoot":"","sources":["../../src/detectors/autocorrelation.ts"],"names":[],"mappings":"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"}

package/dist/detectors/create-pitch-detector.d.ts

@@ -0,0 +1,4 @@
+import type { TunerSettings } from '../tuner-settings.js';
+import type { PitchDetector } from '../types.js';
+export declare function createPitchDetector(settings: TunerSettings): PitchDetector;
+//# sourceMappingURL=create-pitch-detector.d.ts.map

package/dist/detectors/create-pitch-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-pitch-detector.d.ts","sourceRoot":"","sources":["../../src/detectors/create-pitch-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAMhD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,aAAa,CAqC1E"}

package/dist/detectors/create-pitch-detector.js

@@ -0,0 +1,39 @@
+import { AutocorrelationDetector } from './autocorrelation.js';
+import { MpmDetector } from './mpm.js';
+import { PyinDetector } from './pyin.js';
+import { YinDetector } from './yin.js';
+export function createPitchDetector(settings) {
+    const d = settings.detector;
+    const bounds = { minFrequency: d.minFrequency, maxFrequency: d.maxFrequency };
+    if (settings.pitchDetector === 'autocorrelation') {
+        return new AutocorrelationDetector({
+            ...bounds,
+            clarityThreshold: d.clarityThreshold,
+        });
+    }
+    if (settings.pitchDetector === 'pyin') {
+        const p = d.pyin;
+        return new PyinDetector({
+            ...bounds,
+            yinSharpness: p.yinSharpness,
+            transitionSigmaSemitones: p.transitionSigmaSemitones,
+            maxJumpSemitones: p.maxJumpSemitones,
+            logPitchToUv: p.logPitchToUv,
+            logUvToPitch: p.logUvToPitch,
+            logUvToUv: p.logUvToUv,
+            firstDipSemitoneWeight: p.firstDipSemitoneWeight,
+            firstDipThreshold: p.firstDipThreshold,
+        });
+    }
+    if (settings.pitchDetector === 'mpm') {
+        return new MpmDetector({
+            ...bounds,
+            peakThreshold: d.mpmPeakThreshold,
+        });
+    }
+    return new YinDetector({
+        ...bounds,
+        threshold: d.yinThreshold,
+    });
+}
+//# sourceMappingURL=create-pitch-detector.js.map

package/dist/detectors/create-pitch-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-pitch-detector.js","sourceRoot":"","sources":["../../src/detectors/create-pitch-detector.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEtC,MAAM,UAAU,mBAAmB,CAAC,QAAuB;IACzD,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC3B,MAAM,MAAM,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAA;IAE7E,IAAI,QAAQ,CAAC,aAAa,KAAK,iBAAiB,EAAE,CAAC;QACjD,OAAO,IAAI,uBAAuB,CAAC;YACjC,GAAG,MAAM;YACT,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;SACrC,CAAC,CAAA;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,aAAa,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAA;QAChB,OAAO,IAAI,YAAY,CAAC;YACtB,GAAG,MAAM;YACT,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,wBAAwB,EAAE,CAAC,CAAC,wBAAwB;YACpD,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;YACpC,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,sBAAsB,EAAE,CAAC,CAAC,sBAAsB;YAChD,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;SACvC,CAAC,CAAA;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC;QACrC,OAAO,IAAI,WAAW,CAAC;YACrB,GAAG,MAAM;YACT,aAAa,EAAE,CAAC,CAAC,gBAAgB;SAClC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,IAAI,WAAW,CAAC;QACrB,GAAG,MAAM;QACT,SAAS,EAAE,CAAC,CAAC,YAAY;KAC1B,CAAC,CAAA;AACJ,CAAC"}

package/dist/detectors/mpm.d.ts

@@ -0,0 +1,21 @@
+import type { PitchDetection, PitchDetector } from '../types.js';
+/**
+ * McLeod Pitch Method (MPM) via the Normalized Square Difference Function (NSDF).
+ * McLeod & Wyvill — peaks in NSDF indicate candidate periods; we take the first
+ * qualifying peak from short τ upward to reduce octave/subharmonic confusion.
+ */
+export declare class MpmDetector implements PitchDetector {
+    private readonly minFrequency;
+    private readonly maxFrequency;
+    /** Minimum NSDF peak height (0…1, typ. 0.85–0.95) */
+    private readonly peakThreshold;
+    private readonly rmsThreshold;
+    constructor({ minFrequency, maxFrequency, peakThreshold, rmsThreshold, }?: {
+        minFrequency?: number | undefined;
+        maxFrequency?: number | undefined;
+        peakThreshold?: number | undefined;
+        rmsThreshold?: number | undefined;
+    });
+    detect(samples: Float32Array, sampleRate: number): PitchDetection;
+}
+//# sourceMappingURL=mpm.d.ts.map

package/dist/detectors/mpm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mpm.d.ts","sourceRoot":"","sources":["../../src/detectors/mpm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhE;;;;GAIG;AACH,qBAAa,WAAY,YAAW,aAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,EACV,YAAiB,EACjB,YAAmB,EACnB,aAAoB,EACpB,YAAmB,GACpB;;;;;KAAK;IAON,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc;CAqFlE"}

package/dist/detectors/mpm.js

@@ -0,0 +1,95 @@
+/**
+ * McLeod Pitch Method (MPM) via the Normalized Square Difference Function (NSDF).
+ * McLeod & Wyvill — peaks in NSDF indicate candidate periods; we take the first
+ * qualifying peak from short τ upward to reduce octave/subharmonic confusion.
+ */
+export class MpmDetector {
+    minFrequency;
+    maxFrequency;
+    /** Minimum NSDF peak height (0…1, typ. 0.85–0.95) */
+    peakThreshold;
+    rmsThreshold;
+    constructor({ minFrequency = 60, maxFrequency = 1400, peakThreshold = 0.88, rmsThreshold = 0.01, } = {}) {
+        this.minFrequency = minFrequency;
+        this.maxFrequency = maxFrequency;
+        this.peakThreshold = peakThreshold;
+        this.rmsThreshold = rmsThreshold;
+    }
+    detect(samples, sampleRate) {
+        const n = samples.length;
+        if (n < 4) {
+            return { frequency: null, confidence: 0 };
+        }
+        let rms = 0;
+        for (let i = 0; i < n; i++) {
+            const v = samples[i] ?? 0;
+            rms += v * v;
+        }
+        rms = Math.sqrt(rms / n);
+        if (rms < this.rmsThreshold) {
+            return { frequency: null, confidence: 0 };
+        }
+        const tauMin = Math.max(1, Math.ceil(sampleRate / this.maxFrequency));
+        const tauMaxFreq = Math.floor(sampleRate / this.minFrequency);
+        const tauMaxWin = Math.floor(n / 2) - 1;
+        const tauMax = Math.min(tauMaxFreq, tauMaxWin);
+        if (tauMin > tauMax) {
+            return { frequency: null, confidence: 0 };
+        }
+        const nsdf = new Float32Array(tauMax + 1);
+        nsdf[0] = 1;
+        for (let tau = 1; tau <= tauMax; tau++) {
+            let num = 0;
+            let den = 0;
+            for (let i = 0; i < n - tau; i++) {
+                const a = samples[i] ?? 0;
+                const b = samples[i + tau] ?? 0;
+                num += a * b;
+                den += a * a + b * b;
+            }
+            nsdf[tau] = den > 1e-20 ? (2 * num) / den : 0;
+        }
+        const searchLo = Math.max(2, tauMin);
+        const searchHi = tauMax - 1;
+        if (searchLo > searchHi) {
+            return { frequency: null, confidence: 0 };
+        }
+        let peakTau = -1;
+        let peakVal = 0;
+        for (let tau = searchLo; tau <= searchHi; tau++) {
+            const v = nsdf[tau] ?? 0;
+            const vp = nsdf[tau - 1] ?? 0;
+            const vn = nsdf[tau + 1] ?? 0;
+            if (v >= this.peakThreshold && v >= vp && v >= vn) {
+                peakTau = tau;
+                peakVal = v;
+                break;
+            }
+        }
+        if (peakTau < 0) {
+            let best = 0;
+            for (let tau = searchLo; tau <= searchHi; tau++) {
+                best = Math.max(best, nsdf[tau] ?? 0);
+            }
+            return { frequency: null, confidence: Math.max(0, Math.min(1, best)) };
+        }
+        let refinedTau = peakTau;
+        const alpha = nsdf[peakTau - 1] ?? 0;
+        const beta = nsdf[peakTau] ?? 0;
+        const gamma = nsdf[peakTau + 1] ?? 0;
+        const denom = alpha - 2 * beta + gamma;
+        if (Math.abs(denom) > 1e-12) {
+            const offset = (gamma - alpha) / (2 * denom);
+            refinedTau = peakTau + Math.max(-1, Math.min(1, offset));
+        }
+        const frequency = sampleRate / refinedTau;
+        if (frequency < this.minFrequency || frequency > this.maxFrequency) {
+            return { frequency: null, confidence: Math.max(0, Math.min(1, peakVal)) };
+        }
+        return {
+            frequency,
+            confidence: Math.max(0, Math.min(1, peakVal)),
+        };
+    }
+}
+//# sourceMappingURL=mpm.js.map

package/dist/detectors/mpm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mpm.js","sourceRoot":"","sources":["../../src/detectors/mpm.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACL,YAAY,CAAQ;IACpB,YAAY,CAAQ;IACrC,qDAAqD;IACpC,aAAa,CAAQ;IACrB,YAAY,CAAQ;IAErC,YAAY,EACV,YAAY,GAAG,EAAE,EACjB,YAAY,GAAG,IAAI,EACnB,aAAa,GAAG,IAAI,EACpB,YAAY,GAAG,IAAI,GACpB,GAAG,EAAE;QACJ,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAChC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAChC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;QAClC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAED,MAAM,CAAC,OAAqB,EAAE,UAAkB;QAC9C,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAA;QACxB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;QAC3C,CAAC;QAED,IAAI,GAAG,GAAG,CAAC,CAAA;QACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YACzB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;QACd,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAA;QACxB,IAAI,GAAG,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5B,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;QAC3C,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAA;QACrE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAA;QAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QAC9C,IAAI,MAAM,GAAG,MAAM,EAAE,CAAC;YACpB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;QAC3C,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACzC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QACX,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,IAAI,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;YACvC,IAAI,GAAG,GAAG,CAAC,CAAA;YACX,IAAI,GAAG,GAAG,CAAC,CAAA;YACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBACjC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;gBACzB,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;gBAC/B,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;gBACZ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACtB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/C,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QACpC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAA;QAC3B,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;YACxB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;QAC3C,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,CAAC,CAAA;QAChB,IAAI,OAAO,GAAG,CAAC,CAAA;QACf,KAAK,IAAI,GAAG,GAAG,QAAQ,EAAE,GAAG,IAAI,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YACxB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;YAC7B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;YAC7B,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAClD,OAAO,GAAG,GAAG,CAAA;gBACb,OAAO,GAAG,CAAC,CAAA;gBACX,MAAK;YACP,CAAC;QACH,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,IAAI,IAAI,GAAG,CAAC,CAAA;YACZ,KAAK,IAAI,GAAG,GAAG,QAAQ,EAAE,GAAG,IAAI,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC;gBAChD,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAA;QACxE,CAAC;QAED,IAAI,UAAU,GAAG,OAAO,CAAA;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QACpC,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,KAAK,CAAA;QACtC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAA;YAC5C,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;QAC1D,CAAC;QAED,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;QACzC,IAAI,SAAS,GAAG,IAAI,CAAC,YAAY,IAAI,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACnE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,CAAA;QAC3E,CAAC;QAED,OAAO;YACL,SAAS;YACT,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;SAC9C,CAAA;IACH,CAAC;CACF"}

package/dist/detectors/pyin.d.ts

@@ -0,0 +1,49 @@
+import type { PitchDetection, PitchDetector } from '../types.js';
+export interface PyinDetectorOptions {
+    minFrequency?: number;
+    maxFrequency?: number;
+    rmsThreshold?: number;
+    /** Maps YIN CMND value to emission cost; higher → sharper peaks matter more */
+    yinSharpness?: number;
+    /** Gaussian σ (semitones) for pitch continuity in the HMM */
+    transitionSigmaSemitones?: number;
+    /** Max MIDI index jump per frame when scoring transitions */
+    maxJumpSemitones?: number;
+    /** log P(voiced → unvoiced) */
+    logPitchToUv?: number;
+    /** log P(unvoiced → voiced) */
+    logUvToPitch?: number;
+    /** log P(unvoiced → unvoiced) */
+    logUvToUv?: number;
+    firstDipSemitoneWeight?: number;
+    firstDipThreshold?: number;
+}
+/**
+ * Probabilistic YIN–style observations + discrete-pitch HMM (Viterbi forward step).
+ * Stateful: call `reset()` when stopping capture so the Markov chain does not bridge sessions.
+ */
+export declare class PyinDetector implements PitchDetector {
+    private readonly minFrequency;
+    private readonly maxFrequency;
+    private readonly rmsThreshold;
+    private readonly yinSharpness;
+    private readonly transitionSigmaSemitones;
+    private readonly maxJumpSemitones;
+    private readonly logPitchToUv;
+    private readonly logUvToPitch;
+    private readonly logUvToUv;
+    private readonly firstDipSemitoneWeight;
+    private readonly firstDipThreshold;
+    private readonly midiMin;
+    private readonly midiMax;
+    private readonly nPitch;
+    private readonly uvIndex;
+    private readonly nStates;
+    private prevLog;
+    private hasPrev;
+    constructor(options?: PyinDetectorOptions);
+    reset(): void;
+    detect(samples: Float32Array, sampleRate: number): PitchDetection;
+    private secondBestLog;
+}
+//# sourceMappingURL=pyin.d.ts.map

package/dist/detectors/pyin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pyin.d.ts","sourceRoot":"","sources":["../../src/detectors/pyin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAKhE,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAQ;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAE1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAQ;gBAEX,OAAO,GAAE,mBAAwB;IAqB7C,KAAK,IAAI,IAAI;IAKb,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc;IAoIjE,OAAO,CAAC,aAAa;CAatB"}