pitchfinder

Pitchfinder provides several algorithms with different trade-offs:

• YIN: Best balance of accuracy and speed. Occasionally provides incorrect values.
• Mcleod: Good performance, particularly effective on lower frequencies.
• AMDF: Consistent frequency detection, but slow and accuracy is limited to approximately +/- 2%.
• Dynamic Wavelet: Very fast, but struggles with lower frequencies.
• YIN w/ FFT: (Coming soon)
• Goertzel: (Coming soon)

Install the pitchfinder package using npm to use pitch detection algorithms in Node.js or the browser.

npm install --save pitchfinder

To detect the pitch of a .wav file in a Node.js environment, use the wav-decoder library to convert the file buffer into a Float32Array. All pitchfinder algorithms operate on Float32Array inputs. The detector returns the pitch in Hz, or null if the pitch cannot be identified.

const fs = require("fs");
const WavDecoder = require("wav-decoder");
const Pitchfinder = require("pitchfinder");

// Initialize a detector (e.g., YIN)
const detectPitch = Pitchfinder.YIN();

const buffer = fs.readFileSync(PATH_TO_FILE);
const decoded = WavDecoder.decode.sync(buffer); // get audio data from file using `wav-decoder`
const float32Array = decoded.channelData[0]; // get a single channel of sound
const pitch = detectPitch(float32Array); // null if pitch cannot be identified

In the browser, you can extract a Float32Array from a WebAudio AudioBuffer using getChannelData(0) and pass it to a pitchfinder detector.

import * as Pitchfinder from "pitchfinder";

const myAudioBuffer = getAudioBuffer(); // assume this returns a WebAudio AudioBuffer object
const float32Array = myAudioBuffer.getChannelData(0); // get a single channel of sound

const detectPitch = Pitchfinder.AMDF();
const pitch = detectPitch(float32Array); // null if pitch cannot be identified

Each detector can be initialized with specific configuration options. All detectors support a global sampleRate option (defaults to 44100).

YIN

• threshold: Algorithm-specific threshold.
• probabilityThreshold: Prevents returning a pitch if the probability estimate is below this value.

McLeod

• bufferSize: Expected buffer size in samples (defaults to 1024).
• cutoff: Relative size of the chosen peak (e.g., 0.93 chooses the first peak higher than 93% of the highest peak). Defaults to 0.93.

AMDF

• minFrequency: Lowest detectable frequency.
• maxFrequency: Highest detectable frequency.
• sensitivity: Sensitivity setting.
• ratio: Ratio setting.

Dynamic Wavelet

• No special configuration available.

When initializing the Macleod detector, you can provide a MacleodConfig object to tune the algorithm's sensitivity and accuracy.

interface MacleodConfig {
  bufferSize: number;
  cutoff: number;
  sampleRate: number;
}

The AMDF function accepts a Partial<AMDFConfig> object. If parameters are omitted, the following defaults are used:

export interface AMDFConfig {
  sampleRate: number;
  minFrequency: number;
  maxFrequency: number;
  sensitivity: number;
  ratio: number;
}

When using the frequencies function to analyze a series of pitches, you can provide an options object to override the default configuration. The configuration determines how the audio buffer is chunked based on tempo and quantization.

Available options:

• tempo: The tempo in BPM (default: 120).
• quantization: The quantization factor (default: 4).
• sampleRate: The sample rate of the audio in Hz (default: 44100).

const options = {
  tempo: 120,
  quantization: 4,
  sampleRate: 44100
};

The DynamicWavelet detector accepts a DynamicWaveletConfig object to specify the audio properties of the input signal.

Note: The algorithm uses internal constants for MAX_FLWT_LEVELS, MAX_F, DIFFERENCE_LEVELS_N, and MAXIMA_THRESHOLD_RATIO which are not currently exposed via the configuration object.

export interface DynamicWaveletConfig {
  sampleRate: number;
}

When initializing the ACF2PLUS detector, you can provide a configuration object of type ACF2Config to specify the audio sample rate. This is required to correctly calculate the frequency from the detected period.

Config Options:

• sampleRate (number): The sample rate of the input audio buffer (e.g., 44100).

const config = {
  sampleRate: 44100
};

const detector = ACF2PLUS(config);

The ACF2PLUS function implements the ACF2+ algorithm for pitch detection. It returns a PitchDetector function that accepts a Float32Array of audio samples and returns the detected pitch in Hz. If the signal is too weak (RMS < 0.01), it returns -1.

To use it, call ACF2PLUS with a configuration object specifying the sampleRate of your audio data.

import { ACF2PLUS } from 'pitchfinder'; // Note: Import path depends on your project setup

const detector = ACF2PLUS({ sampleRate: 44100 });
const pitch = detector(new Float32Array([0.1, 0.2, ...]));