The OSC (Open Sound Control) protocol allows for communication between computers and other multimedia devices, providing high-speed, low-latency connectivity. Using OSC, it’s possible to control many aspects of Farrago. This page details the basics of setting up an OSC device with Farrago, as well as providing an overview of how you can use OSC to control the app.

Initial Setup

To get started, ensure your OSC device is connected to your Mac, following the instructions provided by your device's manufacturer for setup. Ensure your controller’s IP address is set to publish to the same value listed next to OSC Input in the Controllers tab of Farrago’s Settings.

With your OSC controller connected to the same network as your Mac running Farrago, enable the checkbox next to OSC Input, then set the port number to match the outgoing port of your controller. The OSC Output setting can be configured manually, or by selecting your device from the dropdown menu.

Once your device is enabled, you'll be able to use it to control many aspects of Farrago.

OSC Address Endpoints and Patterns

OSC addresses are used to control various aspects of Farrago, and look similar to file paths. For example, the address pattern /set/0/tile/0/0/ points to the tile at the top left position on the board (tile 0,0) in the first set of the sets list (set 0).

EXAMPLE: To set the current selection state of the tile at x0,y0 on the selected set, you would send a value of 1 to /set/selected/tile/0/0/select

If you request the value at this address, and you get back a value of 1, you can use that to make a button appear highlighted in your OSC software or controller.

Tiles have several endpoints that allow you to control different aspects of the tile:

Tile endpoints

• allowPausing

• back

• color

• currentPosition

• currentTime (get only)

• duration (get only)

• fadeOut

• holdToPlay

• loop

• mute

• notes (get only)

• peakMeterL (get only)

• peakMeterR (get only)

• play

• remainingTime (get only)

• rmsMeterL (get only)

• rmsMeterR (get only)

• select (used in the above example)

• solo

• title (get only)

• toggleAB

• volume

Other OSC Addresses

Farrago also supports additional OSC addresses for sets and global controls:

• /set/{position}/

• /set/selected/ (follows the currently selected set)

• /transport/playPauseAll

• /transport/stopAll

• /transport/previous

• /transport/next

• /master/volumeUp

• /master/volumeDown

• /master/mute

• /master/volume

• /master/fadeAll

• /master/toggleAB

• /inspector/volume

• /inspector/volumeUp

• /inspector/volumeDown

• /inspector/toggleAB

• /inspector/mute

• /inspector/loop

• /inspector/solo

• /inspector/holdToPlay

• /inspector/pausable

• /inspector/color

• /list/reset

• /list/crossfadeDuration

• /global/bringForward

Pattern Matching

OSC addresses support regex-like pattern matching to control multiple tiles or sets simultaneously.

• ? in the address matches any single character.
  Example: /set/0/tile/0/?/ will match addresses like /set/0/tile/0/1/ and /set/0/tile/0/9/

• * matches any sequence of zero or more characters.
  Example: /set/*/tile/0/0/ will match addresses like /set/0/tile/0/0/, /set/1/tile/0/0/, and /set/99/tile/0/0/.

• [0-1] Square brackets (e.g., [0-1] or [a-c]) match any of the characters specified inside the brackets. The - character defines a range.
  Example: /set/[0-2]/tile/0/0/ will match addresses like /set/0/tile/0/0/, /set/1/tile/0/0/, and /set/2/tile/0/0/.

• Placing ! inside the opening bracket negates a match.
  Example: /set/[!0-2]/tile/0/0/ will match addresses like /set/3/tile/0/0/ and /set/9/tile/0/0/, but not /set/0/tile/0/0/, /set/1/tile/0/0/, or /set/2/tile/0/0/

• {foo, bar} A comma-separated list enclosed in curly brackets (e.g., {foo, bar}) matches an address pattern containing those strings.
  Example: /set/{0,1}/tile/0/0/ will match addresses like /set/0/tile/0/0/ and /set/1/tile/0/0/, but not /set/2/tile/0/0/.

A Complete Example

With all of the above in mind, we can take pattern matching for a spin. This one command will control the volume for the first, second, and last tile across the top row of set 1-3:

/set/[0-2]/tile/{0,1,9}/0/volume

This command will match and control the volume of tiles at positions (0,0), (1,0), and (9,0) in sets 0, 1, and 2.

Note: Pattern matching is not supported for the endpoint of an address.

Status Updates

A controller app can receive up-to-date values for all controls by sending a message to “/ping”. When Farrago receives this message it will send the current value for all shortcuts.

← PreviousNext →MIDI SupportStream Deck Support