Difference between revisions of "Custom OSC"

From TidalCycles userbase
Jump to: navigation, search
Line 22: Line 22:
 
* <source inline>Pre MessageStamp</source> - as above, but the timestamp applied to the OSC message itself, filling in the two integer fields "sec" and "usec" (you have to include these in the argument list of your osc format, in this case).
 
* <source inline>Pre MessageStamp</source> - as above, but the timestamp applied to the OSC message itself, filling in the two integer fields "sec" and "usec" (you have to include these in the argument list of your osc format, in this case).
  
Then define the structure of the OSC message. There are two ways to structure the OSC messages that tidal sends. Either as an argument list, or as name-value pairs.
+
Then define the structure of the OSC message. It's worth first spending a bit of time [http://opensoundcontrol.org/spec-1_0 familiarising yourself with the OSC spec]. There are two ways to structure the OSC messages that tidal sends. Either as an argument list, or as name-value pairs.
  
 
The argument list approach is most common. It looks like this:
 
The argument list approach is most common. It looks like this:
Line 35: Line 35:
 
</source>
 
</source>
  
To define the OSC structure, you start with <source inline>OSC</source>  
+
To define the OSC structure, you start with <source inline>OSC</source>, followed by the OSC "address pattern", in this case "/play". Then you list the message arguments, in order. Each argument is given as a 'tuple', containing the name of the parameter, and its default value.
 +
 
 +
In the example above, the first parameter called "sound" doesn't have a default, indicated by the keyword <source inline>Nothing</source>. This means that if no sound parameter is given by a pattern, no OSC message will be sent.
 +
 
 +
The other arguments in the example have defaults indicated by the keyword <source inline>Just</source>, followed by the type of the argument and its default value. VS gives a default as a string, VF as a floating point number, and VI as an integer. Other available types are VB for true/false boolean values (which are converted to 1 / 0 integer values in the message) and VX for binary 'blobs'. If one or more of these arguments aren't present in a pattern, the message will be sent with these default values.
  
 
redspeed = OSC "/mixer/channel/1" $ ArgList [("gain")]
 
redspeed = OSC "/mixer/channel/1" $ ArgList [("gain")]

Revision as of 21:22, 23 May 2020

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. This is the simplest approach, that will work fine in most cases
  • 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 applied to the OSC message itself, filling in the two integer fields "sec" and "usec" (you have to include these in the argument list of your osc format, in this case).

Then define the structure of the OSC message. It's worth first spending a bit of time familiarising yourself with the OSC spec. There are two ways to structure the OSC messages that tidal sends. Either as an argument list, or as name-value pairs.

The argument list approach is most common. It looks like this:

oscplay = OSC "/play" $ ArgList [("sound", Nothing),
                                 ("vowel", Just $ VS "a"),
                                 ("pan", Just $ VF 0.5),
                                 ("volume", Just $ VF 1),
                                 ("cut", Just $ VI 1)
                                ]

To define the OSC structure, you start with OSC, followed by the OSC "address pattern", in this case "/play". Then you list the message arguments, in order. Each argument is given as a 'tuple', containing the name of the parameter, and its default value.

In the example above, the first parameter called "sound" doesn't have a default, indicated by the keyword Nothing. This means that if no sound parameter is given by a pattern, no OSC message will be sent.

The other arguments in the example have defaults indicated by the keyword Just, followed by the type of the argument and its default value. VS gives a default as a string, VF as a floating point number, and VI as an integer. Other available types are VB for true/false boolean values (which are converted to 1 / 0 integer values in the message) and VX for binary 'blobs'. If one or more of these arguments aren't present in a pattern, the message will be sent with these default values.

redspeed = OSC "/mixer/channel/1" $ ArgList [("gain")]

OSC "/{asccolour}/speed" $ ArgList [("ascspeed", Nothing)],


Debugging

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.