uvi-script
Musical event scripting with Lua
User Interface

This guide provides a comprehensive overview of how to create custom user interfaces for your scripts. For a detailed reference of all available widgets and functions, see the User Interface Classes and Functions group.

Overview

The uvi-script UI system allows you to build powerful, interactive control surfaces for your instruments and effects. You can create a variety of widgets, from simple buttons and knobs to complex tables and XY pads.

Key features include:

  • A rich library of over 20 widgets.
  • A flexible layout system with both automatic and manual positioning.
  • An intuitive event-handling system using per-widget callbacks.
  • A convenient table-based syntax for creating and configuring widgets.
Note
All UI widgets must be created during the main script execution. They cannot be created within real-time callbacks like onNote or onRelease.

Quick Start: A Simple Knob

Let's start with a complete example. This script creates a single knob that scales the velocity of incoming notes and a label to display the current value.

-- Create a Knob and a Label
local velScaleKnob = Knob{"VelocityScale", 0.5, 0.0, 1.0}
local valueLabel = Label{"Value"}
-- position label below the knob
valueLabel.bounds = {velScaleKnob.x, velScaleKnob.y + velScaleKnob.height, velScaleKnob.width, 20}
-- react to user input
function velScaleKnob:changed()
valueLabel.text = string.format("%.1f %%", self.value * 100)
end
velScaleKnob:changed()
-- use the value in your script
function onNote(e)
-- velocity is an integer in 1..127: round down, and never let it reach 0
local velocity = math.max(1, math.floor(e.velocity * velScaleKnob.value))
playNote(e.note, velocity)
end
Knob widget.
Definition ui.cpp:1763
text label widget.
Definition ui.cpp:1303
table bounds
widget bounding rect {x,y,width,height}
Definition ui.cpp:988
void onNote(table e)
event callback that will receive all incoming note-on events if defined.
function playNote(note, vel, duration, layer, channel, input, vol, pan, tune, slice, oscIndex, dim1, dim2)
helper function to generate a note event.
Definition api.lua:1089

This example demonstrates the three core steps: creating widgets, defining a changed callback to react to user input, and using the widget's value in your script's logic.

Creating Widgets: The Table Constructor

All widgets are created using a convenient table constructor syntax. This allows you to set properties like position, size, and the changed callback at the moment of creation.

Instead of writing this:

local button = Button("My Button")
button.x = 5
button.y = 20
button.width = 120
button.height = 20
button.changed = function(self) print(self.name .. " clicked") end
stateless transient button.
Definition ui.cpp:1036

You can write this, using curly brackets {}:

local button = Button{"My Button",
x = 5, y = 20, width = 120, height = 20,
changed = function(self) print(self.name .. " clicked") end
}
Warning
The name given to a Knob, Slider, NumBox, OnOffButton, Menu, MultiStateButton or Table is its parameter name. It must be an identifier: a letter, _ or : first, then letters, digits, _, : or . – no spaces or punctuation; use displayName for a readable caption. An invalid name raises an error (only a warning below script API version 11). The first six may not share a name either: the second one raises "parameter name already in use". Either error aborts the load at that line, so the interface stops there and nothing declared after it exists.

The Layout System

The UI canvas has a default width of 720px. By default, its height adjusts automatically to fit the widgets; use setSize to set custom dimensions (including widths beyond 720px) or setHeight to adjust the height only. You can arrange widgets using either the automatic grid system or by setting pixel-perfect manual coordinates.

Automatic Layout

By default, widgets are placed on a grid in their creation order. Each new widget is placed in the first available empty cell, flowing from left-to-right, top-to-bottom. This is useful for quickly creating simple layouts.

The grid consists of:

  • 6 columns, 120px apart, the first one 5px from the left edge.
  • Rows 25px apart (a 20px row plus a 5px gap), the first one 5px from the top. There is no row limit: rows are added as long as widgets keep coming.

A widget goes to the first cell where its default size overlaps no widget already placed and still fits within the panel width (at least 720px). Each Panel lays out its own sub-widgets the same way, relative to itself. Some widgets, like Knobs and Sliders, are larger and may span multiple rows or columns by default.

Manual Layout

