Reference

Complete listing of all form properties, control types, their top-level fields and props, stylesheet macros, and the Lua API.

Sections marked TODO will be filled in from source files in a later pass.

Form YAML Structure

width: <int> # form width in pixels  (required)
height: <int> # form height in pixels (required)
color: <color> # background fill color (optional)

controls:
  <control-id>: # unique string ID — referenced from Lua and macro params
    type: <string> # control type (required)
    visible: <bool> # default: true
    enabled: <bool> # default: true
    zOrder: <int> # stacking order for overlapping controls
    comment: <string> # ignored at runtime — for your own notes
    pos: { x, y, w, h } # absolute placement — use pos OR anchors
    anchors: { left, right, top, bottom, hCenter, vCenter, width, height }
    props:
# type-specific properties
# omitted props fall back to internal defaults,
# which are usually the corresponding stylesheet macros

Form Properties

Property	Type	Required	Description
`width`	int	yes	Form width in pixels
`height`	int	yes	Form height in pixels
`color`	color	no	Background fill color
`infoOverlayColor`	color	no	Info overlay text color
`infoOverlayBackground`	color	no	Info overlay background color

Common Control Top-Level Fields

Field	Type	Required	Default	Description
`type`	string	yes	—	Control type (see types below)
`visible`	bool	no	`true`	Whether the control is rendered
`enabled`	bool	no	`true`	Whether the control accepts input
`zOrder`	int	no	—	Stacking order for overlapping controls
`comment`	string	no	—	Ignored at runtime; for your notes

Placement (`pos` — absolute)

Key	Type	Description
`x`	int	Pixels from left edge of form
`y`	int	Pixels from top edge of form
`w`	int	Control width in pixels
`h`	int	Control height in pixels

Placement (`anchors` — constraint-based)

Key	Type	Description
`left`	int	Distance from left edge of the form
`right`	int	Distance from right edge of the form
`top`	int	Distance from top edge of the form
`bottom`	int	Distance from bottom edge of the form
`hCenter`	int	Offset from the horizontal center of the form
`vCenter`	int	Offset from the vertical center of the form
`width`	int	Required when `left`+`right` do not fully constrain width
`height`	int	Required when `top`+`bottom` do not fully constrain height

`alignment` Values

Used in text and parameterDisplay props.

Value	Description
`topLeft`
`topCenter`
`topRight`
`centerLeft`
`center`
`centerRight`
`bottomLeft`
`bottomCenter`
`bottomRight`

Control Types

`knob`

Rotary control. Bind to a parameter via parameterUid, or drive from Lua via value + onChange.

props:

Prop	Type	Default	Description
`parameterUid`	string	—	Bound parameter (name or UUID)
`value`	double	—	Initial value for script-driven mode
`bipolar`	bool	—	Center-zero display (pan, pitch, etc.)
`displayMode`	enum	`standard`	`standard`, `phaseBitmap`, `rotatedBitmap`
`bitmap`	string	—	Bitmap path for `phaseBitmap` / `rotatedBitmap` modes
`dragAxis`	enum	`vertical`	`vertical`, `horizontal`
`tickAngle`	double	`0.0`	Rotation of the tick mark in degrees
`bgColor`	color	`$knob-bg-color` (`#1AFFFFFF`)
`borderColor`	color	`$knob-border-color` (`#33FFFFFF`)
`trackColorActive`	color	`$knob-track-color-active` (`#C0C7FF`)	Arc from min to current value
`trackColorInactive`	color	`$knob-track-color-inactive` (`#2A2A2A`)	Remaining arc
`tickColor`	color	`$knob-tick-color` (`#FFFFFF`)	Position indicator tick
`tintColor`	color	—	Tint applied over bitmap
`onChange`	string	—	Lua handler name, called on value change
`onChangeStart`	string	—	Lua handler name, called on drag start
`onChangeEnd`	string	—	Lua handler name, called on drag end

`fader`

Linear fader. orientation is required.

props:

