Auto-start and the two-step flow

There are two ways to run a conversion. In the auto-start flow you name the preset when you create the conversion and the encode starts by itself once analysis finishes. In the two-step flow you create without a preset, let analysis run, look at what it found, and then start the encode with a preset you choose. This page explains both, what analysis does, and the one call your client must always make itself.

Choosing a flow

	Auto-start	Two-step
You know the preset up front	Yes	No, you want to see the analysis first
preset on POST /v1/conversions	Sent	Omitted
Your calls	create, upload, analyze, then wait	create, upload, analyze, wait for analyzed, start, wait
Response to create	autoStart: true	autoStart: false

Pipelines nearly always want auto-start: they have already decided. Use two-step when the choice depends on the file, for example which programme to encode, or whether the master is ambisonic and of what order.

What analysis does

Analysis is a read-only pass over the master. It does not encode anything. It discovers:

• the true duration, which replaces the durationSec you sent at create (that value only reserves minutes up front);
• the programmes the master declares (programmeCount);
• the source kind, and for ambisonic files the order (source);
• the beds and objects (objectCount) and the plan for each preset, kept on the server.

While it runs the conversion is analyzing and progress counts from 0 to 100. When it finishes the conversion is analyzed and the conversion.analyzed webhook fires, in both flows.

After analysis the true duration is checked against the per-file limit and your remaining minutes. A master over the limit ends in error with the reason in errorMessage. If the minutes are short, the start is refused with quota-exhausted, and errorMessage says how many more you need.

The client always triggers analysis

The server has no way to know when your upload has finished. Nothing moves a conversion out of uploading until you call POST /v1/conversions/{id}/analyze. This applies to both flows, and it is separate from starting the encode:

1. Create the conversion. You get id, uploadUrl and autoStart.
2. Upload the master.
3. Call POST /v1/conversions/{id}/analyze. It answers 202 with { "id": …, "status": "analyzing" }.

With a preset on create, the server then starts the encode when analysis completes. You never call start.

If the conversion is not in uploading any more, analyze answers 409 already-started. A client that calls it defensively, as the SDK does, can treat that as success.

The SDK's create() makes this call for you after the upload. The CLI does the same. If you use curl or your own HTTP client, you make it yourself.

Auto-start

SDK

// create() uploads the file and then calls analyze for you.
const job = await esfera.conversions.create({ file: "master.wav", preset: "esfera" });
const done = await job.wait();          // follows analysis and the encode to ready
await job.download("master.iamf");

curl

API=https://api.esfera.audio
AUTH="Authorization: Bearer $ESFERA_API_KEY"

# 1. Create, with the preset.
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,"preset":"esfera"}')
ID=$(echo "$RESP" | jq -r .id)
URL=$(echo "$RESP" | jq -r .uploadUrl)

# 2. Upload to the presigned URL (no Authorization header).
curl -s -X PUT "$URL" -H "Content-Type: audio/wav" --data-binary @master.wav

# 3. Trigger analysis. The encode starts on its own afterwards.
curl -s -X POST "$API/v1/conversions/$ID/analyze" -H "$AUTH"

An auto-start conversion can still pause. If the master declares several programmes and you named none, the encode does not start, because we never guess which programme you mean. The conversion stays analyzed. Call start with the programme:

curl -s -X POST "$API/v1/conversions/$ID/start" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"programme":1}'

Naming programme on create avoids this. See Presets and programmes. A preset the analysed source cannot take, such as oa3 for a second-order ambisonic file, ends the conversion in error with that reason instead of encoding.

Two-step

SDK

const job = await esfera.conversions.create({ file: "master.wav" });   // no preset: analyze runs, nothing is started
const analysed = await job.wait({ until: "analyzed" });

console.log(analysed.programmeCount, analysed.source);
await job.start({ preset: "youtube", programme: 0 });

await job.wait();
await job.download("master.iamf");

curl

# 1–3 as above, but create without "preset" and with Idempotency-Key.

# 4. Wait for status "analyzed" (poll, or use the conversion.analyzed webhook).
until [ "$(curl -s "$API/v1/conversions/$ID" -H "$AUTH" | jq -r .status)" = "analyzed" ]; do sleep 3; done

# 5. Look at what analysis found.
curl -s "$API/v1/conversions/$ID" -H "$AUTH" | jq '{programmeCount, objectCount, source, sourceDurationSec}'

# 6. Start with the preset you choose.
curl -s -X POST "$API/v1/conversions/$ID/start" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"preset":"youtube","programme":0}'

POST /v1/conversions/{id}/start takes preset, programme, profile and source, all optional. It answers 202 with the conversion's new status, which is waiting or queued. A profile named here overrides one given at create, "auto" clears it, and leaving it out keeps it. A conversion that is not in a state to be started answers 409 already-started, which includes a second start after the first one succeeded.

The one-call shortcut

start is also accepted on a conversion that is still uploading. The server records your choice and runs the analysis first, and the encode follows. This is the older one-step form. Prefer analyze followed by either auto-start or start: it is the flow the SDK and CLI use and it gives you the analysis to look at before you commit.

What the SDK never does

The SDK never calls start for a conversion you created with a preset. That would turn auto-start into a client behaviour: any other integration, written against the plain API, would hang in analyzed. Auto-start is the server's job and your client only follows the conversion to ready.

Related

• Lifecycle and statuses for every status these flows pass through.
• POST /v1/conversions, analyze and start.
• Idempotency: make the create safe to retry.