For precise control, you can manually position and size widgets using their properties. You can set these during creation or modify them later.

  • x, y: The top-left coordinate of the widget.
  • width, height (aliases w, h): The dimensions of the widget.
  • position (alias pos): A table {x, y}.
  • size: A table {width, height}.
  • bounds: A table {x, y, width, height}.
-- Position a label at x=10, y=50 with a size of 100x20 pixels
local myLabel = Label{"Info", bounds = {10, 50, 100, 20}}

You can also use the moveControl() function to snap a widget to a specific cell in the auto-layout grid.

Script Size and Performance View

Use setSize to set the overall dimensions of your script UI, and setHeight if you only need to adjust the height (the width defaults to 720px):

setSize(650, 380) -- custom width and height
setHeight(200) -- adjust height only (720px width)
function setHeight(h)
sets the desired height of the user interface.
Definition ui.lua:69
void setSize(number w, number h)
set the script UI dimensions explicitly.

To make your script UI visible in the host's performance view, call makePerformanceView. This is what allows end users to see and interact with your UI during performance. It only marks the script as the one providing the performance view – it does not capture the widgets that exist so far – so its position in the script does not matter, as long as the call actually runs. An error while the script loads aborts every line after it, so calling it near the top keeps it from being skipped by a mistake further down:

setSize(650, 380)
-- create widgets and panels ...
void makePerformanceView()
make this script User Interface visible in performance view.
Definition ui.lua:101

A program shows one script UI on its Info page: that of the first program-level script that calls makePerformanceView. A second program script calling it is not shown there, and a script on a Layer shows its UI only in its own module editor. Keygroups cannot host scripts. An instrument that needs several pages builds them as tabs inside that one script (see Panel Switching).

Such a page can also control the program's effects. The parameter-bound widgets (see below) bind to any element parameter, including Bypass, so a custom FX page is a set of ParamKnob, ParamSlider, ParamOnOffButton, ParamMenu or ParamNumBox widgets pointed at Program.inserts[n], with a ParameterValue wherever script code needs to read or react to one of those parameters — the FXControls example builds one. A program locked with Protect Program keeps all of this working: the protection applies to the host's editors, while scripts, macros and automation still set parameters.

Handling User Input: The changed Callback

To respond to user interaction, you assign a function to a widget's changed property. This function is called whenever the widget's value changes.

The callback function always receives the widget instance as its first argument, conventionally named self.

local myKnob = Knob{"Frequency", 500, 20, 20000}
-- Assign a function to the 'changed' property
myKnob.changed = function(self)
print("New frequency: " .. self.value)
end

You can also use Lua's colon syntax, which provides the self argument implicitly:

function myKnob:changed()
print("New frequency: " .. self.value) -- self is implicit
end

For Table widgets, the callback receives a second argument: the index of the value that changed.

function myTable:changed(index)
print("Table value at index " .. index .. " changed to: " .. self:getValue(index))
end
Warning
Assigning value (or calling setValue(v)) from a script calls that widget's own changed handler whenever the value actually changes. Doing so from inside another changed handler therefore re-enters handlers, and two widgets that set each other – a radio group is the usual case – can recurse until the stack overflows. To update a widget without notifying it, call setValue(v, false); note that this form does not clamp v to the widget's range.
Note
Widget callbacks are not coroutines — you cannot call wait, waitBeat, or waitForRelease directly inside a changed callback. To perform delayed operations, use spawn to launch a separate thread from within the callback.

Temporary Value Display

A common pattern is to flash a knob's value on a Label, then revert to the default name after a delay. Since wait cannot be called in a widget callback, use spawn :

local flashCounters = {}
function flashLabel(label, text, defaultText, ms)
label.text = text
flashCounters[label] = (flashCounters[label] or 0) + 1
local myId = flashCounters[label]
spawn(function()
wait(ms or 1000)
if flashCounters[label] == myId then -- only revert if no newer update
label.text = defaultText
end
end)
end
local resLabel = Label{"RES"}
local resKnob = Knob{"Resonance", 0, 0, 1}
resKnob.changed = function(self)
flashLabel(resLabel, string.format("%.0f%%", self.value * 100), "RES", 1500)
end
function changed
callback function used by child widgets to be notified of changes.
Definition ui.cpp:1001
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39
function spawn(fun,...)
Launch a function in a separate parallel execution thread (deferred execution)
Definition api.lua:1338

