Metadata-Version: 2.4
Name: beatlyze-analyzer
Version: 0.1.0
Summary: Audio feature extraction: BPM, key, energy, danceability, mood, genre.
License: AGPL-3.0-or-later
Project-URL: Homepage, https://beatlyze.dev
Project-URL: Repository, https://github.com/mg0024/beatlyze-analyzer
Keywords: audio,music,analysis,bpm,key,dsp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: light
Requires-Dist: librosa>=0.10; extra == "light"
Requires-Dist: soundfile>=0.12; extra == "light"
Requires-Dist: pyloudnorm>=0.1; extra == "light"
Provides-Extra: full
Requires-Dist: beatlyze-analyzer[light]; extra == "full"
Requires-Dist: essentia>=2.1b6.dev1034; extra == "full"
Dynamic: license-file

# 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.
