sc3.synth.server module¶

Server.sc

s = <sc3.synth.server.Server object>¶: Default server global variable.

class Defaults(value)¶

Bases: enum.Enum

Default command values for server options.

UDP_PORT = ('-u', None)¶

TCP_PORT = ('-t', None)¶

BIND_ADDRESS = ('-B', '127.0.0.1')¶

MAX_LOGINS = ('-l', 64)¶

PASSWORD = ('-p', None)¶

ZEROCONF = ('-R', 1)¶

RESTRICTED_PATH = ('-P', None)¶

UGEN_PLUGINS_PATH = ('-U', None)¶

CONTROL_BUSES = ('-c', 16384)¶

AUDIO_BUSES = ('-a', 1024)¶

INPUT_CHANNELS = ('-i', 8)¶

OUTPUT_CHANNELS = ('-o', 8)¶

BLOCK_SIZE = ('-z', 64)¶

BUFFERS = ('-b', 1024)¶

MAX_NODES = ('-n', 1024)¶

MAX_SYNTHDEFS = ('-d', 1024)¶

RT_MEMORY = ('-m', 8192)¶

WIRES = ('-w', 64)¶

RGENS = ('-r', 64)¶

LOAD_SYNTHDEFS = ('-D', 1)¶

HW_DEVICE_NAME = ('-H', None)¶

HW_BUFFER_SIZE = ('-Z', 0)¶

SAMPLE_RATE = ('-S', 0)¶

NRT = ('-N', None)¶

VERBOSE = ('-V', 0)¶

MEMORY_LOCKING = ('-L', None)¶

THREADS = ('-T', 4)¶

USE_SYSTEM_CLOCK = ('-C', 1)¶

INPUT_STREAMS = ('-I', None)¶

OUTPUT_STREAMS = ('-O', None)¶

class ServerOptions¶

Bases: object

Encapsulates commandline and other server options.

program¶

Command name of the server.

Type: str

protocol¶

Transport protocol of the server, either ‘udp’ or ‘tcp’.

Type: str

bind_address¶

The IP address that the server’s TCP or UDP socket is listening on. The default value is ‘127.0.0.1’, meaning only listen to OSC messages on localhost.

Type: str

max_logins¶

Indicate the maximum number of clients which can simultaneously receive notifications from the server. When using TCP this is also the maximum number of simultaneous connections. This is also used by the language to split ranges of nodes, buffers, or busses. In multi-client situations you will need to set this to at least the number of clients you wish to allow. This must be the same in the Server instances on every client. The default is 1.

Type: int

password¶

Set servers’ session password for TCP connections. When using TCP, the session password must be the first command sent. UDP ports never require passwords, so for security use TCP. The default is None (no password).

Type: str

zeroconf¶

Indicate whether or not the server should publish its port using zero configuration networking, to facilitate network interaction. This is True by default. If you find unacceptable delays (beachballing) upon server boot, you can try setting this to false.

Type: bool

restricted_path¶

Restrict the system paths in which the server is allowed to read/write files when running. If None (default) no restrictions are applied. Otherwise, set it as a string representing a single path.

Type: str

ugen_plugins_path¶

A path or a list of paths. If not None, the standard paths are not searched for plugins. Default is None.

Type: str

control_buses¶

The number of internal control rate busses. The default is 16384.

Type: int

audio_buses¶

The number of internal audio rate busses. The default is 1024.

Type: int

input_channels¶

The number of audio input bus channels. This need not correspond to the number of hardware inputs. The default is 2.

Type: int

output_channels¶

The number of audio output bus channels. This need not correspond to the number of hardware outputs (this can be useful for instance in the case of recording). The default is 2.

Type: int

block_size¶

The number of samples in one control period. The default is 64.

Type: int

buffers¶

The number of global sample buffers available. The default is 1024.

Type: int

max_nodes¶

The maximum number of nodes. The default is 1024.

Type: int

max_synthdefs¶

The maximum number of synthdefs. The default is 1024.

Type: int

rt_memory¶

The number of kilobytes of real time memory allocated to the server. This memory is used to allocate synths and any memory that unit generators themselves allocate (for instance in the case of delay ugens which do not use buffers, such as CombN), and is separate from the memory used for buffers. Setting this too low is a common cause of ‘exception in real time: alloc failed’ errors. The default is 8192.

Type: int

wires¶

The maximum number of buffers that are allocated to interconnect unit generators. (Not to be confused with the global sample buffers represented by Buffer.) This sets the limit of complexity of SynthDefs that can be loaded at runtime. This value will be automatically increased if a more complex synthdef is loaded at startup, but it cannot be increased thereafter without rebooting. The default is 64.

Type: int

rgens¶

The number of seedable random number generators. The default is 64.

Type: int

load_synthdefs¶

Indicate whether or not to load the synth definitions in the default synthdefs folder (or anywhere set in the environment variable SC_SYNTHDEF_PATH) at startup. The default is True.

Type: bool

hw_device_name¶

A string to choose I/O device by name or a tuple of two strings for a different input and output device. Default is None and will use the system’s default input and output.

Type: str | tuple(str, str)

hw_buffer_size¶

The preferred hardware buffer size. If not None the server program will attempt to set the hardware buffer frame size. Not all sizes are valid. See the documentation of your audio hardware for details. Default value is None.

Type: int

sample_rate¶

The preferred sample rate. If not None the server app will attempt to set the sample rate of the hardware. The hardware has to support the sample rate that you choose.

Type: int

verbose¶

Control the verbosity of server messages. A value of 0 is normal behaviour, -1 suppresses informational messages, -2 suppresses informational and many error messages, as well as messages from Poll. The default is 0.

Type: int

memory_locking¶

Set whether the server should try to lock its memory into physical RAM. Default is False. Supernova only option.

Type: bool

threads¶

Number of audio threads that are spawned by supernova. For scsynth this value is ignored. If None or 0, it uses the one thread per CPU. Default is None. Supernova only option.

Type: int

use_system_clock¶

Set whether to sync to the driver’s sample clock, or to the system clock. Supernova only option, scsynth always uses system clock and this value is ignored. If True (default), use the system clock. Timestamped messages will maintain consistent latency over long sessions, but may not be perfectly sample-accurate. If False, use the sample clock. This helps to support sample-accurate scheduling; however, messaging latency from the client language will drift over long periods of time.

Type: bool

input_streams¶

Allow turning off input streams that you are not interested in on the audio device. If the string is ‘01100’, for example, then only the second and third input streams on the device will be enabled. Turning off streams can reduce CPU load. The default value is None. Darwin only option.

Type: str

output_streams¶

Allow turning off output streams that you are not interested in on the audio device. If the string is ‘11000’, for example, then only the first two output streams on the device will be enabled. Turning off streams can reduce CPU load. Darwin only option.

Type: str

reserved_audio_buses¶

Undocumented client side option.

Type: int

reserved_control_buses¶

Undocumented client side option.

Type: int

reserved_buffers¶

Undocumented client side option.

Type: int

initial_node_id¶

Node ID from which to start node allocation (client side option). By default, the Server object in the client begins allocating node IDs at 1000, reserving 0-999 for permanent nodes.

Type: int

rec_header_format¶

Default header format for NRT rendering.

Type: str

rec_sample_format¶

Default sample format for NRT rendering.

Type: str

rec_channels¶

Undocumented/unused client side option.

Type: int

rec_buf_size¶

Undocumented/unused client side option.

Type: int

options_list(port, osc_file=None, input_file=None, output_file=None)¶: Return a list of options for the server command.

first_private_bus()¶: Return the bus number after output and input buses.

class ServerProcess(on_exit=None)¶

Bases: object

run(server)¶

running()¶

finish()¶

detach()¶

class MetaServer(*_)¶

Bases: type

sync_s = True¶: Update global variable s when default server is changed.

property default¶: Default server object usualy binded to the s global variable.

remove(server)¶: Remove a server instance from the instances registry.

quit_all(watch_shutdown=True)¶: Quit all known local servers.

free_all(even_remote=False)¶

Free nodes from all registered local or remote servers.

Parameters: even_remote (bool) – Free also the nodes of remote server. False by default.

hard_free_all(even_remote=False)¶

Free nodes from all known local or remote servers.

Parameters: even_remote (bool) – Free also the nodes of remote server. False by default.

class Server(name, addr, options=None)¶

Bases: sc3.synth._graphparam.NodeParameter

property addr¶: NetAddr object of the server.

property name¶: Custom name of the server, only setteable at creation time.

property default_group¶

Servers’ default group node (user space).

Synth and Group target this node by default.

Parameters: all_users (bool) – If true return a list of all default groups (multiuser setup).

property status¶: ServerStatusWatcher instance that keeps track of server status.

property volume¶: Volume instance.

property recorder¶: Recorder instance

property pid¶: Process ID of the server program.

property program_running¶: Returns True if the server program is running in localhost.

property client_id¶: Client ID, usually 0 in a single user scenario.

query_tree(controls=False, action=None, timeout=3)¶

Query the servers’s node tree.

Parameters

controls (bool) – If True also request synth controls values.
action (function) – A responder function that receives the data in JSON format.
timeout (int | float) – Request timeout in seconds.

dump_tree(controls=False)¶

Ask the server to dump its node tree to stdout.

Parameters: controls (bool) – If True also print synth controls with current values.

dump_osc(code=1)¶

Enable server-side message dumping.

The flags for code are as follow:

0 - turn dumping OFF.
1 - print the parsed contents of the message.
2 - print the contents in hexadecimal.
3 - print both the parsed and hexadecimal representations of the

contents.

sync(condition=None, latency=None, elements=None)¶

Wait for previous asynchronous commands to finish.

Parameters

condition (Condition) – An optional instance of Condition that will be used to wait for the reply.
latancy (int | float) – Bundle’s latency as in send_bundle.
elements (list) – A list of lists as OSC messages which will be sent before the '/sync' message.

Notes

This method is a generator that manages server’s '/sync' message and its reply. Use as yield from s.sync() to sync previous commands sent to the server from within a routine.

Internally, it sends a '/sync' message to the server, which will reply with the message '/synced', and waits in a Condition until all previous asynchronous commands have been completed.

bind()¶

Return a BundleNetAddr context manager that collects generated messages into a bundle and send it to the server.

Note that sync will work as expected inside a routine by sending the generated bundle so far:

with s.bind():
    s.addr.send_msg( ... )
    s.addr.send_msg( ... )
    yield from s.sync()  # Sends previous messages in a bundle.
    s.addr.send_msg( ... )
    ...

register(on_complete=None, on_failure=None)¶

Register to a remote server.

Parameters

on_complete (function) – A function to be called after registration succeeded. Optionally, the function receives the server object as its only argument.
on_failure (function) – A function to be called if registration fails. Optionally, the function receives the server object as its only argument.

unregister(on_complete=None, on_failure=None)¶

Unregister from a remote server.

Parameters

on_complete (function) – A function called after deregistration succeeded. Optionally, the function receives the server object as its only argument.
on_failure (function) – A function called if unregistration fails. Optionally, the function receives the server object as its only argument.

boot(register=True, on_complete=None, on_failure=None)¶

Start the local server program.

Parameters

register (bool) – Register the client to receive server notifications.
on_complete (function) – A function to be called after the server boot process is successfully finished. Optionally, the function receives the server object as its only argument.
on_failure (function) – A function to be called if the server boot process fails. Optionally, the function receives the server object as its only argument.

Notes

It is not possible to boot a server application in a remote machine. To register to an already running server in a remote machine use the register method.

reboot(func=None, on_failure=None)¶

Quit and (re)start the server program.

Parameters

func (function) – A function to be called after quit and before the server boots again.
on_failure (function) – A function to be called if the server reboot process fails. Optionally, the function receives the server object as its only argument.

DEFAULT_ADDRESS = NetAddr('127.0.0.1', 57110)¶

all = {<sc3.synth.server.Server object>}¶

named = {'localhost': <sc3.synth.server.Server object>}¶

quit(watch_shutdown=True, on_complete=None, on_failure=None)¶

Stop the server program.

Parameters

watch_shutdown (bool) – Tell the server whether to watch status during shutdown.
on_complete (function) – A function to be called after the server quit process is successfully finished. Optionally, the function receives the server object as its only argument.
on_failure (function) – A function to be called if the server quit process fails. Optionally, the function receives the server object as its only argument.

free_nodes()¶: Free all server’s nodes.

free_default_group(all_users=False)¶: Free all nodes within the client’s default group.

reorder(node_list, target, add_action='addToHead')¶: Reorder nodes in node_list relative to target.