sc3nb.sclang

Module for handling a SuperCollider language (sclang) process.

Module Contents

Class List

SynthArgument	Synth argument, rate and default value
SCLang	Class to control the SuperCollider Language Interpreter (sclang).

Content

sc3nb.sclang._LOGGER

sc3nb.sclang.SCLANG_DEFAULT_PORT = 57120

sc3nb.sclang.SC3NB_SCLANG_CLIENT_ID = 0

class sc3nb.sclang.SynthArgument

Bases: NamedTuple

Synth argument, rate and default value

name: str

rate: str

default: Any

exception sc3nb.sclang.SCLangError(message, sclang_output=None)

Bases: Exception

Exception for Errors related to SuperColliders sclang.

Initialize self. See help(type(self)) for accurate signature.

sclang_output

class sc3nb.sclang.SCLang

Class to control the SuperCollider Language Interpreter (sclang).

Creates a python representation of sclang.

Raises:

NotImplementedError

When an unsupported OS was found.

process: sc3nb.process_handling.Process = None

_server: sc3nb.sc_objects.server.SCServer | None = None

started: bool = False

_port: int

_repl_return = '->'

Overview:

start	Start and initilize the sclang process.
init	Initialize sclang for sc3nb usage.
load_synthdefs	Load SynthDef files from path.
kill	Kill this sclang instance.
__del__
__repr__
cmd	Send code to sclang to execute it.
cmdv	cmd with verbose=True
cmds	cmd with verbose=False, i.e. silent
cmdg	cmd with get_result=True
read	Reads SuperCollider output from the process output queue.
empty	Empties sc output queue.
get_synth_description	Get a SynthDesc like description via sclang's global SynthDescLib.
connect_to_server	Connect this sclang instance to the SuperCollider server.

start(sclang_path: str | None = None, console_logging: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS, timeout: float = 10) → None

Start and initilize the sclang process.

This will also kill sclang processes that does not have allowed parents.

Parameters:

sclang_pathOptional[str], optional

Path with the sclang executable, by default None

console_loggingbool, optional

If True log sclang output to console, by default True

allowed_parentsSequence[str], optional

parents name of processes to keep, by default ALLOWED_PARENTS

timeoutfloat, optional

timeout in seconds for starting the executable, by default 10

Raises:

SCLangError

When starting or initilizing sclang failed.

init()

Initialize sclang for sc3nb usage.

This will register the /return callback in sclang and load the SynthDefs from sc3nb.

This is done automatically by running start.

load_synthdefs(synthdefs_path: str | None = None) → None

Load SynthDef files from path.

Parameters:

synthdefs_pathstr, optional

Path where the SynthDef files are located. If no path provided, load default sc3nb SynthDefs.

kill() → int

Kill this sclang instance.

Returns:

int

returncode of the process.

__del__()

__repr__() → str

cmd(code: str, pyvars: dict | None = None, verbose: bool = True, discard_output: bool = True, get_result: bool = False, print_error: bool = True, get_output: bool = False, timeout: int = 1) → Any

Send code to sclang to execute it.

This also allows to get the result of the code or the corresponding output.

Parameters:

codestr

SuperCollider code to execute.

pyvarsdict, optional

Dictionary of name and value pairs of python variables that can be injected via ^name, by default None

verbosebool, optional

If True print output, by default True

discard_outputbool, optional

If True clear output buffer before passing command, by default True

get_resultbool, optional

If True receive and return the evaluation result from sclang, by default False

print_errorbool, optional

If this and get_result is True and code execution fails the output from sclang will be printed.

get_outputbool, optional

If True return output. Does not override get_result If verbose this will be True, by default False

timeoutint, optional

Timeout in seconds for code execution return result, by default 1

Returns:

Any

if get_result=True,

Result from SuperCollider code, not all SC types supported. When type is not understood this will return the datagram from the OSC packet.

if get_output or verbose

Output from SuperCollider code.

if get_output and get_result=True

(result, output)

else

None

Raises:

RuntimeError

If get_result is True but no OSCCommunication instance is set.

SCLangError

When an error with sclang occurs.

cmdv(code: str, **kwargs) → Any

cmd with verbose=True

cmds(code: str, **kwargs) → Any

cmd with verbose=False, i.e. silent

cmdg(code: str, **kwargs) → Any

cmd with get_result=True

read(expect: str | None = None, timeout: float = 1, print_error: bool = True) → str

Reads SuperCollider output from the process output queue.

Parameters:

expectOptional[str], optional

Try to read this expected string, by default None

timeoutfloat, optional

How long we try to read the expected string in seconds, by default 1

print_errorbool, optional

If True this will print a message when timed out, by default True

Returns:

str

output from sclang process.

Raises:

timeout

If expected output string could not be read before timeout.

empty() → None

Empties sc output queue.

get_synth_description(synth_def)

Get a SynthDesc like description via sclang’s global SynthDescLib.

Parameters:

synth_defstr

SynthDef name

Returns:

dict

{argument_name: SynthArgument(rate, default)}

Raises:

ValueError

When SynthDesc of synth_def can not be found.

connect_to_server(server: sc3nb.sc_objects.server.SCServer | None = None)

Connect this sclang instance to the SuperCollider server.

This will set Server.default and s to the provided remote server.

Parameters:

serverSCServer, optional

SuperCollider server to connect. If None try to reconnect.

Raises:

ValueError

If something different from an SCServer or None was provided

SCLangError

If sclang failed to register to the server.