TouchOSC

TouchOSC is a modular control surface toolkit for designing and constructing custom controllers that can be used on a multitude of operating systems and devices.

TouchOSC can be used on touch-screen mobile devices as well as desktop operating systems using traditional input methods.

TouchOSC can communicate with other software and hardware using the MIDI and Open Sound Control protocols in a variety of ways and via many different types of wired and wireless connections simultaneously.

All versions of TouchOSC include the powerful, integrated editor, to customize every detail of your controller setup. If the default behavior of the selection of available controls does not exactly do as you wish, there is unlimited possibilities using the deep scripting engine and the easily configured inter-control communication using local messages.

Any control surface document you create can be freely exchanged between all versions of the application, and we've worked hard to make sure that every aspect of your controller will be rendered and behave exactly the same, no matter what kind of hardware TouchOSC is running on.

We are always working on adding more protocols, input methods and features, if you would like to suggest anything that is missing for your use-case or workflow - please do not hesitate to contact us and let us know. We think of every single suggestion as a vote - if enough votes are cast, we will make it happen!

Please note that a manual for an application as complex as TouchOSC will always be a work in progress, much like the application itself, and we will continually update these pages based on user feedback and application updates - of which there will be many.

So please do check back from time to time for updates and additions to the material presented here.

Hexler Heavy Industries - 2021

No one likes to read manuals, right?

To get you started as quickly as possible, we've compiled brief tutorials for the minimum steps required to set up working MIDI and OSC connections, and an example of how the MIDI mapping of another application would usually work.

These are not meant to be exhaustive instructions on how to set up TouchOSC, but more of a quick start to make use of your new control surface right now.

If you run into trouble with these, or want to know more, please do consult the detailed sections of the manual for each of the respective functions and configuration, and please feel free to contact us if nothing helps or you think something that should be mentioned here is missing.

• MIDI
• OSC
• Ableton Live

In this short tutorial, we will be setting up the sending of MIDI messages from TouchOSC to another application on the network.

We'll be using the TouchOSC Bridge utility application, to handle sending MIDI messages over the network, as this is a common use-case for control surfaces running on mobile touch-screen devices.

If you want to send MIDI messages between TouchOSC and other applications or ports on the same device or computer, the set-up becomes much more straight forward, and you can skip the steps involving TouchOSC Bridge in this tutorial.

• Protokol
• TouchOSC Bridge
• TouchOSC
• Send MIDI messages

Protokol

We'll be using the Protokol application, our free tool for testing OSC and MIDI connections and messages. This is the same utility we use in-house for testing our applications.

Protokol is available for all the same platforms as TouchOSC and is a free download.

• Download and install any version of Protokol
• Launch the application, switch to the MIDI tab page, and check the checkbox next to Enabled
• Protokol is now waiting for incoming MIDI messages on all available MIDI ports

TouchOSC Bridge

TouchOSC

Send MIDI messages

With both the receiver and sender configured and ready to go, we'll send some MIDI messages.

Move a fader, press a button or interact with any other control on the control surface in TouchOSC and you should see the received MIDI messages being printed in Protokol.

In this short tutorial, we will be setting up the sending of OSC messages from TouchOSC to another application.

• Protokol
• TouchOSC
• Send OSC messages

Protokol

We'll be using the Protokol application, our free tool for testing OSC and MIDI connections and messages. This is the same utility we use in-house for testing our applications.

Protokol is available for all the same platforms as TouchOSC and is a free download.

• Download and install any version of Protokol
• Launch the application, switch to the OSC tab page, and check the checkbox next to Enabled
• Protokol is now listening for OSC messages and is also advertising its OSC receiver on the network.

TouchOSC

Send OSC messages

With both the receiver and sender configured and ready to go, we'll send some OSC messages.

Move a fader, press a button or interact with any other control on the control surface in TouchOSC and you should see the received OSC messages being printed in Protokol.

In this short tutorial, we will walk through mapping MIDI messages from TouchOSC to interface elements in Ableton Live.

Even though we are using Ableton Live in this example, other applications can usually be configured in a similar fashion. Please refer to the application's manual, specifically the MIDI mapping / learn section, to find out how you can map MIDI messages to application functions.

Open Ableton Live's Preferences dialog, select the section labelled "MIDI / Sync" and enable the Track and Remote columns for the MIDI Ports labelled TouchOSC Bridge.

Now Ableton Live is receiving and sending MIDI messages through TouchOSC Bridge. To confirm this, move or press any control in TouchOSC's Simple Mk2 layout (which we loaded in the MIDI tutorial) and you should see the tiny light in the very top-right corner of Ableton Live light up whenever you do so.

Enter Ableton Live's MIDI Mapping mode by pressing the button labelled MIDI, also in the top-right corner. This will highlight all elements in Live's UI that can be assigned to MIDI controllers with a blue overlay. Select one of these elements, such as one of the Audio-channel's volume faders, and the next MIDI message received by Live will be assigned to this UI element.

Move or press any of the controls in TouchOSC and you will see that Live will add a row to the MIDI Mappings window, and will add another overlay right above the selected UI element displaying details about the MIDI message, such as channel and type.

The element is now mapped bi-directionally between TouchOSC and Live. You can now exit Live's MIDI Mapping mode by clicking on the MIDI button in the top-right corner again and start controlling Live with TouchOSC. For more info on configuring Ableton Live please refer to Ableton's official manual.

TouchOSC comes with a powerful, integrated editor on all platforms, for creating and editing control surface documents.

TouchOSC can open touchosc layout files made for TouchOSC Mk1, and some aspects of the import can be configured in the preferences.

Documents will be saved in a new tosc document format, specific to this new version, which is not compatible with the TouchOSC Mk1 application.

Multiple documents can be opened at the same time and all parts of the layout can be copied from one document to another.

Multiple instances of the application can be connected over the network, for synchronized editing and preview on multiple clients in real-time, using the application's Editor Network client-server functionality.

While there a minor differences between the desktop and mobile versions, most functions work identical across all supported platforms, and we'll point out some of the differences in their respective sections.

The main interface of TouchOSC can be in one of two modes, Editor and Control Surface mode.

Switch to control surface mode by pressing the play button in the editor Toolbar, and the circle icon button in the control surface to switch back. On desktop platforms the CTRL/CMD+E keyboard shortcut can be used to toggle between both modes.

The position of the circle button in the control surface can be configured in the preferences.

• Control Surface Editor
• Panel
• Toolbar
• Log View
• Message Mapping
• Font Viewer

Control Surface Editor

Panel

Toolbar

Log View

Message Mapping

Font Viewer

A document is the top-level container for all controls and the root node of the control hierarchy tree.

A document has properties that define the display size and background color, global routing options for messages and optional notes by the creator.

A document can also have a script attached and define control callback functions, which will be called before any other script callbacks and allow to capture certain events globally before they are forwarded to the target controls. See Object Callback Functions for details.

• Width
• Height
• Color
• Routing
• Comments
• Document Tree

Width

Height

Color

Routing

Comments

Document Tree

A control is the main object and basic building block for constructing control surfaces.

A control has properties and values that define its appearance and behavior, and controls can have messages and scripts attached to it.

Some control types can be containers for other controls. All controls carry a reference to their parent control, except for the document root container at the very top of the document hierarchy.

See the Control Reference for a complete list of available control types and their properties.

All controls have properties that determine appearance and behaviour.

Control properties can be changed in the editor and by messages and scripts.

All controls have a set of common properties and another set of properties specific to their type. Not all control types might use all the common properties or use them in the same way.

