Server Guide:
Guides | Server > Abstractions

Server Guide

Using Server objects in different situations


A Server object is the client-side representation of a server app and is used to control the app from the SuperCollider language application. (See Client vs Server for more details on the distinction.) It forwards OSC messages and has a number of allocators that keep track of IDs for nodes, buses and buffers.

The server application is a commandline program, so all commands apart from OSC messages are UNIX commands.

The server application represented by a Server object might be running on the same machine as the client (in the same address space as the language application or separately; see below), or it may be running on a remote machine.

Most of a Server's options are contolled through its instance of ServerOptions. See the ServerOptions helpfile for more detail.


Server apps running on the local machine have two UNIX environment variables: SC_SYNTHDEF_PATH and SC_PLUGIN_PATH. These indicate directories of synthdefs and ugen plugins that will be loaded at startup. These are in addition to the default synthdef/ and plugin/ directories which are hard-coded.

These can be set within SC using the getenv and setenv methods of class String.

The default group

When a Server is booted there is a top level group with an ID of 0 that defines the root of the node tree. (This is represented by a subclass of Group : RootNode.) If the server app was booted from within SCLang (as opposed to from the command line) the method initTree will be called automatically after booting. This will also create a Default Group with an ID of 1, which is the default group for all Nodes when using object style. This provides a predictable basic node tree so that methods such as Server-scope, Server-record, etc. can function without running into order of execution problems.

The default group is persistent, i.e. it is recreated after a reboot, pressing cmd-., etc. See RootNode and Default Group for more information.

NOTE: If a Server has been booted from the command line you must call initTree manually in order to initialize the default group, if you want it. See initTree below.

Local vs. Internal

In general, when working with a single machine one will probably be using one of two Server objects which are created at startup and stored in the class variables *local and *internal. In (OSX), two GUI windows are created to control these. Use -makeGui to create a GUI window manually.

The difference between the two is that the local server runs as a separate application with its own address space, and the internal server runs within the same space as the language/client app.

Both local and internal server supports scoping and synchronous bus access.

The local server, and any other server apps running on your local machine, have the advantage that if the language app crashes, it (and thus possibly your piece) will continue to run. It is thus an inherently more robust arrangement. But note that even if the synths on the server continue to run, any language-side sequencing and control will terminate if the language app crashes.

At the current time, there is generally no benefit in using the internal server, but it remains for the purposes of backwards compatibility.

The default Server

There is always a default Server, which is stored in the class variable default. Any Synths or Groups created without a target will be created on the default server. At startup this is set to be the local server (see above), but can be set to be any Server.

Local vs. Remote Servers, Multi-client Configurations

Most of the time users work with a server app running on the same machine as the SC language client. It is possible to use a server running on a different machine via a network, providing you know the IP address and port of that server. The *remote method provides a convenient way to do this.

NOTE: To enable remote connections you will need to change ServerOptions: -bindAddress in the server's ServerOptions as the default value only allows connections from the local machine. s.options.bindAddress = "" will allow connections from any address.

One common variant of this approach is multiple clients using the same server. If you wish to do this you will need to set the server's ServerOptions: -maxLogins to at least the number of clients you wish to allow. When a client registers for notifications the server will supply a client ID. This also configures the allocators to avoid conflicts when allocating Nodes, Buffers, or Busses. For more info see Multi-client Setups.

In order to use a remote server with tcp one should first boot the remote server using the -t option e.g. as follows:

then run the following code: