copyright © 2002 James McCartney
The SuperCollider 3 Synth Server is a simple but powerful synthesis engine. While synthesis is running, new modules can be created, destroyed and repatched, sample buffers can be created and reallocated. Effects processes can be created and patched into a signal flow dynamically at scheduled times. All running modules are ordered in a tree of nodes that define an order of execution. Patching between modules is done through global audio and control buses.
All commands are received via TCP or UDP using a simplified version of Open Sound Control (OSC). The synth server and its client(s) may be on the same machine or across a network. The synth server does not send or receive MIDI. It is expected that the client will send all control commands. If MIDI is desired, it is up to the client to receive it and convert it to appropriate OSC commands for the synth engine.
Synth definitions are stored in files generated by the SuperCollider language application. Unit generator definitions are Mach-O bundles (not to be confused with CFBundles). The Unit generator API is a simple C interface.
A Node is an addressable node in a tree of nodes run by the synth engine. There are two types, Synths and Groups. The tree defines the order of execution of all Synths. All nodes have an integer ID.
A Group is a collection of Nodes represented as a linked list. A new Node may be added to the head or tail of the group. The Nodes within a Group may be controlled together. The Nodes in a Group may be both Synths and other Groups. At startup there is a top level group with an ID of zero that defines the root of the tree. If the server was booted from within SCLang (as opposed to from the command line) there will also be a 'default group' with an ID of 1 which is the default target for all new Nodes. See RootNode and Default Group for more info.
A Synth is a collection of unit generators that run together. They can be addressed and controlled by commands to the synthesis engine. They read input and write output to global audio and control buses. Synths can have their own local controls that are set via commands to the server.
Synths are created from Synth Definitions. Synth Definition files are created by the SuperCollider language application and are loaded into the synth server. Synth Definitions are referred to by name.
Synths send audio signals to each other via a single global array of audio buses. Audio buses are indexed by integers beginning with zero. Using buses rather than connecting synths to each other directly allows synths to connect themselves to the community of other synths without having to know anything about them specifically. The lowest numbered buses get written to the audio hardware outputs. Immediately following the output buses are the input buses, read from the audio hardware inputs. The number of bus channels defined as inputs and outputs do not have to match that of the hardware.
Synths can send control signals to each other via a single global array of control buses. Buses are indexed by integers beginning with zero.
Buffers are arrays of 32 bit floating point values with a small descriptive header. Buffers are stored in a single global array indexed by integers beginning with zero. Buffers may be safely allocated, loaded and freed while synthesis is running, even while unit generators are using them. Buffers are used for wave tables, sample buffers, delay lines, envelopes, or for any other need which can use an array of floating point values. Sound files may be loaded into or written from buffers.
Unit Generator Definitions are plug-ins loaded automatically when the program starts. They are binary code libraries that are used as building blocks by Synths to build synthesis algorithms. Unit Generator Definitions have names that match the names of SuperCollider language classes used in building Synth Definitions.
One of -u or -t must be supplied. Both may be supplied.
'-H "" output-device-name' or '-H input-device-name ""'The cmd-filename should be a file that contains OSC bundles sorted in ascending time order. If cmd-filename is the underscore character _, then OSC will be streamed from standard input.
The audio input will taken from input-filename. If input-filename is the underscore character _, then no input file will be read.
Output will be written to output-filename.
The output file's sample rate is specified by sample-rate. The output file header-format should be one of: AIFF, WAVE, NeXT. The output file sample-format should be one of: int16, int24, int32, float, double. The number of channels in the output file is specified with the -o argument.
Messages are similar in format to Open Sound Control messages, except that pattern matching of the command name is not performed. When streamed via TCP, messages are each preceded by a 32 bit integer giving the length in bytes of the message. UDP datagrams contain this length information already.
All values are in network byte order.
| long | a 64 bit integer. Used for time stamps only. |
| int | a 32 bit integer. |
| float | a 32 bit single precision floating point number. |
| double | a 64 bit double precision floating point number. |
| string | an OSC format string: 8 bit ASCII characters, zero padded to a multiple of 4 bytes. |
| bytes | a buffer of data preceded by a 32 bit length field and padded to a multiple of 4 bytes. |
Command arguments have single character tags which occur in a tag string to identify their types.
| 'i' | an int |
| 'f' | a float |
| 's' | a string |
| 'b' | bytes |
| 'd' | a double |
| 't' | a timestamp |
a Command consists of:
| string | the command name. See the Command Reference below. |
| string | a string with tags defined by the types of the arguments to follow. The tag string begins with a comma ',' character. |
| ... | any combination of arguments of types: int, float, string or bytes. |
a Bundle consists of:
| time stamp | long. Time stamps are in the same format as defined by Open Sound Control : The top 32 bits are seconds since 1900 and the lower 32 bits represent the 32 bit fraction of one second. |
| ... | a series of Commands each preceded by a 32-bit integer byte length. |
a Message consists of: