@audio/pitch 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/readme.md +20 -151
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audio/pitch",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "type": "module",
5
5
  "description": "Pitch detection — umbrella for @audio/pitch-* atoms (YIN, pYIN, McLeod, HPS, cepstrum, SWIPE, autocorrelation, AMDF)",
6
6
  "exports": {
package/readme.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # @audio/pitch [![test](https://github.com/audiojs/pitch/actions/workflows/test.yml/badge.svg)](https://github.com/audiojs/pitch/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@audio/pitch)](https://www.npmjs.com/package/@audio/pitch) [![MIT](https://img.shields.io/badge/MIT-%E0%A5%90-white)](https://github.com/krishnized/license)
2
2
 
3
- Pitch, chroma, chord and key detection. YIN, McLeod, pYIN, HPS, cepstrum, SWIPE, autocorrelation, AMDF, NNLS chroma, chord templates, Krumhansl-Schmuckler.
3
+ Pitch detection (F0 estimation). YIN, McLeod, pYIN, autocorrelation, AMDF, HPS, cepstrum, SWIPE.
4
4
 
5
5
  <table><tr><td valign="top">
6
6
 
7
- ### Pitch
7
+ ### Time-domain
8
8
 
9
9
  **[YIN](#yin)** — cumulative mean normalized difference<br>
10
10
  **[McLeod](#mcleod)** — normalized square difference (MPM)<br>
@@ -14,22 +14,16 @@ Pitch, chroma, chord and key detection. YIN, McLeod, pYIN, HPS, cepstrum, SWIPE,
14
14
 
15
15
  </td><td valign="top">
16
16
 
17
- ### Spectral pitch
17
+ ### Spectral
18
18
 
19
19
  **[HPS](#hps)** — harmonic product spectrum<br>
20
20
  **[Cepstrum](#cepstrum)** — real cepstrum peak picking<br>
21
21
  **[SWIPE](#swipe)** — sawtooth waveform inspired estimator<br>
22
22
 
23
- </td><td valign="top">
24
-
25
- ### Harmony
26
-
27
- **[Chroma](#chroma)** — PCP / NNLS pitch-class profiles<br>
28
- **[Chord](#chord)** — template matching + Viterbi smoothing<br>
29
- **[Key](#key)** — Krumhansl-Schmuckler key finding<br>
30
-
31
23
  </td></tr></table>
32
24
 
25
+ > Chroma, chord and key detection moved to [@audio/mir](https://github.com/audiojs/mir) (`mir-chroma`, `mir-chord`, `mir-key`).
26
+
33
27
 
34
28
  ## Install
35
29
 
@@ -41,21 +35,13 @@ npm install @audio/pitch
41
35
  ## Usage
42
36
 
43
37
  ```js
44
- import { yin, mcleod, chroma, chord, key } from '@audio/pitch'
38
+ import { yin, mcleod } from '@audio/pitch'
45
39
 
46
40
  let fs = 44100
47
41
  let frame = new Float32Array(2048) // fill from your audio source
48
42
 
49
- // pitch
50
43
  let result = yin(frame, { fs })
51
44
  // → { freq: 440.1, clarity: 0.97 } or null
52
-
53
- // chroma → chord → key
54
- let c = chroma(frame, { fs, method: 'nnls' })
55
- let ch = chord(c)
56
- // → { root: 0, quality: 'maj', label: 'C', confidence: 0.92 }
57
- let k = key(c)
58
- // → { tonic: 0, mode: 'major', label: 'C', confidence: 0.85, scores: [...] }
59
45
  ```
60
46
 
61
47
  > Works in Node.js and browser. No Web Audio API needed — operates on raw `Float32Array` samples.
@@ -71,19 +57,17 @@ for (let i = 0; i + 2048 <= samples.length; i += hop) {
71
57
  }
72
58
  ```
73
59
 
74
- **Full pipeline** — pitch → chroma → chord → key on a sequence of frames:
60
+ **Harmony pipeline** — chroma → chord → key lives in [@audio/mir](https://github.com/audiojs/mir):
75
61
 
76
62
  ```js
77
- import { chroma, chord, smoothChords, key } from '@audio/pitch'
63
+ import { chroma, chord, smoothChords, key } from '@audio/mir'
78
64
 
79
65
  let frames = []
80
66
  for (let i = 0; i + 4096 <= samples.length; i += 2048) {
81
67
  frames.push(chroma(samples.subarray(i, i + 4096), { fs, method: 'nnls' }))
82
68
  }
83
69
  let chords = smoothChords(frames, { selfProb: 0.5 })
84
- // → [{ root: 0, quality: 'maj', label: 'C' }, ...]
85
70
  let k = key(frames)
86
- // → { tonic: 0, mode: 'major', label: 'C', confidence: 0.85, scores: [...] }
87
71
  ```
88
72
 
89
73
 
@@ -95,7 +79,9 @@ All pitch algorithms return `{ freq, clarity } | null`:
95
79
  - `clarity` — algorithm-specific confidence in `[0, 1]`
96
80
  - `null` — no periodic structure found (silence, noise, polyphony)
97
81
 
98
- Time-domain algorithms (YIN, McLeod, pYIN, autocorrelation, AMDF) accept any buffer length. Spectral algorithms (HPS, cepstrum, SWIPE, chroma) require power-of-2 length.
82
+ Time-domain algorithms (YIN, McLeod, pYIN, autocorrelation, AMDF) accept any buffer length. Spectral algorithms (HPS, cepstrum, SWIPE) require power-of-2 length.
83
+
84
+ Each algorithm is also installable standalone: `npm install @audio/pitch-yin` etc.
99
85
 
100
86
 
101
87
  ---
@@ -106,7 +92,7 @@ Time-domain algorithms (YIN, McLeod, pYIN, autocorrelation, AMDF) accept any buf
106
92
  **de Cheveigné & Kawahara, 2002.** The reference algorithm for monophonic pitch estimation. Most cited, most tested, most robust.
107
93
 
108
94
  ```js
109
- import yin from '@audio/pitch/yin.js'
95
+ import yin from '@audio/pitch-yin'
110
96
 
111
97
  let result = yin(samples, { fs: 44100 })
112
98
  ```
@@ -127,7 +113,7 @@ let result = yin(samples, { fs: 44100 })
127
113
  **McLeod & Wyvill, 2005.** Normalized square difference with smarter peak picking. Handles smaller windows — good for vibrato and fast pitch changes.
128
114
 
129
115
  ```js
130
- import mcleod from '@audio/pitch/mcleod.js'
116
+ import mcleod from '@audio/pitch-mcleod'
131
117
 
132
118
  let result = mcleod(samples, { fs: 44100 })
133
119
  ```
@@ -148,7 +134,7 @@ let result = mcleod(samples, { fs: 44100 })
148
134
  **Mauch & Dixon, 2014.** Probabilistic YIN — runs YIN at multiple thresholds weighted by a Beta(2, 18) prior, producing a distribution over candidate pitches instead of a single hard pick. More robust than YIN on ambiguous frames.
149
135
 
150
136
  ```js
151
- import pyin from '@audio/pitch/pyin.js'
137
+ import pyin from '@audio/pitch-pyin'
152
138
 
153
139
  let result = pyin(samples, { fs: 44100 })
154
140
  // → { freq: 440.1, clarity: 0.92, candidates: [{ freq: 440.1, prob: 0.85 }, ...] }
@@ -170,7 +156,7 @@ let result = pyin(samples, { fs: 44100 })
170
156
  Normalized autocorrelation — the simplest pitch estimator. Educational baseline.
171
157
 
172
158
  ```js
173
- import autocorrelation from '@audio/pitch/autocorrelation.js'
159
+ import autocorrelation from '@audio/pitch-autocorrelation'
174
160
 
175
161
  let result = autocorrelation(samples, { fs: 44100 })
176
162
  ```
@@ -191,7 +177,7 @@ let result = autocorrelation(samples, { fs: 44100 })
191
177
  **Ross et al., 1974.** Average Magnitude Difference Function — the classical predecessor to YIN. Measures average absolute difference between a signal and its delayed copy; minima indicate periodicity.
192
178
 
193
179
  ```js
194
- import amdf from '@audio/pitch/amdf.js'
180
+ import amdf from '@audio/pitch-amdf'
195
181
 
196
182
  let result = amdf(samples, { fs: 44100 })
197
183
  ```
@@ -217,7 +203,7 @@ let result = amdf(samples, { fs: 44100 })
217
203
  **Schroeder, 1968.** Harmonic Product Spectrum — multiplies the spectrum by its downsampled copies so that harmonic peaks align at the fundamental. Robust to the missing-fundamental problem.
218
204
 
219
205
  ```js
220
- import hps from '@audio/pitch/hps.js'
206
+ import hps from '@audio/pitch-hps'
221
207
 
222
208
  let result = hps(samples, { fs: 44100 })
223
209
  ```
@@ -242,7 +228,7 @@ let result = hps(samples, { fs: 44100 })
242
228
  **Noll, 1967.** Real cepstrum — $c(\tau) = \text{IFFT}(\log |\text{FFT}(x)|)$. A peak at quefrency $\tau$ corresponds to period $\tau$ in the time domain.
243
229
 
244
230
  ```js
245
- import cepstrum from '@audio/pitch/cepstrum.js'
231
+ import cepstrum from '@audio/pitch-cepstrum'
246
232
 
247
233
  let result = cepstrum(samples, { fs: 44100 })
248
234
  ```
@@ -267,7 +253,7 @@ let result = cepstrum(samples, { fs: 44100 })
267
253
  Simplified single-window form: uses one FFT instead of the multi-resolution loudness pyramid of the original paper — sufficient for stationary windows.
268
254
 
269
255
  ```js
270
- import swipe from '@audio/pitch/swipe.js'
256
+ import swipe from '@audio/pitch-swipe'
271
257
 
272
258
  let result = swipe(samples, { fs: 44100 })
273
259
  ```
@@ -289,124 +275,6 @@ let result = swipe(samples, { fs: 44100 })
289
275
  ---
290
276
 
291
277
 
292
- ## Chroma
293
-
294
- **Fujishima, 1999 (PCP) / Mauch & Dixon, 2010 (NNLS).** Chroma feature — a 12-D vector where each bin holds the energy attributed to one pitch class (C, C#, ..., B).
295
-
296
- ```js
297
- import chroma from '@audio/pitch/chroma.js'
298
-
299
- // PCP — classical spectral folding
300
- let c = chroma(samples, { fs: 44100 })
301
-
302
- // NNLS — nonnegative least squares (cleaner for polyphonic audio)
303
- let c2 = chroma(samples, { fs: 44100, method: 'nnls' })
304
- ```
305
-
306
- ### PCP (default)
307
-
308
- Each spectral bin is mapped to its nearest pitch class and squared magnitudes are accumulated. Simple and fast.
309
-
310
- ### NNLS
311
-
312
- Fits the observed $\sqrt{\text{spectrum}}$ as a nonnegative combination of synthetic pitch-tone profiles (fundamental plus geometrically decaying overtones, Gaussian lobes in log-frequency with σ = 0.5 semitones). Uses multiplicative NMF updates: $a \leftarrow a \cdot (D^\top s) / (D^\top D a + \varepsilon)$. Suppresses octave and harmonic confusion on polyphonic audio.
313
-
314
- Pitch dictionary covers MIDI 24–96 (C1–C7) with configurable harmonics per tone.
315
-
316
- | Param | Default | |
317
- |---|---|---|
318
- | `fs` | `44100` | Sample rate (Hz) |
319
- | `method` | `'pcp'` | `'pcp'` or `'nnls'` |
320
- | `minFreq` | `65` | Min frequency for PCP mapping (~C2) |
321
- | `maxFreq` | `2093` | Max frequency for PCP mapping (~C7) |
322
- | `harmonics` | `8` | Overtones per pitch (NNLS only) |
323
- | `iterations` | `30` | NMF iterations (NNLS only) |
324
-
325
- **Returns:** `Float64Array(12)`, L1-normalized.
326
-
327
- **Use when:** Building chord/key detectors, music information retrieval, audio fingerprinting. NNLS for polyphonic; PCP for speed.<br>
328
- **Ref (PCP):** Fujishima, ["Realtime chord recognition of musical sound"](https://doi.org/10.1109/ICMC.1999.318003), ICMC 1999.<br>
329
- **Ref (NNLS):** Mauch & Dixon, ["Approximate Note Transcription for the Improved Identification of Difficult Chords"](https://doi.org/10.5281/zenodo.1416026), ISMIR 2010.<br>
330
- **Requires:** Power-of-2 window length.
331
-
332
-
333
- ## Chord
334
-
335
- **Fujishima, 1999 (templates) / Viterbi smoothing.** Classifies chroma frames as one of 24 major/minor triads via cosine similarity with binary templates.
336
-
337
- ```js
338
- import chord, { TEMPLATES, smooth as smoothChords } from '@audio/pitch/chord.js'
339
-
340
- // single frame
341
- let c = chord(chromaVec)
342
- // → { root: 0, quality: 'maj', label: 'C', confidence: 0.92 }
343
-
344
- // smoothed sequence
345
- let chords = smoothChords(chromaFrames, { selfProb: 0.5 })
346
- // → [{ root: 0, quality: 'maj', label: 'C' }, ...]
347
- ```
348
-
349
- ### `chord(chromaVec, opts)`
350
-
351
- Cosine similarity against 24 binary templates (12 major + 12 minor triads). Returns the best match with confidence score.
352
-
353
- | Param | Default | |
354
- |---|---|---|
355
- | `minConfidence` | `0.3` | Below this, returns quality `'N'` (no chord) |
356
-
357
- **Returns:** `{ root, quality, label, confidence }` where quality is `'maj'`, `'min'`, or `'N'`.
358
-
359
- ### `smooth(frames, opts)`
360
-
361
- Viterbi decoding with a sticky self-transition prior. Observation log-likelihood = 8 × cosine similarity (temperature 8 gives reasonably sharp distributions).
362
-
363
- | Param | Default | |
364
- |---|---|---|
365
- | `selfProb` | `0.5` | Self-transition probability (higher = smoother) |
366
-
367
- **Returns:** `{ root, quality, label }[]` — one chord per frame.
368
-
369
- ### `TEMPLATES`
370
-
371
- Exported array of 24 chord templates: `{ root, quality, label, vec }` where `vec` is a `Float64Array(12)` with 1 on chord tones.
372
-
373
- **Use when:** Quick chord labeling from chroma features. Combine with NNLS chroma for best results.<br>
374
- **Ref:** Fujishima, ["Realtime chord recognition of musical sound"](https://doi.org/10.1109/ICMC.1999.318003), ICMC 1999.
375
-
376
-
377
- ## Key
378
-
379
- **Krumhansl & Schmuckler.** Detects musical key from chroma via Pearson correlation against 24 rotated major/minor key profiles (Krumhansl-Kessler probe-tone ratings).
380
-
381
- ```js
382
- import key, { KK_MAJOR, KK_MINOR } from '@audio/pitch/key.js'
383
-
384
- let k = key(chromaVec)
385
- // → { tonic: 0, mode: 'major', label: 'C', confidence: 0.85, scores: [...] }
386
-
387
- // from multiple frames (averages internally)
388
- let k2 = key(chromaFrames)
389
- ```
390
-
391
- | Param | Default | |
392
- |---|---|---|
393
- | `profile` | `{ major: KK_MAJOR, minor: KK_MINOR }` | Custom key profiles |
394
-
395
- **Returns:** `{ tonic, mode, label, confidence, scores }` where `scores` is all 24 keys sorted descending.
396
-
397
- ### Exported profiles
398
-
399
- - `KK_MAJOR` — Krumhansl-Kessler major profile: `[6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]`
400
- - `KK_MINOR` — Krumhansl-Kessler minor profile: `[6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]`
401
-
402
- **Use when:** Key detection for music analysis, automatic transposition, music information retrieval.<br>
403
- **Ref:** Krumhansl, [*Cognitive Foundations of Musical Pitch*](https://doi.org/10.1093/acprof:oso/9780195148367.001.0001), Oxford 1990.<br>
404
- **Ref:** Temperley, ["What's Key for Key?"](https://doi.org/10.1525/mp.1999.17.1.65), Music Perception 1999.
405
-
406
-
407
- ---
408
-
409
-
410
278
  ## Comparison
411
279
 
412
280
  ### Pitch algorithms
@@ -424,6 +292,7 @@ let k2 = key(chromaFrames)
424
292
  ## See also
425
293
 
426
294
  - [fourier-transform](https://github.com/scijs/fourier-transform) — FFT used by spectral algorithms
295
+ - [mir](https://github.com/audiojs/mir) — chroma, chord, key, melody, structure, fingerprint
427
296
  - [beat](https://github.com/audiojs/beat) — onset detection, tempo estimation, beat tracking
428
297
  - [digital-filter](https://github.com/audiojs/digital-filter) — filter design and processing
429
298
  - [stretch](https://github.com/audiojs/stretch) — time stretching and pitch shifting