The "SynthControl" network protocol, version 1.0

Matt Wright, 6/11/96, 6/18/96 Adrian Freed, 6/14/96

The "SynthControl" network protocol is an open format for communicating messages between control clients and synthesizer servers. CNMAT's HTM- based software synthesizers, such as softcast, are controlled by this protocol. SynthControl evolved from earlier experience with HTM.

The SynthControl protocol is a transport-independent application layer.

Currently, servers listen for client messages using UDP and UNIX socket transports.

Message format

There are two valid types of SynthControl packets: single message packets and multiple message packets.

A single message packet consists of a SynthControl string (see below) followed by any amount of binary data, up to the end of the packet. The string indicates a message name and address; the binary data represents the arguments to the message.

A multiple message packet begins with the SynthControl string "#group", then any number of single messages, each proceeded by a 4-byte byte count.
(8 bytes) "#group"
(4 bytes) Size of first message, not including this 4-byte count
(x bytes) first message
(4 bytes) Size of second message, not including this 4-byte count
(x bytes) second message
etc.

Addressing scheme

Each message in a SynthControl packet begins with a string that indicates a message name and address. By "address" we mean an indication of a user-visible object inside the synthesizer, such as a particular voice. (The protocol that carries SynthControl packets will have its own notion of a network address, e.g., an IP address and UDP port. Here we assume that the transport protocol has already done its job and delivered the SynthControl packet to the correct destination.)

In SynthControl protocol version 1.0, the address of a message is determined by the first character of the message name/address string. Here are the possible addresses:

charactermeaning
*A message for the HTM kernel
A-ZA message for synthesizer voice 1-26
a-zA message for synthesizer voice 27-52
_A message for the synthesizer, not to any particular voice

Future versions of this protocol will abandon this addressing scheme in favor of something more like URL notation. Watch this space for documentation of this.

Data representation

Integers are represented as 4-byte signed two's complement big-endian. (This is the native data format for SGI machines and Macintoshes, the two main architectures in use at CNMAT. It is also the standard chosen in JAVA for binary interchange in stream protocols).

Floating point numbers are represented as 4-byte IEEE floats.

Strings are represented as a sequence of non-null ASCII characters followed by a null, padded with enough extra null characters to make the total length be a multiple of 4 bytes. (This is so that data following a string will always be correctly aligned on a 4-byte word.)

E.g., the string "hello" would take 8 bytes:

hello\0\0\0

The string "partial" would also take 8 bytes:

partial\0

The string "@" will take 4 bytes:

@\0\0\0

A utility to print received SynthControl packets to the screen

The program dumpSC listens to a particular UDP or Unix protocol port and prints to the screen all of the SynthControl messages it receives. You may find this useful for debugging client applications.

Currently implemented SynthControl bindings

CAST release 1.0 includes the following client software:

Opcode MAX

To generate SynthControl packets from the Opcode MAX programming language on the Macintosh, CNMAT has released two MAX external objects: "SynthControl" and "udp".

UNIX shell command

To generate SynthControl packets from a text-based Unix environment, CNMAT has released a program "sendSC". In sendSC's interactive mode, the user types messages to stdin which are translated to SynthControl packets. In sendSC's command-line mode, there is a syntax for interpreting command-line arguments as SynthControl data; this mode is useful when calling sendSC from other programs like CGI or Tcl/Tk scripts.

TCL/TK

To generate SynthControl packets from a graphical environment in the X window system, CNMAT has released the script "initpanel.tk".

Java and Matlab bindings will be released shortly,

Writing your own SynthControl clients

The src subdirectory of CAST release 1.0 contains a C-language library and API for constructing SynthControl packets. (The "SynthControl" Max object and the "sendSC" program both use this library and API.) The file SynthControl.h describes the API; it contains comments giving instructions for how your program should call the procedures in the library.

The file SynthControl.c defines the procedures in the library; we are releasing it in source form for developer convenience, but there is no need to read or understand this file.

As an example, we have included the source to the entire "sendSC" program, so you can see how our client works.

The job of this library is only to construct packets with the correct data format. In particular, this library does not include a mechanism for actually sending the completed packet over UDP. The files htmsocket.h and htmsocket.c contain an abstraction of UDP ports on the SGI that you might find convenient to use.

Please share your plans for SynthControl clients as we can help coordinate everyone's efforts.