Beatlyze Docs

Beatlyze is a local-first audio analysis API for music products. You upload a track, SonicCore measures it, and you get back a JSON report plus a signed webhook. Beatlyze handles the rest — accounts, scoped API keys, private upload storage, billing, and delivery.

First Integration Path

The supported v2 path is intentionally narrow:

1. Sign in with a one-time email code and create a scoped API key.
2. Create a private storage object for an audio upload.
3. Upload the source to R2 through the returned private upload target.
4. Queue an analysis job with the storage object ID.
5. Poll the result endpoint or receive signed webhook delivery.
6. Read report artifact metadata after SonicCore finishes and the source is cleaned up.

curl -X POST https://api.beatlyze.dev/v1/analyses \
-H "authorization: Bearer $BEATLYZE_API_KEY" \
-H "content-type: application/json" \
-d '{"storage_object_id":"sto_...","webhook_endpoint_id":"wh_..."}'

What you can and can't rely on

Measured directly, the same every run: duration, sample peak, integrated loudness, an RMS-style level, and spectral descriptors.

Tempo, time signature, key, and section boundaries are best-effort estimates. Each one comes back with a confidence score, so you can decide how far to trust it in your own product.

Recognition, genre, mood, energy, valence, and danceability aren't in the default report. They'll arrive as a provider-backed add-on once the providers behind them are production-ready.

Result Shape

{
"job_id": "job_3f7a91c2",
"status": "succeeded",
"result": {
  "duration_seconds": 123.4,
  "integrated_loudness_lufs": -14.1,
  "sample_peak_dbfs": -1.2,
  "rms_loudness": -18.7,
  "bpm": 128.0,
  "bpm_confidence": 0.71
},
"report_artifact": {
  "key": "reports/job_3f7a91c2.json"
}
}

Operational Evidence

The production run emits events for SonicCore completion, report storage, source cleanup, and webhook delivery. Use these events when building customer-facing status, retry, and support workflows.

Public API

The API reference is generated from the FastAPI OpenAPI schema exported by the v2 API app, then rendered statically in the frontend build.