Prop	Type	Required	Default	Description
`orientation`	enum	yes	—	`horizontal`, `vertical`
`parameterUid`	string	no	—	Bound parameter (name or UUID)
`value`	double	no	—	Initial value (script mode)
`bipolar`	bool	no	—	Center-zero display
`trackColorActive`	color	no	`$fader-track-color-active` (`#9095DB`)
`trackColorInactiveFg`	color	no	`$fader-track-color-inactive-fg` (`#343434`)
`trackColorInactiveBg`	color	no	`$fader-track-color-inactive-bg` (`#232323`)
`handleColorFg`	color	no	`$fader-handle-color-fg` (`#575757`)
`handleColorBg`	color	no	`$fader-handle-color-bg` (`#3A3A3A`)
`trackWidth`	string	no	`$fader-track-width` (`4`)	Can be a macro or pixel value
`tintColor`	color	no	—
`trackBitmap`	string	no	—	Custom track image
`handleBitmap`	string	no	—	Custom handle image
`onChange`	string	no	—	Lua handler name
`onChangeStart`	string	no	—	Lua handler name
`onChangeEnd`	string	no	—	Lua handler name

`toggle`

Binary switch (iOS-style). Bind via parameterUid or drive from Lua via value + onChange.

props:

Prop	Type	Default	Description
`parameterUid`	string	—	Bound parameter (name or UUID)
`value`	bool	—	Initial state (script mode)
`invert`	bool	`false`	Flip on/off meaning
`transitionTime`	int	`300`	Animation duration in ms
`trackColorActive`	color	`$toggle-track-color-active` (`#C0C7FF`)
`trackColorInactive`	color	`$toggle-track-color-inactive` (`#2A2A2A`)
`thumbColorActive`	color	`$toggle-thumb-color-active` (`#FFFFFF`)
`thumbColorInactive`	color	`$toggle-thumb-color-inactive` (`#808080`)
`borderColorActive`	color	`$toggle-border-color-active` (`#C0C7FF`)
`borderColorInactive`	color	`$toggle-border-color-inactive` (`#808080`)
`phaseBitmap`	string	—	Custom filmstrip image
`tintColor`	color	—
`onChange`	string	—	Lua handler name

`button`

Push button. No parameterUid — driven entirely via onPressed Lua handler or used as a purely visual element with value.

props:

Prop	Type	Required	Default	Description
`text`	string	yes	—	Button label
`value`	bool	no	—	Display state (pressed/unpressed)
`fgColor`	color	no	`$button-fg-color` (`#C0C7FF`)	Label color
`bgColor`	color	no	`$button-bg-color` (`#2A2A2A`)	Background color
`fgColorPressed`	color	no	`$button-fg-color-pressed` (`#FFFFFF`)	Label color when pressed
`bgColorPressed`	color	no	`$button-bg-color-pressed` (`#808080`)	Background color when pressed
`fontScale`	string	no	`$button-font-scale` (`1.0`)	Font size scale factor
`fontWeight`	string	no	`$button-font-weight` (`500`)
`cornerRadius`	string	no	`$button-corner-radius` (`4`)	Can be a macro or pixel value
`phaseBitmap`	string	no	—	Custom filmstrip image
`tintColor`	color	no	—
`onPressed`	string	no	—	Lua handler name

`buttonSelector`

A horizontal or vertical row of labeled buttons where exactly one is active at a time. The active index is tracked by a parameter or via value + onChange.

props:

Prop	Type	Default	Description
`parameterUid`	string	—	Bound parameter (name or UUID)
`value`	int	—	Active index (script mode)
`labels`	string list	—	Button label for each slot
`bitmaps`	string list	—	Inactive-state bitmap per slot
`activeBitmaps`	string list	—	Active-state bitmap per slot
`orientation`	enum	`horizontal`	`horizontal`, `vertical`
`indicatorAlignment`	enum	`end`	`start`, `end` — where active indicator appears
`textColorActive`	color	`$button-selector-text-color-active` (`#FFFFFF`)
`textColorInactive`	color	`$button-selector-text-color-inactive` (`#808080`)
`fontScale`	string	`$button-selector-font-scale` (`1.0`)
`fontWeight`	string	`$button-selector-font-weight` (`500`)
`indicatorColor`	color	`$button-selector-indicator-color` (`#C0C7FF`)
`onChange`	string	—	Lua handler name

`text`

Static text label. Supports macro substitution in text.

props:

Prop	Type	Default	Description
`text`	string	—	Display text (macro substitution applies)
`alignment`	enum	—	See alignment values
`color`	color	`$text-color` (`#FFFFFF`)
`fontScale`	string	`$text-font-scale` (`1.0`)	Scale factor relative to base font size
`fontWeight`	string	`$text-font-weight` (`500`)

`parameterDisplay`

Read-only display of a bound parameter’s current value. parameterUid is required.

props:

Prop	Type	Required	Default	Description
`parameterUid`	string	yes	—	Parameter to display (name or UUID)
`alignment`	enum	no	—	See alignment values
`color`	color	no	`$parameter-display-color` (`#C0C7FF`)
`fontScale`	string	no	`$parameter-display-font-scale` (`1.0`)

`inlineSelector`

A compact left/right arrow selector for stepping through a parameter’s discrete values. parameterUid is required.

props:

Prop	Type	Required	Default	Description
`parameterUid`	string	yes	—	Parameter to control (name or UUID)
`textColor`	color	no	`$inline-selector-text-color` (`#FFFFFF`)
`arrowColor`	color	no	`$inline-selector-arrow-color` (`#C0C7FF`)
`fontScale`	string	no	`$inline-selector-font-scale` (`1.0`)

`image`

Displays a static image asset.

props:

Prop	Type	Required	Default	Description
`image`	string	yes	—	Path to image file
`fit`	enum	no	—	`contain`, `cover`, `fill`, `fitWidth`, `fitHeight`, `none`, `scaleDown`
`tintColor`	color	no	—	Tint color applied over the image

`portal`

Shows one of several forms based on a parameter value or value prop. This is the primary tool for tabbed interfaces, conditional panels, and any layout that switches between sub-forms.

props:

Prop	Type	Default	Description
`forms`	list of form entries	—	Ordered list of forms; active index = parameter value
`parameterUid`	string	—	Bound parameter (name or UUID)
`value`	int	—	Active index (script mode)
`transition`	enum	`crossfade`	`crossfade`, `slide`
`transitionTime`	int	`500`	Transition duration in ms

Each entry in forms is an object with:

Key	Type	Required	Description
`form`	string	yes	Form name (without `.frm`)
`macroParameters`	string map	no	Macro overrides for this form instance

Example:

content:
  type: portal
  anchors: { left: 0, right: 0, top: 32, bottom: 0 }
  props:
    parameterUid: tab-index
    forms:
      - form: osc_tab
      - form: filter_tab
      - form: env_tab

`subForm`

Embeds another form inside this control’s bounds.

props:

Prop	Type	Required	Description
`form`	string	yes	Form name (without `.frm`)
`macroParameters`	string map	no	Macro overrides scoped to this instance

Example:

my_panel:
  type: subForm
  anchors: { left: 0, right: 0, top: 0, bottom: 0 }
  props:
    form: param_knob
    macroParameters:
      $param-id: "uuid-or-name"
      $label-text: Cutoff

`levelMeter`

VU / peak meter driven by an audio processor output.

props:

Prop	Type	Required	Default	Description
`processorUid`	string	yes	—	UID of the metered audio processor
`channelOfInterest`	int	yes	—	Channel index to display
`type`	enum	yes	—	`rms`, `peak`
`orientation`	enum	no	`horizontal`	`horizontal`, `vertical`
`phaseBitmap`	string	no	—	Custom filmstrip image
`colorActive`	color	no	`$level-meter-color-active` (`#C0C7FF`)
`colorActiveHigh`	color	no	`$level-meter-color-active-high` (`#FF8000`)
`colorActivePeak`	color	no	`$level-meter-color-active-peak` (`#FF0000`)
`colorInactiveBg`	color	no	`$level-meter-color-inactive-bg` (`#232323`)
`colorInactiveFg`	color	no	`$level-meter-color-inactive-fg` (`#343434`)
`thresholdHigh`	string	no	`$level-meter-threshold-high` (`0.8`)	Can be a macro or numeric value
`thresholdPeak`	string	no	`$level-meter-threshold-peak` (`0.9`)
`decayFactor`	string	no	`$level-meter-decay-factor` (`0.97`)
`trackWidth`	string	no	`$level-meter-track-width` (`4`)
`conversionFormula`	string	no	`$level-meter-conversion-formula` (`x ^ 0.33`)

`keyboard`

Piano keyboard widget.

props:

