English | 日本語

Detect the musical key of any audio file from the command line. Built on the Krumhansl-Schmuckler key-finding algorithm with chroma feature extraction via librosa.

Zero API keys required. Works offline. Free forever.

• Single file detection -- key-detect detect song.wav
• Batch processing -- key-detect batch ./music/ --recursive
• Camelot wheel notation -- Perfect for DJ harmonic mixing
• Multiple output formats -- Text, JSON, Rich table
• Confidence scores -- Know how certain the detection is
• Tuning estimation -- Detect pitch deviation
• Top-3 alternatives -- See the next best guesses

pip install key-detect

Or install from source:

git clone https://github.com/izag8216/key-detect.git
cd key-detect
pip install -e .

# Detect key of a single file
key-detect detect song.wav

# Verbose output with alternatives
key-detect detect song.wav -v

# JSON output for scripting
key-detect detect song.wav --format json

# Batch analyze a directory
key-detect batch ./samples/

# Recursive batch with JSON output
key-detect batch ./music/ -r --format json

# Filter by confidence
key-detect batch ./music/ --min-confidence 0.7 --sort confidence

# Show Camelot wheel reference
key-detect keys

File:   song.wav
Key:    C major
Camelot: 8B
Confidence: 85.23%

{
  "path": "song.wav",
  "key": "C",
  "mode": "major",
  "camelot": "8B",
  "confidence": 0.8523,
  "tuning": 0.12,
  "duration": 234.5,
  "alternatives": [
    {"key": "G", "mode": "major", "camelot": "9B", "correlation": 0.72},
    {"key": "A", "mode": "minor", "camelot": "11A", "correlation": 0.65}
  ]
}

key-detect keys

Displays the full 12-key Camelot wheel for harmonic mixing.

1. Load audio via librosa (preserving original sample rate)
2. Separate harmonic content from percussive elements
3. Extract chroma features using Constant-Q Transform
4. Correlate against 24 Krumhansl-Kessler key profiles (12 major + 12 minor)
5. Map best match to Camelot wheel notation
6. Estimate tuning deviation from A440

The Krumhansl-Schmuckler algorithm compares the distribution of pitch classes in the audio against known tonal profiles for each key. The key with the highest Pearson correlation is the detected key.

WAV, MP3, FLAC, OGG, AIFF, AU, M4A, WMA, AAC, OPUS

from key_detect.core import analyze_file, analyze_batch

# Single file
result = analyze_file("song.wav")
print(f"{result.key} {result.mode} ({result.camelot}) - {result.confidence:.1%}")

# Batch
results = analyze_batch("./music/", recursive=True, min_confidence=0.5)
for r in results:
    print(f"{r.path}: {r.key} {r.mode}")

pip install -e ".[dev]"
pytest --cov=key_detect --cov-report=term-missing
ruff check src/ tests/

MIT License -- see LICENSE for details.