Metadata-Version: 2.4
Name: beatlyze
Version: 0.1.0
Summary: Python SDK for the Beatlyze audio analysis API.
License: MIT
Project-URL: Homepage, https://beatlyze.dev
Project-URL: Documentation, https://beatlyze.dev/docs
Project-URL: Repository, https://github.com/mg0024/beatlyze-analyzer
Keywords: audio,music,analysis,bpm,key,beatlyze
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0

# 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