Prop	Type	Required	Default	Description
`variant`	enum	yes	—	`generic`, `synth`
`showKeyLabels`	bool	no	`false`	Show note names on keys
`allowOctaveShift`	bool	no	`false`	Enable octave shift controls
`startOctave`	int	no	`0`	Lowest displayed octave
`bgColor`	color	no	`#000000`	Background color

`canvas`

A scriptable drawing surface. All rendering is performed in the onPaint Lua callback; the canvas does not redraw automatically. Mouse events are routed to optional callbacks. Call sys_canvas_repaint whenever the visual content changes.

See Lua Scripting — Canvas Control for the full drawing API (sys_canvas_* functions, the paint object, paths, and transforms).

props:

Prop	Type	Required	Description
`onPaint`	string	yes	Lua function name; called with `(controlName, ctx, width, height)`
`onMouseDown`	string	no	Lua function name; called with `(controlName, x, y)` on press
`onMouseUp`	string	no	Lua function name; called with `(controlName)` on release
`onMouseMove`	string	no	Lua function name; called with `(controlName, x, y)` on move
`onMouseDoubleClick`	string	no	Lua function name; called with `(controlName, x, y)` on double-click

Stylesheet Macro Reference

Macro Syntax

Macros appear as $macro-name in any property value and are resolved before rendering. A macro value may itself reference other macros (resolved recursively). Use macroParameters in a subForm or portal entry to override macros for a specific instance.

Built-In Macros

Text

Macro	Default
`$text-color`	`#FFFFFF`
`$text-font-scale`	`1.0`
`$text-font-weight`	`500`

Knob

Macro	Default
`$knob-track-color-active`	`#C0C7FF`
`$knob-track-color-inactive`	`#2A2A2A`
`$knob-tick-color`	`#FFFFFF`
`$knob-bg-color`	`#1AFFFFFF`
`$knob-border-color`	`#33FFFFFF`

Fader

Macro	Default
`$fader-track-color-active`	`#9095DB`
`$fader-track-color-inactive-fg`	`#343434`
`$fader-track-color-inactive-bg`	`#232323`
`$fader-handle-color-fg`	`#575757`
`$fader-handle-color-bg`	`#3A3A3A`
`$fader-track-width`	`4`

Toggle

Macro	Default
`$toggle-track-color-active`	`#C0C7FF`
`$toggle-track-color-inactive`	`#2A2A2A`
`$toggle-thumb-color-active`	`#FFFFFF`
`$toggle-thumb-color-inactive`	`#808080`
`$toggle-border-color-active`	`#C0C7FF`
`$toggle-border-color-inactive`	`#808080`

Button

Macro	Default
`$button-fg-color`	`#C0C7FF`
`$button-bg-color`	`#2A2A2A`
`$button-fg-color-pressed`	`#FFFFFF`
`$button-bg-color-pressed`	`#808080`
`$button-corner-radius`	`4`
`$button-font-scale`	`1.0`
`$button-font-weight`	`500`

ButtonSelector

Macro	Default
`$button-selector-text-color-active`	`#FFFFFF`
`$button-selector-text-color-inactive`	`#808080`
`$button-selector-indicator-color`	`#C0C7FF`
`$button-selector-font-scale`	`1.0`
`$button-selector-font-weight`	`500`

ParameterDisplay

Macro	Default
`$parameter-display-color`	`#C0C7FF`
`$parameter-display-font-scale`	`1.0`

LevelMeter

Macro	Default
`$level-meter-color-active`	`#C0C7FF`
`$level-meter-color-active-high`	`#FF8000`
`$level-meter-color-active-peak`	`#FF0000`
`$level-meter-color-inactive-bg`	`#232323`
`$level-meter-color-inactive-fg`	`#343434`
`$level-meter-threshold-high`	`0.8`
`$level-meter-threshold-peak`	`0.9`
`$level-meter-decay-factor`	`0.97`
`$level-meter-conversion-formula`	`x ^ 0.33`
`$level-meter-track-width`	`4`

InlineSelector

Macro	Default
`$inline-selector-text-color`	`#FFFFFF`
`$inline-selector-arrow-color`	`#C0C7FF`
`$inline-selector-font-scale`	`1.0`

Lua API Reference

See Lua Scripting for usage context and patterns.

