Presets and programmes

A preset decides what the encoder does with the master's beds and objects and which IAMF profile the file declares. A programme is one of the complete mixes an ADM master can contain, and one conversion encodes exactly one. This page lists the four presets, explains how programme indexes work and when to send one, and covers ambisonic masters: which orders each preset accepts and how source.normalization works.

GET /v1/presets is the authority for everything about presets and profiles on the deployment you are calling. Read it at run time. The tables below describe the contract of this version, and the Presets reference has the profile table and the full response.

The four presets

Preset	Label	Objects	Declares when you send no profile	Accepts
esfera	Esfera	Kept: the bed and every object stay discrete. An ambisonic file is kept whole at its own order.	base-enhanced for a bed-only or ambisonic master, advanced-1 with objects up to 18 elements and 18 channels, advanced-2 above that	ADM, ambisonic of any order
youtube	YouTube	Folded: an ADM master's objects go into one scene element beside the bed. An ambisonic file is kept whole at its own order.	base	ADM, ambisonic of any order
bed714_3oa	7.1.4 + 3OA	Rendered into a third-order Ambisonics scene beside a 7.1.4 bed. For an ambisonic file the bed is rendered from the scene.	base-enhanced	ADM, third-order ambisonic
oa3	3OA only	Everything rendered to one third-order Ambisonics scene. An ambisonic file goes in as it is.	base	ADM, third-order ambisonic

Notes on reading the table:

• "Declares" is the default. Send profile on create or start to ask for a specific writable profile instead, or "auto" to leave it to the preset. The conversion's outputProfile tells you what the finished file declares, and output lists the elements and mix presentations the encoder wrote.
• When several profiles are possible, the encoder picks by content. That is why esfera lists three.
• The element and channel limits belong to the profiles, not the presets. They are in the profile table.
• A master whose content does not fit the profile it would declare is refused before the encode with preset-over-cap, or the job ends in error with the encoder's reason. Choose another preset or profile.

Programmes

An ADM master can declare several programmes, for example a full mix and a commentary variant. One conversion encodes one of them.

• Index. Programmes are numbered from 0. A master with three programmes has indexes 0, 1 and 2.
• Where to find the count. programmeCount on the conversion is null until analysis has run, then the number the master declares.
• When to send programme. Only when the master declares two or more. Send it on create or on start.
• When not to. A master with a single programme gives you nothing to choose, and a bed-only master declares none at all, so there is no programme 0 to ask for. For both, leave programme out. If you send one anyway, the server does not pass it to the encoder.
• If you do not choose. A master with several programmes and no choice does not encode. A one-step conversion waits in analyzed and a POST /v1/conversions/{id}/start without programme is refused with programme-required. Send the index and it proceeds. Do not leave such a conversion waiting: it holds a concurrency slot while it does.
• Bad values. A value that is not a whole number from 0 to 32767 is refused with invalid-programme. So is an index at or above the number of programmes the file declares, once the file has been analysed. The message says which range is valid.

The SDK and the CLI read the programme count from the file's header before they upload. The CLI converts programme 0 with a note when the file declares several and you gave none; pass --programme <n> to choose.

# Create a conversion for programme 1 of a multi-programme master
curl -X POST https://api.esfera.audio/v1/conversions \
  -H "Authorization: Bearer $ESFERA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"master.wav","durationSec":1800,"preset":"esfera","programme":1}'

Ambisonic masters

A bare ambisonic WAV is accepted as well as an ADM master. First, second and third order are supported (4, 9 and 16 channels). After analysis the conversion reports what the file is in source:

Field	Meaning
source.kind	adm or ambisonic.
source.order	1, 2 or 3 for an ambisonic source, otherwise null.
source.normalization	The convention you declared, null for ADM.
source.note	The probe's doubt about a four-channel file, which could be first-order ambisonics or a quad mix. Absent for ADM.

Normalisation

Ambisonic files do not say which channel normalisation they use, so you may need to. Send it as source.normalization on create or on start:

{ "filename": "scene.wav", "durationSec": 600, "preset": "esfera", "source": { "normalization": "fuma" } }

Value	Convention	Notes
sn3d	AmbiX	The default. Used when source is absent.
n3d	N3D	Accepted for any order.
fuma	FuMa	First order only, and it must be declared, because nothing in the file says it.

Anything else is refused with invalid-source-normalization. So is fuma on a second- or third-order source, and so is sending source for an ADM master. The last two are decided once the file has been analysed, so they surface when the encode is started, not when the field is first accepted.

Which presets accept which order

Preset	1OA	2OA	3OA
esfera	Yes	Yes	Yes
youtube	Yes	Yes	Yes
bed714_3oa	No	No	Yes
oa3	No	No	Yes

A first- or second-order source sent to bed714_3oa or oa3 is refused with preset-not-for-source. When the preset was given at create, the check happens after analysis and the conversion ends in error with that reason. The SDK and CLI check the order from the file header first and refuse before uploading anything. Use esfera or youtube for lower orders, or supply a third-order source.

Related

• Presets reference and GET /v1/presets.
• Auto-start and two-step: choosing the preset and programme after analysis.
• Errors for each refusal named above.