For a list of control type specific properties, see the control reference.

• Type
• Name
• Tag
• X, Y, W, H
• Color
• Locked
• Visible
• Interactive
• Background
• Outline
• Grab Focus
• Pointer
• Corner
• Orientation

Type

Name

Tag

X, Y, W, H

Color

Locked

Visible

Interactive

Background

Outline

Grab Focus

Pointer

Corner

Orientation

A control can have multiple value objects that are related to a control's internal state.

Values differ from properties in that they can be used as triggers for messages and script callback functions.

A value object can be changed by pointers, messages and scripts. Whenever any value object changes, the application will invoke the control's onValueChanged script callback function, if it is defined, and then process all messages that specify the changed value in their list of triggers.

All controls have a Touch value object, the BOOLEAN value of which indicates if there are any pointers currently interacting with the control.

• Locked
• Type
• Default
• Current
• Default Pull
• Default-Current Lock

Locked

Type

Default

Current

Default Pull

Default-Current Lock

TouchOSC supports multiple message types to send and receive.

MIDI, OSC and local messages can be sent in response to control value object changes using a message's trigger configuration.

MIDI and OSC messages can be also be sent using script functions and can be received on configured connections.

Messages can be added by pressing the plus button on the right of the message panel header in the editor panel and selecting one of the available message types.

Messages can be removed by pressing the x button on the right of each individual message's panel header and confirming the action.

A control can have an unlimited number of messages configured. Messages will be processed in the order they are listed in the interface, the order of messages can be changed by dragging the message to a new position in the list.

• MIDI
• OSC
• Local
• Gamepad

MIDI

OSC

Local

Gamepad

A control can have multiple MIDI messages configured. Messages can be both sent and received on multiple connections.

When a message is enabled to send, it will be sent on the configured connections when any of the control's values enabled as trigger change, and if the change matches the change condition of the trigger.

When a message is enabled to receive, it will be considered to be matched against received MIDI messages if the incoming message is received on one of the enabled connections.

Message matching depends on the type of MIDI message. TouchOSC defines part of a MIDI message as the address part, used for routing to determine the target controls, and another part as the payload.

The type of the message and the address part will be used to determine if the incoming message matches the control's message, and the payload part will then be processed to extract values and properties to update (if so configured).

See the message matching section for details on address/payload for each message type.

• TEST
• Enabled
• Send
• Receive
• Feedback
• No Duplicates
• Connections
• Trigger
• Type
• Matching

TEST

Enabled

Send

Receive

Feedback

No Duplicates

Connections

Trigger

Type

Matching

A control can have multiple OSC messages configured. Messages can be both sent and received on multiple connections.

When a message is enabled to send, it will be sent on the configured connections when any of the control's values enabled as trigger change, and if the change matches the change condition of the trigger.

When a message is enabled to receive, it will be considered to be matched against received OSC messages if the incoming message is received on one of the enabled connections and the address part matches the received message.

• TEST
• Enabled
• Send
• Receive
• Feedback
• No Duplicates
• Connections
• Trigger
• Address
• Arguments
• Partials

TEST

Enabled

Send

Receive

Feedback

No Duplicates

Connections

Trigger

Address

Arguments

Partials

A control can have multiple local messages configured. Local messages act like a direct connection between controls to change values and properties locally.

A control can be both the source and target of a local message, for example changing its own color based on the state of its touch value object.

On desktop platforms, a local connection between controls can be quickly created in the editor by holding down the ALT key and drawing a connection between source and target controls. On all platforms, the target can be picked using the picker icon in the target row.

• Enabled
• Trigger
• Source
• Target
• Scale
• Conversion

Enabled

Trigger

Source

Target

Scale

Conversion

A control can have multiple gamepad messages configured. Gamepad messages can only be received and not sent.

A gamepad message is configured to wait for a certain game controller input on one or multiple configured gamepad connections, and apply the received input value to one of the control's values or properties.

For portability between platforms, and to allow TouchOSC documents to be shared with users using different input devices, all game controllers are mapped to a standard Xbox 360-like controller layout.

This is the same strategy as employed by the ubiquitous Steam game client and the popular SDL2 game development library, and we support the same mapping database format as these.

On desktop platforms, if no mapping can be found for the game controller in the included database, TouchOSC will output a warning to the log view upon connection.

It is possible to update and customize TouchOSC's internal database of controller mappings by placing a text file following SDL2's game controller database format in TouchOSC's configuration directory, found at the following location for each platform:

• Windows:

  %AppData%/TouchOSC/

• macOS:

  ~/Library/Application Support/net.hexler.lex/

• Linux:

  ~/.TouchOSC/

TouchOSC will look for a file called gamecontrollerdb.txt at this path once at application launch, and if found, will try to load and apply that configuration.

• Enabled
• Connections
• Input
• Target
• Scale
• Conversion

Enabled

Connections

Input

Target

Scaling

value = (input - min) / (max - min)

Conversion

The script editor UI for editing script source code. Please see the Scripting API section of the manual for details about the script language and available functions and objects.

• Editor
• Summary
• Log
• Run

Editor

Summary

Log

Run

The application's editor network feature allows one instance of the application to act as editor server on the network and lets multiple other instances on the network connect as clients.

The editor server will broadcast the current document and all editor actions to all connected clients in real-time.

The editor clients will be locked into control surface mode and not be able to make any edits while connected to the server. Once disconnected from the server, the document can be edited and saved on the client.

Connected clients will still be able to use the control surface with all messages and scripts fully functional, making it possible to test the configuration of a control surface immediately, while making changes on the server.

NOTE that the current values of a control's value objects are only transmitted once after the initial connect or if explicitly edited on the server, as it would interfere with the ability to test a control surface's functionality and use, if value objects would be continually reset to the current state of the server document while connected.

• Client
  • Manual Connect
  • Available Servers
• Server
  • Enabled

Client

Server

TouchOSC supports multiple connection types for messages to be sent and received on.

Each type of connection can have between four and ten separate, simultaneous connections configured, each with separate send and receive endpoints.

Each of these numbered connections can be enabled individually in a message's configuration.

• MIDI
• OSC
• Bridge
• Gamepad

MIDI

OSC

Bridge

Gamepad

TouchOSC allows to configure ten separate MIDI connections, each with freely assignable input and output ports. Each of these connections can be individually enabled for a control's MIDI messages to be sent and received on.

All enabled TouchOSC Bridge connections can also be configured here as input and output ports just like regular MIDI ports - with TouchOSC transparently handling the transport of MIDI messages over the network via these ports.

• Enable
• Expand
• Send Port
• Receive Port
• Browse

Enable

Expand

Send Port

Receive Port

Browse

TouchOSC allows to configure ten separate OSC connections, each with freely assignable send destination and receive port. Each of these connections can be individually enabled for a control's configured OSC messages to be sent and received on.

Each connection's receive port can also be advertised on the network using the Zero Configuration Networking (Zeroconf ) standard for other OSC enabled applications and devices to discover.

• Enable
• Expand
• Type
• Host
• Send Port
• Receive Port
• Network Info
• Zeroconf
• Browse

Enable

Expand

Type

Host

Send Port

Receive Port

Network Info

Zeroconf

Browse

TouchOSC allows to configure five separate connections to connect to instances of the TouchOSC Bridge application.

TouchOSC Bridge acts as a virtual MIDI interface, transparently transmitting MIDI messages to and from another host on the network, or using a USB cable connection on iOS devices.

Each enabled Bridge connection can be individually selected as MIDI input and output port in the MIDI connections configuration.

