sc3.synth.synthdef module

SynthDef.sc

class MetaSynthDef(*_)

Bases: type

tmp_name_prefix = 'tmp__'
generate_tmp_name()
class SynthDef(name, func, rates=None, prepend=None, variants=None, metadata=None)

Bases: object

Build the instructions to create synthesis nodes in the server.

SynthDef instances build the instructions to create synthesis nodes in the server from a function containing interconnected UGen objects. In order for the server to have the synthesis definition available it should be sent using add, load, send or store methods.

Parameters

  • name (str) – The name of the synthesis definition used by the server to create synth nodes.

  • func (function) – A common function containing UGen objects.

  • rates (list) – An optional list of rate specifications that map to the func defined parameters. If value is None (default) control rate instances will be created instead. Possible values are ‘ar’, ‘kr’, ‘ir’, ‘tr’ or a number (indicating lag value for ‘kr’ controls). This parameter overrides rates defined by function annotations.

  • prepend (list) – An optional list of positional values that will be passed to func when evaluated. This prevents controls from being created for those parameters.

  • variants (dict) – An optional dictionary with different keys that specify dictionaries of default values to create synthesis nodes in the server. When using variants, synthesis definition names are composed as ‘synthname.variantkey’.

  • metadata (dict) – An user defined JSON serializable dictionary to provide information about the synthesis definition.

property name

SynthDef’s name.

property func

SynthDef’s function.

property variants

SynthDef’s argument variants dict.

property metadata

SynthDef’s metadata dict.

classmethod wrap(func, rates=None, prepend=None)

Wrap a function within another SynthDef function.

The wrapped func must return an UGen or None, rates and prepend are processed as in the default constructor and parameters are converted to controls of the resulting SynthDef.

dump_ugens()

Print the generated graph instructions in a human readable way.

add(libname=None, completion_msg=None, keep_def=True)

Send the definition to the servers and keep a description.

Adds the synthesis definition to the SynthDescLib specified by libname and sends it to the library’s registered servers. All operations take place in memory (no scsyndef file is written). This method is used for most cases.

Parameters

  • libname (str) – SynthDescLib library name. If not specified ‘default’ will be used.

  • completion_msg (list | function) – An OSC message or a function that receives a server as argument and return an OSC message. This message will be executed in the server after the definition is loaded.

  • keep_def (bool) – A flag indicating if the function’s code will be kept in the SynthDesc object, default value is True.

as_bytes()

Binary format of the synthesis definition.

send(server=None, completion_msg=None)

Send the definition to the server.

Parameters

  • server (Server | list) – A single server object or list.

  • completion_msg (list | function) – An OSC message or a function that receives a server as argument and return an OSC message. This message will be executed in the server after the definition is loaded.

load(server, completion_msg=None, dir=None)

Write the definition to a file that is loaded from the server.

This method is used for definitions too large to be sent over UDP.

Parameters

  • server (Server | list) – A single server object or list.

  • completion_msg (list | function) – An OSC message or a function that receives a server as argument and return an OSC message. This message will be executed in the server after the definition is loaded.

  • dir (str | pathlib.Path) – Directory in which the file is saved, if not specified platform’s default directory is used.

store(libname='default', dir=None, completion_msg=None, md_plugin=None)

Add a description, write the definition to disk and send it to the registered servers.

Similar to add but write to disk.

Parameters

  • libname (str) – SynthDescLib library name. If not specified ‘default’ will be used.

  • dir (str | pathlib.Path) – Directory in which the file is saved, if not specified platform’s default directory is used.

  • completion_msg (function) – An OSC message or a function that receives a server as argument and return an OSC message. This message will be executed in the server after the definition is loaded.

  • md_plugin – TODO: Not defined yet.

classmethod send_from_file(server, name, dir=None)

Read a synthdef file and send the definition to the server.

Parameters

  • name (str) – SynthDef name.

  • dir (str | pathlib.Path) – Path to the synthdef directory, if not set default location is used.

classmethod load_from_file(server, name, completion_msg=None, dir=None)

Ask the server to load a synthdef from disk.

Parameters

  • name (str) – SynthDef name.

  • completion_msg (list) – An OSC message to be evaluated by the server after load command finishes.

  • dir (str | pathlib.Path) – Path to the synthdef directory, if not set default location is used.

classmethod load_directory(server, dir, completion_msg=None)

Ask the server to load synthdefs from a directory.

Parameters

  • name (str) – SynthDef name.

  • completion_msg (list | function) – An OSC message to be evaluated by the server after load command finishes.

synthdef(func=None, **kwargs)

Decorator function to build and add definitions.

The name of the decorated function becomes the name of the definition. After instantiation the add method is called and is also set to be called at subsequent server’s boot.

It can be used with optional keyword only arguments.

Examples

@synthdef
def test(freq=440, amp=0.1, pan=0, gate=1):
    sig = SinOsc(freq) * amp
    sig *= EnvGen(Env.asr(), gate)
    Out(0, Pan2(sig, pan))

# Same as:

def test(freq=440, amp=0.1, pan=0, gate=1):
    ...

sd = SynthDef('test', test)
sd.add()

# With arguments:

@synthdef(rates=[0.02, 0.02], variants={'low': {'freq': 110}})
def test(freq=440, amp=0.1, pan=0, gate=1):
    ...

# Same as:

def test(freq=440, amp=0.1, pan=0, gate=1):
    ...

sd = SynthDef('test', test, [0.02, 0.02], None, {'low': {'freq': 110}})
sd.add()