TouchOSC

TouchOSC provides the following global functions.

• Utility Functions
  • getVersion
  • getMillis
  • getDate
  • hasAccelerometer
  • getAccelerometer
  • hasGyroscope
  • getGyroscope
  • getBatteryLevel
  • bytesToInt
  • bytesToFloat
• Message Functions
  • MIDI Messages
  • Simple OSC Messages
  • Complex OSC Messages
  • Bundled OSC Messages
• JSON Functions
  • json.fromTable
  • json.toTable

Utility Functions

function getVersion()


-- example
local t = getVersion()
print(table.unpack(t))
> 1 2 5 183 -- major minor patch build

Returns a list containing the application's version as major minor patch build number values.

function getMillis()


-- example
local n = getMillis()
print(n)
> 576970.847

Returns the number of milliseconds since application start.

function getDate()


-- example
local t = getDate()
print(table.unpack(t))
> 2023 10 31 32400 -- year month day tzd

Returns a list with the current local date's year month day tzd number values. tzd refers to the timezone differential in seconds.

function getTime()


-- example
local t = getTime()
print(table.unpack(t))
> 10 11 37 893 -- hour minute second millisecond

Returns a list with the current local time's hour minute second millisecond number values.

function hasAccelerometer()


-- example
local b = hasAccelerometer()
print(b)
> true

Returns true if the host device provides an accelerometer sensor, false otherwise.

function getAccelerometer()


-- example
local t = getAccelerometer()
print(table.unpack(t))
> -8.925 0.134 4.078 -- x y z

Returns a list of three number values that are sampled from the host device's accelerometer sensor. If no accelerometer sensor is available, the values will be all zero.

function hasGyroscope()


-- example
local b = hasGyroscope()
print(b)
> true

Returns true if the host device provides a gyroscope sensor, false otherwise.

function getGyroscope()


-- example
local t = getGyroscope()
print(table.unpack(t))
> -8.925 0.134 4.078 -- x y z

Returns a list of three number values that are sampled from the host device's gyroscope sensor. If no gyroscope sensor is available, the values will be all zero.

function getBatteryLevel()


-- example
local n = getBatteryLevel()
print(n)
> 0.84

Returns the current battery charge level as a number ranging from 0.0 to 1.0 on mobile devices, 1.0 otherwise.

function bytesToInt(number, number, number, number)


-- example
local i = bytesToInt(0x4D,0x01,0x00,0x00)
print(i)
> 333

Returns a number that is the 32-bit integer representation created from the four byte number parameter values given.

function bytesToFloat(number, number, number, number)


-- example
local f = bytesToFloat(0x00,0x00,0x99,0x42)
print(f)
> 76.5

Returns a number that is the 32-bit floating point representation created from the four byte number parameter values.

Message Functions

TouchOSC provides the following functions to send MIDI and OSC messages.

MIDI Messages

function sendMIDI(table [, table])


-- example
sendMIDI({ 176, 0, 102 })            -- control change
sendMIDI({ 0xF0, 0x00, 0x01, 0xF7 }) -- system exclusive

Send a MIDI message on one or multiple configured connections.

The first argument table is a list of byte values that make up the MIDI message.

Starting with version 1.2.1.171 the function will process byte data for multiple messages and continue until either the end of the list or an invalid MIDI message is encountered.

The optional second argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the list has fewer elements than the number of connections, the omitted elements default to false.

For more usage examples see the Sending MIDI Messages example.

Simple OSC Messages

function sendOSC(string [, ... [, table]])


-- example
sendOSC('/1/fader1', 0.5)
sendOSC('/3/xy1', 0.25, 0.75)
sendOSC('/hello', 'world')

Send an OSC message on one or multiple configured connections.

string is the path of the OSC message to be sent.

The optional argument values ... will be auto-converted to boolean, float or string OSC types and added to the OSC message as arguments.

Note that argument values are never auto-converted to integer OSC types as scripts do not treat floating point and integer numbers as separate types. Use the complex OSC message send function instead.

The optional last argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the list has fewer elements than the number of connections, the omitted elements default to false.

For more usage examples see the Sending OSC Messages example.

Complex OSC Messages

function sendOSC(table [, table])


-- example
sendOSC(
  {
    '/complex',
    {
      { tag = 'i', value = 42 },                   -- int
      { tag = 'f', value = 3.14159 },              -- float
      { tag = 's', value = 'Goodbye Cruel World' } -- string
    }
  }
)

Sends an OSC message on one or multiple configured connections.

The first argument table is a list that represents the OSC message to be sent, where the first element is the path string of the message, and the second element is a list of argument tables with tag and value keys for each argument:

{
    path,
    {
        { tag = 'argumentTypeTag', value = argumentValue },
        { tag = 'argumentTypeTag', value = argumentValue },
        { tag = 'argumentTypeTag', value = argumentValue },
        ...
    }
}

Each argument value will be converted to an OSC type according to the type tag string provided:

If the tag key is omitted, the value will be auto-converted the same way as when sending simple OSC messages.

The T F N and I types do not need a value to be specified.

The b OSC blob type expects the value to be a list of byte values making up the blob data.

The optional second argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the list has fewer elements than the number of connections, the omitted elements default to false.

For more usage examples see the Sending OSC Messages example.

Bundled OSC Messages

function sendOSCBundle(table [, table])


-- example
sendOSCBundle(
  {
    { '/message1', { { tag = 'i', value = 1337 } } },
    { '/message2', { { tag = 'f', value = 2.71828 } } },
    { '/message3', { { tag = 's', value = 'Hello World' } } }
  }
)

Sends one or more OSC messages as a bundle on one or multiple configured connections.

The first argument table is a list of one or more OSC messages to be sent. The messages are in the same format as described in Complex OSC Messages above.

The optional second argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the list has fewer elements than the number of connections, the omitted elements default to false.

For more usage examples see the Sending OSC Messages example.

JSON Functions

TouchOSC provides the following functions to convert Lua tables to and from JSON encoded strings. All JSON functions are provided inside the global table json.

function json.fromTable(table)


-- example
local t = { a = 123, b = 'hey', c = false, d = json.null }
local str = json.fromTable(t)

Convert a Lua table to a JSON encoded string. The special value json.null can be used to store a null value in the Lua table.

The input table should either be a sequential list of values, which will be converted to the JSON array type, or a list of key/value pairs, which will be converted to the JSON object type.

function json.toTable(string)


-- example
local str = '{ "a":123, "b":"hey", "c":false, "d":null }'
local t = json.toTable(str)

Parse a JSON encoded string and return the result as a Lua table. The JSON null value will be written to the output table as the special value json.null.