The counter ensures that only the last update reverts the label, so rapid knob turns don't cause flickering. See the TemporaryDisplay example for a complete working script.

Widget Catalogue

Value Controls

Knob — Rotary control, ideal for continuous parameters. Supports strip images for custom graphics via setStripImage().

Slider — Horizontal or vertical fader. Set vertical to true in the constructor for a vertical slider. Supports background and handle images.

NumBox — Numeric text input. Users can click and drag or type a value directly.

local cutoff = Knob{"Cutoff", 20000, 20, 20000,
mapper = Mapper.Exponential, unit = Unit.Hertz}
local mix = Slider{"Mix", 0.5, 0, 1, unit = Unit.PercentNormalized}
local voices = NumBox{"Voices", 4, 1, 16, true} -- integer mode
Predefined mapper types.
Definition ui.cpp:745
@ Exponential
Exponential mapper, the parameter's range should be strictly positive.
Definition ui.cpp:757
Numeric input widget.
Definition ui.cpp:1624
Horizontal or vertical slider widget.
Definition ui.cpp:1687
Predefined unit types.
Definition ui.cpp:803
@ Hertz
display Hz symbol.
Definition ui.cpp:830
@ PercentNormalized
display % symbol but actual value is in the 0..1 range
Definition ui.cpp:818

Buttons

Button — Stateless push button. Triggers its callback once per click.

OnOffButton — Toggle button with on/off state. self.value is a boolean.

MultiStateButton — Cycles through multiple named states. Alternative to Menu for small option sets.

local trigger = Button{"Play"}
trigger.changed = function(self) playNote(60, 100, 500) end
local bypass = OnOffButton{"Bypass", false}
bypass.changed = function(self) print("Bypass:", self.value) end
local mode = MultiStateButton{"Mode", {"Poly", "Mono", "Legato"}}
mode.changed = function(self) print("Mode:", self.selectedText) end
MultiStateButton widget.
Definition ui.cpp:1485
2 states boolean button.
Definition ui.cpp:1128

Selection

Menu — Dropdown selector for longer lists of options.

local scale = Menu{"Scale", {"Major", "Minor", "Dorian", "Mixolydian"}}
scale.backgroundColour = "black"
scale.textColour = "white"
Menu widget.
Definition ui.cpp:1359
string backgroundColour
background colour: colour string that defines the desired colour.
Definition ui.cpp:1417

Set hierarchical to true to create nested sub-menus from path-like entries. Use "/" as separator — the menu builds the tree automatically:

local irMenu = Menu{"IR", {
"Halls/Large Hall", "Halls/Small Hall",
"Plates/Bright", "Plates/Dark",
"Rooms/Studio A", "Rooms/Studio B"
}, hierarchical = true}
irMenu.changed = function(self)
print("Selected:", self.selectedText) -- e.g. "Halls/Large Hall"
end

See the IRLoader example for a complete hierarchical menu with impulse response loading.

Display

Label — Text display with custom font, alignment, and colour.

Image — Displays a static image (PNG, JPG). Supports an overImage for mouse-over state.

SVG — Displays a Scalable Vector Graphics image.

local title = Label{"title", text = "My Instrument", align = "centred"}
local logo = Image("resources/logo.png")
logo.pos = {10, 10}
Image widget.
Definition ui.cpp:1214

Containers

Panel — Groups widgets together. Create sub-widgets using method syntax:

local panel = Panel{"Controls"}
panel.bounds = {0, 0, 720, 100}
panel.backgroundColour = "3f000000"
-- sub-widgets belong to the panel
local k = panel:Knob("Gain", 0.5, 0, 1)
local s = panel:Slider("Pan", 0, -1, 1)
local b = panel:OnOffButton("Mute", false)
Panel widget.
Definition ui.cpp:2234

Viewport — Scrollable container. Useful when content exceeds available space. A viewport shows a single child: each widget created in it replaces the previous one, so create one Panel in it and put the content in that panel.

Panel Switching (Tabs)

A common pattern for multi-page UIs: use OnOffButton as tab selectors and toggle Panel visibility. Each tab button deselects the others and shows only the matching panel:

