Anatomy of a preset file

A preset is a TOML file with a two-line header and a [params] table:

system = "fragment_field"   # required — which built-in system to drive
name   = "Aurora"           # optional — display name (defaults to the system name)

[params]                    # each key is a system parameter; each value is an expression string
warp  = "0.3 + clamp(bass * 14, 0, 1.8)"
hue   = "time * 0.03 + clamp(treb * 5, 0, 1)"
zoom  = "1.0 + bar * 0.25"
glow  = "0.4 + clamp((bass + mid) * 8, 0, 1.1)"
flash = "clamp(onset * 3, 0, 1)"

Rules:

• system must be one of the known system names (below). An unknown system rejects the whole file.
• representative is an optional boolean, absent meaning false. It marks this preset as one of its family’s samples for the dev lane’s per-phase test tier. It changes nothing about how the preset looks, and nothing about what the plan close and CI render, which is the whole library either way — the only thing it moves is how early a defect in this preset is noticed. A non-boolean value rejects the file. See Parameter roster for what the flag is for and who sets it.
• name is free text shown in the standalone title bar. If omitted, the system name is used.
• [params] binds parameters by name to expression strings. Every value is a string (quote it), even a bare number: warp = "0.4", not warp = 0.4.
• Unbound parameters fall back to the system’s default, so you only need to write the parameters you want to drive. Order does not matter — bindings are sorted by name at load for determinism.
• An unknown parameter name is a load-time warning, not an error — see When a preset is wrong.

Beyond [params], a preset may carry optional tables — [curve] / [generator] (structural config for the line systems), [particles] (attractor family and sample density), [path] (an authored silhouette for the shape field, as inline SVG path data — summarised below), [spectrum] (the readout’s element count, layout and per-element easing — summarised below), [feedback] (how an accumulation reads its own past — below), [smoothing] (per-parameter easing), [latch] (an event armed on one condition and fired by another — below), [hold] (a binding re-sampled on a musical edge rather than every frame — below), [palette] / [palette_b] (colour), and [layer] (a second scene composed under or over the main one — the expression language inside [layer.params] is exactly this document’s). All are documented in Parameter roster and Colour and palettes.

Every [params] value is evaluated once per frame and applied to the system before it renders. An expression is a pure function of the variables it is handed — you cannot accumulate a running total, integrate, or remember the last frame inside one.

Two things bend that sentence without breaking it. A binding naming index is evaluated once per element by the spectrum system rather than once per frame; it is still the same pure expression over the same frame. And two tables depend on the frames before this one — in both, the state lives in the engine rather than in the expression, which goes on being a pure function of what it is handed. A [latch] is a variable whose value the engine carries; a [hold] leaves the expression alone and changes which frame’s result the scene is shown.

---