Presets

What this deployment's encoder accepts: profiles and presets.

What the encoder accepts

GET /v1/presets is the authority for this table: it is served by the deployment you are calling, so read it at run time rather than hard-coding ids. The tables here describe the contract as of this version.

For how presets interact with programmes and ambisonic sources, see Presets and programmes.

Profiles

The IAMF profiles are grouped in two families. Eclipsa (simple, base, base-enhanced) are the profiles the Eclipsa certification covers; IAMF 2.0 (base-advanced, advanced-1, advanced-2) are the object profiles. base-advanced is listed so the vocabulary is complete, but the encoder reads it and never declares it: passing it as profile is refused with profile-not-writable.

Profile	Family	Elements	Channels	Objects	Written by this encoder
simple	Eclipsa	1	16	no	yes
base	Eclipsa	2	18	no	yes
base-enhanced	Eclipsa	28	28	no	yes
base-advanced	IAMF 2.0	18	18	yes	no, it is read but never declared
advanced-1	IAMF 2.0	18	18	yes	yes
advanced-2	IAMF 2.0	28	28	yes	yes

A profile the content cannot satisfy, for example discrete objects kept under a profile that carries none, is refused by the encoder at encode time. The conversion then ends in error and errorMessage carries the encoder's reason.

Presets

Preset	What it does	Declares without a profile
esfera	Keeps the bed and every object discrete for Esfera playback; 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
youtube	Folds an ADM master's objects into one scene element beside the bed; an ambisonic file is kept whole at its own order.	base (2 elements, 18 channels)
bed714_3oa	A 7.1.4 bed plus a third-order Ambisonics scene built from the objects and HOA groups. For an ambisonic file the bed is rendered from the scene, so it needs a third-order file.	base-enhanced
oa3	Everything rendered to a single third-order Ambisonics scene. An ambisonic file goes in as it is and needs to be third order.	base

A first- or second-order ambisonic source cannot go through bed714_3oa or oa3. Those requests are refused with preset-not-for-source. Use esfera or youtube, or supply a third-order source.

Ambisonic sources

A bare ambisonic WAV (first, second or third order) is accepted alongside ADM. source.normalization selects its channel normalisation: sn3d (AmbiX) is the default when the field is absent, n3d is accepted, and fuma is first order only and must be declared, because the file does not say which convention it uses. Sending source for an ADM master is refused with invalid-source-normalization.

Operations

GET Profiles and presets this encoder accepts

GET /v1/presets

The IAMF profiles grouped by family (eclipsa: Simple, Base, Base-Enhanced — the profiles the Eclipsa certification covers; iamf-2: Base-Advanced, Advanced-1, Advanced-2), with writable saying whether this encoder will declare each one, and the presets with the profile(s) each declares by default and the inputs it accepts. engine.orbitcore is the encoder version.

Responses

Status	Meaning	Body
200	The vocabulary. Cacheable for five minutes.	PresetsResponse
401	The API key is missing, malformed, unknown, revoked, expired, or for the other environment (invalid-api-key).	Problem
429	Over 120 requests/minute for this key (rate-limited). Honour Retry-After.	Problem

curl

curl "https://api.esfera.audio/v1/presets" \
  -H "Authorization: Bearer $ESFERA_API_KEY"

Node.js

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

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

const { profiles, presets, engine } = await esfera.presets.get();

Python

import os
import requests

res = requests.get(
    "https://api.esfera.audio/v1/presets",
    headers={
        "Authorization": f"Bearer {os.environ['ESFERA_API_KEY']}",
    },
)
res.raise_for_status()
print(res.json())

Response · 200

{
  "engine": {
    "orbitcore": "2.3.0"
  },
  "profiles": [
    {
      "id": "base-enhanced",
      "code": 2,
      "family": "eclipsa",
      "label": "Base-Enhanced",
      "maxElements": 28,
      "maxChannels": 28,
      "objects": false,
      "writable": true
    },
    {
      "id": "advanced-1",
      "code": 4,
      "family": "iamf-2",
      "label": "Advanced-1",
      "maxElements": 18,
      "maxChannels": 18,
      "objects": true,
      "writable": true
    }
  ],
  "presets": [
    {
      "id": "esfera",
      "label": "Esfera",
      "declares": [
        "base-enhanced",
        "advanced-1",
        "advanced-2"
      ],
      "objects": "keep",
      "inputs": [
        "adm",
        "ambisonic"
      ],
      "description": "Keeps the bed and every object discrete for Esfera playback."
    }
  ]
}

Objects

Profile

Field	Type	Required	Description
id	simple | base | base-enhanced | base-advanced | advanced-1 | advanced-2	yes
code	integer	yes	The IAMF primary_profile value. 0 to 5.
family	eclipsa | iamf-2	yes
label	string	yes
maxElements	integer	yes
maxChannels	integer	yes
objects	boolean	yes	Whether the profile carries discrete objects.
writable	boolean	yes	Whether this encoder will declare it. Base-Advanced is read but not written.

Preset

Field	Type	Required	Description
id	esfera | youtube | bed714_3oa | oa3	yes
label	string	yes
declares	simple | base | base-enhanced | base-advanced | advanced-1 | advanced-2[]	yes	What the preset declares when you pass no profile. Several means the encoder picks by content (Esfera: Base-Enhanced for a bed-only master, Advanced-1 with objects within 18 elements / 18 channels, Advanced-2 above). outputProfile on the conversion is the per-job answer.
objects	keep | fold | scene	yes	What happens to the master's objects.
inputs	adm | ambisonic[]	yes
description	string	yes