Krumhansl-Schmuckler Key Profiler — User Guide
Music key detection: implements the Krumhansl-Schmuckler algorithm for automatic key identification from audio signals using correlation with psychological key profiles.
What this does
This script implements the Krumhansl-Schmuckler key-finding algorithm — a psychological model of key perception that correlates audio pitch-class distributions with empirically-derived key profiles. Process: (1) Spectral analysis: Extract spectral peaks from sliding windows. (2) Chroma vector construction: Build 12-dimensional pitch-class distribution (C, C#, D, ..., B). (3) Profile correlation: Compute Pearson correlation between audio chroma and 24 key profiles (12 major, 12 minor). (4) Key identification: Select key with highest correlation as detected key. Result: Automatic key detection with confidence scores and visualizations.
Key Features:
- Psychological Model: Based on Krumhansl & Schmuckler's tonal hierarchy research
- 24-Key Detection: All major and minor keys (C Major through B Minor)
- Confidence Scoring: Pearson correlation coefficients (r-values) for each key
- Visual Chromagram: Pitch-class distribution visualization
- Full Correlation Profile: Optional display of all 24 key correlations
- Harmonic Filtering: Remove duplicate harmonics to focus on fundamentals
- Adaptive Processing: Window-based analysis for evolving tonality
Technical Implementation: (1) Preprocessing: Optional downsampling for speed, duration validation. (2) Window extraction: Sliding window analysis (Hanning window). (3) Spectral analysis: FFT, peak detection (local maxima). (4) Harmonic filtering: Remove duplicate harmonics based on frequency ratios. (5) Chroma accumulation: Convert frequencies to pitch classes, accumulate across windows. (6) Normalization: Create normalized chroma vector (sum = 1). (7) Correlation calculation: Pearson correlation with 24 key profiles. (8) Result selection: Find maximum correlation, compute confidence. (9) Visualization: Draw chromagram and correlation profile. (10) Output: Text results with top candidates.
Quick start
- In Praat, select exactly one Sound object (mono or stereo).
- Run script… →
Krumhansl_Schmuckler_Key_Profiler.praat. - Set Frequency Range (min: 60 Hz, max: 1500 Hz recommended).
- Adjust Window Settings (size: 0.5s, step: 0.25s typical).
- Enable Remove harmonic duplicates for cleaner analysis.
- Enable Use downsampling for faster processing on long files.
- Set Minimum confidence threshold (0.2 typical).
- Enable Show full correlation profile for detailed view.
- Click OK — analysis runs, results displayed graphically and textually.
Algorithm Theory
The Krumhansl-Schmuckler Key Profiles
🎵 Psychological Tonal Hierarchies
Empirical foundation: Based on probe-tone experiments (Krumhansl & Kessler, 1982)
Methodology: Listeners rated how well tones fit after tonal context
Result: 12-dimensional weight vectors for each key
C Major Profile:
C Minor Profile:
Mathematical Processing Pipeline
🔢 From Audio to Key Decision
Step 1: Chroma Vector Extraction
Step 2: Chroma Normalization
Step 3: Profile Correlation
Step 4: Key Selection
Profile Rotation for All Keys
🔄 Generating 24 Key Profiles
C Major profile is canonical major: P_maj = [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
C Minor profile is canonical minor: P_min = [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
For key with root r (0=C, 1=C#, ..., 11=B):
Result: 24 profiles (12 major × 12 minor) covering all keys
Spectral Analysis Details
🔬 Peak Detection & Harmonic Filtering
Peak detection algorithm:
Harmonic duplicate removal:
Frequency to pitch class conversion:
Window-Based Analysis
⏱️ Temporal Integration
Sliding window approach:
Hanning window function:
Parameters Explained
Analysis Parameters
| Parameter | Default | Range | Description |
|---|---|---|---|
| Min_frequency_Hz | 60 | 20-500 | Minimum frequency for analysis |
| Max_frequency_Hz | 1500 | 500-5000 | Maximum frequency for analysis |
| Harmonic_tolerance_cents | 50 | 10-100 | Tolerance for harmonic detection |
| Remove_harmonic_duplicates | yes | yes/no | Filter out harmonic multiples |
Window Settings
| Parameter | Default | Range | Description |
|---|---|---|---|
| Window_size_seconds | 0.5 | 0.05-5.0 | Analysis window duration |
| Time_step_seconds | 0.25 | 0.01-2.0 | Time between windows |
| Max_peaks_per_frame | 8 | 1-20 | Maximum spectral peaks per window |
Speed Optimization
| Parameter | Default | Description |
|---|---|---|
| Use_downsampling | yes | Downsample long files for speed |
| Target_sample_rate_Hz | 8000 | Target rate for downsampling |
Display Options
| Parameter | Default | Description |
|---|---|---|
| Show_full_correlation_profile | yes | Show all 24 key correlations |
| Minimum_confidence_threshold | 0.2 | Threshold for confidence warnings |
Parameter Guidelines
- Piano/solo instrument: Window size: 0.3-0.5s, Min freq: 60Hz, Max freq: 2000Hz
- Orchestral/polyphonic: Window size: 1.0-2.0s, Min freq: 40Hz, Max freq: 1500Hz
- Pop/rock with bass: Min freq: 40Hz (include bass), Harmonic tolerance: 30 cents
- Choral music: Window size: 0.5-1.0s, Max peaks: 12-15
- Short excerpts (<10s): Disable downsampling, smaller time step (0.1s)
- Noisy recordings: Increase harmonic tolerance (70-100 cents), lower min freq
Output Interpretation
Graphical Output
📊 Understanding the Visualizations
Top section: Key Result
- Detected Key: Primary result (e.g., "G Major")
- Confidence: Pearson r-value with interpretation
- Second choice: Runner-up key with correlation
Middle section: Chromagram
- 12 bars: One for each pitch class (C to B)
- Height: Relative strength of that pitch class
- Green bar: Tonic of detected key
- Blue bars: Other pitch classes
- Interpretation: Visual pattern of tonal hierarchy
Bottom section (optional): Full Correlation Profile
- 24 dots: One for each key (12 major, 12 minor)
- Height: Correlation strength (r-value)
- Green dot: Detected key
- Orange dots: Other keys with r > 0.3
- Gray dots: Low-correlation keys
Text Output (Info Window)
Confidence Interpretation
🎯 What the Correlation Values Mean
| Correlation (r) | Confidence Level | Interpretation |
|---|---|---|
| 0.8 - 1.0 | Excellent | Clear, unambiguous key |
| 0.6 - 0.8 | Very Good | Strong key feeling |
| 0.4 - 0.6 | Good | Moderately clear key |
| 0.2 - 0.4 | Low | Ambiguous or weakly tonal |
| < 0.2 | Very Low | Atonal or analysis failure |
Common Output Patterns
- Clear major key: High r (>0.7), dominant and mediant strong in chromagram
- Clear minor key: High r (>0.7), minor third and sixth prominent
- Modulating music: Moderate r (0.4-0.6), multiple keys with similar correlations
- Pentatonic music: Moderate r, only 5 pitch classes strong in chromagram
- Atonal music: Low r (<0.3), flat or random chromagram
- Ambiguous cases: Close runner-up (difference <0.1 in r-value)
Troubleshooting Output Issues
Cause: Frequency range doesn't match audio content
Solution: Adjust Min_frequency_Hz and Max_frequency_Hz
Cause: Audio may be atonal, noisy, or non-Western
Solution: Check if music is tonal Western music
Cause: Relative major/minor confusion, or modulation
Solution: Check runner-up keys, analyze shorter sections
Cause: Long file, no downsampling, small time step
Solution: Enable downsampling, increase time step
Applications
Musicological Research
Use case: Analyzing key usage in musical corpora
Workflow: Batch process multiple pieces, collect key statistics
Research questions: Key distributions by composer/period, modulation patterns
Music Information Retrieval
Use case: Automatic metadata generation for music databases
Application: Key-based music organization, playlist generation
Example: DJ software for harmonic mixing (matching compatible keys)
Music Education
Use case: Ear training and key identification practice
Tool: Students analyze excerpts, compare with algorithm
Pedagogical value: Visual feedback on tonal perception
Audio Processing
Use case: Key-aware audio effects and processing
Examples: Key-tuned equalization, harmonic exciters, adaptive filters
Real-time applications: Live performance processing, DJ tools
Music Transcription & Analysis
Use case: Assisting in automatic music transcription
Integration: Key information improves pitch spelling accuracy
Workflow: First detect key, then transcribe with key context
Composition & Production
Use case: Analyzing influence pieces, understanding key relationships
Creative applications: Key-based sample organization, harmonic planning
Production workflow: Ensure consistency in key across project
Practical Examples
🎵 Analyzing a Beethoven Sonata Movement
Goal: Detect primary key and modulations
Settings: Window size: 1.0s, Time step: 0.5s, Frequency range: 40-2000Hz
Method: Analyze whole movement, then sections separately
Results: Primary key: C Minor, Modulation to E♭ Major detected
📊 Batch Analysis of Pop Song Corpus
Goal: Statistical analysis of key preferences in pop music
Settings: Default parameters, enable downsampling for speed
Automation: Script to process folder of songs, export CSV results
Findings: Most common keys: C Major, G Major, D Major (guitar-friendly)
🎧 DJ Harmonic Mixing Assistant
Goal: Determine compatible keys for smooth transitions
Settings: Quick analysis: Window size: 0.3s, downsampling enabled
Camelot wheel mapping: Convert key results to Camelot codes (e.g., 8A = C Minor)
Application: Suggest tracks compatible with current playing key
Limitations & Considerations
- Equal temperament assumption: Historical tunings may reduce accuracy
- Western tonal system: Designed for Western common practice period music
- No chord recognition: Detects key, not individual chords
- Temporal resolution: Modulations faster than window size may be missed
- Monophonic bias: Works best with clear tonal center
- Psychological not acoustic: Based on perception, not acoustic properties
- Profile rigidity: Fixed profiles don't adapt to style variations
Advanced Techniques
- Custom profiles: Modify profile vectors for specific styles
- Dynamic windowing: Adapt window size based on musical features
- Multi-profile correlation: Test against multiple profile sets
- Temporal tracking: Plot key confidence over time for modulation detection
- Ensemble methods: Combine with other key detection algorithms
- Mode detection: Extend to modal music (Dorian, Phrygian, etc.)
- Visualization enhancement: Add circle of fifths display, chord progressions