# beatlyze

Python SDK for the [Beatlyze](https://beatlyze.dev) audio analysis API.

## Install

```bash
pip install beatlyze
```

## Quick start

```python
from beatlyze import Beatlyze

bz = Beatlyze("bz_your_api_key")

# Analyze from URL (blocks until complete)
result = bz.analyze_url("https://example.com/track.mp3")
print(result["bpm"])        # 128.4
print(result["key"])        # "A"
print(result["energy"])     # 0.78

# Analyze a local file
result = bz.analyze_file("./my-track.wav")

# Async: submit without waiting
job = bz.analyze_url("https://example.com/track.mp3", wait=False)
print(job["job_id"])  # check later with bz.get_analysis(job["job_id"])

# Batch (up to 10 URLs)
jobs = bz.analyze_batch([
    "https://example.com/a.mp3",
    "https://example.com/b.mp3",
])

# Check usage
usage = bz.get_usage()
print(f"{usage['count']}/{usage['limit']} analyses used this month")
```

## Result fields

| Field | Type | Description |
|---|---|---|
| `bpm` | float | Tempo in beats per minute |
| `key` | str | Musical key (e.g. "A") |
| `scale` | str | "major" or "minor" |
| `key_notation` | str | Combined (e.g. "Am") |
| `energy` | float | 0.0 - 1.0 |
| `danceability` | float | 0.0 - 1.0 |
| `valence` | float | 0.0 - 1.0 (mood) |
| `loudness_lufs` | float | Integrated loudness |
| `duration_seconds` | float | Track duration |
| `mood_tags` | list[str] | e.g. ["energetic", "dark"] |
| `genre_suggestions` | list[str] | e.g. ["techno", "house"] |

## License

MIT