local tabNames = {"Main", "FX", "Seq"}
local tabButtons, tabPanels = {}, {}
for i = 1, #tabNames do
tabButtons[i] = OnOffButton{tabNames[i], i == 1,
bounds = {(i - 1) * 80, 0, 78, 25},
backgroundColourOff = "333333", backgroundColourOn = "FF8800",
persistent = false}
tabPanels[i] = Panel{bounds = {0, 30, 500, 100}}
end
tabPanels[1]:Knob("Volume", 0.8, 0, 1)
tabPanels[2]:Knob("Cutoff", 20000, 20, 20000)
tabPanels[3]:Table("Steps", 8, 0, -12, 12, true)
for i = 1, #tabNames do
tabButtons[i].changed = function()
for j = 1, #tabNames do
tabButtons[j]:setValue(j == i, false) -- deselect others
tabPanels[j].visible = (j == i) -- show matching panel
end
end
end
tabButtons[1]:changed() -- show first tab
Table widget.
Definition ui.cpp:1556

See the PanelSwitcher example for a complete working script.

Data

Table — Multi-value bar editor. Commonly used for sequencer steps, velocity curves, or envelope shapes.

XY — Two-dimensional pad returning X and Y values.

local steps = Table{"Steps", 16, 0, -12, 12, true} -- 16 steps, int, range -12..12
steps.changed = function(self, index)
print("Step", index, "=", self:getValue(index))
end
-- an XY pad drives two existing parameters, named at construction
local padX = Knob("PadX", 0.5, 0, 1)
local padY = Knob("PadY", 0.5, 0, 1)
local pad = XY("PadX", "PadY")
padX.changed = function(self)
print("X:", self.value, "Y:", padY.value)
end
XY widget.
Definition ui.cpp:2386

Monitoring

AudioMeter — Real-time level meter bound to an element's audio bus.

WaveView — Displays the waveform of a sample.

local meter = AudioMeter("out", Program, true, 0, true)
meter.bounds = {680, 0, 40, 100}
AudioMeter widget.
Definition ui.cpp:2423
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350

File

FileSelector — Embedded file browser for selecting samples or presets.

DnDArea — Drag-and-drop zone. Fires a callback when a file is dropped, or when a text dragged from a Button of the same script is dropped (to drag widgets onto each other, e.g. to reorder slots).

local dnd = DnDArea{"Drop"}
dnd.fileDropped = function(self)
print("Dropped:", self.filepath)
end
-- text drag: the button carries "slot:1", the area takes the texts starting with "slot:"
local handle = Button("Handle")
handle.dragAndDropText = "slot:1"
dnd.acceptedText = "slot:"
dnd.textDropped = function(self)
print("Dropped:", self.droppedText)
end
DnDArea widget.
Definition ui.cpp:1258
FileFormat::Type acceptedFileFormat
accepted file format
Definition ui.cpp:1266
Predefined format file types.
Definition ui.cpp:904
@ Audio
Audio file type (wav, aiff, FLAC, ...)
Definition ui.cpp:915

Parameter-Bound Widgets

Parameter-bound widgets drive an existing Element parameter directly instead of carrying their own script value. This is the inverse of parameter export: rather than publishing a widget value to the host, the widget reads from and writes to a parameter that already lives on an Element — an oscillator, effect, modulation, etc. Range, default, Unit and Mapper all come from the target parameter, so no min/max/default is passed — only the element and the parameter name.

The first argument is an Element reference (or a path string identifying one); the second is the parameter name, the same name accepted by setParameter.

The main benefit over a plain widget is that the control adopts the parameter's Unit and Mapper. From the unit, values are both formatted for display and parsed back from typed text for free: the user can type "1.5 kHz", "-6 dB" or "50 %" and it is converted to the correct underlying value, with the right suffix shown. From the mapper, the control follows the parameter's own response curve (e.g. exponential for a frequency), so the knob travel matches the engine. You get all of this without setting unit, mapper or displayText yourself, and without writing a changed handler.

ParamKnob, ParamSlider, ParamOnOffButton, ParamMenu and ParamNumBox mirror their standard counterparts but bind to a parameter:

