Custom OSC

From TidalCycles userbase
Revision as of 19:48, 23 May 2020 by Yaxu (talk | contribs)
Jump to: navigation, search

The following is where in-development documentation will appear for TidalCycles 1.5.0 and later. For older versions, please see Custom OSC - pre 1.5.0.

Open Sound Control (OSC) is a standard network protocol, ostensibly designed for music, but it's really just an easy way to send numbers and other data across a network. A range of live coding and other systems including DAWs (Digital Audio Workstations), visualisers and mixers are compatible with OSC.

Really the one and only job of TidalCycles is to send patterned OSC messages, most often to the SuperDirt audio framework. It's fairly straightforward to configure Tidal to send OSC to another system. It involves specifying and where messages should be sent to (the target) - and the structure of the OSC data that is sent (the shape or format of the message).

First, define a target:

let target =
      Target {oName = "visualiser",   -- A friendly name for the target (only used in error messages)
              oAddress = "localhost", -- The target's network address, normally "localhost"
              oPort = 5050,           -- The network port the target is listening on
              oLatency = 0.2,         -- Additional delay, to smooth out network jitter/get things in sync
              oSchedule = Live,       -- The scheduling method - see below
              oWindow = Nothing       -- Not yet used

The scheduling method for oSchedule can be one of:

  • Live - send OSC messages on time
  • Pre BundleStamp - send OSC message in batches, ahead of time, with a timestamp on the OSC 'bundle' so that the target can schedule them accurately (therefore avoiding potential network/processing jitter)
  • Pre MessageStamp - as above, but the timestamp is added to the OSC message itself, as two integer fields, one for seconds and one for microseconds.


One way to debug OSC is to use a packet sniffer like wireshark. You can put "osc" in the filter field (no double quotes) to filter out everything except OSC packets. If you click on an OSC network packet and expand fields you can find a nicely formatted representation of your OSC message.