@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.
- package/package.json +1 -1
- package/readme.md +20 -151
package/package.json
CHANGED
package/readme.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# @audio/pitch [](https://github.com/audiojs/pitch/actions/workflows/test.yml) [](https://www.npmjs.com/package/@audio/pitch) [](https://github.com/krishnized/license)
|
|
2
2
|
|
|
3
|
-
Pitch
|
|
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
|
-
###
|
|
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
|
|
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
|
|
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
|
-
**
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|