Top-level script code runs once when the form loads. Named top-level functions can be referenced by name in control props (e.g. onChange, onPressed).

`sys_form_macros`

A read-only Lua table available in every form script. Keys are macro names (including the $ prefix); values are the substituted strings. Contains both built-in stylesheet macros and any custom macroParameters supplied when the form was embedded as a subForm.

local uid = sys_form_macros["$param-id"]

`sys_log(object)`

Argument	Type	Description
`object`	any	Value to print — strings, numbers, and tables are all accepted

Writes to the script console in the editor.

`sys_modify_control(control_name, domain, changes)`

Argument	Type	Description
`control_name`	string	Control ID as defined in the `controls:` map
`domain`	string	`"pos"`, `"anchors"`, `"props"`, or `""` for a root-level field
`changes`	table	Lua table of `key = value` pairs to update

Not all properties are mutable at runtime. Bitmaps cannot be changed via script (they require preloading at form initialization).

domain values:

`domain`	Targets
`""`	Root-level fields: `visible`, `enabled`, `zOrder`
`"pos"`	Absolute placement fields: `x`, `y`, `w`, `h`
`"anchors"`	Anchor fields: `left`, `right`, `top`, `bottom`, etc.
`"props"`	Type-specific props (colors, text, etc.)

`sys_set_parameter_value(parameter_id, value)`

Argument	Type	Description
`parameter_id`	string	Parameter UUID, or its name if it has one (global parameters only)
`value`	number	New value (clamped to the parameter’s min/max range)

`sys_subscribe_to_parameter(parameter_id, callback)`

Argument	Type	Description
`parameter_id`	string	Parameter UUID, or its name if it has one (global parameters only)
`callback`	function	Called with `(value)` whenever the parameter changes

Returns: the parameter’s current value at the time of subscription.

Replaces any existing subscription for the same parameter. Passing the return value into the same callback function applies the initial state and registers for future changes in one call:

local function sync(value) sys_modify_control("panel", "", {visible = value}) end
sync(sys_subscribe_to_parameter(uid, sync))

Control handler props

These props fields accept a string naming a top-level Lua function:

All handler callbacks receive the control’s ID as their first argument. This is a strict convention that allows wiring the same function to multiple controls and dispatching on the caller.

Prop	Controls	Handler signature
`onChange`	`knob`, `fader`, `toggle`, `buttonSelector`	`function(controlName, value)`
`onChangeStart`	`knob`, `fader`	`function(controlName, value)`
`onChangeEnd`	`knob`, `fader`	`function(controlName, value)`
`onPressed`	`button`	`function(controlName)`
`onPaint`	`canvas`	`function(controlName, ctx, width, height)`
`onMouseDown`	`canvas`	`function(controlName, x, y)`
`onMouseUp`	`canvas`	`function(controlName)`
`onMouseMove`	`canvas`	`function(controlName, x, y)`
`onMouseDoubleClick`	`canvas`	`function(controlName, x, y)`

Note: The scripting surface is an initial set. It will expand based on user feedback over time.

Reference

Form YAML Structure

Form Properties

Common Control Top-Level Fields

Placement (pos — absolute)

Placement (anchors — constraint-based)

alignment Values

Control Types

knob

fader

toggle

button

buttonSelector

text

parameterDisplay

inlineSelector

image

portal

subForm

levelMeter

keyboard

canvas

Stylesheet Macro Reference

Macro Syntax

Built-In Macros

Text

Knob

Fader

Toggle

Button

ButtonSelector

ParameterDisplay

LevelMeter

InlineSelector

Lua API Reference

sys_form_macros

sys_log(object)

sys_modify_control(control_name, domain, changes)

sys_set_parameter_value(parameter_id, value)

sys_subscribe_to_parameter(parameter_id, callback)

Control handler props

Placement (`pos` — absolute)

Placement (`anchors` — constraint-based)

`alignment` Values

`knob`

`fader`

`toggle`

`button`

`buttonSelector`

`text`

`parameterDisplay`

`inlineSelector`

`image`

`portal`

`subForm`

`levelMeter`

`keyboard`

`canvas`

`sys_form_macros`

`sys_log(object)`

`sys_modify_control(control_name, domain, changes)`

`sys_set_parameter_value(parameter_id, value)`

`sys_subscribe_to_parameter(parameter_id, callback)`