![]() |
uvi-script
Musical event scripting with Lua
|
uvi-script is built on the Lua programming language, a lightweight, fast, and embeddable scripting language. Understanding Lua is essential for writing effective uvi-scripts.
This page covers the Lua-specific aspects of uvi-script: which version is used, what libraries are available, and the real-time constraints that shape how you write scripts.
If you're new to Lua or need a reference, we recommend these excellent resources:
These resources are well-written and provide a solid foundation for scripting. Using a simple, widespread, yet powerful scripting language that can be learned online was one of the main motivations for choosing Lua.
What you need to know:
uvi-script uses a sandboxed Lua 5.1 virtual machine with custom extensions designed for real-time audio processing.
Most script code executes with real-time priority to ensure sample-accurate timing and low-latency performance. This places specific constraints on what you can do:
Real-Time Requirements:
Exceptions (Non-Real-Time): These callbacks run with relaxed constraints and can allocate memory:
To maintain real-time safety, uvi-script uses a pre-allocated memory pool for all Lua operations during real-time execution.
Best Practices:
The compiler is the standard Lua 5.1.4 one, unmodified, so its fixed limits apply as they are. Small scripts never meet them; a large instrument script, or one ported line for line from a language where every variable is declared up front, can.
| limit | applies to | error message |
|---|---|---|
| 200 active local variables | each function, the main chunk included | main function has more than 200 local variables or function at line N has more than 200 local variables |
| 60 upvalues | each function | function at line N has more than 60 upvalues |
| 250 registers | each function | ‘function or expression too complex near ’...'\ilinebr </td> </tr> <tr class="markdownTableRowEven"> <td class="markdownTableBodyNone"> 200 nesting levels \ilinebr </td> <td class="markdownTableBodyNone"> the whole chunk \ilinebr </td> <td class="markdownTableBodyNone">chunk has too many syntax levels` |
What counts as a local:
local x and local function f of the script counts against the main chunk, and each name of a local a, b, c counts separately;for adds three hidden variables plus its loop variable, a generic for three hidden ones plus its variables — while the loop is open;The limit is on locals active at the same time: a local declared inside a do … end block, or inside a loop body, stops counting at the block's end.
The upvalue limit is the one a callback meets. Every top-level local that onNote, a widget's changed handler or any other function refers to is one of its upvalues, so a callback that touches more than 60 distinct top-level locals fails to compile even when the chunk as a whole is under 200. The register limit usually shows up in the same scripts: with close to 200 locals in scope, little room is left for the temporaries of a long expression or a call with many arguments.
The message is prefixed with the usual chunk:line: location, and that line is where the limit was crossed — the declaration of the 201st local, the use of the 61st upvalue. The N inside the message is different: it is the line where the offending function starts. Neither message has a near part; Lua 5.1 reports these limits without pointing at a token.
A compile error names the script as its chunk, then the line:
/path/to/script.lua:12: …;[string "--------------------------------..."]:12: ….The second form looks like a quoted fragment of code, and it is: Lua labels an embedded chunk with the start of its source, and most scripts start with a comment banner. The number after it is still the line in the script.
There is no built-in counter. For the main chunk, counting top-level declarations is a good estimate when the script is indented conventionally:
counts the lines that start with local at the first column. Add one for every extra name on a local a, b, c line; declarations inside a top-level for or do block are indented and correctly left out. For an exact answer, append a throw-away local line with a known number of names at the end of the script: if it still loads, at least that many slots were free.
Group related values into tables. A table is one local and, from a callback, one upvalue, however many fields it has:
Widgets can be grouped the same way — ui.cutoff = Knob{…} rather than one local per knob.
do … end, or move it into a function that is called once: the locals it needs stop counting when the block ends.No single allocation above about 1 MB can succeed in the script's Lua heap. When one is attempted Lua raises not enough memory, and the console and the log show an out-of-memory error. In practice that caps:
Many small tables and strings are not affected; the limit is on one block, not on the total.
The script side sets no limit on the number of widgets or parameters. Host automation does: Falcon has 128 host automation slots, shared by the whole plugin instance — every script and every exported parameter in it. Once they are all taken, setting exported on another widget reports an error in the console, and that parameter is not automatable. See Parameter Export.
uvi-script provides access to a subset of Lua's standard libraries. Libraries that require operating system access or blocking I/O are not available to maintain real-time safety.
base - Basic Functions
assert, error, pcall, type, tonumber, tostringpairs, ipairs, nextprint, select, unpackrequire - Load Lua modulestable.insert, table.removetable.concattable.sorttable.copy(t) - uvi-script extension: creates a shallow copy of a tablestring - String Operations
string.sub, string.find, string.matchstring.format, string.gsubmath - Mathematical Functions
math.sin, math.cos, math.tan, math.asin, etc.math.abs, math.floor, math.ceil, math.min, math.maxmath.random, math.randomseedmath.pi, math.hugebit - Bitwise Operations
bit.band, bit.bor, bit.bxor, bit.bnot, bit.lshift, bit.rshiftclass - Object-Oriented Programming
os - Operating System Facilities
io - File I/O
coroutine and debug
coroutine and debug globals are removed after the runtime has loadedrequire "coroutine" still returns them; do not use itThird-Party Lua Libraries
The runtime replaces a few base library functions with script-friendly versions and adds several global helpers.
print(...) writes to the script console, not to a standard output stream. Arguments are converted to text and separated by single spaces (the standard print separates them with tabs). Event tables — tables carrying a numeric type field, such as the argument of onNote — are expanded to their key=value contents instead of being shown as a table address. Errors (syntax errors at load time, runtime errors in callbacks) are shown in the same console with their file and line number, and are also appended to ScriptProcessor.log (macOS: ~/Library/Logs/<host>/ScriptProcessor.log, Windows: APPDATA%\<host>\ScriptProcessor.log); print output goes to the console only:
Other tables print as an address, like with the standard print; use the helpers below to display their contents.
print_table(t, printer, indent) prints one key:value line per entry and recurses into nested tables, indenting each nesting level by two extra spaces. printer (optional) is the output function, print by default; indent (optional) is the initial indentation string. Values that are not booleans, numbers, or strings are shown by their type name.
table.tostring(t) returns the top-level key=value pairs of a table as a single space-separated string. Pairs appear in unspecified order and nested tables appear as addresses.
table.print(t) prints table.tostring(t) wrapped in braces. Does nothing if t is not a table.
table.copy(t) returns a new table with the same keys and values. The copy is shallow: nested tables are shared with the original, not duplicated.
assert(cond, msg, level) raises an error with message msg (default "error") when cond is false or nil. Unlike the standard assert, it takes a third level argument selecting the stack level at which the error is reported: 1 (the default) blames the caller of assert, 2 blames the caller's caller, and so on — useful for reporting argument errors at the call site of your own functions. Also unlike the standard version, it does not return its arguments on success.
warning(condition, msg, level) has the same signature but never raises an error: when condition is false it prints msg prefixed with warning: [file]:line, where the location is taken from the stack level selected by level (default 1, the caller of warning).
uvi-script includes a built-in class system. Use class to define classes with constructors, methods, and instance state. This is useful for encapsulating complex logic like sequencers, state machines, or multi-voice managers.
Create instances with the class name as a function call:
The synthesis engine objects (Program, Layer, Keygroup, Oscillator, etc.) are C++ objects exposed to Lua. They support the same colon method syntax:
uvi-script uses Lua coroutines internally to implement its cooperative threading model. Each event callback (onNote, onRelease, etc.) runs as a separate coroutine that can be suspended using wait, waitBeat, or waitForRelease.
What you need to know:
wait() functionsFor detailed information about threading and timing, see Threading and Timing.