# beatlyze-analyzer

Audio feature extraction library: BPM, musical key, energy, danceability, valence, LUFS loudness, mood tags, genre suggestions, and structural sections.

## Installation

**Light tier** (librosa-only, cross-platform):
```bash
pip install "beatlyze-analyzer[light]"
```

**Full tier** (Essentia for higher-quality extraction; Linux x86_64 / macOS arm64):
```bash
pip install "beatlyze-analyzer[full]"
```

## Usage

```python
from beatlyze_analyzer import analyze

result = analyze("/path/to/track.mp3")
print(result["bpm"])          # 128.4
print(result["key_notation"]) # "Am"
print(result["mood_tags"])    # ["energetic", "dark"]
```

## Output fields

| Field | Type | Description |
|---|---|---|
| `bpm` | float | Tempo in beats per minute |
| `bpm_confidence` | float 0–1 | Extraction confidence |
| `key` | str | Root note (e.g. `"A"`) |
| `scale` | str | `"major"` or `"minor"` |
| `key_notation` | str | Shorthand (e.g. `"Am"`) |
| `key_confidence` | float 0–1 | |
| `energy` | float 0–1 | Perceived loudness / intensity |
| `danceability` | float 0–1 | Beat regularity + onset density |
| `valence` | float 0–1 | Musical positivity |
| `loudness_lufs` | float | Integrated loudness (LUFS R128) |
| `mood_tags` | list[str] | e.g. `["energetic", "uplifting"]` |
| `genre_suggestions` | list[str] | Top 3 genre labels |
| `duration_seconds` | float | Track length |
| `time_signature` | int | Beats per bar (2, 3, 4, or 6) |
| `sections` | list[dict] | Structural segments with per-section features |

## License

AGPLv3 — required by the [Essentia](https://essentia.upf.edu/) dependency (AGPLv3).
Source code must remain publicly available when used in a network service.
