Correlation-Based Pitch Class Extraction — User Guide

Intelligent note isolation: analyzes pitch content, identifies musical notes, and extracts specific pitch classes using matched filter correlation for melody analysis and note separation.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 0.1 (2025) License: MIT License Repo: https://github.com/ShaiCohen-ops/Praat-plugin_AudioTools

Contents:

What this does Quick start Signal Processing Theory Processing Workflow Parameters Applications

What this does

This script implements correlation-based pitch class extraction — an intelligent signal processing technique that isolates specific musical notes from polyphonic audio using matched filter principles. Unlike simple filtering, this method provides: (1) Pitch analysis: Comprehensive fundamental frequency detection and note identification. (2) Musical intelligence: Automatic clustering of pitches into musical note classes (C4, D4, etc.). (3) Template matching: Uses the cleanest occurrence of each note as a matched filter template. (4) Cross-correlation detection: Identifies all occurrences of the target note throughout the audio. (5) Intelligent gating: Removes weak correlations to isolate only significant note events. Process analyzes pitch content, identifies unique note classes, lets user select target note, extracts template segment, performs cross-correlation, and applies intelligent gating. Result: precise isolation of specific musical notes from complex audio with detailed analysis of their temporal distribution.

Key Features:

Automatic Note Detection — Identifies all musical pitches present in audio
MIDI Note Mapping — Converts frequencies to standard note names (C4, D#5, etc.)
Template Selection — Automatically finds best example of each note
Matched Filter Correlation — Professional signal detection technique
Intelligent Gating — Removes weak matches for clean results
Comprehensive Analysis — Multiple output objects for detailed examination

What is correlation-based pitch extraction? Traditional pitch processing: Simple filtering or fundamental frequency tracking. Correlation-based extraction: Advanced signal processing that uses the audio's own content as a template for detecting specific musical events. Key characteristics: (1) Content-aware: Uses actual audio examples rather than synthetic templates. (2) Musical understanding: Recognizes pitch classes and note names. (3) Temporal precision: Locates exact timing of note occurrences. (4) Robust detection: Works with varying timbres and amplitudes. Advantages: (1) Accuracy: Detects notes based on actual audio characteristics. (2) Flexibility: Adapts to different instruments and voices. (3) Musical relevance: Results in standard musical notation. (4) Comprehensive analysis: Provides multiple perspectives on the audio. Use cases: Music analysis (melody extraction, note detection), audio editing (isolating specific notes), music education (pitch identification), music information retrieval (content analysis), sound design (note-based processing), forensic audio (pitch-based event detection).

Technical Implementation: (1) Pitch analysis: Extract fundamental frequency contour using autocorrelation or cross-correlation methods. (2) Note clustering: Convert frequencies to MIDI note numbers and group into pitch classes. (3) Template selection: Find longest continuous segment for each note as optimal template. (4) Cross-correlation: Compute matched filter response using template and original audio. (5) Gating: Apply amplitude threshold to isolate significant correlation peaks. (6) Normalization: Scale output for consistent levels. Key insight: Using the audio's own content as a matched filter template provides optimal detection for that specific performance's timbral characteristics, making the method robust to variations in instrument, recording quality, and performance style.

Quick start

In Praat, select exactly one Sound object containing melodic content.
Run script… → pitch_class_extraction.praat.
Set Pitch_floor and Pitch_ceiling appropriate for your audio.
Choose Method for pitch detection (Accurate for clean signals, Standard for noisy).
Enable Apply_gate_function and set Gate_threshold for clean results.
Enable Normalize_result for consistent output levels.
Click OK — script analyzes pitch and shows detected notes.
Select target note from the dialog that appears.
Click Extract — note isolation process completes.

Quick tip: Use monophonic audio (single melody line) for best results. Set pitch floor/ceiling to match your audio's range — typical vocal range: 80-400 Hz, instrumental melodies: 50-1000 Hz. Choose Accurate method for clean recordings with clear pitch, Standard method for noisy or complex signals. The script automatically identifies all musical notes present and displays them with frequencies — choose the note you want to isolate. Enable gating with threshold around -30 to -40 dB to remove weak matches. Processing creates four objects: pitch analysis, template (clean note example), correlation (detection signal), and result (isolated note occurrences). Peaks in the result show where your target note occurs in the melody.

Important: MONOPHONIC AUDIO WORKS BEST — polyphonic audio (chords, multiple instruments) may produce unreliable pitch detection. Very short audio files (< 2 seconds) may not contain enough pitch data for reliable analysis. Extreme pitch ranges or very rapid pitch changes may challenge the detection algorithm. The gate threshold is relative to the peak correlation — set appropriately to capture all significant note events without including noise. Template selection uses the longest continuous segment of each note — ensure your audio contains clear, sustained examples of the target note. Processing time increases with audio duration — long files may take several minutes. Always verify results by listening to the extracted output and comparing with the original.

Signal Processing Theory

Pitch Detection Fundamentals

Fundamental Frequency Analysis

Pitch detection methods:

Autocorrelation method (Standard): For signal x[n], compute: R[τ] = Σ x[n] × x[n+τ] Fundamental period T0 = argmax(R[τ]) for τ > 0 Fundamental frequency f0 = 1/T0 Cross-correlation method (Accurate): Compare signal with windowed versions: CC[τ] = Σ x[n] × w[n] × x[n+τ] × w[n+τ] Uses complementary windowing for better accuracy More robust to noise and formant structure Pitch contour extraction: Compute f0 at regular time intervals (frames) Typically 10ms frame shift for temporal resolution Voicing decision: reliable f0 vs unvoiced regions In this implementation: Method 1 (Accurate): To Pitch (cc) - cross-correlation Method 2 (Standard): To Pitch - autocorrelation Both methods provide f0 contour over time

Why Two Pitch Detection Methods?

Method selection criteria:

Accurate (cc): Better for clean signals, precise f0 estimation
Standard (ac): More robust for noisy or complex signals
Performance: Cross-correlation more computationally intensive
Accuracy: Cross-correlation generally more precise for clear pitches

Musical Note Mapping

Frequency to MIDI Conversion

Equal temperament mapping:

MIDI note number calculation: MIDI = 12 × log₂(f / 440) + 69 Where: f = frequency in Hz 440 Hz = reference frequency (A4) 69 = MIDI note number for A4 Note name derivation: note_class = (MIDI - 12) mod 12 octave = floor((MIDI - 12) / 12) Note class mapping: 0: C, 1: C#, 2: D, 3: D#, 4: E, 5: F 6: F#, 7: G, 8: G#, 9: A, 10: A#, 11: B Example calculations: f = 261.63 Hz (Middle C) MIDI = 12 × log₂(261.63/440) + 69 ≈ 60 note_class = (60-12) mod 12 = 48 mod 12 = 0 → C octave = floor(48/12) = 4 → C4 f = 329.63 Hz (E4) MIDI = 12 × log₂(329.63/440) + 69 ≈ 64 note_class = (64-12) mod 12 = 52 mod 12 = 4 → E octave = floor(52/12) = 4 → E4 Pitch clustering: Round MIDI numbers to nearest integer Group all frequencies mapping to same MIDI note Calculate average frequency for each note class

Why MIDI Note Mapping?

Musical advantages:

Standardization: Universal note naming system
Perceptual relevance: Matches human pitch perception
Equal temperament: Standard musical tuning system
Instrument compatibility: Works with all Western instruments

Matched Filter Correlation

Cross-Correlation Detection

Template matching mathematics:

Cross-correlation definition: For template t[n] and signal x[n]: y[τ] = Σ x[n] × t[n-τ] Where τ = time lag (sample offset) y[τ] = correlation at lag τ Peak normalization: Normalize by template energy: y_norm[τ] = y[τ] / √(Σ t²[n]) Detection principle: High correlation when template matches signal Peaks indicate positions where target note occurs Amplitude indicates match quality In this implementation: Template = cleanest occurrence of target note Signal = original audio Correlation computed for all time lags Peak at 0.99 normalization for consistent scaling Matched filter optimality: Maximizes signal-to-noise ratio for known template Optimal detection for template in white noise

Why Template Matching Works

Detection advantages:

Timbral matching: Uses actual instrument/voice characteristics
Phase coherence: Detects waveform similarity
Amplitude invariance: Works across different loudness levels
Temporal precision: Locates exact note onset times

🎵 Musical Intuition

Pitch detection:

Finds the fundamental frequency pattern

Like identifying the main note being sung/played

Note clustering:

Groups similar pitches into musical notes

Like naming the notes in a melody

Template matching:

Uses a good example to find all similar ones

Like using a "wanted poster" to find all occurrences

Complete Processing Pipeline

SETUP: Select Sound object with melodic content Set pitch analysis parameters Extract audio properties (duration, sampling rate) STEP 1: PITCH ANALYSIS Compute fundamental frequency contour Use selected method (cc or ac) Create Pitch object with f0 values STEP 2: PITCH EXTRACTION Extract all valid f0 values from Pitch object Store frequencies and timing information STEP 3: NOTE CLUSTERING Convert frequencies to MIDI note numbers Group into unique pitch classes Calculate average frequency for each note Map to standard note names (C4, D#5, etc.) STEP 4: USER SELECTION Display detected notes with frequencies User chooses target note for extraction STEP 5: TEMPLATE SELECTION Find longest continuous segment of target note Extract this segment as matched filter template Add small padding for complete waveform STEP 6: CROSS-CORRELATION Compute cross-correlation between template and original Normalize correlation peak to 0.99 Create correlation signal showing detection strength STEP 7: GATING Apply amplitude threshold to correlation Remove weak matches below gate threshold Isolate significant note occurrences STEP 8: NORMALIZATION Scale result to consistent amplitude Prepare for playback and analysis OUTPUT: 4 objects: Pitch analysis, Template, Correlation, Result Comprehensive view of extraction process

Processing Workflow

Step 1: Pitch Analysis

🎯 Fundamental Frequency Extraction

Process: Analyzes audio to extract pitch contour over time

Output: Pitch object with f0 values and voicing decisions

Key parameters: Pitch floor, pitch ceiling, method selection

Pitch analysis details:

Parameter	Effect	Recommended Values
Pitch floor	Lowest detectable frequency	Male voice: 75 Hz, Female: 150 Hz, Instruments: 50 Hz
Pitch ceiling	Highest detectable frequency	Male: 300 Hz, Female: 600 Hz, Instruments: 1000 Hz
Method (cc)	Cross-correlation, accurate	Clean signals, precise instruments
Method (ac)	Autocorrelation, robust	Noisy audio, complex timbres

Step 2: Note Identification

🎵 Musical Note Mapping

Process: Converts frequencies to musical notes and clusters similar pitches

Output: List of detected notes with names and average frequencies

Key feature: Automatic MIDI note mapping and naming

Note identification process:

Frequency collection:
Extract all valid f0 values from pitch analysis
Typically hundreds to thousands of measurements

MIDI conversion:
Convert each frequency to MIDI note number
Round to nearest integer for note classification

Note clustering:
Group all frequencies mapping to same MIDI note
Calculate average frequency for each note class

Note naming:
Convert MIDI numbers to standard note names
Example: MIDI 60 → C4, MIDI 65 → F4

User presentation:
Display notes with frequencies and MIDI numbers
User selects target for extraction

Step 3: Template Extraction

📊 Optimal Template Selection

Process: Finds cleanest, longest example of target note

Output: Template sound object for matched filtering

Key feature: Automatic selection of best note example

Template selection criteria:

Criterion	Importance	Effect on Results
Duration	High	Longer templates provide better correlation
Pitch stability	High	Stable pitch gives cleaner correlation peaks
Amplitude consistency	Medium	Consistent level helps detection thresholding
Signal-to-noise ratio	Medium	Clean audio improves detection reliability

Step 4: Correlation & Gating

🔍 Matched Filter Detection

Process: Cross-correlation followed by intelligent gating

Output: Detection signal showing note occurrences

Key parameters: Gate threshold, normalization

Correlation and gating workflow:

Cross-correlation computation:
Compute correlation at all possible time lags
High values indicate good template matches
Normalize peak to 0.99 for consistent scaling

Peak analysis:
Identify correlation maximum for reference
This indicates best possible match quality

Gate threshold calculation:
Convert dB threshold to linear scale
threshold_linear = 10^(dB/20) × peak_correlation

Gating application:
Set all correlation values below threshold to zero
Preserve only significant detection peaks

Result interpretation:
Peaks in result show target note occurrences
Peak amplitude indicates detection confidence
Peak timing shows exact note positions

Parameters

Pitch Analysis Parameters

Parameter	Type	Default	Description
Pitch_floor_(Hz)	real	75	Lowest detectable fundamental frequency
Pitch_ceiling_(Hz)	real	600	Highest detectable fundamental frequency
Method	option	Accurate (cc)	Pitch detection algorithm

Post-processing Parameters

Parameter	Type	Default	Description
Apply_gate_function	boolean	1 (on)	Enable amplitude gating of weak correlations
Gate_threshold_(dB)	real	-40	Amplitude threshold for gating
Normalize_result	boolean	1 (on)	Scale output to consistent amplitude
Peak_amplitude	real	0.99	Target peak level for normalization

Automatic Calculations

Calculation	Formula	Purpose
MIDI note	12×log₂(f/440)+69	Convert frequency to musical note
Linear threshold	10^(dB/20)×peak	Convert dB gate to linear amplitude
Note name	MIDI mapping table	Convert MIDI to standard note names

Applications

Music Analysis and Transcription

Use case: Analyzing melodic content and identifying specific notes

Technique: Use to extract and study individual notes from melodies

Example: Analyze vocal melody to identify all occurrences of the tonic note

Audio Editing and Restoration

Use case: Isolating or removing specific notes from recordings

Technique: Extract target note, then use for selective processing

Workflow:

Extract problematic note (wrong pitch, bad tone)
Use correlation to locate all occurrences
Apply corrective processing only to those regions
Or mute/remove specific note occurrences

Music Education

Use case: Pitch training and note identification practice

Advantages:

Visual feedback on pitch accuracy
Precise note naming and frequency mapping
Detection of pitch stability and intonation
Analysis of vocal or instrumental technique

Example: Student performance analysis for pitch correction

Music Information Retrieval

Use case: Content-based audio analysis and indexing

Technique: Extract note distributions for musical similarity

Application: Melodic similarity, genre classification

Practical Workflow Examples

🎵 Melodic Analysis

Goal: Study the distribution of specific notes in a melody

Settings:

Audio: Monophonic melody (voice or instrument)
Pitch range: Appropriate for instrument (e.g., 80-400 Hz for voice)
Method: Accurate (cc) for clean recordings
Gate threshold: -35 dB
Target: Select tonic or other significant note

Result: Clear detection of when specific notes occur in melody

🎵 Pitch Correction Analysis

Goal: Identify and locate pitch errors in performance

Settings:

Audio: Student performance with some pitch issues
Pitch range: Set to expected performance range
Method: Standard (ac) for potentially unstable pitch
Gate threshold: -30 dB (more sensitive)
Target: Select notes that are frequently out of tune

Result: Identification of problematic note occurrences for focused practice

🎵 Instrument Technique Study

Goal: Analyze note production consistency

Settings:

Audio: Instrument playing scale or exercises
Pitch range: Full instrument range
Method: Accurate (cc) for detailed analysis
Gate threshold: -40 dB
Target: Select multiple notes for comparison

Result: Comparison of detection strength for different notes, indicating production consistency

Advanced Techniques

Creative analysis strategies:

Multiple note extraction: Run script multiple times for different target notes
Temporal analysis: Study timing patterns of specific notes
Amplitude correlation: Compare detection strength across different notes
Template comparison: Use different template segments to study variation
Threshold sensitivity: Experiment with different gate settings

The four output objects provide comprehensive analysis capabilities

Parameter optimization guide:

Clean signals: Use Accurate method with narrow pitch range
Noisy audio: Use Standard method with conservative gate threshold
Wide range: Set pitch ceiling high, let clustering handle note separation
Precise detection: Use lower gate thresholds (-45 to -50 dB)
Clean results: Use higher gate thresholds (-30 to -35 dB)
Educational use: Enable all post-processing for clear results

Troubleshooting Common Issues

Problem: No pitch detected
Cause: Pitch outside analysis range or insufficient voiced content
Solution: Adjust pitch floor/ceiling, ensure audio has clear pitch

Problem: Too many false detections
Cause: Gate threshold too low or template not representative
Solution: Increase gate threshold, check template quality

Problem: Missed note occurrences
Cause: Gate threshold too high or significant timbral variation
Solution: Decrease gate threshold, try different template segment

Problem: Poor note clustering
Cause: Unstable pitch or vibrato too wide
Solution: Use Standard method, consider pitch-stable audio

Technical Deep Dive

Signal Processing Mathematics

Cross-Correlation Properties

Mathematical foundations:

Cross-correlation definition: For continuous signals: (x ⋆ t)(τ) = ∫ x(t) × t(t-τ) dt For discrete signals: y[τ] = Σ x[n] × t[n-τ] Peak normalization: y_norm[τ] = y[τ] / √(Σ x²[n] × Σ t²[n]) Ensures maximum correlation = 1 for perfect match Detection statistics: For template length N and white noise: Expected correlation ~ N(0, 1/√N) Detection threshold based on desired false alarm rate Matched filter optimality: For known template in white Gaussian noise: Cross-correlation maximizes signal-to-noise ratio y[τ] is sufficient statistic for detection Practical implementation: Use FFT for efficient computation: O(N log N) vs O(N²) Zero-padding to avoid circular correlation effects Peak normalization for consistent thresholding

Pitch Detection Algorithms

Comparative analysis:

Autocorrelation method:
Computes: R[τ] = Σ x[n] × x[n+τ]
Peaks at multiples of fundamental period
Robust to noise, works with harmonic signals
Praat default for general-purpose pitch tracking

Cross-correlation method:
Computes: CC[τ] = Σ x[n] × w[n] × x[n+τ] × w[n+τ]
Uses complementary windows for accuracy
Better for precise f0 estimation
More computationally intensive

Performance comparison:
Accuracy: Cross-correlation generally more precise
Robustness: Autocorrelation better for noisy signals
Speed: Autocorrelation faster for most cases
Memory: Similar requirements for both methods

Selection guidance:
Clean signals → Cross-correlation for precision
Noisy/complex signals → Autocorrelation for robustness
Real-time applications → Autocorrelation for speed
Analysis applications → Cross-correlation for accuracy