TouchOSC

TouchOSC provides the following global functions.

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

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.

function vibrate()


-- example
vibrate()

On devices that support it, a short vibration will be triggered. Has no effect otherwise.

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 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.

Shared Scripts

function require(string)


-- example
require("Shared Script 1")
require("Shared Script 2")

The require function allows to include a Shared Script by name.

If no Shared Script with a name equal to the parameter string can be found, the function will return false and log an error.

If the Shared Script is found and returns a value, the function will return this value, or true otherwise.

NOTE that Shared Script code can not call require to include other Shared Script code. This might change in a future update.

NOTE that while the require function behaves similarly to Lua's native require function, it is a new implementation native to TouchOSC, and will exhibit differences in behavior.