• Enable
• Host
• Browse

Enable

Host

Browse

TouchOSC can be configured to receive inputs from four separate, connected game controllers. Each of these connections can be enabled for a control's Gamepad messages to receive input from.

• Enable
• Controller
• Browse

Enable

Controller

Browse

• User interface scale
• Updates
• Show comments after loading
• Send anonymous usage statistics
• Enable debug logging

User interface scale

Updates

Show comments after loading

Send anonymous usage statistics

Enable debug logging

• Appearance
  • Show Grid
  • Snap to Grid
  • Show Rulers
• Behaviour
  • Create default MIDI messages
  • Create default OSC messages
  • Assign new names on copy/paste
  • Pager navigation only with ALT key
• Script
  • Font Size
  • Word Wrap
  • Code Highlighting
  • Code Completion

Appearance

Behaviour

Script

• Display
  • Orientation
  • Filter
  • Allow sleep
• Padding
• Back Button
  • Double-tap
  • Vertical
  • Horizontal

Display

Filter

Allow sleep

Padding

Back Button

• Timeout
• Invalid API Usage

Timeout

In Control Surface mode, long-running scripts will be terminated to prevent the application from stalling.

• SHORT

  The default setting, any one script is allowed to take up to ~200ms.

• LONG

  For older devices running complex layouts it might be helpful to extend the timeout to ~2000ms. Please use this setting with caution and only if absolutely necessary.

NOTE that in editor mode, the timeout will always be longer than either of these settings to allow for long-running, manually launched scripts to help with editing actions.

Invalid API Usage

When invalid API usage is detected (e.g. accessing non-existent control properties or values, or calling API functions with wrong arguments) the following action will be taken:

• ERROR

  If the Log View is active an error message will be printed to the SCRIPT log and the script will be stopped.

• WARN

  If the Log View is active a warning message will be printed to the SCRIPT log and the script will continue to execute. If the API call in question expects a return value, nil will be returned.

• IGNORE

  No message will be printed in the SCRIPT log and the script will continue to execute. If the API call in question expects a return value, nil will be returned.

• Font Size
• Keep log lines
• Display
  • Timestamps
  • Control name as path
  • Open in separate window

Font Size

Keep log lines

Display

Options that apply to the import of touchosc files.

TouchOSC Mk1 defines some OSC messages that are either enabled globally in the application's OSC options or automatically enabled for all controls. To provide backwards compatibility some of the following preferences offer the option to generate these messages automatically on import.

• Appearance
  • Apply Classic Style
• Global OSC Messages
  • Ping
  • Accelerometer
• Control OSC Messages
  • Touch
  • Visibility
  • Position
  • Size
  • Color

Appearance

Global OSC Messages

Control OSC Messages

• General
  • Read NOTE OFF message velocity
• Virtual Ports
  • Create MIDI input
  • Create MIDI output

General

Virtual Ports

In this overview we describe all properties and values that are specific to each control type. For a description of common properties and values that all types of controls share, please see Properties and Values.

All properties and values can also be accessed from within scripts. Please see the scripting API's Properties & Values section for information about the field names and types to use for script access.

• BOX
• BUTTON
• LABEL
• TEXT
• FADER
• XY
• RADIAL
• ENCODER
• RADAR
• RADIO
• GROUP
• PAGER
• GRID

BOX

A box control is a simple shape with no behavior. It is meant to be efficient to render, for creating decorative elements and backgrounds or to be moved and positioned using messages and script.

BUTTON

A simple button control with properties to control the press/release behavior. As it uses a FLOAT value for its display, it can be also used as a simple LED display.

LABEL

A single-line text display.

TEXT

A multi-line text display.

FADER

A fader control.

XY

A two-dimensional fader control.

RADIAL

A rotary fader control.

ENCODER

A circular encoder control.

RADAR

A circular XY control, measuring distance from center and angle.

RADIO

A single value selection from a number of discrete values.

GROUP

A simple container for child controls. A group will clip the rendering of any contained child controls to its display area.

PAGER

A paged container for child controls. A pager contains a number of group child controls ("pages") and will display only the active one based on its page value. A pager control can be ungrouped to extract the individual page group child controls.

GRID

A container for a two-dimensional, uniform grid of child controls of the same type. A grid control can be ungrouped to extract the individual child controls. The editor will display the child control type's properties in addition to the grid control's own properties,

Examples, instructions and recipes on how to set up TouchOSC with other applications and hardware.

We'll be adding more of these in the future, so please check back again at a later time.

Getting Started

• Protokol / MIDI
• Protokol / OSC
• Ableton Live

How-to's

• Android USB MIDI
• Resolume Wire
• Steam Deck
• Traktor Pro
• Logic Pro

Beginning with the Android 6.0 (Marshmallow) release, device makers can enable optional MIDI support in the platform.

If your device manufacturer added support for the USB peripheral mode, please follow these steps to enable it and make your device appear as a MIDI device via the USB cable connection, which TouchOSC can then use to send and receive MIDI messages.

• Device Setup
• TouchOSC Setup
• Send MIDI messages

Device Setup

While attached to a USB host, pull down from the top of screen and select the entry USB for ... or similar. The exact wording will depend on the customizations applied by your device manufacturer.

From the list of options that appear, select MIDI or similar. Again, the exact wording will depend on the customizations applied by your device manufacturer.

Alternatively these options can also be found in the Android Developer Options at Settings > Developer options > Networking > Select USB Configuration.

TouchOSC Setup

By enabling the USB peripheral mode on your Android device, the OS will also create MIDI input and output ports that TouchOSC can use to send and receive MIDI messages via the USB cable connection.

In TouchOSC's MIDI connection configuration select the newly created Android USB Peripheral Port (or similar) for both the Send Port and Receive Port fields.

Sadly, again, the exact naming of these ports will depend on the customizations applied by your device manufacturer.

Send MIDI messages

We'll use the Protokol application to confirm that the MIDI ports are visible to our USB host and that we can receive MIDI messages sent from TouchOSC.

Protokol is our free tool for testing OSC and MIDI connections and messages. This is the same utility we use in-house for testing our applications.

Launch the Protokol application, switch to the MIDI tab page, and check the checkbox next to Enabled

If all went well, you should see a connected MIDI endpoint in Protokol that is named similarly to your device, and MIDI messages sent from TouchOSC via the USB connection should be received by Protokol.

As you might have guessed, the exact names of the MIDI ports that your device creates depend on the customizations applied by your device manufacturer.

Resolume Wire is a modular node-based patching environment to create effects, mixers and video generators for Resolume Arena & Avenue.

Wire supports both MIDI and OSC control, but as OSC is the more flexible of the two and can be used both locally and over a network, we'll walk through integrating OSC control from TouchOSC into your Wire project.

• Enable OSC Input
• Configure TouchOSC
• Create OSC nodes
• Print OSC messages

Enable OSC Input

Open the Wire preferences, switch to the OSC section on the left and enable the OSC Input.

Wire is now listening for incoming OSC messages at the IP Address and Incoming Port number displayed here.

Configure TouchOSC

Open TouchOSC and make sure that you are connected to the same network as the machine that is running Wire.

Open TouchOSC's OSC connection settings.

Make sure Connection 1 is enabled and set to type UDP.

Use the Browse button to search for and select Wire's OSC input on the network and fill in the required values automatically.

If the Wire receiver cannot be found, manually fill in the IP Address displayed in Wire's OSC preferences in the Host field, and the Incoming Port number into the Send Port field.

Close the dialog and open any document configured to send OSC messages, such as the included example layout Simple Mk2.

