:mod:`sc3nb` ============ .. py:module:: sc3nb .. autoapi-nested-parse:: Package for interfacing SuperCollider. Collection of Classes and functions for communicating with SuperCollider within python and jupyter notebooks, as well as playing recording and visualizing audio. .. rubric:: Examples For example usage please refer to the user guide. .. !! processed by numpydoc !! Package Contents ---------------- Function List ~~~~~~~~~~~~~ .. autoapisummary:: :nosignatures: sc3nb.startup Class List ~~~~~~~~~~ .. autoapisummary:: :nosignatures: sc3nb.SC sc3nb.SCServer sc3nb.ServerOptions sc3nb.SCLang sc3nb.Node sc3nb.Synth sc3nb.Group sc3nb.AddAction sc3nb.SynthDef sc3nb.Buffer sc3nb.Bus sc3nb.Score sc3nb.Recorder sc3nb.TimedQueue sc3nb.TimedQueueSC sc3nb.OSCMessage sc3nb.Bundler Content ~~~~~~~ .. py:function:: startup(start_server: bool = True, scsynth_path: Optional[str] = None, start_sclang: bool = True, sclang_path: Optional[str] = None, magic: bool = True, scsynth_options: Optional[sc3nb.sc_objects.server.ServerOptions] = None, with_blip: bool = True, console_logging: bool = False, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS, timeout: float = 10) -> SC Inits SuperCollider (scsynth, sclang) and registers ipython magics :Parameters: **start_server** : bool, optional If True boot scsynth, by default True **scsynth_path** : Optional[str], optional Path of scscynth executable, by default None **start_sclang** : bool, optional If True start sclang, by default True **sclang_path** : Optional[str], optional Path of sclang executable, by default None **magic** : bool, optional If True register magics to ipython, by default True **scsynth_options** : Optional[ServerOptions], optional Options for the server, by default None **with_blip** : bool, optional make a sound when booted, by default True **console_logging** : bool, optional If True write scsynth/sclang output to console, by default False **allowed_parents** : Sequence[str], optional Names of parents that are allowed for other instances of sclang/scsynth processes, by default ALLOWED_PARENTS **timeout** : float, optional timeout in seconds for starting the executable, by default 10 :Returns: SC SuperCollider Interface class. .. !! processed by numpydoc !! .. class:: SC(*, start_server: bool = True, scsynth_path: Optional[str] = None, start_sclang: bool = True, sclang_path: Optional[str] = None, scsynth_options: Optional[sc3nb.sc_objects.server.ServerOptions] = None, with_blip: bool = True, console_logging: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS, timeout: float = 5) Create a SuperCollider Wrapper object. :Parameters: **start_server** : bool, optional If True boot scsynth, by default True. **scsynth_path** : Optional[str], optional Path of scscynth executable, by default None. **start_sclang** : bool, optional If True start sclang, by default True. **sclang_path** : Optional[str], optional Path of sclang executable, by default None. **scsynth_options** : Optional[ServerOptions], optional Options for the server, by default None. **with_blip** : bool, optional Make a sound when booted, by default True. **console_logging** : bool, optional If True write scsynth/sclang output to console, by default True. **allowed_parents** : Sequence[str], optional Names of parents that are allowed for other instances of sclang/scsynth processes, by default ALLOWED_PARENTS. **timeout** : float, optional timeout in seconds for starting the executables, by default 5 .. !! processed by numpydoc !! .. py:attribute:: default :type: Optional[SC] :value: None Default SC instance. This will be used by all SuperCollider objects if no SC/server/lang is specified. .. !! processed by numpydoc !! .. py:attribute:: _console_logging .. py:attribute:: _server :value: None .. py:attribute:: _sclang :value: None **Overview:** .. autoapisummary:: :nosignatures: sc3nb.SC.get_default sc3nb.SC.start_sclang sc3nb.SC.start_server sc3nb.SC._try_to_connect sc3nb.SC.__del__ sc3nb.SC.__repr__ sc3nb.SC.exit .. py:method:: get_default() -> SC :classmethod: Get the default SC instance :Returns: SC default SC instance :Raises: RuntimeError If there is no default SC instance. .. !! processed by numpydoc !! .. py:method:: start_sclang(sclang_path: Optional[str] = None, console_logging: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS, timeout: float = 5) Start this SuperCollider language :Parameters: **sclang_path** : Optional[str], optional Path of sclang executable, by default None **console_logging** : bool, optional If True write scsynth/sclang output to console, by default True **allowed_parents** : Sequence[str], optional Names of parents that are allowed for other instances of sclang/scsynth processes, by default ALLOWED_PARENTS **timeout** : float, optional timeout in seconds for starting the executable, by default 5 .. !! processed by numpydoc !! .. py:method:: start_server(scsynth_options: Optional[sc3nb.sc_objects.server.ServerOptions] = None, scsynth_path: Optional[str] = None, console_logging: bool = True, with_blip: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS, timeout: float = 5) Start this SuperCollider server :Parameters: **scsynth_options** : Optional[ServerOptions], optional Options for the server, by default None **scsynth_path** : Optional[str], optional Path of scscynth executable, by default None **console_logging** : bool, optional If True write scsynth/sclang output to console, by default True **with_blip** : bool, optional make a sound when booted, by default True **allowed_parents** : Sequence[str], optional Names of parents that are allowed for other instances of sclang/scsynth processes, by default ALLOWED_PARENTS **timeout** : float, optional timeout in seconds for starting the executable, by default 5 .. !! processed by numpydoc !! .. py:method:: _try_to_connect() .. py:method:: __del__() .. py:method:: __repr__() -> str .. py:method:: exit() -> None Closes SuperCollider and shuts down server .. !! processed by numpydoc !! .. class:: SCServer(options: Optional[ServerOptions] = None) **Bases:** :class:`sc3nb.osc.osc_communication.OSCCommunication` SuperCollider audio server representaion. Parameters ---------- options : Optional[ServerOptions], optional Options used to start the local server, by default None Create an OSC communication server :Parameters: **server_ip** : str IP address to use for this server **server_port** : int port to use for this server **default_receiver_ip** : str IP address used for sending by default **default_receiver_port** : int port used for sending by default .. !! processed by numpydoc !! .. py:attribute:: _num_node_ids :type: int :value: 0 .. py:attribute:: process :type: Optional[sc3nb.process_handling.Process] :value: None .. py:attribute:: _programm_name .. py:attribute:: _client_id :type: int .. py:attribute:: _scsynth_address .. py:attribute:: _scsynth_port .. py:attribute:: _max_logins .. py:attribute:: _server_running :type: bool :value: False .. py:attribute:: _has_booted :type: bool :value: False .. py:attribute:: latency :type: float :value: 0.0 .. py:attribute:: nodes :type: weakref.WeakValueDictionary[int, sc3nb.sc_objects.node.Node] .. py:attribute:: node_watcher .. py:attribute:: node_ids :type: Optional[sc3nb.sc_objects.allocators.Allocator] :value: None .. py:attribute:: buffer_ids :type: Optional[sc3nb.sc_objects.allocators.BlockAllocator] :value: None .. py:attribute:: control_bus_ids :type: Optional[sc3nb.sc_objects.allocators.BlockAllocator] :value: None .. py:attribute:: audio_bus_ids :type: Optional[sc3nb.sc_objects.allocators.BlockAllocator] :value: None .. py:attribute:: _root_node .. py:attribute:: _default_groups :type: Dict[int, sc3nb.sc_objects.node.Group] .. py:attribute:: _is_local :type: bool :value: False .. py:attribute:: _output_bus .. py:attribute:: _input_bus .. py:attribute:: init_hooks :type: Set[Hook] .. py:attribute:: _volume **Overview:** .. autoapisummary:: :nosignatures: sc3nb.SCServer.boot sc3nb.SCServer.init sc3nb.SCServer.execute_init_hooks sc3nb.SCServer.connect_sclang sc3nb.SCServer.add_init_hook sc3nb.SCServer.remove_init_hook sc3nb.SCServer.bundler sc3nb.SCServer.blip sc3nb.SCServer.remote sc3nb.SCServer.reboot sc3nb.SCServer.ping sc3nb.SCServer.quit sc3nb.SCServer.sync sc3nb.SCServer.send_synthdef sc3nb.SCServer.load_synthdef sc3nb.SCServer.load_synthdefs sc3nb.SCServer.notify sc3nb.SCServer.free_all sc3nb.SCServer.clear_schedule sc3nb.SCServer.send_default_groups sc3nb.SCServer.mute sc3nb.SCServer.unmute sc3nb.SCServer.version sc3nb.SCServer.status sc3nb.SCServer.dump_osc sc3nb.SCServer.dump_tree sc3nb.SCServer.query_tree sc3nb.SCServer._init_osc_communication sc3nb.SCServer._get_errors_for_address sc3nb.SCServer._log_repr sc3nb.SCServer._log_message sc3nb.SCServer._warn_fail sc3nb.SCServer.__repr__ .. py:method:: boot(scsynth_path: Optional[str] = None, timeout: float = 5, console_logging: bool = True, with_blip: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = ALLOWED_PARENTS) Start the Server process. :Parameters: **scsynth_path** : str, optional Path of scscynth executable, by default None **timeout** : float, optional Timeout for starting the executable, by default 5 **console_logging** : bool, optional If True write process output to console, by default True **with_blip** : bool, optional make a sound when booted, by default True **kill_others** : bool kill other SuperCollider server processes. **allowed_parents** : Sequence[str], optional Names of parents that are allowed for other instances of scsynth processes that won't be killed, by default ALLOWED_PARENTS :Raises: ValueError If UDP port specified in options is already used ProcessTimeout If the process fails to start. .. !! processed by numpydoc !! .. py:method:: init(with_blip: bool = True) Initialize the server. This adds allocators, loads SynthDefs, send default Groups etc. :Parameters: **with_blip** : bool, optional make a sound when initialized, by default True .. !! processed by numpydoc !! .. py:method:: execute_init_hooks() -> None Run all init hook functions. This is automatically done when running free_all, init or connect_sclang. Hooks can be added using add_init_hook .. !! processed by numpydoc !! .. py:method:: connect_sclang(port: int) -> None Connect sclang to the server This will add the "sclang" receiver and execute the init hooks :Parameters: **port** : int Port of sclang (NetAddr.langPort) .. !! processed by numpydoc !! .. py:method:: add_init_hook(fun: Callable, *args: Any, **kwargs: Any) -> Hook Create and add a hook to be executed when the server is initialized :Parameters: **hook** : Callable[..., None] Function to be executed **args** : Any, optional Arguments given to function **kwargs** : Any, optional Keyword arguments given to function :Returns: Hook The created Hook .. !! processed by numpydoc !! .. py:method:: remove_init_hook(hook: Hook) Remove a previously added init Hook :Parameters: **hook** : Hook the hook to be removed .. !! processed by numpydoc !! .. py:method:: bundler(timetag=0, msg=None, msg_params=None, send_on_exit=True) Generate a Bundler with added server latency. This allows the user to easly add messages/bundles and send it. :Parameters: **timetag** : float Time at which bundle content should be executed. This servers latency will be added upon this. If timetag <= 1e6 it is added to time.time(). **msg_addr** : str SuperCollider address. **msg_params** : list, optional List of parameters to add to message. (Default value = None) :Returns: Bundler bundler for OSC bundling. .. !! processed by numpydoc !! .. py:method:: blip() -> None Make a blip sound .. !! processed by numpydoc !! .. py:method:: remote(address: str, port: int, with_blip: bool = True) -> None Connect to remote Server :Parameters: **address** : str address of remote server **port** : int port of remote server **with_blip** : bool, optional make a sound when initialized, by default True .. !! processed by numpydoc !! .. py:method:: reboot() -> None Reboot this server :Raises: RuntimeError If this server is remote and can't be restarted. .. !! processed by numpydoc !! .. py:method:: ping() :abstractmethod: Ping the server. .. !! processed by numpydoc !! .. py:method:: quit() -> None Quits and tries to kill the server. .. !! processed by numpydoc !! .. py:method:: sync(timeout=5) -> bool Sync the server with the /sync command. :Parameters: **timeout** : int, optional Time in seconds that will be waited for sync. (Default value = 5) :Returns: bool True if sync worked. .. !! processed by numpydoc !! .. py:method:: send_synthdef(synthdef_bytes: bytes) Send a SynthDef as bytes. :Parameters: **synthdef_bytes** : bytes SynthDef bytes **wait** : bool If True wait for server reply. .. !! processed by numpydoc !! .. py:method:: load_synthdef(synthdef_path: str) Load SynthDef file at path. :Parameters: **synthdef_path** : str Path with the SynthDefs **bundle** : bool Wether the OSC Messages can be bundle or not. If True sc3nb will not wait for the server response, by default False .. !! processed by numpydoc !! .. py:method:: load_synthdefs(synthdef_dir: Optional[str] = None, completion_msg: Optional[bytes] = None) -> None Load all SynthDefs from directory. :Parameters: **synthdef_dir** : str, optional directory with SynthDefs, by default sc3nb default SynthDefs **completion_msg** : bytes, optional Message to be executed by the server when loaded, by default None .. !! processed by numpydoc !! .. py:method:: notify(receive_notifications: bool = True, client_id: Optional[int] = None, timeout: float = 1) -> None Notify the server about this client. This provides the client id and max logins info needed for default groups. :Parameters: **receive_notifications** : bool, optional Flag for receiving node notification from server, by default True **client_id** : int, optional Propose a client id, by default None **timeout** : float, optional Timeout for server reply, by default 1.0 :Raises: RuntimeError If server has too many users. OSCCommunicationError If OSC communication fails. .. !! processed by numpydoc !! .. py:method:: free_all(root: bool = True) -> None Free all node ids. :Parameters: **root** : bool, optional If False free only the default group of this client, by default True .. !! processed by numpydoc !! .. py:method:: clear_schedule() Send /clearSched to the server. This clears all scheduled bundles and removes all bundles from the scheduling queue. .. !! processed by numpydoc !! .. py:method:: send_default_groups() -> None Send the default groups for all clients. .. !! processed by numpydoc !! .. py:method:: mute() -> None Mute audio .. !! processed by numpydoc !! .. py:method:: unmute() -> None Set volume back to volume prior to muting .. !! processed by numpydoc !! .. py:method:: version() -> ServerVersion Server version information .. !! processed by numpydoc !! .. py:method:: status() -> ServerStatus Server status information .. !! processed by numpydoc !! .. py:method:: dump_osc(level: int = 1) -> None Enable dumping incoming OSC messages at the server process :Parameters: **level** : int, optional Verbosity code, by default 1 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. .. !! processed by numpydoc !! .. py:method:: dump_tree(controls: bool = True, return_tree=False) -> Optional[str] Server process prints out current nodes :Parameters: **controls** : bool, optional If True include control values, by default True **return_tree** : bool, optional If True return output as string, by default False :Returns: str If return_tree this is the node tree string. .. !! processed by numpydoc !! .. py:method:: query_tree(include_controls: bool = True) -> sc3nb.sc_objects.node.Group Query all nodes at the server and return a NodeTree :Parameters: **include_controls** : bool, optional If True include control values, by default True :Returns: NodeTree object containing all the nodes. .. !! processed by numpydoc !! .. py:method:: _init_osc_communication() .. py:method:: _get_errors_for_address(address: str) .. py:method:: _log_repr() .. py:method:: _log_message(sender, *params) .. py:method:: _warn_fail(sender, *params) .. py:method:: __repr__() -> str .. class:: ServerOptions(udp_port: int = SCSYNTH_DEFAULT_PORT, max_logins: int = 6, num_input_buses: int = 2, num_output_buses: int = 2, num_audio_buses: int = 1024, num_control_buses: int = 4096, num_sample_buffers: int = 1024, publish_rendezvous: bool = False, block_size: Optional[int] = None, hardware_buffer_size: Optional[int] = None, hardware_sample_size: Optional[int] = None, hardware_input_device: Optional[str] = None, hardware_output_device: Optional[str] = None, other_options: Optional[Sequence[str]] = None) Options for the SuperCollider audio server This allows the encapsulation and handling of the command line server options. .. !! processed by numpydoc !! .. py:attribute:: options :value: [] .. py:attribute:: udp_port .. py:attribute:: num_input_buses .. py:attribute:: num_output_buses .. py:attribute:: num_audio_buses .. py:attribute:: num_control_buses .. py:attribute:: num_sample_buffers .. py:attribute:: publish_rendezvous .. py:attribute:: other_options **Overview:** .. autoapisummary:: :nosignatures: sc3nb.ServerOptions.__repr__ .. py:method:: __repr__() .. 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.start sc3nb.SCLang.init sc3nb.SCLang.load_synthdefs sc3nb.SCLang.kill sc3nb.SCLang.__del__ sc3nb.SCLang.__repr__ sc3nb.SCLang.cmd sc3nb.SCLang.cmdv sc3nb.SCLang.cmds sc3nb.SCLang.cmdg sc3nb.SCLang.read sc3nb.SCLang.empty sc3nb.SCLang.get_synth_description sc3nb.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 !! .. class:: Node(*, nodeid: Optional[int] = None, add_action: Optional[Union[AddAction, int]] = None, target: Optional[Union[Node, int]] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) **Bases:** :class:`abc.ABC` Representation of a Node on SuperCollider. Create a new Node :Parameters: **nodeid** : int or None This Nodes node id or None **add_action** : AddAction or corresponding int, optional This Nodes AddAction when created in Server, by default None **target** : Node or int or None, optional This Nodes AddActions target, by default None **server** : SCServer, optional The Server for this Node, by default use the SC default server .. !! processed by numpydoc !! .. py:attribute:: _server .. py:attribute:: _state_lock .. py:attribute:: _free_event .. py:attribute:: _on_free_callback :value: None .. py:attribute:: _started :value: False .. py:attribute:: _freed :value: False .. py:attribute:: _nodeid .. py:attribute:: _group :value: None .. py:attribute:: _target_id .. py:attribute:: _is_playing :value: None .. py:attribute:: _is_running :value: None .. py:attribute:: _current_controls **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Node.new sc3nb.Node._get_status_repr sc3nb.Node._set_node_attrs sc3nb.Node.free sc3nb.Node.run sc3nb.Node.set sc3nb.Node._update_control sc3nb.Node._update_controls sc3nb.Node.fill sc3nb.Node.map sc3nb.Node.release sc3nb.Node.query sc3nb.Node.trace sc3nb.Node.move sc3nb.Node.register sc3nb.Node.unregister sc3nb.Node.on_free sc3nb.Node.wait sc3nb.Node._parse_info sc3nb.Node._handle_notification sc3nb.Node.__eq__ sc3nb.Node._get_nodeid .. py:method:: new(*args, add_action: Optional[Union[AddAction, int]] = None, target: Optional[Union[Node, int]] = None, return_msg: bool = False, **kwargs) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] :abstractmethod: Create a new Node :Parameters: **add_action** : AddAction or int, optional Where the Node should be added, by default AddAction.TO_HEAD (0) **target** : Node or int, optional AddAction target, if None it will be the default group of the server .. !! processed by numpydoc !! .. py:method:: _get_status_repr() -> str .. py:method:: _set_node_attrs(target: Optional[Union[Node, int]] = None, add_action: Optional[Union[AddAction, int]] = None) -> None Derive Node group from addaction and target :Parameters: **target** : int or Node Target nodeid or Target Node of this Node's AddAction **add_action** : AddAction AddAction of this Node, default AddAction.TO_HEAD (0) .. !! processed by numpydoc !! .. py:method:: free(return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Free the node with /n_free. This will set is_running and is_playing to false. Even when the message is returned to mimic the behavior of the SuperCollider Node See https://doc.sccode.org/Classes/Node.html#-freeMsg :Returns: Node or OSCMessage self for chaining or OSCMessage when return_msg=True .. !! processed by numpydoc !! .. py:method:: run(on: bool = True, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Turn node on or off with /n_run. :Parameters: **on** : bool True for on, False for off, by default True :Returns: Node or OSCMessage self for chaining or OSCMessage when return_msg=True .. !! processed by numpydoc !! .. py:method:: set(argument: Union[str, Dict, List], *values: Any, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Set a control value(s) of the node with n_set. :Parameters: **argument** : str | dict | list if string: name of control argument if dict: dict with argument, value pairs if list: use list as message content **value** : any, optional only used if argument is string, by default None .. rubric:: Examples >>> synth.set("freq", 400) >>> synth.set({"dur": 1, "freq": 400}) >>> synth.set(["dur", 1, "freq", 400]) .. !! processed by numpydoc !! .. py:method:: _update_control(control: str, value: Any) -> None .. py:method:: _update_controls(controls: Optional[Dict[str, Any]] = None) -> None .. py:method:: fill(control: Union[str, int], num_controls: int, value: Any, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Fill ranges of control values with n_fill. :Parameters: **control** : int or string control index or name **num_controls** : int number of control values to fill **value** : float or int value to set **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: map(control: Union[str, int], bus: sc3nb.sc_objects.bus.Bus, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Map a node's control to read from a bus using /n_map or /n_mapa. :Parameters: **control** : int or string control index or name **bus** : Bus control/audio bus **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: release(release_time: Optional[float] = None, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Set gate as specified. https://doc.sccode.org/Classes/Node.html#-release :Parameters: **release_time** : float, optional amount of time in seconds during which the node will release. If set to a value <= 0, the synth will release immediately. If None using its Envs normal release stage(s) **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: query() -> Union[SynthInfo, GroupInfo] Sends an n_query message to the server. The answer is send to all clients who have registered via the /notify command. Content of answer: node ID the node's parent group ID previous node ID, -1 if no previous node. next node ID, -1 if no next node. 1 if the node is a group, 0 if it is a synth if the node is a group: ID of the head node, -1 if there is no head node. ID of the tail node, -1 if there is no tail node. :Returns: SynthInfo or GroupInfo n_info answer. See above for content description .. !! processed by numpydoc !! .. py:method:: trace(return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Trace a node. Print out values of the inputs and outputs for one control period. If node is a group then print the node IDs and names of each node. :Parameters: **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: Node or OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: move(add_action: AddAction, another_node: Node, return_msg: bool = False) -> Union[Node, sc3nb.osc.osc_communication.OSCMessage] Move this node :Parameters: **add_action** : AddAction [TO_HEAD, TO_TAIL, AFTER, BEFORE] What add action should be done. **another_node** : Node The node which is the target of the add action **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: Node or OSCMessage if return_msg this will be the OSCMessage, else self :Raises: ValueError If a wrong AddAction was provided .. !! processed by numpydoc !! .. py:method:: register() :abstractmethod: Register to be watched. .. !! processed by numpydoc !! .. py:method:: unregister() :abstractmethod: Unregister to stop being watched. .. !! processed by numpydoc !! .. py:method:: on_free(func) Callback that is executed when this Synth is freed .. !! processed by numpydoc !! .. py:method:: wait(timeout: Optional[float] = None) -> None Wait until this Node is freed :Raises: TimeoutError If timeout was provided and wait timed out. .. !! processed by numpydoc !! .. py:method:: _parse_info(nodeid: int, group: int, prev_nodeid: int, next_nodeid: int, *rest: Sequence[int]) -> Union[SynthInfo, GroupInfo] .. py:method:: _handle_notification(kind: str, info) -> None .. py:method:: __eq__(other) .. py:method:: _get_nodeid(value: Union[Node, int]) -> int :staticmethod: Get the corresponding node id :Parameters: **value** : Node or int If a Node is provided it will get its nodeid If a int is provided it will be returned :Returns: int nodeid :Raises: ValueError When neither Node or int was provided .. !! processed by numpydoc !! .. class:: Synth(name: Optional[str] = None, controls: Dict[str, Any] = None, *, nodeid: Optional[int] = None, new: bool = True, add_action: Optional[Union[AddAction, int]] = None, target: Optional[Union[Node, int]] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) **Bases:** :class:`Node` Representation of a Synth on SuperCollider. Create a Python representation of a SuperCollider synth. :Parameters: **name** : str, optional name of the synth to be created, by default "default" **controls** : dict, optional synth control arguments, by default None **nodeid** : int, optional ID of the node in SuperCollider, by default sc3nb will create one. Can be set to an existing id to create a Python instance of a running Node. **new** : bool, optional True if synth should be created on the server, by default True Should be False if creating an instance of a running Node. **add_action** : AddAction or int, optional Where the Synth should be added, by default AddAction.TO_HEAD (0) **target** : Node or int, optional AddAction target, if None it will be the default group of the server **server** : SCServer sc3nb SCServer instance :Raises: ValueError Raised when synth can't be found via SynthDescLib.global .. rubric:: Examples >>> scn.Synth(sc, "s1", {"dur": 1, "freq": 400}) .. !! processed by numpydoc !! .. py:attribute:: _server .. py:attribute:: _initialized :value: False **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Synth._update_synth_state sc3nb.Synth.new sc3nb.Synth.get sc3nb.Synth.seti sc3nb.Synth.__getattr__ sc3nb.Synth.__setattr__ sc3nb.Synth.__repr__ .. py:method:: _update_synth_state(name: Optional[str], controls: Optional[dict]) .. py:method:: new(controls: Optional[dict] = None, add_action: Optional[Union[AddAction, int]] = None, target: Optional[Union[Node, int]] = None, *, return_msg: bool = False) -> Union[Synth, sc3nb.osc.osc_communication.OSCMessage] Creates the synth on the server with s_new. Attention: Here you create an identical synth! Same nodeID etc. - This will fail if there is already this nodeID on the SuperCollider server! .. !! processed by numpydoc !! .. py:method:: get(control: str) -> Any Get a Synth argument This will request the value from scsynth with /s_get(n). :Parameters: **control** : str name of the Synth control argument .. !! processed by numpydoc !! .. py:method:: seti(*args) :abstractmethod: Set part of an arrayed control. .. !! processed by numpydoc !! .. py:method:: __getattr__(name) .. py:method:: __setattr__(name, value) .. py:method:: __repr__() -> str .. class:: Group(*, nodeid: Optional[int] = None, new: bool = True, parallel: bool = False, add_action: AddAction = AddAction.TO_HEAD, target: Optional[Union[Node, int]] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) **Bases:** :class:`Node` Representation of a Group on SuperCollider. Create a Python representation of a SuperCollider group. :Parameters: **nodeid** : int, optional ID of the node in SuperCollider, by default sc3nb will create one. Can be set to an existing id to create a Python instance of a running Node. **new** : bool, optional True if synth should be created on the server, by default True Should be False if creating an instance of a running Node. **parallel** : bool, optional If True create a parallel group, by default False **add_action** : AddAction or int, optional Where the Group should be added, by default AddAction.TO_HEAD (0) **target** : Node or int, optional AddAction target, if None it will be the default group of the server **server** : SCServer, optional Server instance where this Group is located, by default use the SC default server .. !! processed by numpydoc !! .. py:attribute:: _server **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Group._update_group_state sc3nb.Group.new sc3nb.Group.move_node_to_head sc3nb.Group.move_node_to_tail sc3nb.Group.free_all sc3nb.Group.deep_free sc3nb.Group.dump_tree sc3nb.Group.query_tree sc3nb.Group._repr_pretty_ sc3nb.Group.__repr__ .. py:method:: _update_group_state(children: Optional[Sequence[Node]] = None) -> None .. py:method:: new(add_action=AddAction.TO_HEAD, target=None, *, parallel=None, return_msg=False) -> Union[Group, sc3nb.osc.osc_communication.OSCMessage] Creates the synth on the server with g_new / p_new. Attention: Here you create an identical group! Same nodeID etc. - This will fail if there is already this nodeID on the SuperCollider server! :Parameters: **add_action** : AddAction or int, optional where the group should be added, by default AddAction.TO_HEAD (0) **target** : Node or int, optional add action target, by default 1 **parallel** : bool, optional If True use p_new, by default False **return_msg** : bool, optional If ture return the OSCMessage instead of sending it, by default False :Returns: Group self .. !! processed by numpydoc !! .. py:method:: move_node_to_head(node, return_msg=False) Move node to this groups head with g_head. :Parameters: **node** : Node node to move **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: Group self .. !! processed by numpydoc !! .. py:method:: move_node_to_tail(node, return_msg=False) Move node to this groups tail with g_tail. :Parameters: **node** : Node node to move **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: Group self .. !! processed by numpydoc !! .. py:method:: free_all(return_msg=False) Frees all nodes in the group with g_freeAll. :Parameters: **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: deep_free(return_msg=False) Free all synths in this group and its sub-groups with g_deepFree. Sub-groups are not freed. :Parameters: **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: dump_tree(post_controls=True, return_msg=False) Posts a representation of this group's node subtree with g_dumpTree. :Parameters: **post_controls** : bool, optional True for control values, by default False **return_msg** : bool, optional If True return msg else send it directly, by default False :Returns: OSCMessage if return_msg else self .. !! processed by numpydoc !! .. py:method:: query_tree(include_controls=False) -> Group Send a g_queryTree message for this group. See https://doc.sccode.org/Reference/Server-Command-Reference.html#/g_queryTree for details. :Parameters: **include_controls** : bool, optional True for control values, by default False :Returns: tuple /g_queryTree.reply .. !! processed by numpydoc !! .. py:method:: _repr_pretty_(printer, cylce) .. py:method:: __repr__() -> str .. class:: AddAction(*args, **kwds) **Bases:** :class:`enum.Enum` AddAction of SuperCollider nodes. This Enum contains the codes for the different ways to add a node. .. !! processed by numpydoc !! .. py:attribute:: TO_HEAD :value: 0 .. py:attribute:: TO_TAIL :value: 1 .. py:attribute:: BEFORE :value: 2 .. py:attribute:: AFTER :value: 3 .. py:attribute:: REPLACE :value: 4 .. class:: SynthDef(name: str, definition: str, sc: Optional[sc3nb.sc.SC] = None) Wrapper for SuperCollider SynthDef Create a dynamic synth definition in sc. :Parameters: **name** : string default name of the synthdef creation. The naming convention will be name+int, where int is the amount of already created synths of this definition **definition** : string Pass the default synthdef definition here. Flexible content should be in double brackets ("...{{flexibleContent}}..."). This flexible content, you can dynamic replace with set_context() **sc** : SC object SC instance where the synthdef should be created, by default use the default SC instance .. !! processed by numpydoc !! .. py:attribute:: synth_descs .. py:attribute:: synth_defs .. py:attribute:: sc .. py:attribute:: definition .. py:attribute:: name .. py:attribute:: current_def **Overview:** .. autoapisummary:: :nosignatures: sc3nb.SynthDef.get_description sc3nb.SynthDef.send sc3nb.SynthDef.load sc3nb.SynthDef.load_dir sc3nb.SynthDef.reset sc3nb.SynthDef.set_context sc3nb.SynthDef.set_contexts sc3nb.SynthDef.unset_remaining sc3nb.SynthDef.add sc3nb.SynthDef.free sc3nb.SynthDef.__repr__ .. py:method:: get_description(name: str, lang: Optional[sc3nb.sclang.SCLang] = None) -> Optional[Dict[str, sc3nb.sclang.SynthArgument]] :classmethod: Get Synth description :Parameters: **name** : str name of SynthDef :Returns: Dict dict with SynthArguments .. !! processed by numpydoc !! .. py:method:: send(synthdef_bytes: bytes, server: Optional[sc3nb.sc_objects.server.SCServer] = None) :classmethod: Send a SynthDef as bytes. :Parameters: **synthdef_bytes** : bytes SynthDef bytes **wait** : bool If True wait for server reply. **server** : SCServer, optional Server instance that gets the SynthDefs, by default use the SC default server .. !! processed by numpydoc !! .. py:method:: load(synthdef_path: str, server: Optional[sc3nb.sc_objects.server.SCServer] = None) :classmethod: Load SynthDef file at path. :Parameters: **synthdef_path** : str Path with the SynthDefs **server** : SCServer, optional Server that gets the SynthDefs, by default use the SC default server .. !! processed by numpydoc !! .. py:method:: load_dir(synthdef_dir: Optional[str] = None, completion_msg: Optional[bytes] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) :classmethod: Load all SynthDefs from directory. :Parameters: **synthdef_dir** : str, optional directory with SynthDefs, by default sc3nb default SynthDefs **completion_msg** : bytes, optional Message to be executed by the server when loaded, by default None **server** : SCServer, optional Server that gets the SynthDefs, by default use the SC default server .. !! processed by numpydoc !! .. py:method:: reset() -> SynthDef Reset the current synthdef configuration to the self.definition value. After this you can restart your configuration with the same root definition :Returns: object of type SynthDef the SynthDef object .. !! processed by numpydoc !! .. py:method:: set_context(searchpattern: str, value) -> SynthDef Set context in SynthDef. This method will replace a given key (format: "...{{key}}...") in the synthdef definition with the given value. :Parameters: **searchpattern** : string search pattern in the current_def string **value** : string or something with can parsed to string Replacement of search pattern :Returns: **self** : object of type SynthDef the SynthDef object .. !! processed by numpydoc !! .. py:method:: set_contexts(dictionary: Dict[str, Any]) -> SynthDef Set multiple values at onces when you give a dictionary. Because dictionaries are unsorted, keep in mind, that the order is sometimes ignored in this method. :Parameters: **dictionary** : dict {searchpattern: replacement} :Returns: **self** : object of type SynthDef the SynthDef object .. !! processed by numpydoc !! .. py:method:: unset_remaining() -> SynthDef This method will remove all existing placeholders in the current def. You can use this at the end of definition to make sure, that your definition is clean. Hint: This method will not remove pyvars :Returns: **self** : object of type SynthDef the SynthDef object .. !! processed by numpydoc !! .. py:method:: add(pyvars=None, name: Optional[str] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) -> str This method will add the current_def to SuperCollider.s If a synth with the same definition was already in sc, this method will only return the name. :Parameters: **pyvars** : dict SC pyvars dict, to inject python variables **name** : str, optional name which this SynthDef will get **server** : SCServer, optional Server where this SynthDef will be send to, by default use the SC default server :Returns: str Name of the SynthDef .. !! processed by numpydoc !! .. py:method:: free() -> SynthDef Free this SynthDef from the server. :Returns: **self** : object of type SynthDef the SynthDef object .. !! processed by numpydoc !! .. py:method:: __repr__() .. class:: Buffer(bufnum: Optional[int] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) A Buffer object represents a SuperCollider3 Buffer on scsynth and provides access to low-level buffer commands of scsynth via methods of the Buffer objects. The constructor merely initializes a buffer: * it selects a buffer number using the server's buffer allocator * it initializes attribute variables :Parameters: **bufnum** : int, optional buffer number to be used on scsynth. Defaults to None, can be set to enforce a given bufnum **server** : SCServer, optional The server instance to establish the Buffer, by default use the SC default server :Attributes: **server** : the SCServer object to communicate with scsynth **_bufnum** : int buffer number = bufnum id on scsynth **_sr** : int the sampling rate of the buffer **_channels** : int number of channels of the buffer **_samples** : int buffer length = number of sample frames **_alloc_mode** : str ['file', 'alloc', 'data', 'existing', 'copy'] according to previously used generator, defaults to None **_allocated** : boolean True if Buffer has been allocated by any of the initialization methods **_path** : str path to the audio file used in load_file() .. rubric:: Notes For more information on Buffer commands, refer to the Server Command Reference in SC3. https://doc.sccode.org/Reference/Server-Command-Reference.html#Buffer%20Commands .. rubric:: Examples (see examples/buffer-examples.ipynb) >>> b = Buffer().read(...) >>> b = Buffer().load_data(...) >>> b = Buffer().alloc(...) >>> b = Buffer().load_asig(...) >>> b = Buffer().use_existing(...) >>> b = Buffer().copy(Buffer) .. !! processed by numpydoc !! .. py:attribute:: _server .. py:attribute:: _bufnum_set_manually .. py:attribute:: _bufnum .. py:attribute:: _sr :value: None .. py:attribute:: _channels :value: None .. py:attribute:: _samples :value: None .. py:attribute:: _alloc_mode .. py:attribute:: _allocated :value: False .. py:attribute:: _path :value: None .. py:attribute:: _synth_def :value: None .. py:attribute:: _synth :value: None **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Buffer.read sc3nb.Buffer.alloc sc3nb.Buffer.load_data sc3nb.Buffer.load_collection sc3nb.Buffer.load_asig sc3nb.Buffer.use_existing sc3nb.Buffer.copy_existing sc3nb.Buffer.fill sc3nb.Buffer.gen sc3nb.Buffer.zero sc3nb.Buffer.gen_sine1 sc3nb.Buffer.gen_sine2 sc3nb.Buffer.gen_sine3 sc3nb.Buffer.gen_cheby sc3nb.Buffer.gen_copy sc3nb.Buffer.play sc3nb.Buffer.write sc3nb.Buffer.close sc3nb.Buffer.to_array sc3nb.Buffer.query sc3nb.Buffer.__repr__ sc3nb.Buffer.free sc3nb.Buffer._gen_flags .. py:method:: read(path: str, starting_frame: int = 0, num_frames: int = -1, channels: Optional[Union[int, Sequence[int]]] = None) -> Buffer Allocate buffer memory and read a sound file. If the number of frames argument num_frames is negative or zero, the entire file is read. :Parameters: **path** : string path name of a sound file. **starting_frame** : int starting frame in file **num_frames** : int number of frames to read **channels** : list | int channels and order of channels to be read from file. if only a int is provided it is loaded as only channel :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: alloc(size: int, sr: int = 44100, channels: int = 1) -> Buffer Allocate buffer memory. :Parameters: **size** : int number of frames **sr** : int sampling rate in Hz (optional. default = 44100) **channels** : int number of channels (optional. default = 1 channel) :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: load_data(data: numpy.ndarray, sr: int = 44100, mode: str = 'file', sync: bool = True) -> Buffer Allocate buffer memory and read input data. :Parameters: **data** : numpy array Data which should inserted **sr** : int, default: 44100 sample rate **mode** : 'file' or 'osc' Insert data via filemode ('file') or n_set OSC commands ('osc') Bundling is only supported for 'osc' mode and if sync is False. **sync: bool, default: True** Use SCServer.sync after sending messages when mode = 'osc' :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: load_collection(data: numpy.ndarray, mode: str = 'file', sr: int = 44100) -> Buffer Wrapper method of :func:`Buffer.load_data` .. !! processed by numpydoc !! .. py:method:: load_asig(asig: pya.Asig, mode: str = 'file') -> Buffer Create buffer from asig :Parameters: **asig** : pya.Asig asig to be loaded in buffer **mode** : str, optional Insert data via filemode ('file') or n_set OSC commands ('osc'), by default 'file' :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: use_existing(bufnum: int, sr: int = 44100) -> Buffer Creates a buffer object from already existing Buffer bufnum. :Parameters: **bufnum** : int buffer node id **sr** : int Sample rate :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: copy_existing(buffer: Buffer) -> Buffer Duplicate an existing buffer :Parameters: **buffer** : Buffer object Buffer which should be duplicated :Returns: **self** : Buffer the newly created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: fill(start: int = 0, count: int = 0, value: float = 0) -> Buffer Fill range of samples with value(s). :Parameters: **start** : int or list int : sample starting index list : n*[start, count, value] list **count** : int number of samples to fill **value** : float value :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen(command: str, args: List[Any]) -> Buffer Call a command to fill a buffer. If you know, what you do -> you can use this method. :Parameters: **command** : str What fill command to use. **args** : List[Any] Arguments for command :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. seealso:: :obj:`gen_sine1`, :obj:`gen_sine2`, :obj:`gen_cheby`, :obj:`gen_cheby`, :obj:`gen_copy` .. .. !! processed by numpydoc !! .. py:method:: zero() -> Buffer Set buffer data to zero. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine1(amplitudes: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves & given amplitude :Parameters: **amplitudes** : list The first float value specifies the amplitude of the first partial, the second float value specifies the amplitude of the second partial, and so on. **normalize** : bool Normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, then the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set then the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine2(freq_amps: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves given list of [frequency, amplitude] lists :Parameters: **freq_amps** : list Similar to sine1 except that each partial frequency is specified explicitly instead of being an integer multiple of the fundamental. Non-integer partial frequencies are possible. **normalize** : bool If set, normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set, the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine3(freqs_amps_phases: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves & given a list of [frequency, amplitude, phase] entries. :Parameters: **freqs_amps_phases** : list Similar to sine2 except that each partial may have a nonzero starting phase. **normalize** : bool if set, normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set, the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_cheby(amplitudes: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fills a buffer with a series of chebyshev polynomials, which can be defined as cheby(n) = amplitude * cos(n * acos(x)) :Parameters: **amplitudes** : list The first float value specifies the amplitude for n = 1, the second float value specifies the amplitude for n = 2, and so on **normalize** : bool If set, normalize the peak amplitude of the Buffer to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_copy(source: Buffer, source_pos: int, dest_pos: int, copy_amount: int) -> Buffer Copy samples from the source buffer to the destination buffer specified in the b_gen command. :Parameters: **source** : Buffer Source buffer object **source_pos** : int sample position in source **dest_pos** : int sample position in destination **copy_amount** : int number of samples to copy. If the number of samples to copy is negative, the maximum number of samples possible is copied. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: play(rate: float = 1, loop: bool = False, pan: float = 0, amp: float = 0.3) -> sc3nb.sc_objects.node.Synth Play the Buffer using a Synth :Parameters: **rate** : float, optional plackback rate, by default 1 **loop** : bool, optional if True loop the playback, by default False **pan** : int, optional pan position, -1 is left, +1 is right, by default 0 **amp** : float, optional amplitude, by default 0.3 :Returns: Synth Synth to control playback. :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: write(path: str, header: str = 'wav', sample: str = 'float', num_frames: int = -1, starting_frame: int = 0, leave_open: bool = False) -> Buffer Write buffer data to a sound file :Parameters: **path** : string path name of a sound file. **header** : string header format. Header format is one of: "aiff", "next", "wav", "ircam"", "raw" **sample** : string sample format. Sample format is one of: "int8", "int16", "int24", "int32", "float", "double", "mulaw", "alaw" **num_frames** : int number of frames to write. -1 means all frames. **starting_frame** : int starting frame in buffer **leave_open** : boolean Whether you want the buffer file left open. For use with DiskOut you will want this to be true. The file is created, but no frames are written until the DiskOut UGen does so. The default is false which is the correct value for all other cases. :Returns: **self** : Buffer the Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: close() -> Buffer Close soundfile after using a Buffer with DiskOut :Returns: **self** : Buffer the Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: to_array() -> numpy.ndarray Return the buffer data as an array representation. :Returns: np.ndarray: Values of the buffer :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: query() -> BufferInfo Get buffer info. :Returns: Tuple: (buffer number, number of frames, number of channels, sampling rate) :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: __repr__() -> str .. py:method:: free() -> None Free buffer data. :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: _gen_flags(a_normalize=False, a_wavetable=False, a_clear=False) -> int Generate Wave Fill Commands flags from booleans according to the SuperCollider Server Command Reference. :Parameters: **a_normalize** : bool, optional Normalize peak amplitude of wave to 1.0, by default False **a_wavetable** : bool, optional If set, then the buffer is written in wavetable format so that it can be read by interpolating oscillators, by default False **a_clear** : bool, optional If set then the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer, by default False :Returns: int Wave Fill Commands flags .. !! processed by numpydoc !! .. class:: Bus(rate: Union[BusRate, str], num_channels: int = 1, index: Optional[int] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) Represenation of Control or Audio Bus(es) on the SuperCollider Server If num_channels > 1 this will be represent muliple Buses in a row. :Parameters: **rate** : Union[BusRate, str] Rate of the Bus, either control or audio **num_channels** : int, optional How many channels to allocate, by default 1 **index** : int, optional Starting Bus index this Bus, by default this will be handled by the servers Bus allocator. **server** : SCServer, optional Server instance for this Bus, by default the default SC server instance. .. !! processed by numpydoc !! .. py:attribute:: _server .. py:attribute:: _num_channels .. py:attribute:: _rate **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Bus.is_audio_bus sc3nb.Bus.is_control_bus sc3nb.Bus.set sc3nb.Bus.fill sc3nb.Bus.get sc3nb.Bus.free sc3nb.Bus.__del__ sc3nb.Bus.__repr__ .. py:method:: is_audio_bus() -> bool Rate check :Returns: bool True if this is a audio bus .. !! processed by numpydoc !! .. py:method:: is_control_bus() -> bool Rate check :Returns: bool True if this is a control bus .. !! processed by numpydoc !! .. py:method:: set(*values: Sequence[Union[int, float]], return_msg=False) -> Union[Bus, sc3nb.osc.osc_communication.OSCMessage] Set ranges of bus values. :Parameters: **values** : sequence of int or float Values that should be set **return_msg** : bool, optional If True return msg else send it directly, by default False :Raises: RuntimeError If trying to setn an Audio Bus .. !! processed by numpydoc !! .. py:method:: fill(value: Union[int, float], return_msg=False) -> Union[Bus, sc3nb.osc.osc_communication.OSCMessage] Fill bus(es) to one value. :Parameters: **value** : Union[int, float] value for the buses **return_msg** : bool, optional If True return msg else send it directly, by default False :Raises: RuntimeError If fill is used on a Audio Bus .. !! processed by numpydoc !! .. py:method:: get() -> Union[Union[int, float], Sequence[Union[int, float]]] Get bus value(s). :Returns: bus value or sequence of bus values The current value of this bus Multiple values if this bus has num_channels > 1 :Raises: RuntimeError If get is used on an Audio Bus .. !! processed by numpydoc !! .. py:method:: free(clear: bool = True) -> None Mark this Buses ids as free again :Parameters: **clear** : bool, optional Reset bus value(s) to 0, by default True .. !! processed by numpydoc !! .. py:method:: __del__() -> None .. py:method:: __repr__() -> str .. class:: Score **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Score.load_file sc3nb.Score.write_file sc3nb.Score.record_nrt .. py:method:: load_file(path: Union[str, bytes, os.PathLike]) -> Dict[float, List[sc3nb.osc.osc_communication.OSCMessage]] :classmethod: Load a OSC file into a dict. :Parameters: **path** : Union[str, bytes, os.PathLike] Path of the OSC file. :Returns: Dict[float, List[OSCMessage]] dict with time tag as keys and lists of OSCMessages as values. .. !! processed by numpydoc !! .. py:method:: write_file(messages: Dict[float, List[sc3nb.osc.osc_communication.OSCMessage]], path: Union[str, bytes, os.PathLike], tempo: float = 1) :classmethod: Write this score as binary OSC file for NRT synthesis. :Parameters: **messages** : Dict[float, List[OSCMessage]] Dict with times as key and lists of OSC messages as values **path** : Union[str, bytes, os.PathLike] output path for the binary OSC file **tempo** : float Times will be multiplied by 1/tempo .. !! processed by numpydoc !! .. py:method:: record_nrt(messages: Dict[float, List[sc3nb.osc.osc_communication.OSCMessage]], osc_path: str, out_file: str, in_file: Optional[str] = None, sample_rate: int = 44100, header_format: str = 'AIFF', sample_format: str = 'int16', options: Optional[sc3nb.sc_objects.server.ServerOptions] = None) :classmethod: Write an OSC file from the messages and wri :Parameters: **messages** : Dict[float, List[OSCMessage]] Dict with times as key and lists of OSC messages as values. **osc_path** : str Path of the binary OSC file. **out_file** : str Path of the resulting sound file. **in_file** : Optional[str], optional Path of input soundfile, by default None. **sample_rate** : int, optional sample rate for synthesis, by default 44100. **header_format** : str, optional header format of the output file, by default "AIFF". **sample_format** : str, optional sample format of the output file, by default "int16". **options** : Optional[ServerOptions], optional instance of server options to specify server options, by default None :Returns: subprocess.CompletedProcess Completed scsynth non-realtime process. .. !! processed by numpydoc !! .. class:: Recorder(path: str = 'record.wav', nr_channels: int = 2, rec_header: str = 'wav', rec_format: str = 'int16', bufsize: int = 65536, server: Optional[sc3nb.sc_objects.server.SCServer] = None) Allows to record audio easily. Create and prepare a recorder. :Parameters: **path** : str, optional path of recording file, by default "record.wav" **nr_channels** : int, optional Number of channels, by default 2 **rec_header** : str, optional File format, by default "wav" **rec_format** : str, optional Recording resolution, by default "int16" **bufsize** : int, optional size of buffer, by default 65536 **server** : SCServer, optional server used for recording, by default use the SC default server .. !! processed by numpydoc !! .. py:attribute:: _state .. py:attribute:: _server .. py:attribute:: _record_buffer .. py:attribute:: _record_synth :type: Optional[sc3nb.sc_objects.node.Synth] :value: None **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Recorder.prepare sc3nb.Recorder.start sc3nb.Recorder.pause sc3nb.Recorder.resume sc3nb.Recorder.stop sc3nb.Recorder.__repr__ sc3nb.Recorder.__del__ .. py:method:: prepare(path: str = 'record.wav', nr_channels: int = 2, rec_header: str = 'wav', rec_format: str = 'int16', bufsize: int = 65536) Pepare the recorder. :Parameters: **path** : str, optional path of recording file, by default "record.wav" **nr_channels** : int, optional Number of channels, by default 2 **rec_header** : str, optional File format, by default "wav" **rec_format** : str, optional Recording resolution, by default "int16" **bufsize** : int, optional size of buffer, by default 65536 :Raises: RuntimeError When Recorder does not needs to be prepared. .. !! processed by numpydoc !! .. py:method:: start(timetag: float = 0, duration: Optional[float] = None, node: Union[sc3nb.sc_objects.node.Node, int] = 0, bus: int = 0) Start the recording. :Parameters: **timetag** : float, by default 0 (immediately) Time (or time offset when <1e6) to start **duration** : float, optional Length of the recording, by default until stopped. **node** : Union[Node, int], optional Node that should be recorded, by default 0 **bus** : int, by default 0 Bus that should be recorded :Raises: RuntimeError When trying to start a recording unprepared. .. !! processed by numpydoc !! .. py:method:: pause(timetag: float = 0) Pause the recording. :Parameters: **timetag** : float, by default 0 (immediately) Time (or time offset when <1e6) to pause :Raises: RuntimeError When trying to pause if not recording. .. !! processed by numpydoc !! .. py:method:: resume(timetag: float = 0) Resume the recording :Parameters: **timetag** : float, by default 0 (immediately) Time (or time offset when <1e6) to resume :Raises: RuntimeError When trying to resume if not paused. .. !! processed by numpydoc !! .. py:method:: stop(timetag: float = 0) Stop the recording. :Parameters: **timetag** : float, by default 0 (immediately) Time (or time offset when <1e6) to stop :Raises: RuntimeError When trying to stop if not started. .. !! processed by numpydoc !! .. py:method:: __repr__() -> str .. py:method:: __del__() .. class:: TimedQueue(relative_time: bool = False, thread_sleep_time: float = 0.001, drop_time_threshold: float = 0.5) Accumulates events as timestamps and functions. Executes given functions according to the timestamps :Parameters: **relative_time** : bool, optional If True, use relative time, by default False **thread_sleep_time** : float, optional Sleep time in seconds for worker thread, by default 0.001 **drop_time_threshold** : float, optional Threshold for execution time of events in seconds. If this is exceeded the event will be dropped, by default 0.5 .. !! processed by numpydoc !! .. py:attribute:: drop_time_thr .. py:attribute:: start .. py:attribute:: onset_idx .. py:attribute:: event_list :value: [] .. py:attribute:: close_event .. py:attribute:: lock .. py:attribute:: thread **Overview:** .. autoapisummary:: :nosignatures: sc3nb.TimedQueue.close sc3nb.TimedQueue.join sc3nb.TimedQueue.complete sc3nb.TimedQueue.put sc3nb.TimedQueue.get sc3nb.TimedQueue.peek sc3nb.TimedQueue.empty sc3nb.TimedQueue.pop sc3nb.TimedQueue.__worker sc3nb.TimedQueue.__repr__ sc3nb.TimedQueue.elapse .. py:method:: close() -> None Closes event processing without waiting for pending events .. !! processed by numpydoc !! .. py:method:: join() -> None Closes event processing after waiting for pending events .. !! processed by numpydoc !! .. py:method:: complete() -> None Blocks until all pending events have completed .. !! processed by numpydoc !! .. py:method:: put(timestamp: float, function: Callable[Ellipsis, None], args: Iterable[Any] = (), spawn: bool = False) -> None Adds event to queue :Parameters: **timestamp** : float Time (POSIX) when event should be executed **function** : Callable[..., None] Function to be executed **args** : Iterable[Any], optional Arguments to be passed to function, by default () **spawn** : bool, optional if True, create new sub-thread for function, by default False :Raises: TypeError raised if function is not callable .. !! processed by numpydoc !! .. py:method:: get() -> Event Get latest event from queue and remove event :Returns: Event Latest event .. !! processed by numpydoc !! .. py:method:: peek() -> Event Look up latest event from queue :Returns: Event Latest event .. !! processed by numpydoc !! .. py:method:: empty() -> bool Checks if queue is empty :Returns: bool True if queue if empty .. !! processed by numpydoc !! .. py:method:: pop() -> None Removes latest event from queue .. !! processed by numpydoc !! .. py:method:: __worker(sleep_time: float, close_event: threading.Event) -> NoReturn Worker function to process events .. !! processed by numpydoc !! .. py:method:: __repr__() .. py:method:: elapse(time_delta: float) -> None Add time delta to the current queue time. :Parameters: **time_delta** : float Additional time .. !! processed by numpydoc !! .. class:: TimedQueueSC(server: sc3nb.osc.osc_communication.OSCCommunication = None, relative_time: bool = False, thread_sleep_time: float = 0.001) **Bases:** :class:`TimedQueue` Timed queue with OSC communication. :Parameters: **server** : OSCCommunication, optional OSC server to handle the bundlers and messsages, by default None **relative_time** : bool, optional If True, use relative time, by default False **thread_sleep_time** : float, optional Sleep time in seconds for worker thread, by default 0.001 .. !! processed by numpydoc !! .. py:attribute:: server **Overview:** .. autoapisummary:: :nosignatures: sc3nb.TimedQueueSC.put_bundler sc3nb.TimedQueueSC.put_msg .. py:method:: put_bundler(onset: float, bundler: sc3nb.osc.osc_communication.Bundler) -> None Add a Bundler to queue :Parameters: **onset** : float Sending timetag of the Bundler **bundler** : Bundler Bundler that will be sent .. !! processed by numpydoc !! .. py:method:: put_msg(onset: float, msg: Union[sc3nb.osc.osc_communication.OSCMessage, str], msg_params: Iterable[Any]) -> None Add a message to queue :Parameters: **onset** : float Sending timetag of the message **msg** : Union[OSCMessage, str] OSCMessage or OSC address **msg_params** : Iterable[Any] If msg is str, this will be the parameters of the created OSCMessage .. !! processed by numpydoc !! .. class:: OSCMessage(msg_address: str, msg_parameters: Optional[Union[Sequence, Any]] = None) Class for creating messages to send over OSC :Parameters: **msg_address** : str OSC message address **msg_parameters** : Optional[Union[Sequence]], optional OSC message parameters, by default None .. !! processed by numpydoc !! .. py:attribute:: _content :type: pythonosc.osc_message.OscMessage **Overview:** .. autoapisummary:: :nosignatures: sc3nb.OSCMessage.to_pythonosc sc3nb.OSCMessage._build_message sc3nb.OSCMessage.__repr__ .. py:method:: to_pythonosc() -> pythonosc.osc_message.OscMessage Return python-osc OscMessage .. !! processed by numpydoc !! .. py:method:: _build_message(msg_address: str, msg_parameters: Optional[Union[Sequence, Any]] = None) -> pythonosc.osc_message.OscMessage :staticmethod: Builds pythonsosc OSC message. :Parameters: **msg_address** : str SuperCollider address. **msg_parameters** : list, optional List of parameters to add to message. :Returns: OscMessage Message ready to be sent. .. !! processed by numpydoc !! .. py:method:: __repr__() -> str .. class:: Bundler(timetag: float = 0, msg: Optional[Union[OSCMessage, str]] = None, msg_params: Optional[Sequence[Any]] = None, *, server: Optional[OSCCommunication] = None, receiver: Optional[Union[str, Tuple[str, int]]] = None, send_on_exit: bool = True) Class for creating OSCBundles and bundling of messages Create a Bundler :Parameters: **timetag** : float, optional Starting time at which bundle content should be executed. If timetag > 1e6 it is interpreted as POSIX time. If timetag <= 1e6 it is assumed to be relative value in seconds and is added to time.time(), by default 0, i.e. 'now'. **msg** : OSCMessage or str, optional OSCMessage or message address, by default None **msg_params** : sequence of any type, optional Parameters for the message, by default None **server** : OSCCommunication, optional OSC server, by default None **receiver** : Union[str, Tuple[str, int]], optional Where to send the bundle, by default send to default receiver of server **send_on_exit** : bool, optional Whether the bundle is sent when using as context manager, by default True .. !! processed by numpydoc !! .. py:attribute:: timetag .. py:attribute:: default_receiver .. py:attribute:: contents :type: List[Union[Bundler, OSCMessage]] :value: [] .. py:attribute:: passed_time :value: 0.0 .. py:attribute:: send_on_exit **Overview:** .. autoapisummary:: :nosignatures: sc3nb.Bundler.wait sc3nb.Bundler.add sc3nb.Bundler.messages sc3nb.Bundler.send sc3nb.Bundler.to_raw_osc sc3nb.Bundler.to_pythonosc sc3nb.Bundler._calc_timetag sc3nb.Bundler.__deepcopy__ sc3nb.Bundler.__enter__ sc3nb.Bundler.__exit__ sc3nb.Bundler.__repr__ .. py:method:: wait(time_passed: float) -> None Add time to internal time :Parameters: **time_passed** : float How much seconds should be passed. .. !! processed by numpydoc !! .. py:method:: add(*args) -> Bundler Add content to this Bundler. :Parameters: **args** : accepts an OSCMessage or Bundler or a timetag with an OSCMessage or Bundler or Bundler arguments like (timetag, msg_addr, msg_params) (timetag, msg_addr) (timetag, msg) :Returns: Bundler self for chaining .. !! processed by numpydoc !! .. py:method:: messages(start_time: Optional[float] = 0.0, delay: Optional[float] = None) -> Dict[float, List[OSCMessage]] Generate a dict with all messages in this Bundler. They dict key is the time tag of the messages. :Parameters: **start_time** : Optional[float], optional start time when using relative timing, by default 0.0 :Returns: Dict[float, List[OSCMessage]] dict containg all OSCMessages .. !! processed by numpydoc !! .. py:method:: send(server: Optional[OSCCommunication] = None, receiver: Tuple[str, int] = None, bundle: bool = True) Send this Bundler. :Parameters: **server** : OSCCommunication, optional Server instance for sending the bundle. If None it will use the server from init or try to use sc3nb.SC.get_default().server, by default None **receiver** : Tuple[str, int], optional Address (ip, port) to send to, if None it will send the bundle to the default receiver of the Bundler **bundle** : bool, optional If True this is allowed to be bundled, by default True :Raises: RuntimeError When no server could be found. .. !! processed by numpydoc !! .. py:method:: to_raw_osc(start_time: Optional[float] = None, delay: Optional[float] = None) -> bytes Create a raw OSC Bundle from this bundler. :Parameters: **start_time** : Optional[float], optional used as start time when using relative timing, by default time.time() **delay: float, optinal** used to delay the timing. :Returns: OscBundle bundle instance for sending .. !! processed by numpydoc !! .. py:method:: to_pythonosc(start_time: Optional[float] = None, delay: Optional[float] = None) -> pythonosc.osc_bundle.OscBundle Build this bundle. :Parameters: **start_time** : Optional[float], optional used as start time when using relative timing, by default time.time() **delay: float, optinal** used to delay the timing. :Returns: OscBundle bundle instance for sending .. !! processed by numpydoc !! .. py:method:: _calc_timetag(start_time: Optional[float]) .. py:method:: __deepcopy__(memo) -> Bundler .. py:method:: __enter__() .. py:method:: __exit__(exc_type, exc_value, exc_traceback) .. py:method:: __repr__() -> str Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 2 osc/index.rst resources/index.rst sc_objects/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 magics/index.rst process_handling/index.rst sc/index.rst sclang/index.rst timed_queue/index.rst util/index.rst version/index.rst