uvi-script
Musical event scripting with Lua
Element Class Reference

Common Elements base class. More...

Inheritance diagram for Element:
AuxEffect BusRouter ControlSignalSource EventProcessor InsertEffect Keygroup Layer Oscillator Part Program SampledReverb SignalConnection Synth

Public Member Functions

void setParameter (string parameter, Value value)
 Sets an Element parameter.
 
Value getParameter (string parameter)
 Gets an Element parameter.
 
bool hasParameter (string parameter)
 
table getParameterConnections (string parameter)
 Get all SignalConnection for this parameter.
 
AsyncTask insertEffect (string type, int slot, function completion)
 Insert a new effect in this element's insert chain.
 
AsyncTask removeEffect (int slot, function completion)
 Remove the effect at slot from this element's insert chain.
 
AsyncTask moveEffect (int from, int to, function completion)
 Move the effect at from so that it ends up at to in this element's insert chain.
 

Public Attributes

string name
 internal element name
 
string displayName
 name to display on the User Interface, name is used if displayName is not specified.
 
string type
 internal element type
 
string path
 full path of the element in the synthesis tree
 
Element & parent
 element parent
 
table children
 element children using the element name as key
 
table synthChildren
 children of the element in the synthesis hierarchy, as a 1-indexed array.
 
table mods
 all ControlSignalSource for this node as a 1-indexed array (same content as modulations, keyed by index instead of name)
 
int output
 output bus index for the element. Reading returns the index parsed from the current output bus name (1 when the element uses the default bus). Writing is asynchronous: the engine applies the new routing shortly after the assignment, so reading the property back immediately may still return the old value. Assigning on an element that cannot change its output raises an error.
 
int numParams
 number of parameters
 
table parameterDefinitions
 table of parameter definitions.
 

Detailed Description

Common Elements base class.

See also
Elements & parameters

Member Function Documentation

◆ getParameter()

Value Element::getParameter ( string parameter)

Gets an Element parameter.

Parameters
parameterparameterName or parameterId
Returns
parameterValue (number|bool|string) according to definition
See also
Elements & parameters

◆ getParameterConnections()

table Element::getParameterConnections ( string parameter)

Get all SignalConnection for this parameter.

Parameters
parameterparameterName or parameterId
Returns
table of parameter connections, or nil when nothing is connected to the parameter (or the parameter does not exist)
See also
Elements & parameters

◆ hasParameter()

bool Element::hasParameter ( string parameter)
Parameters
parameterparameterName or parameterId
Returns
true or false
See also
Elements & parameters

◆ insertEffect()

AsyncTask Element::insertEffect ( string type,
int slot,
function completion )

Insert a new effect in this element's insert chain.

Available on every element that has an inserts chain: Synth, Part, Program, Layer, Keygroup and AuxEffect. Calling it on any other element raises an error.

The edit is asynchronous: the call returns at once and the chain changes a little later, so read inserts again in the completion callback, not right after the call. task.success is false when the edit could not be applied: unknown type, a type that is not an effect, an effect that cannot run per voice on a Keygroup, or a slot past the end of the chain at the time the edit runs.

The new effect starts with its default settings; configure it with setParameter once the task has completed.

Parameters
typeeffect type, as listed in Elements & parameters (e.g. "Chorus", "SparkVerb")
slot(optional) 1-based position of the new effect; nil or omitted appends it
completion(optional) function called with the AsyncTask when the edit has been applied
Returns
an AsyncTask

Example:

Program:insertEffect("Chorus", 1, function(task)
if task.success then
Program.inserts[1]:setParameter("Mix", 0.3)
end
end)
AsyncTask insertEffect(string type, int slot, function completion)
Insert a new effect in this element's insert chain.
void setParameter(string parameter, Value value)
Sets an Element parameter.
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
table inserts
all InsertEffect for this node
Definition Engine.cpp:355
Program & Program
convenience global pointing to the parent Program element
Definition Engine.cpp:702
See also
removeEffect, moveEffect, FX Rack example

◆ moveEffect()

AsyncTask Element::moveEffect ( int from,
int to,
function completion )

Move the effect at from so that it ends up at to in this element's insert chain.

The effect is not recreated: it keeps its settings, its modulations and its audio state (a reverb or delay tail carries on), and references to it stay valid. Asynchronous, like insertEffect; task.success is false when either slot is out of range by the time the edit runs.

Parameters
from1-based position of the effect to move
to1-based position the effect should have once moved
completion(optional) function called with the AsyncTask when the edit has been applied
Returns
an AsyncTask

Example:

-- put the last effect first
AsyncTask moveEffect(int from, int to, function completion)
Move the effect at from so that it ends up at to in this element's insert chain.
See also
insertEffect, removeEffect

◆ removeEffect()

AsyncTask Element::removeEffect ( int slot,
function completion )

Remove the effect at slot from this element's insert chain.

Asynchronous, like insertEffect. task.success is false when there is no effect at slot by the time the edit runs. A reference to the removed effect held by the script expires.

Parameters
slot1-based position of the effect to remove
completion(optional) function called with the AsyncTask when the edit has been applied
Returns
an AsyncTask
See also
insertEffect, moveEffect

◆ setParameter()

void Element::setParameter ( string parameter,
Value value )

Sets an Element parameter.

Parameters
parameterparameterName or parameterId
valueparameterValue (number|bool|string) according to definition
Warning
An unknown parameter name or id, or a value whose Lua type does not match the parameter type, is silently ignored: no error is raised. Check with Element::hasParameter when the name comes from user input or may differ between element types.
See also
Elements & parameters

Member Data Documentation

◆ parameterDefinitions

table Element::parameterDefinitions

table of parameter definitions.

returns the following table:

property type optional
name string no
id number no
type "int","float","bool","string" no
default type no
displayName string no
description string no
readOnly boolean no
serialize boolean no
min type yes
max type yes

◆ synthChildren

table Element::synthChildren

children of the element in the synthesis hierarchy, as a 1-indexed array.

Differs from children in both content and indexing: children is keyed by element name and lists every direct sub-element (insert and aux effects, event processors, modulation sources, sends, ...), while synthChildren is an ordered array restricted to the nested synthesis structure — the Parts of a Synth, the Program of a Part, the Layers of a Program, the Keygroups of a Layer. Use #element.synthChildren for the count or iterate with ipairs. Oscillators are not synthesis-tree nodes: a Keygroup exposes them through oscillators instead.

Only valid on synthesis-tree elements (Synth, Part, Program, Layer, Keygroup); reading it on any other element raises the error "this Element doesn't have sub elements".