Switch to control surface mode using the Play button in the toolbar.

Send a few OSC messages from TouchOSC to Wire by using any of the controls in the layout.

In Wire, expand the OSC Input log by pressing the button with the arrow pointing to the right in the top right corner of the OSC preferences.

If everything is working, you should see the OSC messages sent from TouchOSC to Wire appear in the OSC Input log and the basic configuration is complete.

Create OSC nodes

Create a new Wire project and double-click on the empty project's background to open the node search window.

Enter OSC to filter all nodes related to OSC communication.

Select OSC In to create an OSC input node.

Open the node search window again and create a Read OSC node.

Connect the output of the OSC In node to the input of the Read OSC node.

In the Read OSC node's Address field, enter the OSC address that you want to receive.

If you've opened the Simple Mk2 layout in the previous steps, enter /1/fader1.

Open the node search window once again, search for print and create a Print node.

Connect the Param 1 output of the Read OSC node to the input of the Print node.

With this setup, the value of the first parameter of OSC messages with OSC address /1/fader1 sent to Wire will be printed to the Log.

If you've opened the Simple Mk2 layout in the previous steps, this will be a floating point value ranging from 0.0 to 1.0.

Print OSC messages

With both the setup in TouchOSC and Wire now complete, let's open the Log view in Wire and confirm that the values are being printed.

The Log view in Wire can be found in the Log tab in the panel to the top right of the window.

Send OSC messages from TouchOSC by using the fader control pictured below and you should see the received values printed in the Log view in Wire.

Starting with this basic patch, it should be easy to use the values received from TouchOSC in your own compositions and visual effects.

Happy patching!

Follow these steps to download, install and run TouchOSC on the Steam Deck.

• Switch to Desktop Mode
• Download TouchOSC
• Extract TouchOSC
• Launch TouchOSC

Switch to Desktop Mode

Open the Steam Menu using the Steam Button and select Power.

In the following dialog select Switch to Desktop.

The Steam Deck will now switch to Desktop Mode.

Download TouchOSC

Start the Firefox web browser from the task bar at the bottom and navigate to the TouchOSC download section located at https://hexler.net/touchosc#get.

In the Desktop section of the downloads, click the button labelled LINUX.

A pop-up dialog with all available versions for Linux will appear. Click the button labelled ZIP in the section x86 / 64-bit.

The zip file will be downloaded to your Downloads folder.

Open the file browser from the task bar at the bottom (or the downloads menu in Firefox) and select Downloads in the list of Places on the left.

Extract TouchOSC

In the file browser double-click or tap the downloaded zip file and the archiving tool will launch and display the contents of the zip archive.

Select the line that reads TouchOSC and click the Extract button in the top left.

In the dialog that appears there's no need to change anything, just click Extract again to unpack the TouchOSC executable to your Downloads folder.

Launch TouchOSC

Back in the Downloads folder in the file browser there is now a new file named TouchOSC.

Double-click or tap this file.

In the dialog prompting "What do you wish to do with this file?" choose Execute.

The application should launch and the main TouchOSC window should appear - ready for some portable control surface action!

If you are new to TouchOSC please have a look at our Getting Started section.

If you are running into any problems following these steps, please do not hesitate to contact us and let us know!

For the next generation of TouchOSC, Traktor wizard Andrew Norris has created the follow-up to his legendary Jog-On layout.

Jog-On 2 is the essential control surface for Native Instruments' Traktor Pro software and is included with TouchOSC and ready to go.

Downloads

Download the detailed manual and Traktor setup file below. The layout itself is included with the application on all platforms.

Updates

v2.1 - 04 Mar 2024

• Stem Decks: volume, filter, or FX sends for all four individual Stem Tracks can now be controlled together without having to switch between pages/tabs.
• Added volume level meters for each individual Stem Track.
• All volume level meters on all Decks now display individual L/R volume levels rather than L/R summed to mono.
• All volume level meters on all Decks now display ‘warning’ colour change when volume level approaches peak.

v2.0 - 06 Jun 2021

• Complete redesign of the original Jog-On layout for TouchOSC.

Videos

A selection of videos by Andrew demonstrating and explaining the inner workings of the layout.

Minimum required versions

• Logic Pro 9.1.2 or higher

Note: Make sure your computer and all mobile devices are on the same wireless network.

Adding TouchOSC as Control Surface in Logic

• Start Logic 9.1.2 or higher.
• Start TouchOSC and configure an OSC Connection as follows:
  • Enable a connection and set Type to UDP.
  • Click the Browse button and select the name of the computer running Logic. The Host and Send Port fields should now be filled in.
  • Enter a port number in the Receive Port field (ie 7000).
  • Set the Zeroconf option to LogicPad or LogicTouch, depending on which of these two layouts you plan to use.
  • Click Done to apply the connections settings.
• Logic will display the following alert:

• Click the Add button. Logic will add the device as a control surface and open the Control Surfaces Setup window.

Note: If you share the wireless network with other Logic systems, you may want to select the Don't show again check-box when adding your last TouchOSC device. This will prevent the dialog from appearing whenever other users start their TouchOSC devices. You can reset this alert suppression by re-enabling New > Automatic Installation in the Control Surfaces Setup window.

Note: If the macOS software firewall is enabled, an alert will come up when sending the first OSC message. You will need to confirm the alert so that Logic can communicate with the OSC device.

Note: It is not possible at this time to use customized Layouts or to learn OSC commands. However, authorized 3rd party developers can create Logic CS plug-ins which can use OSC-based communication.

TouchOSC's scripting API is based on the Lua 5.1 language and virtual machine with custom additions and modifications.

Scripts can be added to all controls in a document and at the document root level. Each control's script will be executed in its own Lua context.

• Lua Functions
• Global Functions
  • Utility
  • Message
  • JSON
• Objects
  • Control
  • Messages
  • Rectangle
  • Color
  • Vectors
• Enumerations
• Constants
• Properties & Values
• Examples

The following Lua standard library functions are available.

base

Only the following Lua base library functions are available:

error
ipairs
next
pairs
print
select
tonumber
tostring
unpack
type

table

All standard Lua table library functions are available plus the following additions:

table.pack(...)

Returns a new sequential table created from the elements provided.

table.unpack(...)

Same as the Lua base library function unpack.

math

All standard Lua math library functions are available plus the following additions:

math.clamp(number, number, number)

Returns min(max(x, minVal), maxVal) where x is the first parameter and minVal and maxVal the second and third parameters.

string

All standard Lua string library functions are available.

bit32

Support for bitwise operations has been back-ported from Lua 5.2. All functions are available inside the table bit32.

utf8

Basic support for UTF-8 encoding has been back-ported from Lua 5.3. All functions are available inside the table utf8.

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

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.

TouchOSC defines the following objects to represent its internal and native types.

• Control
• Messages
• Rectangle
• Color
• Vectors

A control object represents a reference to a single control contained within a TouchOSC document.

Using this reference most of a control's properties and values can be queried and set. From within a control's script, the self reference can be used to refer to the control's own fields and functions, the root reference (since 1.0.5.109) can be used to refer to the document's root control.

Each control is assigned a unique ID on creation that remains unchanged during and between application runs, document save/load and editor network transfer.

All controls live in a document tree hierarchy starting at the document root. All controls except for the root have a reference to a parent control, and some control types are containers for child controls.

During compilation each script will be checked for the definitions of any of the callback functions listed below, which serve as the main customization points during the various stages of TouchOSC's processing of an application frame.

