# @suaveplan/audio-analysis-pitch - Universal pitch, key, and chord detection AnalysisOp plugins for the @suaveplan/audio-* family. YIN/McLeod/cepstrum f0 estimation, Krumhansl-Schmuckler / Temperley key finding, chromagram template-matched chord progressions with temporal smoothing.

Universal pitch, key, and chord detection Analysis Op plugins for the `@suaveplan/audio-*` family. Three detectors:

- `PitchDetector` — fundamental frequency via YIN (default), McLeod, or cepstrum.
- `KeyDetector` — Krumhansl-Schmuckler / Temperley key finding over an aggregated chromagram.
- `ChordDetector` — per-frame chromagram template matching with temporal smoothing.

Runs identically in browser and server. No DOM or Node-only APIs. The package vendors its own real FFT so it has no hard dependency on `@suaveplan/audio-analysis-spectrum`.

<!-- begin:auto-docs -->
## Documentation tree

- [chord-matching](./src/algorithms/chord-matching.md) — `chord-matching.ts` identifies the closest chord template (major / minor / diminished / augmented over twelve roots — 4…
- [chromagram](./src/algorithms/chromagram.md) — `chromagram.ts` folds a spectral frame into the twelve pitch classes used by Western tonal analysis. Each magnitude bin…
- [downmix](./src/algorithms/downmix.md) — `downmix.ts` provides the per-block mono-folding utilities shared by all three detectors in `@suaveplan/audio-analysis-…
- [key-finding](./src/algorithms/key-finding.md) — `key-finding.ts` correlates an aggregated chromagram against 24 major/minor key profiles to estimate the musical key of…
- [yin](./src/algorithms/yin.md) — `yin.ts` ships three fundamental-frequency estimators behind a unified `PitchEstimate` shape so the `PitchDetector` can…
- [chord-detector](./src/detector/chord-detector.md) — `chord-detector.ts` ships the `ChordDetector` Analysis Op which produces a time-ordered chord progression for an `Audio…
- [key-detector](./src/detector/key-detector.md) — `key-detector.ts` ships the `KeyDetector` Analysis Op (plugin slot 3) which estimates the musical key of an `AudioDocum…
- [pitch-detector](./src/detector/pitch-detector.md) — `pitch-detector.ts` exposes the `PitchDetector` class — the Analysis Op plugin (plugin slot 3 in the `@suaveplan/audio-…
- [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` defines the stable `AUDIO_ANALYSIS_PITCH.*` error code registry, the metadata table describing each co…
  - [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` defines the stable `AUDIO_ANALYSIS_PITCH.*` error code registry, the metadata table describing each co…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/audio-analysis-pitch
```

## Quick start

```ts
import {
    ChordDetector,
    KeyDetector,
    PitchDetector,
} from "@suaveplan/audio-analysis-pitch";

const pitch = await new PitchDetector().analyze(doc);
const key = await new KeyDetector().analyze(doc);
const chords = await new ChordDetector().analyze(doc);
```

## Subpath exports

Every feature module is independently importable for fine-grained tree-shaking:

```ts
import { yinPitch } from "@suaveplan/audio-analysis-pitch/algorithms/yin";
import { detectKey } from "@suaveplan/audio-analysis-pitch/algorithms/key-finding";
import { PitchDetector } from "@suaveplan/audio-analysis-pitch/detector/pitch-detector";
```

## Error codes

All errors are `AudioAnalysisError`s carrying one of the `AUDIO_ANALYSIS_PITCH.*` codes: `INVALID_OPTIONS`, `ABORTED`, `UNSUPPORTED_FORMAT`, `INSUFFICIENT_DATA`.

## License

MIT