Lua: Runtime Utilities
Description
The Lua runtime exposes utility functions for conversion, printing, update-rate control, dependency tracking, inlet access, object references, and object lifetime management.
Frequency and MIDI Conversion
local frequency = midi_to_freq(69) -- 440
local midi = freq_to_midi(440) -- 69
modalys.midi_to_freq and modalys.freq_to_midi use A4 = 440 Hz. They are also available as midi_to_freq and freq_to_midi.
| Function | Description |
|---|---|
| modalys.midi_to_freq(midi) | Returns the frequency for a MIDI note number. Fractional MIDI values are accepted. |
| modalys.freq_to_midi(frequency) | Returns the MIDI note number for a frequency. The result can be fractional. |
Printing and Modalys Messages
print("hello from mlys.lua")
modalys.post_thru_modalys_tilde("status", 1)
print is mapped to modalys.print, which prints to the Max console. modalys.post_thru_modalys_tilde sends a message through the modalys~ message outlet and prefixes it with mlys.lua and the current mlys.lua object name.
Use post_thru_modalys_tilde when a patch needs to receive a message from the Lua script. Use print for diagnostics in the Max console.
Update Rate
local rate = get_update_rate()
set_update_rate(-1)
These functions are aliases for the internal mlys.lua update-rate functions. A value of 0 means every sample, and -1 means automatic.
| Function | Description |
|---|---|
| modalys.get_update_rate() | Returns the current mlys.lua update rate in seconds. |
| modalys.set_update_rate(seconds) | Changes the current mlys.lua update rate. |
Controller Dependencies
local ctrl = create_controller{ kind="dynamic", name="CtrlInternal" }
add_controller_dependency(ctrl)
modalys.add_controller_dependency makes the Lua controller update when one of the specified Modalys controllers changes. It is also available as add_controller_dependency.
Pass one controller reference or several controller references. This is useful when a Lua script caches values and must react as soon as upstream controllers change.
get_current_value
function update()
local previousLeft = get_current_value(1)
local previousRight = get_current_value(2)
return previousLeft * 0.9, previousRight * 0.9
end
modalys.get_current_value returns the current output value of the running mlys.lua controller for the requested rank. It is also available as get_current_value, modalys.out, and out.
The rank is indexed from 1. If the requested rank is outside the controller dimension, the function returns 0.
To read another Modalys controller, use modalys.get_value or get_info("value", controller).
get_info and set_info
local sampleRate = get_info("sample-rate")
local currentValue = get_info("value", ctrl)
local plate = get_ref("MyPlate")
set_info("label", plate, "prepared plate")
modalys.get_info queries runtime information from Modalys. It is also available as get_info and getinfo.
Common forms include:
| Form | Description |
|---|---|
| get_info("sample-rate") | Returns the current sample rate. |
| get_info("value", controller) | Returns the current value of a controller. |
| get_info("value", controller, rank) | Returns one component of a multidimensional controller. |
| get_info("dimension", controller) | Returns the dimension of a controller. |
| get_info("class-name", reference) | Returns the Modalys class name for a reference. |
| get_info(key, object) | Queries information attached to a Modalys object, access, connection, or controller. |
modalys.set_info writes runtime information associated with a Modalys reference. It is also available as set_info and setinfo.
The available keys depend on the target reference and on the Modalys object type. Use object-specific documentation and existing examples when choosing keys.
get_energy
function update()
return get_energy("MyDrum")
end
modalys.get_energy returns the current energy for a Modalys object reference. It is also available as get_energy.
The argument can be a Modalys reference or the name of an item in the Max patch. This is typically used for monitoring or for adaptive control patches where the Lua script reacts to the amount of energy currently stored in an object.
Inlets
local count = get_inlet_count()
local value = inlet(1)
local secondComponent = inlet(1, 2)
local inputRef = inlet_ref(1)
mlys.lua inlets are indexed from 1 in Lua scripts.
| Function | Description |
|---|---|
| modalys.inlet(index) | Returns the current value received by an mlys.lua inlet. If the inlet contains a Modalys reference rather than controller values, the reference is returned. |
| modalys.inlet(index, rank) | Returns one component from a multidimensional controller connected to an inlet. |
| modalys.get_inlet_count() | Returns the number of inlets for the current mlys.lua controller. |
| modalys.get_inlet_ref(index) | Returns the Modalys reference connected to an inlet, when the inlet carries one. |
These functions are also available as inlet, modalys.input, input, modalys.in, in, get_inlet_count, modalys.inlet_ref, and inlet_ref.
get_ref
local access = get_ref("MyPlate_access_in_1")
local force = get_info("force", access)
modalys.get_ref returns the Modalys reference associated with a named item in the Max patch. It is also available as get_ref.
Use it when a Lua script must manipulate Modalys objects, accesses, controllers, or connections created elsewhere in the patch rather than created inside the same script.
Object Controller Assignment
local oscillator = create_object{ kind="harmonic-oscillator", frequency=220, name="LuaOsc" }
local amp = create_controller{ kind="constant", value=0.2, name="LuaAmp" }
local freq = create_controller{ kind="constant", value=330, name="LuaFreq" }
local loss = create_controller{ kind="constant", value=1.0, name="LuaLoss" }
set_amplitude_controller("LuaOsc", "LuaAmp")
set_frequency_controller("LuaOsc", "LuaFreq")
set_loss_controller("LuaOsc", "LuaLoss")
These functions assign controllers explicitly to Modalys objects:
| Function | Description |
|---|---|
| modalys.set_amplitude_controller(object, controller) | Sets the amplitude controller for an object. |
| modalys.set_frequency_controller(object, controller) | Sets the frequency controller for an object. |
| modalys.set_loss_controller(object, controller) | Sets the loss controller for an object. |
They are also available without the modalys. prefix.
The public wrappers resolve their arguments with get_ref, so named Max items and Lua-created references can both be used.
freeze_object
local object = create_object{ kind="mono-string", pitch=60, length=1.0 }
freeze_object(object)
freeze_object(object, false)
modalys.freeze_object freezes the current state of a Modalys object. It is also available as freeze_object.
The second argument is optional. It defaults to true. Pass false to unfreeze the object.
Use it when an object has been configured through intermediate operations and should be made stable before later processing or reuse.
apply_envelope
local ctrl = create_controller{ kind="dynamic" }
apply_envelope(ctrl, { 0, 0, 0.01, 1, 0.2, 0 })
modalys.apply_envelope applies an envelope description to a controller. It is also available as apply_envelope.
The envelope values are expected as a sequence of time/value points. For multidimensional controllers, each time is followed by one value per dimension. You can also pass a separate time array:
apply_envelope{
ctrl = ctrl,
time = { 0, 0.01, 0.2 },
value = { 0, 1, 0 }
}
The wrapper interleaves time and value before calling the lower-level runtime.
Object Lifetime
release(mesh, object, controller)
modalys.release destroys numeric Modalys references passed as arguments. It is useful when building intermediate meshes or temporary objects. It is also available as release.
Environment Queries
local osName = get_os()
local sampleRate = get_sample_rate()
| Function | Description |
|---|---|
| modalys.get_os() | Returns "windows", "mac", or "linux". |
| modalys.get_sample_rate() | Returns the current sample rate. This is equivalent to get_info("sample-rate"). |
| modalys.compute_modes(object) | Computes modes for a modal object when they have not already been computed. |
| modalys.set_cents_pitchbend(...) | Calls the Modalys spectral/pitchbend runtime helper. |
| modalys.set_spectral_diffraction(...) | Calls the Modalys spectral diffraction runtime helper. |
These functions are also available as get_os and get_sample_rate.
★