Skip to content

Options & Embedded Engine

nanosynth.scsynth

Embedded SuperCollider synthesis engine lifecycle management.

BootStatus

Bases: IntEnum

State machine for the embedded engine lifecycle.

Options dataclass

SuperCollider server options configuration.

All fields have sensible defaults. The most commonly adjusted options:

  • verbosity -- log level (0 = silent, default).
  • sample_rate -- preferred sample rate (None = use hardware default).
  • output_bus_channel_count / input_bus_channel_count -- number of hardware I/O channels.
  • memory_size -- real-time memory pool in KB (default 8192).
  • block_size -- control block size in samples (default 64).
  • ugen_plugins_path -- override UGen plugin search path (normally auto-detected from the installed wheel or SC_PLUGIN_PATH).

EmbeddedProcessProtocol

Process protocol that runs scsynth in-process via libscsynth.

boot 

boot(options: Options) -> None

Boot the embedded scsynth engine with the given options.

Creates a World via libscsynth, opens a UDP port for OSC communication, installs print and reply callbacks, and starts a daemon thread that waits for engine shutdown.

Raises: ServerCannotBoot: If a World is already active, or if World_New or World_OpenUDP fails.

send_packet 

send_packet(data: bytes) -> bool

Send a raw OSC packet to the engine.

send_msg 

send_msg(address: str | int, *args: OscArgument) -> bool

Send an OSC message to the engine.

set_reply_callback 

set_reply_callback(
    callback: Callable[[bytes], None] | None,
) -> None

Set (or clear) the callback for OSC replies from the engine.

If the engine is already booted, the callback is installed immediately. Otherwise it will be installed on the next boot.

Args: callback: A callable receiving raw OSC bytes, or None to clear.

buffer_info 

buffer_info(buffer_id: int) -> tuple[int, int, float]

Return (frames, channels, sample_rate) for a buffer.

buffer_get 

buffer_get(buffer_id: int) -> Any

Copy a buffer's samples into a (frames, channels) float32 array.

buffer_set 

buffer_set(buffer_id: int, data: Any) -> None

Copy a (frames, channels) float32 array into a buffer.

quit 

quit() -> None

Shut down the embedded scsynth engine.

No-op if the engine is not currently online. Blocks until the engine thread has joined (up to 5 seconds, then force-cleanup).

find_ugen_plugins_path 

find_ugen_plugins_path() -> Path | None

Find the UGen plugins directory for the embedded scsynth.

Searches: 1. The SC_PLUGIN_PATH environment variable. 2. Bundled plugins (installed in wheel alongside this package). 3. Common SuperCollider installation plugin directories.