local flt = Program.layers[1].keygroups[1].inserts[1]
local cutoff = ParamKnob(flt, "Freq") -- knob follows the filter cutoff
local bypass = ParamOnOffButton(flt, "Bypass") -- toggle follows the bypass state
-- table form also accepts widget options (bounds, colours, ...)
local vol = ParamKnob{Program.auxs[1].inserts[4], "Volume", bounds = {0, 0, 80, 80}}
A knob bound to an existing Element parameter.
Definition ui.cpp:1840
An on/off button bound to an existing boolean Element parameter (e.g.
Definition ui.cpp:1969
table layers
Layer list for this Program (1-indexed, use #Program.layers to get the count)
Definition Engine.cpp:359
table auxs
all AuxEffect for this node, in position order. Falcon can add and delete them; a delete shifts the i...
Definition Engine.cpp:356

Moving the widget writes the parameter; changing the parameter elsewhere (host automation, modulation, preset load) updates the widget. No changed callback is required to keep them in sync.

Note
The Param* widgets never call a changed handler: assigning one is accepted but it is never invoked. To react to the parameter from script code, pair the widget with a ParameterValue on the same parameter and use its changed.

A bound widget can be retargeted with bind(elementOrPath, paramName), and can be created with a name only to start unbound. Widgets are created once, when the script loads, so this is how one set of controls follows an element chosen at run time:

local amount = ParamKnob("Amount") -- unbound: a placeholder for now
function editInsert(i) -- e.g. on a slot selection
amount:bind(Program.inserts[i], "Mix")
end
table inserts
all InsertEffect for this node
Definition Engine.cpp:355

If the bound element is deleted, the widget reads as unbound (value is nil) until it is bound again.

These five are also available as Panel methods, for placing them inside a container:

local panel = Panel{"Filter"}
panel:ParamKnob(flt, "Freq")
panel:ParamSlider(flt, "Q")
A fader bound to an existing Element parameter.
Definition ui.cpp:1903

ParameterValue is a non-visual, logical binding to a parameter — it draws nothing. Use it to read or drive a parameter from script code without placing a control on the UI. It is a global function only (not a Panel method) and does not accept layout options:

-- inserts[4] is a Gain effect: its Volume is a linear gain, 1.0 is unity
local vol = ParameterValue(Program.auxs[1].inserts[4], "Volume")
vol.value = 0.5 -- write the parameter (about -6 dB)
print(vol.value) -- read it back
vol.changed = function(self)
print("Volume is now", self:toString())
end
A non-visual (logical) binding to an existing Element parameter.
Definition ui.cpp:2161

Its changed handler is called each time the parameter changes, whoever changed it, and once more when the script's interface is built.

Note
Given an Element reference, a ParameterValue binds at once. Given a path string, it binds only when the script's interface is built: until then value reads nil, writes are dropped (both print a message in the script console) and bound is false. A write is also dropped when the Lua type does not match the parameter (a number for a float or integer parameter, a boolean for a boolean one, a string for a string one), with no error raised.

Mappers and Units

Knob, Slider, and NumBox accept a Mapper and a Unit to control the value curve and display formatting.

A Mapper defines the curve between the widget's visual position and the parameter value:

Mapper Formula Typical use
Linear (default) min + (max-min) × pos General purpose
Exponential min × (max/min)^pos Frequency, time
Quadratic min + (max-min) × pos² Gentle curve
Cubic min + (max-min) × pos³ Volume (perceptual)
SquareRoot min + (max-min) × √pos Inverse gentle

See Mapper for the full list (QuarticRoot, CubeRoot, Quartic, Quintic, etc.).

A Unit tells the engine how to format the displayed value:

Unit Display (float widget) Auto-scale
Hertz "440.00 Hz" → kHz from 1000 Hz
Seconds "2.00 s" → ms below 1 s, us below 1 ms
MilliSeconds "250 ms" → s from 1000 ms, us below 1 ms
Cents "50.00 Cents" → Semitones from ±100 cents, if the range exceeds ±100
SemiTones "7.00 Semitones" → Cents below ±1 semitone
LinearGain "-6.02 dB" linear gain shown in dB, 0 as "-oo dB"
Decibels "-6.00 dB" Direct dB value
Percent "50.00%" Direct percent value
PercentNormalized "50.00%" 0..1 shown as 0%..100%
Pan "Left 50", "Center", "Right 50" -1..1 shown as -100..100
MidiKey "C3" MIDI note name, integer widgets only

The scaling and most of the formats above apply to float widgets. An integer widget (created with the integer flag) formats only MidiKey (note name), SemiTones, Cents, Percent, Seconds, MilliSeconds (→ s from 1000 ms) and Hertz (→ kHz from 1000 Hz), without switching between cents and semitones; any other unit shows the bare number.

See Unit for the complete list.

When no built-in unit fits, use the displayText property to override:

gate.changed = function(self)
self.displayText = string.format("%d%%", self.value * 100)
end

Colours

All colour properties accept a string in one of these formats:

Format Example Description
Named "red", "darkgrey", "blue" CSS-style named colours
RGB hex "#FF00CC" or "FF00CC" 6-digit hex (opaque)
ARGB hex "#3C00FECD" or "3C00FECD" 8-digit hex, alpha first (00 transparent, FF opaque)

The leading # is optional and hex digits are case-insensitive. A string that is neither 6 or 8 hex digits nor a known colour name raises no error and sets no colour, so the widget keeps drawing with its default one.

Common colour properties: backgroundColour, textColour, fillColour, outlineColour, thumbColour, trackColour.

local k = Knob{"Gain", 0.5, 0, 1}
k.fillColour = "lightgrey"
k.outlineColour = "#FF8800" -- orange
local panel = Panel{"bg"}
panel.backgroundColour = "3f000000" -- semi-transparent black
string fillColour
fill colour.
Definition ui.cpp:1803
string backgroundColour
background colour.
Definition ui.cpp:2244

Images and Retina

Many widgets accept image paths for custom graphics. Supported formats: PNG and JPG.

setBackground("resources/background.png")
local btn = OnOffButton{"Play", false}
btn.normalImage = "resources/play_off.png" -- off state
btn.pressedImage = "resources/play_on.png" -- on state (and while held down)
local knob = Knob{"Filter", 0.5, 0, 1}
knob:setStripImage("resources/knob_strip.png", 128) -- 128 frames
string normalImage
image path for the off state
Definition ui.cpp:1146
void setBackground(string imagePath)
set the script background Image.

For Retina / HiDPI displays, place a @2x variant alongside the standard file:

  • resources/knob.png — standard resolution
  • resources/knob@2x.png — 2× pixel dimensions

The engine automatically picks the appropriate variant.

State and Persistence

Automatic Persistence

Set persistent to true (the default) to have widget values automatically saved and restored with the preset:

local mix = Knob{"Mix", 0.5, 0, 1}
mix.persistent = true -- value saved/restored automatically (default)
bool persistent
flag to tell if the widget values should be serialized when saving.
Definition ui.cpp:998

Parameter Export

Set exported to true to expose a widget as a host-automatable parameter. The widget's paramId is assigned automatically and is read-only:

local cutoff = Knob{"Cutoff", 20000, 20, 20000}
cutoff.exported = true -- visible to the host for automation
bool exported
default: false, set it to true to export this parameter as an automatable parameter
Definition ui.cpp:1016

Host automation slots are a shared resource: Falcon has 128 for the whole plugin instance. When they are all taken, exporting another widget reports an error in the console and the parameter stays unautomatable — see Widgets, parameters and automation.

For custom data beyond widget values, use onSave / onLoad callbacks. See Asynchronous Operations for file-based persistence with saveData / loadData.

Keyboard Colours

Use setKeyColour and resetKeyColour to colorize the on-screen keyboard. This is useful for indicating key ranges, keyswitches, or active notes:

-- mark keyswitch range in red
for i = 36, 43 do
setKeyColour(i, "FF0000")
end
-- mark the playable range: transparent white is not drawn as a colour, it
-- flags the key as valid; transparent black ("#00000000") flags it as invalid
for i = 48, 84 do
setKeyColour(i, "#00FFFFFF")
end
function setKeyColour(note, colour)
customize the keyboard colours.
Definition ui.lua:50

Next Steps

Explore the full widget reference with all properties and methods in the User Interface Classes and Functions module documentation.