• Fields
  • ID
  • type
  • index
  • parent
  • children
  • properties
  • values
  • messages
  • pointers
• Functions
  • getValueField
  • setValueField
  • getValueProperty
  • setValueProperty
  • notify
  • findByID
  • findByType
  • findAllByType
  • findByProperty
  • findAllByProperty
  • findByName
  • findAllByName
• Callback Functions
  • init
  • update
  • onValueChanged
  • onPointer
  • onReceiveMIDI
  • onReceiveOSC
  • onReceiveGamepad
  • onReceiveNotify

Fields

control.ID


-- example
local myID = self.ID
local parentID = self.parent.ID
print(myID == parentID)
> false

A unique ID string, generated when the control is created. It remains unchanged over a control's lifetime, during document load/save and during editor network transmission.

control.type


-- example
local myType = self.type
print(myType == ControlType.BUTTON)
> true

Control type numeric constant, one of the ControlType enumeration values.

control.index


-- example
local myIndex = self.index
local parentIndex = self.parent.index

The control's position in its parent list of child controls, 1 to n for regular controls, 0 for the document root.

control.parent


-- example
local myParentControl = self.parent
local noParentControl = root.parent -- will be nil, root has no parent

A reference to the control's parent Control object, or nil for the document root.

control.children


-- example
self.children.button1.visible = false -- set 'visible' property on child 'button1'
self.children['button1'].visible = false -- same as the previous line
local firstChild = self.children[1] -- first child control
local secondChild = self.children[2] -- second child control
print(#self.children) -- print the number of child controls

A list of the control's child Control objects. The list can be indexed by control name (a string) or index (a number). Control names are user assignable and not unique.

control.properties


-- example
self.properties.name = 'new_name'
self.properties['name'] = 'new_name' -- same as the previous line
self.name = 'new_name' -- same as the previous line
self.frame.x = 10
self.color = Color(1,0,0)
self.color.r = 0
print(#self.properties) -- print the number of properties

A list of the control's properties. The list can be indexed by property name (a string) or index (a number). Property names are unique.

NOTE For convenience, indexing a control reference directly using control.name or control[name], where name is not one of the field or function names listed here, will implicitly index the control's property list with control.properties[name].

Therefore control.color and control.properties.color will refer to the same property value.

See Control Properties and Values for a list of possible properties for each control type.

control.values


-- example
self.values.x = 1
self.values['x'] = 1 -- same as the previous line
print(#self.values) -- print the number of values

A list of the control's values. The list can be indexed by value name (a string) or index (a number). Value names are unique.

See Control Properties and Values for a list of possible values for each control type.

control.messages


-- example
local midiMessages = self.messages.MIDI -- same as: self.messages[1]
local oscMessages = self.messages.OSC -- same as: self.messages[2]
local localMessages = self.messages.LOCAL -- same as: self.messages[3]
local gamepadMessages = self.messages.GAMEPAD -- same: as self.messages[4]
print(#self.messages)
> 4

A list of the control's messages, containing separate lists for each message type. The list can be indexed by

• message type name (a string): MIDI, OSC, LOCAL, GAMEPAD
• index (a number): 1 - 4

The messages in each of the lists will be in the same order as they are displayed in the editor UI.

See Script · Objects · Messages for a description of the four message object types.

control.pointers


-- example
local pointer = self.pointers[1]
print(pointer.ID,
      pointer.x, pointer.y,
      pointer.state,
      pointer.created, pointer.modified)
> 0 33.285 20.393 1 1836924.838 1836914.867

A list containing one table for each pointer currently associated with the control during the current frame with the following table keys per pointer:

Each pointer progresses through the states in the PointerState enumeration during its lifetime:

• After being created the pointer will be in state PointerState.BEGIN for one frame.
• During its lifetime the pointer will be either in state PointerState.ACTIVE or PointerState.MOVE depending on whether the pointer's position has changed since the last frame.
• When the pointer event ends it will be in state PointerState.END for one frame and will then be removed from the list of pointers.

See Control Callback Functions for more pointer example use.

Functions

function getValueField(string, field)


-- example
self:getValueField('x', ValueField.CURRENT) -- same as: self.values.x
self:getValueField('x', ValueField.DEFAULT)

Returns a value field of the control value with name string, or nil if none is found.

The parameter field can be one of the possible values of the ValueField enumeration and determines which value is returned:

• ValueField.CURRENT - Returns the current value.
• ValueField.LAST - Returns the value before the last change.
• ValueField.DEFAULT - Returns the default value.

Invoking the function with field parameter ValueField.CURRENT is equivalent to referencing control.values[string].

See Control Properties and Values for a list of possible values for each control type.

function setValueField(string, field, value)


-- example
self:setValueField('x', ValueField.CURRENT, 1.0) -- same as: self.values.x = 1.0
self:setValueField('x', ValueField.DEFAULT, 0.5)

Set a value field of the control value with name string.

The parameter field can be one of the following values of the ValueField enumeration, and determines which value field will be set:

• ValueField.CURRENT - Set the current value.
• ValueField.DEFAULT - Set the default value.

Invoking the function with field parameter ValueField.CURRENT is equivalent to calling control.values[string] = value.

function getValueProperty(string, property)


-- example
local valueLocked = self:getValueProperty('x', ValueProperty.LOCKED)
local valueType = self:getValueProperty('x', ValueProperty.TYPE)
print(valueType == ValueType.FLOAT)
> true

Returns the value of the property property of the control value with name string, or nil if none is found.

The parameter property can be one of the possible values of the ValueProperty enumeration and determines which property value is returned:

• ValueProperty.TYPE - The type of the value, one of the possible values of the ValueType enumeration
• ValueProperty.LOCKED - Locked state of the value, a boolean value
• ValueProperty.LOCKED_DEFAULT_CURRENT - Default and current value locked state, a boolean value
• ValueProperty.DEFAULT_PULL - Default pull of the value, an integer value ranging from 0 to 100

See Control Properties and Values for a list of possible values for each control type.

function setValueProperty(string, property, value)


-- example
self:setValueProperty('x', ValueProperty.LOCKED, false)
self:setValueProperty('x', ValueProperty.DEFAULT_PULL, 50)

Set the value of the property property of the control value with name string.

The parameter property can be one of the possible values of the ValueProperty enumeration with the exception of ValueProperty.TYPE and determines which property value is set.

See the getValueProperty function above for a description of the possible value properties.

See Control Properties and Values for a list of possible values for each control type.

function notify(string [, value])


-- example
self.parent:notify('hello parent')
self.children.button1:notify('hello child', self.name)
self.children.button2:notify('hello child', 1.5)

Invokes the onReceiveNotify callback function on another control.

The parameter string and an optional parameter value will be copied to the receiving control's Lua context and passed to the onReceiveNotify callback function, only if that callback function is defined in the receiving control's script. Calling the function on self has no effect.

The optional parameter value can be of type boolean, number, string, table or any of TouchOSC's object types.

Please note that because the parameter values have to be copied between Lua execution contexts and because this introduces overhead, it is advisable not to invoke the notify function from inside the update function every frame.

function findByID(string [, boolean])


-- example
local buttonID = self.children.button1.ID
local childButton = self:findByID(buttonID)

Returns the child Control object with ID string or nil if none is found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

function findByType(controltype [, boolean])


-- example
local firstChildButton = self:findByType(ControlType.BUTTON)
local firstChildFader = self:findByType(ControlType.FADER)

Returns the first child Control object whose type matches controltype or nil if none is found. The controltype parameter can be any of the ControlType enumeration values. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

function findAllByType(controltype [, boolean])


-- example
local allChildButtons = self:findAllByType(ControlType.BUTTON)
local allChildFaders = self:findAllByType(ControlType.FADER)

Returns a list of child Control objects whose types match controltype or an empty list if none are found. The controltype parameter can be any of the ControlType enumeration values. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

function findByProperty(string, value [, boolean])


-- example
local firstRedControl = self:findByProperty('color', Color(1,0,0))
local firstHiddenControl = self:findByProperty('visible', false)

Returns the first child Control object whose current value of the property named string matches the provided value or nil if none is found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

function findAllByProperty(string, value [, boolean])


-- example
local allRedControls = self:findAllByProperty('color', Color(1,0,0))
local allHiddenControls = self:findAllByProperty('visible', false)

Returns a list of child Control objects whose current values of the property named string matches the provided value or an empty list if none are found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

function findByName(string [, boolean])


-- example
local childButton1 = self:findByName('button1') -- same as: self.children.button1
local childFader1 = self:findByName('fader1') -- same as: self.children.fader1

Equivalent to calling findByProperty('name', string [, boolean]).

function findAllByName(string [, boolean])


-- example
local allChildrenNamedA = self:findAllByName('A')

Equivalent to calling findAllByProperty('name', string [, boolean]).

Callback Functions

If any of the following functions are defined in a control's script, these callback functions are invoked during the various stages of processing of an application frame.

When considering a script function for registration as a callback, the parameter declarations are optional and the function will be called regardless of the parameters being omitted or not.

See Control Callback Functions for example implementations.

function init()


-- example
function init()
  print("init")
end

Called once when the application transitions from editing mode to control surface mode.

Note that this function might be called again under certain conditions:

• When the application comes back to the foreground after being suspended on a mobile device
• When the application is running as editor network client and receives updates from the server that significantly change the structure of the local document

function update()


-- example
function update()
  print("Elapsed ms:", getMillis())
end

Called once per application frame after all processing of user input and received messages has completed.

function onValueChanged(string)


-- example
function onValueChanged(valueName)
  print("Value of ", valueName, "has changed to", self.values[valueName])
end

Called after any of the control's values have changed, once for each changed value, and before any further processing as a result of the change.

The parameter string is the name of the value that has changed. It is valid to set the changed value again from inside the callback, but note that the callback will not be invoked again as a result.

Returning true from this callback will end any further processing TouchOSC would normally do as a result of the change (ie sending of messages).

function onPointer(table)


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

Called after processing of user input is complete and all active pointers (mouse cursor or touch input) have been mapped and assigned to any controls, and before any further processing of the pointer state and internal control behavior in response to the pointer input is evaluated.

Will only be invoked if there are any pointers associated with the control during the current frame.

The table passed as parameter to the callback contains a list of one or more pointers that have been selected as the significant event input according to the control's configuration and do not necessarily include all pointers currently associated with the control.

For example, a button type control will commonly only be interested in a single significant touch input, which will be selected by the application and passed to the control for processing based on the control's configuration.

To access all pointers currently associated with a control access the control.pointers field.

Returning true from this callback will end any further processing TouchOSC would normally do for the current control as a result of the input (ie changing a control's values).

For a description of the pointer table format and pointer states see the control.pointers field.

function onReceiveMIDI(message, connections)


-- example
function onReceiveMIDI(message, connections)
  print('onReceiveMIDI')
  print('\t message     =', table.unpack(message))
  print('\t connections =', table.unpack(connections))
end

Called after receiving a MIDI message and determining that the control should be a receiver of the message according to the routing table, and before any further evaluation or processing of potential changes to a control's values or properties.

Returning true from this callback will end any further processing TouchOSC would normally do for the current control as a result of receiving the message (ie changing a control's values or properties).

NOTE If it is defined, the document root's onReceiveMIDI callback function will always be invoked first, and if true is returned from that callback, processing of the message will end, it will not be passed along to any other controls in the routing table and no further callbacks will be invoked.

For the format of the message and connections parameters see the sendMIDI function.

function onReceiveOSC(message, connections)


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

Called after receiving an OSC message and determining that the control should be a receiver of the message according to the routing table, and before any further evaluation or processing of potential changes to a control's values or properties.

Returning true from this callback will end any further processing TouchOSC would normally do for the current control as a result of receiving the message (ie changing a control's values or properties).

NOTE If it is defined, the document root's onReceiveOSC callback function will always be invoked first, and if true is returned from that callback, processing of the message will end, it will not be passed along to any other controls in the routing table and no further callbacks will be invoked.

For the format of the message and connections parameters see the sendOSC function for complex messages.

function onReceiveGamepad(input, value, connections)


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

Called after receiving input from a connected game controller and determining that the control should be a receiver of the input according to the routing table, and before any further evaluation or processing of potential changes to a control's values or properties.

Returning true from this callback will end any further processing TouchOSC would normally do for the current control as a result of receiving the input (ie changing a control's values or properties).

NOTE If it is defined, the document root's onReceiveGamepad callback function will always be invoked first, and if true is returned from that callback, processing of the message will end, it will not be passed along to any other controls in the routing table and no further callbacks will be invoked.

The first parameter input will be one of the possible values of the GamepadInput enumeration.

The second parameter value will be the raw, numeric value as received by the game controller.

See the Control Callback Functions sample script for an example of how to handle game controller messages.

function onReceiveNotify(string [, value])


-- example
function onReceiveNotify(key, value)
  print('onReceiveNotify')
  print('\t key   =', key)
  print('\t value =', value)
end

Called as a result of the control's notify function being called by another control.

The parameters string and an optional value will be copied from the calling control's Lua context to the receiving control's Lua context and passed as parameters to the callback function.

Please note that because the parameter values have to be copied between Lua execution contexts and because this introduces overhead, it is advisable not to invoke the notify function from inside the update function every frame.

Script objects representing the different types of messages associated with a control.

The objects representing the different message types described here can be accessed via a control's messages field.

• MIDIMessage
  • Fields
    • enabled
    • send
    • receive
    • feedback
    • noDuplicates
    • connections
  • Functions
    • trigger
    • data

• OSCMessage
  • Fields
    • enabled
    • send
    • receive
    • feedback
    • noDuplicates
    • connections
  • Functions
    • trigger
    • data

• LocalMessage
  • Fields
    • enabled
  • Functions
    • trigger

• GamePadMessage
  • Fields
    • enabled
    • connections

MIDIMessage

An object representing a single MIDI message in a control's list of MIDI messages.

Fields

The following fields allow to dynamically configure some of the same properties that are available in the editor UI.

message.enabled


-- example
self.messages.MIDI[1].enabled = false

A boolean value. Enable or disable the message.

See Editor · Messages · MIDI.

message.send


-- example
self.messages.MIDI[1].send = false

A boolean value. Enable or disable the sending of the message.

See Editor · Messages · MIDI.

message.receive


-- example
self.messages.MIDI[1].receive = false

A boolean value. Enable or disable the receiving of the message.

See Editor · Messages · MIDI.

message.feedback


-- example
self.messages.MIDI[1].feedback = false

A boolean value. Enable or disable allowing message feedback (sending) immediately after receiving.

See Editor · Messages · MIDI.

message.noDuplicates


-- example
self.messages.MIDI[1].noDuplicates = true

A boolean value. Enable or disable allowing identical messages to be sent in succession.

See Editor · Messages · MIDI.

message.connections


-- example
local firstMessage = self.messages.MIDI[1]
firstMessage.connections[1] = false
firstMessage.connections[3] = true
print(#firstMessage.connections)
> 5

A list of boolean values for each of the connections the message should be sent or received on.

This list currently has ten entries, but the number is subject to change in a future release and will always be the same number as connections available in the MIDI connection configuration.

See Editor · Messages · MIDI.

Functions

message:trigger()


-- example
self.messages.MIDI[1]:trigger()

Trigger and potentially send the message.

Process the message in the same way as if one of its configured triggers had been set. If both the Enabled and Send fields of the message are enabled, the message will be sent on its configured connections.

Note that the No Duplicates flag might still prevent the sending of the message.

See Editor · Messages · MIDI.

message:data()


-- example
local message_data = self.messages.MIDI[1]:data()
sendMIDI(message_data) -- send on all connections
sendMIDI(message_data, {true, false, false, false, false}) -- send on first connection
sendMIDI(message_data, self.messages.MIDI[1].connections) -- send on message's configured connections

Return the message data prepared for sending.

Process the message based on its current configuration and return the message data in the format used by the sendMIDI and onReceiveMIDI functions (ie a list of byte values making up the MIDI message).

Note: The Enabled and Send fields will not be considered.

See Script · Global Functions · MIDI Messages.

OSCMessage

An object representing a single OSC message in a control's list of OSC messages.

Fields

The following fields allow to dynamically configure some of the same properties that are available in the editor UI.

message.enabled


-- example
self.messages.OSC[1].enabled = false

A boolean value. Enable or disable the message.

See Editor · Messages · OSC.

message.send


-- example
self.messages.OSC[1].send = false

A boolean value. Enable or disable the sending of the message.

See Editor · Messages · OSC.

message.receive


-- example
self.messages.OSC[1].receive = false

A boolean value. Enable or disable the receiving of the message.

See Editor · Messages · OSC.

message.feedback


-- example
self.messages.OSC[1].feedback = false

A boolean value. Enable or disable allowing message feedback (sending) immediately after receiving.

See Editor · Messages · OSC.

message.noDuplicates


-- example
self.messages.OSC[1].noDuplicates = true

A boolean value. Enable or disable allowing identical messages to be sent in succession.

See Editor · Messages · OSC.

message.connections


-- example
local firstMessage = self.messages.OSC[1]
firstMessage.connections[1] = false
firstMessage.connections[3] = true
print(#firstMessage.connections)
> 5

A list of boolean values for each of the connections the message should be sent or received on.

This list currently has ten entries, but the number is subject to change in a future release and will always be the same number as connections available in the OSC connection configuration.

See Editor · Messages · OSC.

Functions

message:trigger()


-- example
self.messages.OSC[1]:trigger()

Trigger and potentially send the message.

Process the message in the same way as if one of its configured triggers had been set. If both the Enabled and Send fields of the message are enabled, the message will be sent on its configured connections.

Note that the No Duplicates flag might still prevent the sending of the message.

See Editor · Messages · OSC.

message:data()


-- example
local message_data = self.messages.OSC[1]:data()
sendOSC(message_data) -- send on all connections
sendOSC(message_data, {true, false, false, false, false}) -- send on first connection
sendOSC(message_data, self.messages.OSC[1].connections) -- send on message's configured connections

Return the message data prepared for sending.

Process the message based on its current configuration and return the message data in the format used by the sendOSC and onReceiveOSC functions.

Note: The Enabled and Send fields will not be considered.

See Script · Global Functions · OSC Messages.

LocalMessage

An object representing a single Local message in a control's list of Local messages.

Fields

The following fields allow to dynamically configure some of the same properties that are available in the editor UI.

message.enabled


-- example
self.messages.LOCAL[1].enabled = false

A boolean value. Enable or disable the message.

See Editor · Messages · Local.

Functions

message:trigger()


-- example
self.messages.LOCAL[1]:trigger()

Trigger and potentially send the message.

Process the message in the same way as if one of its configured triggers had been set. If the Enabled field of the message is enabled, the message will be sent.

See Editor · Messages · LOCAL.

GamePadMessage

An object representing a single Gamepad message in a control's list of Gamepad messages.

The following fields allow to dynamically configure some of the same properties that are available in the editor UI.

message.enabled


-- example
self.messages.GAMEPAD[1].enabled = false

A boolean value. Enable or disable the message.

See Editor · Messages · Gamepad.

message.connections


-- example
local firstMessage = self.messages.GAMEPAD[1]
firstMessage.connections[1] = false
firstMessage.connections[3] = true
print(#firstMessage.connections)
> 4

A list of boolean values for each of the connections the message received on.

This list currently has four entries, but the number is subject to change in a future release and will always be the same number as connections available in the Gamepad connection configuration.

See Editor · Messages · Gamepad.

A rectangle object native to TouchOSC. Will be returned and can be passed anywhere a rectangle is required.

• Fields
• Constructor Functions
• Functions

Fields

rectangle.x

The x position of the rectangle.

rectangle.y

The y position of the rectangle.

rectangle.w

The width of the rectangle.

rectangle.h

The height of the rectangle.

Constructor Functions

function Rectangle()                               -- [1]
function Rectangle(rectangle)                      -- [2]
function Rectangle(number, number)                 -- [3]
function Rectangle(number, number, number, number) -- [4]

Returns a new rectangle object with

1. position and size set to (0,0).
2. position and size copied from another Rectangle object.
3. position set to (0,0) and size set to the two numbers.
4. position set to the first pair of numbers and size set to the second two numbers.

Functions

function contains(number, number)


-- example
local r = Rectangle(10,10,50,50)
local b = r:contains(20,20)
print(b)
> true

Tests if the point at position (number, number) is contained within the rectangle and returns a boolean value.

A color object native to TouchOSC. Will be returned and can be passed anywhere a color is required. Color components are stored as floating point values ranging from 0.0 to 1.0.

• Fields
• Constructor Functions
• Static Functions
• Operators

Fields

color.r

The red component of the color.

color.g

The green component of the color.

color.b

The blue component of the color.

color.a

The alpha component of the color.

Constructor Functions

function Color()                               -- [1]
function Color(color)                          -- [2]
function Color(number)                         -- [3]
function Color(number, number)                 -- [4]
function Color(number, number, number)         -- [5]
function Color(number, number, number, number) -- [6]

Returns a new color object with

1. all components initialized with 0.0.
2. all components copied from another Color object.
3. all components initialized with number.
4. rgb components initialized with the first number, the a component initialized with the second number.
5. rgb components initialized with the three numbers, the a component initialized with 1.0
6. rgba components initialized with the four numbers provided.

Static functions

function Color.toHexString(color)


-- example
local redColor = Color(1,0,0)
print(Color.toHexString(redColor))
> FF0000FF

Returns a hexadecimal string representation of the color in the format RRGGBBAA.

function Color.fromHexString(string)


-- example
local red = Color.fromHexString('FF0000FF')
local blue = cColor.fromHexString('0000FF')
local grayAlpha = Color.fromHexString('FF80');
local gray = Color.fromHexString('80');

Returns a color object created from the hexadecimal string representation. The string can be in one of the following formats: RRGGBBAA, RRGGBB, GGAA, GG, with the latter two forms creating a grayscale color from the GG value.

Operators

-- multiplication
color * color
color * number

-- division
color / color
color / number

-- addition
color + color
color + number

-- subtraction
color - color
color - number

All operators operate component-wise and return a new color object.

TouchOSC provides 2,3 and 4 component vector types as Vec2 Vec3 Vec4 objects.

• Fields
• Constructor Functions
• Functions
• Operators

Fields

vec2.x
vec3.x
vec4.x

The x component of the vector.

vec2.y
vec3.y
vec4.y

The y component of the vector.

vec3.z
vec4.z

The z component of the vector.

vec4.w

The w component of the vector.

Constructor Functions

function Vec2()                                -- [1]
function Vec2(vec2)                            -- [2]
function Vec2(number)                          -- [3]
function Vec2(number, number)                  -- [4]

function Vec3()                                -- [1]
function Vec3(vec3)                            -- [2]
function Vec3(number)                          -- [3]
function Vec3(number, number, number)          -- [4]

function Vec4()                                -- [1]
function Vec4(vec4)                            -- [2]
function Vec4(number)                          -- [3]
function Vec4(number, number, number, number)  -- [4]

Returns a new vector object with

1. all components initialized with 0.0.
2. all components copied from another vector object.
3. all components initialized with number.
4. each component initialized with the numbers provided.

Functions

function length()


-- example
local v = Vec2(1,0)
local l = v:length()
print(l)
> 1

Returns the length of the vector

function normalize()


-- example
local v = Vec2(1,1)
local n = v:normalize()

Returns a new vector that is the normalized vector

Operators

-- multiplication
vector * vector
vector * number

-- division
vector / vector
vector / number

-- addition
vector + vector
vector + number

-- subtraction
vector - vector
vector - number

All operators operate component-wise and return a new vector object.

• AlignH
• AlignV
• ButtonType
• ControlType
• CursorDisplay
• Font
• GamepadInput
• MIDIMessageType
• Orientation
• OutlineStyle
• PointerPriority
• PointerState
• RadioType
• Response
• Shape
• ValueField
• ValueProperty
• ValueType

AlignH

Possible values for a Control object's textAlignH property.

• AlignH.LEFT
• AlignH.CENTER
• AlignH.RIGHT

AlignV

Possible values for a Control object's textAlignV property.

• AlignV.TOP
• AlignV.MIDDLE
• AlignV.BOTTOM

ButtonType

Possible values for a Control object's buttonType property.

• ButtonType.MOMENTARY
• ButtonType.TOGGLE_RELEASE
• ButtonType.TOGGLE_PRESS

ControlType

Possible values for a Control object's type field.

• ControlType.BOX
• ControlType.BUTTON
• ControlType.LABEL
• ControlType.TEXT
• ControlType.FADER
• ControlType.XY
• ControlType.RADIAL
• ControlType.ENCODER
• ControlType.RADAR
• ControlType.RADIO
• ControlType.GROUP
• ControlType.PAGER
• ControlType.GRID

CursorDisplay

• CursorDisplay.ALWAYS
• CursorDisplay.ACTIVE
• CursorDisplay.INACTIVE

Font

Possible values for a Control object's font property.

• Font.DEFAULT
• Font.MONOSPACED

GamepadInput

• GamepadInput.STICK_LEFT_X
• GamepadInput.STICK_LEFT_Y
• GamepadInput.STICK_RIGHT_X
• GamepadInput.STICK_RIGHT_Y
• GamepadInput.TRIGGER_LEFT
• GamepadInput.TRIGGER_RIGHT
• GamepadInput.BUTTON_UP
• GamepadInput.BUTTON_DOWN
• GamepadInput.BUTTON_LEFT
• GamepadInput.BUTTON_RIGHT
• GamepadInput.BUTTON_A
• GamepadInput.BUTTON_B
• GamepadInput.BUTTON_X
• GamepadInput.BUTTON_Y
• GamepadInput.BUTTON_STICK_LEFT
• GamepadInput.BUTTON_STICK_RIGHT
• GamepadInput.BUMPER_LEFT
• GamepadInput.BUMPER_RIGHT
• GamepadInput.BUTTON_START
• GamepadInput.BUTTON_SELECT
• GamepadInput.BUTTON_HOME

MIDIMessageType

• MIDIMessageType.NOTE_OFF
• MIDIMessageType.NOTE_ON
• MIDIMessageType.POLYPRESSURE
• MIDIMessageType.CONTROLCHANGE
• MIDIMessageType.PROGRAMCHANGE
• MIDIMessageType.CHANNELPRESSURE
• MIDIMessageType.PITCHBEND
• MIDIMessageType.SYSTEMEXCLUSIVE
• MIDIMessageType.QUARTERFRAME
• MIDIMessageType.SONGPOSITION
• MIDIMessageType.SONGSELECT
• MIDIMessageType.CLOCK
• MIDIMessageType.START
• MIDIMessageType.CONTINUE
• MIDIMessageType.STOP
• MIDIMessageType.ACTIVESENSING
• MIDIMessageType.SYSTEMRESET

Orientation

Possible values for a Control object's orientation property.

• Orientation.NORTH
• Orientation.EAST
• Orientation.SOUTH
• Orientation.WEST

OutlineStyle

Possible values for a Control object's outlineStyle property.

• OutlineStyle.FULL
• OutlineStyle.CORNERS
• OutlineStyle.EDGES

PointerPriority

• PointerPriority.OLDEST
• PointerPriority.NEWEST

PointerState

• PointerState.BEGIN
• PointerState.ACTIVE
• PointerState.MOVE
• PointerState.END

RadioType

Possible values for a Control object's radioType property.

• RadioType.SELECT
• RadioType.METER

Response

Possible values for a Control object's response property.

• Response.ABSOLUTE
• Response.RELATIVE

Shape

Possible values for a Control object's shape property.

• Shape.RECTANGLE
• Shape.CIRCLE
• Shape.TRIANGLE
• Shape.DIAMOND
• Shape.PENTAGON
• Shape.HEXAGON

ValueField

• ValueField.CURRENT
• ValueField.LAST
• ValueField.DEFAULT

ValueProperty

• ValueProperty.TYPE
• ValueProperty.LOCKED
• ValueProperty.LOCKED_DEFAULT_CURRENT
• ValueProperty.DEFAULT_PULL

ValueType

• ValueType.BOOLEAN
• ValueType.INTEGER
• ValueType.FLOAT
• ValueType.STRING

Colors

• Colors.clear
• Colors.black
• Colors.white
• Colors.red
• Colors.green
• Colors.blue
• Colors.orange
• Colors.yellow
• Colors.cyan
• Colors.purple
• Colors.violet
• Colors.gray
• Colors.darkGray
• Colors.lightGray

In this reference we list the names and types of the properties and values for each control type, for access from control scripts.

For a description of the meaning and effects of each property and value, please see the Properties, Values and Control Reference sections.

• Common
• BOX
• BUTTON
• LABEL
• TEXT
• FADER
• XY
• RADIAL
• ENCODER
• RADAR
• RADIO
• PAGER

Common

Properties and values that are common to all controls, independent of their type. Not all control types will utilize the value of these properties.

Properties

Values

BOX

Properties

BUTTON

Properties

Values

LABEL

Properties

Values

TEXT

Properties

Values

FADER

Properties

Values

XY

Properties

Values

RADIAL

Properties

Values

ENCODER

Properties

Values

RADAR

Properties

Values

RADIO

Properties

Values

PAGER

Properties

Page Properties

Values

• 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
-- send on all configured connections
sendMIDI({ 176, 0, 102 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE, 0, 102 })

-- control change, controller 0, channel 2
-- send on all configured connections
sendMIDI({ 177, 0, 103 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE + 1, 0, 103 })

-- control change, controller 2, channel 6
-- send on all configured connections
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
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
    true, -- 6
    true, -- 7
    true, -- 8
    true, -- 9
    true  -- 10
  }
)

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