TouchOSC

• Control Callback Functions
• Sending MIDI Messages
• Sending OSC Messages
• Control "Double-tap"
• Send Periodic Message
• Send Accelerometer Data

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.

if(hasAccelerometer()) then
  update = function()
    local values = getAccelerometer()
    sendOSC('/accxyz', table.unpack(values))
  end
end