Gravity Profiles and certification
The profile format, conversion, review checklist, fixture tests and adapter certification.
A Gravity Profile is a machine-readable description of one plugin's position controls: which parameters exist, their units and ranges, their OSC addresses and how to convert Gravity Feed's neutral coordinates into them. Profiles are what turn a plan into writable actions. This page explains the format, how a profile is reviewed and the fixture tests a profile must pass before its conversion is marked verified.
Listing profiles
curl -s https://spatial9.ai/api/gravity-feed/v1/profiles| Profile | Product | Status | Conversion verified |
|---|---|---|---|
canonical_v1 | Neutral reference | Reference | Not applicable |
iem_stereoencoder_candidate_v1 | IEM StereoEncoder | Documented route | No |
icst_ambiencoder_candidate_v1 | ICST AmbiEncoder | Documented route | No |
Profile format
| Field | Description |
|---|---|
id | Unique id, ending in a version such as _v1 |
version | Semantic version of the profile |
product | Plugin name as the maker writes it |
status | reference, documented_route, prototype, tested_beta, supported or legacy |
notes | Plain-language caveats, such as missing controls |
parameters | List of { name, unit, range, osc? } |
conversion_verified | true only after the fixture tests pass |
source | Link to the maker's documentation for the addresses and ranges |
Parameter names are azimuth, elevation, distance or xyz. A profile that uses xyz addresses each source by index, so targets using it must send source_index.
How conversion works
Gravity Feed computes every position in the neutral frame: X forward, Y left, Z up, azimuth positive to the left. The compiler then:
- Applies locks and style bounds in the neutral frame.
- Converts each point to the profile's parameters, for example to Cartesian X, Y and Z for
xyz. - Clamps each value to the parameter's range.
- Emits one action per parameter with the profile's OSC address.
Changes the profile cannot express, such as distance on StereoEncoder, are listed in unsupported_actions rather than silently dropped.
Review checklist
A new profile is accepted as a documented route when:
- Every address and range is cited from the maker's documentation.
- The units match that documentation.
- The profile id and version are new.
- Unsupported controls are left out, not guessed.
Fixture tests
A profile is marked conversion_verified: true only after a person runs these tests in a real host and records the plugin version, host and date:
| Test | Plan value | Expected in the plugin |
|---|---|---|
| Front | Azimuth 0, elevation 0 | Straight ahead |
| Left | Azimuth +90 | Hard left |
| Right | Azimuth -90 | Hard right |
| Behind | Azimuth 180 | Directly behind |
| Up | Elevation +45 | Raised, still in front |
| Near and far | Distance 0.2 then 0.9 | Clearly closer, then further, if distance is supported |
| Timing | A rise from beat 0 to beat 16 at 120 BPM | Motion ends exactly 8 seconds in |
If any test fails, the profile is corrected and given a new version; old plans keep naming the version they were built with.
Certification for adapters
An adapter (a DAW script or plugin) moves from prototype to live only when:
- It passes the fixture tests with at least one verified profile.
- It refuses to write when the session revision changed or the plan expired.
- It writes a whole alternative in one undo step, or explains why the host cannot.
- It shows every
unsupported_actionsreason to the user. - It sends
audio_uploaded: falseand no audio, paths or client names.
FAQ
Can a plugin maker publish its own profile?
Yes. Send the profile and the documentation links to Spatial9; it is reviewed against the checklist above and published with the documented-route status until the fixture tests pass.
Do profiles cover effect parameters?
Not yet. Effect ideas stay executable: false until an effect profile format has been designed and tested.