MUSIC ANALYZER

# Music Analyzer - Complete Guide

## What It Does

The Music Analyzer is a powerful browser-based tool that instantly detects two key musical properties from your audio files:

- **BPM (Beats Per Minute)** - The tempo of your song
- **Musical Key** - The key and scale (Major/Minor) your song is in

Perfect for DJs, music producers, playlist creators, and anyone working with music who needs to know these details quickly.

---

## Supported Audio Formats

✅ **MP3** - Most common format  
✅ **WAV** - Uncompressed audio  
✅ **OGG** - Open source format  
✅ **M4A** - Apple/iTunes format  
✅ **FLAC** - Lossless compression  

---

## How It Works Under the Hood

### The Technology Stack

The Music Analyzer uses cutting-edge audio analysis technology that runs entirely in your browser:

#### 1. **Essentia.js Library**
- Developed by the Music Technology Group at Universitat Pompeu Fabra (Barcelona)
- The same professional-grade library used by **Tunebat.com**
- Originally built for music information retrieval research
- Compiled to WebAssembly (WASM) for lightning-fast browser performance

#### 2. **Web Audio API**
- Built into modern browsers (Chrome, Firefox, Safari, Edge)
- Handles audio decoding and processing
- Converts your audio file into raw audio data that can be analyzed

### The Analysis Process

When you drop an audio file into the analyzer, here's what happens:

#### **Step 1: File Loading**
```
Your audio file → Browser reads it → Converts to binary data
```

#### **Step 2: Audio Decoding**
```
Binary data → Web Audio API → Raw audio waveform (Float32Array)
```
- If your file is stereo (2 channels), it's converted to mono by averaging both channels
- This gives us a single stream of audio samples to analyze

#### **Step 3: Format Conversion**
```
JavaScript audio array → Essentia.js vector format
```
- Essentia.js uses its own optimized data format for processing
- The conversion happens via `essentia.arrayToVector()`

#### **Step 4: BPM Detection**
```
Audio vector → PercivalBpmEstimator algorithm → BPM value
```
**How BPM detection works:**
- Analyzes the audio signal for rhythmic patterns
- Uses the Percival algorithm (published in 2014)
- Detects onset times (when beats occur)
- Calculates the tempo by measuring time between beats
- Returns a precise BPM value (rounded to nearest whole number for display)

#### **Step 5: Key Detection**
```
Audio vector + sample rate → KeyExtractor algorithm → Key + Scale
```
**How key detection works:**
- Extracts pitch information from the audio using HPCP (Harmonic Pitch Class Profile)
- HPCP is like a "fingerprint" showing which musical notes are present
- Compares this fingerprint against known key profiles (using Temperley-Krumhansl algorithm)
- Determines both the key (C, D, E, F, G, A, B) and scale (Major or Minor)
- Returns the most likely key with a confidence score

#### **Step 6: Display Results**
```
Analysis complete → Results shown on screen → Ready for next file
```

### Why It's Accurate

The Music Analyzer achieves professional-level accuracy because:

1. **Research-Grade Algorithms** - Uses peer-reviewed academic algorithms, not simple hacks
2. **Full Audio Analysis** - Processes the entire song, not just snippets
3. **Proven Technology** - The same library powering commercial music analysis tools
4. **No Compression Shortcuts** - Analyzes the actual audio waveform, not metadata

### Privacy & Security

🔒 **Your files never leave your computer**
- All processing happens locally in your browser
- No uploads to servers
- No data collection
- Works offline (after the initial page load)

### Performance Notes

- **Analysis Time**: 10-20 seconds for typical songs (3-5 minutes)
- **File Size**: Can handle files up to ~100MB (browser dependent)
- **Processing**: Depends on your computer's CPU speed
- **Browser Requirements**: Any modern browser with Web Audio API support

---

## Troubleshooting

### "Analysis engine not ready"
- Wait a few seconds for Essentia.js to load
- Check your internet connection (needed for initial library load)
- Try refreshing the page

### "Error analyzing file"
- Make sure it's a valid audio file
- Try converting to MP3 if using an unusual format
- Check if the file is corrupted

### Inaccurate Results
- Some songs are genuinely hard to analyze (e.g., changing tempo, atonal music)
- Electronic music with complex polyrhythms may confuse BPM detection
- Songs without clear key centers may return unexpected keys

### Slow Performance
- Large files (>50MB) take longer
- Close other browser tabs to free up memory
- Use a more powerful computer for faster processing

---

## Credits & Attribution

- **Essentia.js**: Music Technology Group, Universitat Pompeu Fabra, Barcelona
- **Algorithms**: Based on published academic research in music information retrieval
- **Development**: Built with modern web standards (ES6, Web Audio API, WebAssembly)

---

## License & Usage

This tool is free to use for personal and commercial purposes. The underlying Essentia.js library is open source under the Affero GPL license.

---