Script · Examples
- Control Callback Functions
- Sending MIDI Messages
- Sending OSC Messages
- Control "Double-tap"
- Send Periodic Message
- Send Accelerometer Data
- Snap Fader to Grid
Control Callback Functions
The following script demonstrates all possible callback handlers during TouchOSC's processing of an application frame and all associated events.
As the root level of a document will always be called first if it defines any of the following callback functions
(except for the onReceiveNotify callback), when getting started with the scripting API, we recommend
setting this script at the root level, in order to see all possible events being handled and printed to the log view.
function init()
print('init')
end
function update()
print('update')
end
function onPointer(pointers)
print('onPointer')
for i=1,#pointers do
local pointer = pointers[i]
print('\t', pointer.ID, pointer.x, pointer.y, pointer.state, pointer.created, pointer.modified)
end
end
function onValueChanged(key)
print('onValueChanged')
print('\t', key, '=', self.values[key])
end
function onReceiveMIDI(message, connections)
print('onReceiveMIDI')
print('\t message =', table.unpack(message))
print('\t connections =', table.unpack(connections))
end
function onReceiveOSC(message, connections)
print('onReceiveOSC')
local path = message[1]
local arguments = message[2]
print('\t path =', path)
for i=1,#arguments do
print('\t argument =', arguments[i].tag, arguments[i].value)
end
print('\t connections =', table.unpack(connections))
end
function onReceiveGamepad(input, value, connections)
print('onReceiveGamepad')
print('\t input =', input) -- one of the GamepadInput enumeration values
print('\t value =', value)
print('\t connections =', table.unpack(connections))
end
function onReceiveNotify(key, value)
print('onReceiveNotify')
print('\t key =', key)
print('\t value =', value)
end
Sending MIDI Messages
Send MIDI messages on one or multiple connections.
For more information see the MIDI Messages script documentation.
-- control change, controller 0, channel 1
-- all configured connections (1-5)
sendMIDI({ 176, 0, 102 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE, 0, 102 })
-- control change, controller 0, channel 2
-- all configured connections (1-5)
sendMIDI({ 177, 0, 103 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE + 1, 0, 103 })
-- control change, controller 2, channel 6
-- all configured connections (1-5)
sendMIDI({ 181, 2, 104 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE + 5, 2, 104 })
-- send only on connections 1 and 2
sendMIDI({ MIDIMessageType.NOTE_ON, 12, 88 }, { true, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 12, 0 }, { true, true })
-- send only on connections 1 and 3
sendMIDI({ MIDIMessageType.NOTE_ON, 13, 88 }, { true, false, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 13, 0 }, { true, false, true })
-- send only on connections 1 and 5
sendMIDI({ MIDIMessageType.NOTE_ON, 14, 88 }, { true, false, false, false, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 14, 0 }, { true, false, false, false, true })
-- send system exlusive
sendMIDI({ 0xF0, 0x00, 0x01, 0xF7 })
sendMIDI({ MIDIMessageType.SYSTEMEXCLUSIVE, 0x00, 0x0D, 0xF7 })
Sending OSC Messages
Send OSC messages on one or multiple connections.
Messages can either be sent using a simple format, where TouchOSC will auto-convert parameter types, or using a complex format, where each parameter type can be specified using OSC protocol type-tags.
For more information see the Simple OSC Messages and Complex OSC Messages script documentation.
-- -----------------------------------------
-- Send simple OSC messages
--
-- arguments are auto-converted to
-- boolean, float or string (not integer!)
-- -----------------------------------------
-- send on all configured connections (1-5)
sendOSC('/simple')
sendOSC('/ping', 'pong')
sendOSC('/on', true)
sendOSC('/1/fader1', 0.5)
sendOSC('/3/xy1', 0.25, 0.75)
sendOSC('/mixedarguments', 'Hello', 1, true, 'World')
-- send only on connections 1 and 2
sendOSC('/1/fader1', 0.5, { true, true })
-- send only on connections 1 and 3
sendOSC('/3/xy1', 0.25, 0.75, { true, false, true })
-- send only on connections 1 and 5
sendOSC('/mixedarguments', 'Hello', 1, true, 'World', { true, false, false, false, true })
-- -----------------------------------------
-- Send complex OSC messages
-- with argument type tags
-- -----------------------------------------
sendOSC(
-- message
{
-- path
'/complex',
-- argument list
{
{ tag = 'T' }, -- true
{ tag = 'F' }, -- false
{ tag = 'N' }, -- nil
{ tag = 'I' }, -- infinitum
{ tag = 'i', value = 42 }, -- int32
{ tag = 'h', value = 1337 }, -- int64
{ tag = 'f', value = 3.14159 }, -- float32
{ tag = 'd', value = 3.14159265358979 }, -- double
{ tag = 's', value = 'Goodbye Cruel World' }, -- string
{ tag = 'b', value = { 0xC0, 0x00, 0x10, 0xFF } } -- blob
}
},
-- connections
{
true, -- 1
true, -- 2
true, -- 3
true, -- 4
true -- 5
}
)
Control "Double-tap"
Detect a "double-tap" on a control, with a certain maximum time passing between the taps.
local delay = 300 -- the maximum elapsed time between taps
local last = 0
function onValueChanged()
if(not self.values.touch) then
local now = getMillis()
if(now - last < delay) then
print('double tap!')
last = 0
else
last = now
end
end
end
Send a Periodic Message
Repeatedly send an OSC message, in this example once every second.
local delay = 1000 -- every 1000ms = 1s
local last = 0
function update()
local now = getMillis()
if(now - last > delay) then
last = now
sendOSC('/ping')
end
end
Send Accelerometer Sensor Data
Read data from the host device's accelerometer sensor (if available) and send as OSC message.
For more information see the documentation for the getAccelerometer utitlity
function.
function update()
local values = getAccelerometer()
sendOSC('/accxyz', table.unpack(values))
end
Snap Fader to Grid
Snap a fader's values to the configured grid line interval. Works for any control with a value of type FLOAT and a grid steps property.
function onValueChanged(key)
if(key ~= 'touch') then
local steps = self.gridSteps - 1;
self.values[key] =
math.floor(steps * self.values[key] + .5) / steps
end
end