Quickstart

This page converts one master to IAMF from start to finish, three ways: with the SDK, with the command-line tool, and with plain HTTP. Each takes a master (ADM WAV or ambisonic WAV) and an API key, and ends with an .iamf file on disk. You need a key first.

Set the key in your environment. Every example reads it from there.

export ESFERA_API_KEY=esf_sk_live_v1_…

Install

Neither package is on npm yet. Until the first release, build them from the repository, or install the tarballs Esfera sends you.

# from a checkout of the Esfera Developer Hub repository
pnpm install
pnpm --filter @esfera/sdk build
(cd packages/sdk && pnpm pack)             # writes esfera-sdk-0.2.0.tgz
npm install ./packages/sdk/esfera-sdk-0.2.0.tgz   # in your own project

The CLI runs straight from the build with node packages/cli/dist/index.js. See CLI. The curl route needs curl and jq only.

Convert a master

SDK

import { Esfera } from "@esfera/sdk";

const esfera = new Esfera({ apiKey: process.env.ESFERA_API_KEY! });

// Uploads the file, then the encode starts by itself because a preset is given.
const job = await esfera.conversions.create({
  file: "master.wav",
  preset: "esfera",
});

// Poll until ready. Throws ConversionFailedError if the encode fails.
const done = await job.wait({
  onProgress: (c) => console.log(c.status, `${c.progress}%`),
});

await job.download("master.iamf");
console.log(done.outputProfile, done.outputLoudnessLufs);

CLI

esfera login                    # opens your browser; or set ESFERA_API_KEY
esfera convert master.wav --preset esfera -o master.iamf

curl

API=https://api.esfera.audio        # https://staging-api.esfera.audio with a test key
AUTH="Authorization: Bearer $ESFERA_API_KEY"

# 1. Create. The preset makes the encode start after analysis.
SIZE=$(stat -f %z master.wav 2>/dev/null || stat -c %s master.wav)
RESP=$(curl -s -X POST "$API/v1/conversions" -H "$AUTH" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d "{\"filename\":\"master.wav\",\"durationSec\":1800,\"sizeBytes\":$SIZE,\"preset\":\"esfera\"}")
ID=$(echo "$RESP" | jq -r .id)
UPLOAD_URL=$(echo "$RESP" | jq -r .uploadUrl)

# 2. Upload the bytes to storage. No Authorization header here.
curl -s -X PUT --upload-file master.wav "$UPLOAD_URL"

# 3. Tell the API the upload has landed. Analysis runs, then the encode.
curl -s -X POST "$API/v1/conversions/$ID/analyze" -H "$AUTH"

# 4. Poll until ready.
until [ "$(curl -s "$API/v1/conversions/$ID" -H "$AUTH" | jq -r .status)" = "ready" ]; do sleep 5; done

# 5. Download the IAMF.
curl -s "$API/v1/conversions/$ID/output" -H "$AUTH" -o master.iamf

Replace durationSec in the curl example with the real length of your master in seconds. The SDK and the CLI read it from the file's header for you.

What just happened

• Create returned an id and a presigned upload URL. The master goes straight to storage, so its size is never limited by the API's request size.
• The upload is one PUT with an explicit Content-Length. The SDK and the CLI send masters over 16 MiB in parallel parts instead, and a single PUT cannot exceed 5 GiB, so use the multipart calls for anything larger over plain HTTP.
• Analyse reads the file's programmes, beds and objects. The SDK calls it for you after the upload. Over plain HTTP, you call it.
• The encode started by itself because the request named a preset. Without a preset, the conversion waits at analyzed and you choose with start.
• Download is available for 72 hours after the conversion is ready.

Check what is accepted

esfera presets

or, from code, esfera.presets.get() or GET /v1/presets. The response lists every profile and preset the encoder accepts, which is the source of truth for the preset and profile values you can send.

Next

• Handle failures with the error reference and rate limits.
• Make retries safe with idempotency.
• Know what each status means and when a job counts as stuck.
• Replace polling with webhooks, and verify their signatures.