Introduction
The Esfera developer platform converts spatial audio masters into IAMF files from your own code. You send a master over HTTPS, the same encoder that serves the Esfera app does the work, and you download the result. It is one REST API, with a TypeScript SDK and a command-line tool built on top of it, so you can start from whichever fits the job.
What it does
A conversion takes one master file and produces one IAMF file (audio/iamf).
- Sources. An ADM master (WAV, RF64 or BW64 with ADM metadata) or a bare ambisonic WAV of first, second or third order (4, 9 or 16 channels).
- Presets. A preset decides what happens to the master's objects and which IAMF profile is written.
GET /v1/presetslists what the encoder you are calling accepts, and Presets describes each one. - Result. An IAMF file you download for 72 hours after the conversion is
ready, with loudness, channel and element facts on the conversion record.
How it fits together
- Create a conversion. You get an id and a presigned URL for the upload.
- Upload the master straight to storage. Nothing large passes through the API.
- Analyse and encode. With a
preseton create, the encode starts by itself after analysis. Without one, you read the analysis and choose. - Follow it by polling, or let a webhook tell you.
- Download the IAMF.
Limits you should know
| Limit | Value |
|---|---|
| Source duration | 180 minutes per file |
| Source size | 100 GiB per file |
| Output retention | 72 hours after ready |
| Request rate | 120 requests per minute per key |
| Concurrent conversions | One per account unless raised for your account |
GET /v1/usage returns the limits that apply to your account, so a script can check them before a long upload.
Where to go next
- Quickstart: one conversion, start to finish, with the SDK, the CLI or curl.
- Getting access: how an account gets API keys.
- Authentication and Environments.
- The API reference, the SDK and the CLI.
- Conversion guides: lifecycle and statuses, presets and programmes, auto-start and two-step, idempotency, uploading large masters and retention.
- Webhook guides: events and payload, verifying signatures and retries and replay.