OSC Messages¶
Many people have been using message passing not only to control Max/PD objects, but also to interact with processes living outside MAX/PD such as CSound, SuperCollider, etc.
To make their life easier, Antescofo comes with a builtin OSC server. The OSC protocol can be used to interact with external processes using UDP messages. It can also be used to make two Antescofo objects interact within the same patch. The management of OSC messages is achieved in Antescofo through 4 primitives.
OSCSEND¶
This keyword introduces the declaration of a named OSC output channel of communication. The declaration takes the form:
oscsend name host : port msg_prefix
where:
-
name
is a simple identifier and refers to the output channel (used later to send messages). -
host
is the optional IP address (in the formnn.nn.nn.nn
wherenn
is an integer) or the symbolic name of the host (in the form of a simple identifier or a string, like localhost or "test.ircam.fr"). If this argument is not provided, the localhost (that is, IP 127.0.0.1) is assumed. -
port
is the mandatory number of the port where the message is routed (e.g. between 49152 and 65535, see List of TCP and UDP port numbers). -
msg_prefix
is the OSC address in the form of a string that will prefix the OSC message send to this channel.
As soon as the OSC channel is declared, it is started and can be used to send messages. Note that sending a message before the definition of the corresponding output channel is interpreted as sending a message to MAX.
Sending an OSC message takes a form similar to sending a message to MAX or PD:
name arg₁ arg₂ ...
This action construct and send the osc message
msg_prefix arg₁ arg₂ ...
where msg_prefix
is the OSC address declared for name
. Note that to
handle different message prefixes, different output channels have to be
declared.
The character /
is accepted in an identifier, so the usual
hierarchical name used in OSC message prefixes can be used to identify
the output channels. For instance, the declarations:
oscsend extprocess/start test.ircam.fr : 3245 "start" oscsend extprocess/stop test.ircam.fr : 3245 "stop"
can be used to later invoke
0.0 extprocess/start "filter1" 1.5 extprocess/stop "filter1"
OSCRECEIVE¶
This keyword introduces the declaration of an input channel of communication. The declaration takes the form:
oscrecv name port msg_prefix $v₁ $v₂ ...
where:
-
name
is the identifier of the input channel, and its used later to stop or restart the listening of the channel. -
port
is the mandatory port number where the is received. -
On the previous port, the channel accepts messages with OSC address
msg_prefix
. Note that for a given input channel, the message prefixes have to be all different. -
When an OSC message is received, the argument are automatically assigned to the variables
$v₁
,$v₂
... If there is less variables than arguments, the remaining arguments are simply thrown away (and an error message is emitted). Otherwise, if there is less arguments than variables, the remaining variables are untouched (and an error message is emitted).
Currently, Antescofo accepts only the following OSC types: bool, int32, int64, float, double, string and the arrays markers bracketing sequence of these values (nested arrays are allowed). These value are converted respectively into boolean, integer, float, string and bracketed sequence are converted into tab.
A Whenever can be used to react to the reception of an OSC message: it
is enough to put one of the variables $vᵢ
as the condition of the
whenever.
The reception is active as soon as the input channel is declared.
OSCON and OSCOFF¶
These two commands take the name of an input channel. Switching off an input channel stops the listening and the message that arrives after, are ignored. Switching on restarts the listening. These commands have no effect on an output channel.
Conversion between OSC types and Antescofo types¶
Sending (or receiving) an OSC message implies the conversion of an Antescofo value into an OSC value (or the reverse). The conversion is applied following the following mapping
Antescofo value | OSC value |
---|---|
bool | bool |
int | int32 see function @set_osc_handling_int64 |
int | int64 see function @set_osc_handling_int64 |
Float | float see function @set_osc_handling_double |
Float | double see function @set_osc_handling_double |
string | string |
string | symbol |
tab | see function @set_osc_handling_tab |
Remarks
-
Antescofo value types that are not present in the table are not handled (e.g. proc or nim).
-
The default handling of Antescofo integers is to send them as 32 bits integers, the only precision required by the OSC protocol. A call to
@set_osc_handling_int64(true)
switches this default behavior to send 64 bits integers instead. Notice that this feature is not implemented in all OSC packages. See function @set_osc_handling_int64. -
The default handling of Antescofo float is to sending them as floats (32 bits representation), the precision required by the OSC protocol. A call to
@set_osc_handling_double(true)
switches this default behavior to send double (64 bits representation) instead. Notice that this feature is not implemented in all OSC packages. See function @set_osc_handling_double. -
The handling of tab can be changed using the @set_osc_handling_tab functions. By default, Antescofo sends the elements of a tab as the successive arguments of a message, without using the OSC array facilities. A call to
@set_osc_handling_tab(true)
switches the behavior to rely on the array feature present in OSC v1.1. A call to@set_osc_handling_tab(false)
switches to the default behavior (tab flattening).