![]() |
uvi-script
Musical event scripting with Lua
|
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.
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:
onNote or onRelease.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.
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.
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:
You can write this, using curly brackets {}:
_ 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 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.
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:
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.
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}.You can also use the moveControl() function to snap a widget to a specific cell in the auto-layout grid.
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):
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:
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.
changed CallbackTo 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.
You can also use Lua's colon syntax, which provides the self argument implicitly:
For Table widgets, the callback receives a second argument: the index of the value that changed.
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.changed callback. To perform delayed operations, use spawn to launch a separate thread from within the callback.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 :
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.
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.
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.
Menu — Dropdown selector for longer lists of options.
Set hierarchical to true to create nested sub-menus from path-like entries. Use "/" as separator — the menu builds the tree automatically:
See the IRLoader example for a complete hierarchical menu with impulse response loading.
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.
Panel — Groups widgets together. Create sub-widgets using method syntax:
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.
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:
See the PanelSwitcher example for a complete working script.
Table — Multi-value bar editor. Commonly used for sequencer steps, velocity curves, or envelope shapes.
XY — Two-dimensional pad returning X and Y values.
AudioMeter — Real-time level meter bound to an element's audio bus.
WaveView — Displays the waveform of a sample.
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).
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:
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.
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:
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:
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:
Its changed handler is called each time the parameter changes, whoever changed it, and once more when the script's interface is built.
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.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:
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.
Many widgets accept image paths for custom graphics. Supported formats: PNG and JPG.
For Retina / HiDPI displays, place a @2x variant alongside the standard file:
resources/knob.png — standard resolutionresources/knob@2x.png — 2× pixel dimensionsThe engine automatically picks the appropriate variant.
Set persistent to true (the default) to have widget values automatically saved and restored with the preset:
Set exported to true to expose a widget as a host-automatable parameter. The widget's paramId is assigned automatically and is read-only:
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.
Use setKeyColour and resetKeyColour to colorize the on-screen keyboard. This is useful for indicating key ranges, keyswitches, or active notes:
Explore the full widget reference with all properties and methods in the User Interface Classes and Functions module documentation.