Classes | Server > Nodes

SynthDesc : Object

Description of a synth definition


Contains a description of a SynthDef, including its name, control names and default values. Information is also stored on its outputs and inputs and whether it has a gate control.

SynthDescs are needed by the event stream system, so when using Pbind, the instruments' default parameters are derived from the SynthDesc.


SynthDescs are created by SynthDescLib, by reading a compiled synth def file. and aSynthDef.add also create a synthDesc in the global library.

saves a synthdef file on disk (like .load);
creates the synthDesc wholly in memory and sends the synthdef to registered servers.

Browse the properties of SynthDescs:

Class Methods, keepDefs: false, dict)

Adds all synthDescs in a path to a dict. You should not use this method or *readFile to read SynthDescs into a SynthDescLib. Use SynthDescLib: read or SynthDescLib: readStream instead.

Inherited class methods

Undocumented class methods



SynthDesc.mdPlugin = value



SynthDesc.populateMetadataFunc = value

SynthDesc.readFile(stream, keepDefs: false, dict, path)

Instance Methods


.name = value


the name of the SynthDef


.controls = value


an array of instances of ControlName, each of which have the following fields: name, index, rate, defaultValue



.controlDict = value

An IdentityDictionary of the ControlName's, indexed by name. This can be used for fast lookup of control index by name, for example to set a specific element of a multichannel control.


.controlNames = value


an array of Strings with the names of controls


.outputs = value


an array of IODesc that describes the available outputs.


.inputs = value


an array of IODesc that describes the available inputs.


A Dictionary of ControlSpecs for a SynthDef. Equivalent to: d.metadata[\specs]


.hasGate = value

is true if the Synthdef has a gate input


.canFreeSynth = value

is true if the Synth can free itself (via some means, usually a doneAction)


This can be used to decide if to remove a Synth directly via free-message.


Returns an array of events with information about any UGens that write to a bus (such as Out etc.). This includes the rate and number of channels of the UGen. If its first input is a control, also the corresponding control name is provided.


.msgFunc = value

the function which is used to create an array of arguments for playing a synth def in patterns


Inherited instance methods

Undocumented instance methods


From extension in /Library/Application Support/SuperCollider/downloaded-quarks/wslib/wslib-classes/Main Features/SynthTracker/


.constants = value


.def = value


.hasArrayArgs = value


.hasVariants = value


From extension in /SuperCollider/Contents/Resources/SCClassLibrary/Common/GUI/PlusGUI/Control/



From extension in /SuperCollider/Contents/Resources/SCClassLibrary/Common/GUI/PlusGUI/Control/


.metadata = value


.msgFuncKeepGate = bool: false

.readSynthDef(stream, keepDef: false)

.readSynthDef2(stream, keepDef: false)



.send(server, completionMsg)



From extension in /Library/Application Support/SuperCollider/downloaded-quarks/wslib/wslib-classes/Main Features/SynthTracker/


From extension in /Library/Application Support/SuperCollider/downloaded-quarks/wslib/wslib-classes/Main Features/SynthTracker/

.writeMetadata(path, mdPlugin)

SynthDescs and SynthDef metadata

Metadata associated with a SynthDef consists of an Event (a syntactically shorter form of an identity dictionary) containing information about the SynthDef that is useful to the client, and which cannot be inferred from the binary .scsyndef stream.

For example, by listing argument names and ControlSpecs under the 'specs' key in the event, the client can use the specs to build a GUI allowing control over all the SynthDef's inputs, with sensible range mappings. (The "window" button in the SynthDescLib browser does exactly this -- any ControlSpecs listed in the metadata will be used for the corresponding synth input's slider.)

Currently only the 'specs' key is reserved. Other keys may be used as needed for specific applications. As the use of SynthDef metadata evolves, other keys may be standardized.

Creation and access

Metadata are specified when creating a SynthDef. If the SynthDef is .store'd (or .add'd) into a SynthDescLib, the metadata become part of the SynthDesc as well. Thereafter, the metadata can be accessed through SynthDescLib:

Persistence and metadata plug-ins

Storing a SynthDef into the library with .store persists the SynthDef on disk. Metadata may also be persisted at the same time by using the appropriate metadata plug-in class. The plug-in is responsible for writing a separate metadata file into the synthdefs directory, and reading the file back at the same time that a SynthDesc is created for a .scsyndef file using or

The currently available plug-ins are:

A dummy plug-in, which writes no metadata. , so that users who are not interested in metadata will not find extra files in the synthdefs directory.
Writes the metadata as a SuperCollider text archive -- metadata.writeArchive(path). This is the default. Metadata are written only if the SynthDef contains metadata.

Other plug-ins may be written at a later date, to support sharing metadata with applications in other languages using formats like JSON (JavaScript Object Notation) or XML.

You may specify a global default metadata plug-in as follows:

Metadata are not written when using SynthDef().load(server). This is because SynthDesc exists to describe a SynthDef to the client, whereas SynthDef is really just an abstraction to create a UGen graph for the server. Metadata are also not written for SynthDef().add, because in the normal case, nothing is persisted to disk. (If the SynthDef is very large and a disk file is required, then the metadata will persist along with the .scsyndef file.)

Automatic population

You may write a function to populate entries into the metadata automatically, based on the SynthDesc object. This function executes when reading a SynthDesc from disk, when using .add, and before writing a metadata file (in .store).


Whenever a .scsyndef file is written, any existing metadata files will be deleted so that a new .scsyndef file will not exist on disk with out-of-date metadata.


When reading a SynthDesc, metadata files will be checked and one will be read, regardless of format. (Even if the default SynthDesc.mdPlugin is different from the file format on disk, the disk file will be read using the appropriate plug-in anyway.)

There should be only one metadata file at a time. However, in the case of conflicts, the default SynthDesc.mdPlugin will be preferred. The file extension identifies the format.

Metadata Examples