:mod:`sc3nb.sclang` =================== .. py:module:: sc3nb.sclang .. autoapi-nested-parse:: Module for handling a SuperCollider language (sclang) process. .. !! processed by numpydoc !! Module Contents --------------- Class List ~~~~~~~~~~ .. autoapisummary:: :nosignatures: sc3nb.sclang.SynthArgument sc3nb.sclang.SCLang Content ~~~~~~~ .. py:data:: _LOGGER .. py:data:: SCLANG_DEFAULT_PORT :value: 57120 .. py:data:: SC3NB_SCLANG_CLIENT_ID :value: 0 .. class:: SynthArgument **Bases:** :class:`NamedTuple` Synth argument, rate and default value .. !! processed by numpydoc !! .. py:attribute:: name :type: str .. py:attribute:: rate :type: str .. py:attribute:: default :type: Any .. exception:: SCLangError(message, sclang_output=None) **Bases:** :class:`Exception` Exception for Errors related to SuperColliders sclang. Initialize self. See help(type(self)) for accurate signature. .. !! processed by numpydoc !! .. py:attribute:: sclang_output .. class:: SCLang Class to control the SuperCollider Language Interpreter (sclang). Creates a python representation of sclang. :Raises: NotImplementedError When an unsupported OS was found. .. !! processed by numpydoc !! .. py:attribute:: process :type: sc3nb.process_handling.Process :value: None .. py:attribute:: _server :type: Optional[sc3nb.sc_objects.server.SCServer] :value: None .. py:attribute:: started :type: bool :value: False .. py:attribute:: _port :type: int .. py:attribute:: _repl_return :value: '->' **Overview:** .. autoapisummary:: :nosignatures: sc3nb.sclang.SCLang.start sc3nb.sclang.SCLang.init sc3nb.sclang.SCLang.load_synthdefs sc3nb.sclang.SCLang.kill sc3nb.sclang.SCLang.__del__ sc3nb.sclang.SCLang.__repr__ sc3nb.sclang.SCLang.cmd sc3nb.sclang.SCLang.cmdv sc3nb.sclang.SCLang.cmds sc3nb.sclang.SCLang.cmdg sc3nb.sclang.SCLang.read sc3nb.sclang.SCLang.empty sc3nb.sclang.SCLang.get_synth_description sc3nb.sclang.SCLang.connect_to_server .. py:method:: start(sclang_path: Optional[str] = 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_path** : Optional[str], optional Path with the sclang executable, by default None **console_logging** : bool, optional If True log sclang output to console, by default True **allowed_parents** : Sequence[str], optional parents name of processes to keep, by default ALLOWED_PARENTS **timeout** : float, optional timeout in seconds for starting the executable, by default 10 :Raises: SCLangError When starting or initilizing sclang failed. .. !! processed by numpydoc !! .. py:method:: 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. .. !! processed by numpydoc !! .. py:method:: load_synthdefs(synthdefs_path: Optional[str] = None) -> None Load SynthDef files from path. :Parameters: **synthdefs_path** : str, optional Path where the SynthDef files are located. If no path provided, load default sc3nb SynthDefs. .. !! processed by numpydoc !! .. py:method:: kill() -> int Kill this sclang instance. :Returns: int returncode of the process. .. !! processed by numpydoc !! .. py:method:: __del__() .. py:method:: __repr__() -> str .. py:method:: cmd(code: str, pyvars: Optional[dict] = 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: **code** : str SuperCollider code to execute. **pyvars** : dict, optional Dictionary of name and value pairs of python variables that can be injected via ^name, by default None **verbose** : bool, optional If True print output, by default True **discard_output** : bool, optional If True clear output buffer before passing command, by default True **get_result** : bool, optional If True receive and return the evaluation result from sclang, by default False **print_error** : bool, optional If this and get_result is True and code execution fails the output from sclang will be printed. **get_output** : bool, optional If True return output. Does not override get_result If verbose this will be True, by default False **timeout** : int, 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. .. !! processed by numpydoc !! .. py:method:: cmdv(code: str, **kwargs) -> Any cmd with verbose=True .. !! processed by numpydoc !! .. py:method:: cmds(code: str, **kwargs) -> Any cmd with verbose=False, i.e. silent .. !! processed by numpydoc !! .. py:method:: cmdg(code: str, **kwargs) -> Any cmd with get_result=True .. !! processed by numpydoc !! .. py:method:: read(expect: Optional[str] = None, timeout: float = 1, print_error: bool = True) -> str Reads SuperCollider output from the process output queue. :Parameters: **expect** : Optional[str], optional Try to read this expected string, by default None **timeout** : float, optional How long we try to read the expected string in seconds, by default 1 **print_error** : bool, 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. .. !! processed by numpydoc !! .. py:method:: empty() -> None Empties sc output queue. .. !! processed by numpydoc !! .. py:method:: get_synth_description(synth_def) Get a SynthDesc like description via sclang's global SynthDescLib. :Parameters: **synth_def** : str SynthDef name :Returns: dict {argument_name: SynthArgument(rate, default)} :Raises: ValueError When SynthDesc of synth_def can not be found. .. !! processed by numpydoc !! .. py:method:: connect_to_server(server: Optional[sc3nb.sc_objects.server.SCServer] = None) Connect this sclang instance to the SuperCollider server. This will set Server.default and s to the provided remote server. :Parameters: **server** : SCServer, 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. .. !! processed by numpydoc !!