core¶

Core interfaces for interfacting with scsynth-compatible execution contexts.

Context subclasses expose a common interface for realtime and non-realtime synthesis.

class Completion(context: Context, moment: Moment)¶

Bases: object

A context manager for collecting requests to be made “on completion” of another request.

Multiple requests made inside a completion are bundled together.

Parameters:

context: Context¶: The completion’s context.
moment: Moment¶: The completion’s moment.

__call__(request: Request) → Request¶

Bundle this completion’s collected requests into the on_completion argument of the request.

Parameters:

request: Request¶: The request to complete.

__enter__() → Completion¶: Set this completion as the current “request context”.

__exit__(*args) → None¶: Unset this completion as the current “request context”.

class Context(options: Options | None, **kwargs)¶

Bases: object

A synthesis execution context.

Parameters:

options: Options | None¶: The context’s options.
**kwargs¶: Keyword arguments for options.

Add a new buffer to the context.

Emit /b_alloc, /b_allocRead or /b_allocReadChannel requests depending on parameters.

Parameters:

channel_count: int | None = None¶: The channel count of the new buffer. Cannot be used when reading from file paths.
channel_indices: List[int] | None = None¶: The channels to read from a file when reading from a file.
file_path: PathLike | None = None¶: The (optional) file to read from.
frame_count: int | None = None¶: The frame count of the new buffer.
starting_frame: int | None = None¶: The frame to start reading from when reading from a file.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

add_buffer_group(*, channel_count: int | None = None, count: int = 1, frame_count: int | None = None) → BufferGroup¶

Add a group of new buffers to the context.

Emit /b_alloc requests.

Parameters:

channel_count: int | None = None¶: The channel count of the new buffers.
count: int = 1¶: The number of buffers to add.
frame_count: int | None = None¶: The frame count of the new buffers.

add_bus(calculation_rate: CalculationRate | SupportsInt | str | None = CalculationRate.CONTROL) → Bus¶

Add a new bus to the context.

Emit no requests.

Parameters:

calculation_rate: CalculationRate | SupportsInt | str | None = CalculationRate.CONTROL¶: The calculation rate of the new bus.

add_bus_group(calculation_rate: CalculationRate | SupportsInt | str | None = CalculationRate.CONTROL, count: int = 1) → BusGroup¶

Add a group of new buses to the context.

Emit no requests.

Parameters:

calculation_rate: CalculationRate | SupportsInt | str | None = CalculationRate.CONTROL¶: The calculation rate of the new bus.
count: int = 1¶: The number of buses to add.

add_group(*, add_action: AddAction | SupportsInt | str | None = AddAction.ADD_TO_HEAD, target_node: SupportsInt | None = None, parallel: bool = False, permanent: bool = False) → Group¶

Add a new group node to the context.

Emit /g_new or /p_new requests depending on parameters.

Parameters:

add_action: AddAction | SupportsInt | str | None = AddAction.ADD_TO_HEAD¶: The add action to use when placing the new group.
target_node: SupportsInt | None = None¶: The node to place the new group relative to.
parallel: bool = False¶: Flag for parallel vs non-parallel groups.
permanent: bool = False¶: Flag for using a permanent node ID.

add_synth(synthdef: SynthDef, *, add_action: AddAction | SupportsInt | str | None = AddAction.ADD_TO_HEAD, target_node: SupportsInt | None = None, permanent: bool = False, **settings) → Synth¶

Add a new synth node to the context.

Emit /s_new requests.

Parameters:

synthdef: SynthDef¶: The SynthDef to use for the new synth.
add_action: AddAction | SupportsInt | str | None = AddAction.ADD_TO_HEAD¶: The add action to use when placing the new synth.
target_node: SupportsInt | None = None¶: The node to place the new synth relative to.
permanent: bool = False¶: Flag for using a permanent node ID.
**settings¶: The new synth’s control settings.

add_synthdefs(*synthdefs: SynthDef, on_completion: Callable[[Context], None] | None = None) → Completion¶

Add one or more SynthDefs to the context.

Emit /d_recv requests.

Parameters:

*synthdefs: SynthDef¶: The synthdefs to add.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

at(seconds=None) → Moment¶

Create a Moment.

Parameters:

seconds=None¶: The timestamp of the new moment.

clear_schedule() → None¶

Clear all scheduled bundles.

Emit /clearSched requests.

close_buffer(buffer: Buffer, on_completion: Callable[[Context], None] | None = None) → Completion¶

Close a buffer.

Emit /b_close requests.

Parameters:

buffer: Buffer¶: The buffer to close.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

copy_buffer(*, source_buffer: Buffer, target_buffer: Buffer, source_starting_frame: int, target_starting_frame: int, frame_count: int)¶

Copy a buffer.

Emit /b_gen <buffer.id_> copy ... requests.

Parameters:

source_buffer: Buffer¶: The buffer to copy from.
target_buffer: Buffer¶: The buffer to copy to.
source_starting_frame: int¶: The frame index in the source buffer to start reading from.
target_starting_frame: int¶: The frame index in the target buffer to start writing at.
frame_count: int¶: The number of frames to copy.

do_nothing()¶: Emit a no-op “nothing” command.

fill_buffer(buffer: Buffer, starting_frame: int, frame_count: int, value: float) → None¶

Fill a buffer with a single value.

Emit /b_fill requests.

Parameters:

buffer: Buffer¶: The buffer to fill.
starting_frame: int¶: The frame index to start filling at.
frame_count: int¶: The number of frames to fill.
value: float¶: The value to fill with.

fill_bus_range(bus: Bus, count: int, value: float) → None¶

Fill a contiguous range of buses with a single value.

Emit /c_fill requests.

Parameters:

count: int¶: The number of buses to fill.
value: float¶: The value to fill with.

free_all_synthdefs() → None¶

Free all SynthDefs.

Emit /d_freeAll requests.

free_buffer(buffer: Buffer, on_completion: Callable[[Context], None] | None = None) → Completion¶

Free a buffer.

Emit /b_free requests.

Note

Freeing the first buffer of a buffer group will free the IDs of all buffers in the group, but will only issue a /b_free request for the first buffer.

Parameters:

buffer: Buffer¶: The buffer to free.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

free_buffer_group(buffer_group: BufferGroup) → None¶

Free a buffer grop.

Emit /b_free requests.

Parameters:

buffer_group: BufferGroup¶: The buffer group to free.

free_bus(bus: Bus) → None¶

Free a bus.

Emit no requests.

Note

Freeing the first bus of a bus group will free the IDs of the entire group.

Parameters:

bus: Bus¶: The bus to free.

free_bus_group(bus_group: BusGroup) → None¶

Free a bus group.

Emit no requests.

Parameters:

bus_group: BusGroup¶: The bus group to free.

free_group_children(group: Group, synths_only: bool = False) → None¶

Free a group’s children.

Emit /g_deepFree or /g_freeAll requests depending on parameters.

Parameters:

group: Group¶: The group whose children will be freed.
synths_only: bool = False¶: Flag for freeing only child synths, or all children.

free_node(node: Node, force: bool = False) → None¶

Free a node.

Emit /n_free for groups, for synths without a gate control, or when force is True.

Emit /n_set <node.id_> gate 0 for synths with gate controls.

Parameters:

node: Node¶: The node to free.
force: bool = False¶: Flag for force-freeing, without releasing.

free_synthdefs(*synthdefs: SynthDef) → None¶

Free one or more SynthDefs.

Emit /d_free requests.

Parameters:

*synthdefs: SynthDef¶: The synthdefs to free.

generate_buffer(buffer: Buffer, command_name: Literal['sine1', 'sine2', 'sine3', 'cheby'], amplitudes: Sequence[float], frequencies: Sequence[float] | None = None, phases: Sequence[float] | None = None, as_wavetable: bool = False, should_clear_first: bool = False, should_normalize: bool = False) → None¶

Generate a buffer.

Emit /b_gen requests.

Parameters:

buffer: Buffer¶: The buffer to generate.
command_name: Literal['sine1', 'sine2', 'sine3', 'cheby']¶: The generation command name.
amplitudes: Sequence[float]¶: A sequence of partial amplitudes.
frequencies: Sequence[float] | None = None¶: A sequence of partial frequencies.
phases: Sequence[float] | None = None¶: A sequence of partial phases.
as_wavetable: bool = False¶: Flag for generating the output in wavetable format.
should_clear_first: bool = False¶: Flag for clearing the buffer before generating.
should_normalize: bool = False¶: Flag for normalizing the generated output.

load_synthdefs(path: PathLike, on_completion: Callable[[Context], None] | None = None) → Completion¶

Load SynthDefs from a path.

Emit /d_load requests.

Warning

At the time of this writing, supernova does not support globbing.

Parameters:

path: PathLike¶: The file path to load from. Globbing characters (e.g. *) are permitted.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

load_synthdefs_directory(path: PathLike, on_completion: Callable[[Context], None] | None = None) → Completion¶

Load all SynthDefs from a directory.

Emit /d_loadDir requests.

Parameters:

path: PathLike¶: The directory path to load from.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

map_node(node: Node, **settings: Bus | None) → None¶

Map a node’s controls to buses.

Emit /n_map and /n_mapa requests.

Parameters:

node: Node¶: The node whose controls will be mapped.
**settings: Bus | None¶: A mapping of control names to buses (or to None to unmap the control).

move_node(node: Node, add_action: AddAction | SupportsInt | str | None, target_node: Node) → None¶

Move a node.

Emit /n_after, /n_before, /g_head and /g_tail requests depending on parameters.

Parameters:

node: Node¶: The node to move.
add_action: AddAction | SupportsInt | str | None¶: The add action to use when moving the node.
target_node: Node¶: The target node to place the node relative to.

normalize_buffer(buffer: Buffer, new_maximum: float = 1.0, as_wavetable: bool = False) → None¶

Normalize a buffer.

Emit /b_gen <buffer.id_> (w)?normalize requests depending on parameters.

Parameters:

buffer: Buffer¶: The buffer to normalize.
new_maximum: float = 1.0¶: The new maximum to normalize to.
as_wavetable: bool = False¶: Flag for treating the buffer contents as a wavetable.

order_nodes(target_node: Node, *nodes: Node, add_action: AddAction | SupportsInt | str | None = None) → None¶

Re-order nodes.

Emit /n_order requests.

Parameters:

target_node: Node¶: The node to re-order the other nodes relative to.
*nodes: Node¶: The nodes to re-order.
add_action: AddAction | SupportsInt | str | None = None¶: The add action to use when re-ordering the nodes.

pause_node(node: Node) → None¶

Pause a node.

Emit /n_run <node.id_> 0 requests.

Parameters:

node: Node¶: The node to pause.

read_buffer(buffer: Buffer, file_path: PathLike, *, buffer_starting_frame: int | None = None, channel_indices: List[int] | None = None, frame_count: int | None = None, leave_open: bool = False, starting_frame: int | None = None, on_completion: Callable[[Context], None] | None = None) → Completion¶

Read a file into a buffer.

Emit /b_read or /b_readChannel requests, depending on parameters.

Parameters:

buffer: Buffer¶: The buffer to read into.
file_path: PathLike¶: The file path to read from.
channel_indices: List[int] | None = None¶: A list of channel indices to read from when reading from a file.
frame_count: int | None = None¶: The number of frames to read.
leave_open: bool = False¶: Flag for leaving the file open (e.g. to continue reading via DiskIn) or close it.
starting_frame: int | None = None¶: The starting frame in the buffer to begin reading into at.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

abstract send(message: SupportsOsc)¶

Send a message to the execution context.

Parameters:

message: SupportsOsc¶: The message to send.

set_buffer(buffer: Buffer, index: int, value: float) → None¶

Set a buffer sample.

Emit /b_set requests.

Parameters:

buffer: Buffer¶: The buffer to modify.
index: int¶: The sample index to write at.
value: float¶: The value to write.

set_buffer_range(buffer: Buffer, index: int, values: Sequence[float]) → None¶

Set a buffer sample range.

Emit /b_setn requests.

Parameters:

buffer: Buffer¶: The buffer to modify.
index: int¶: The sample index to start writing at.
values: Sequence[float]¶: The values to write.

set_bus(bus: Bus, value: float) → None¶

Set a control bus to a value.

Emit /c_set requests.

Parameters:

bus: Bus¶: The control bus to set.
value: float¶: The value to set the control bus to.

set_bus_range(bus: Bus, values: Sequence[float]) → None¶

Set a range of control buses.

Emit /c_setn requests.

Parameters:

bus: Bus¶: The bus to start writing at.
values: Sequence[float]¶: The values to write.

set_node(node: Node, *indexed_settings: Tuple[int, SupportsFloat | Sequence[SupportsFloat]], **settings: SupportsFloat | Sequence[SupportsFloat]) → None¶

Set a node’s controls.

Emit /n_set requests.

Parameters:

node: Node¶: The node whose controls will be set.
*indexed_settings: Tuple[int, SupportsFloat | Sequence[SupportsFloat]]¶: A sequence of control indices to values.
**settings: SupportsFloat | Sequence[SupportsFloat]¶: A mapping of control names to values.

set_node_range(node: Node, *indexed_settings: Tuple[int, Sequence[SupportsFloat]], **settings: Sequence[SupportsFloat]) → None¶

Set a range of node controls.

Emit /n_setn requests.

Parameters:

node: Node¶: The node whose controls will be set.
*indexed_settings: Tuple[int, Sequence[SupportsFloat]]¶: A sequence of control indices to values.
**settings: Sequence[SupportsFloat]¶: A mapping of control names to values.

unpause_node(node: Node) → None¶

Unpause a node.

Emit /n_run <node.id_> 1 requests.

Parameters:

node: Node¶: The node to unpause.

Write a buffer to disk.

Emit /b_write requests.

Parameters:

buffer: Buffer¶: The buffer to write to disk.
file_path: PathLike¶: The file path to write into.
frame_count: int | None = None¶: The number of frames to write.
header_format: HeaderFormat | SupportsInt | str | None = 'aiff'¶: The header format to use, e.g. AIFF or WAVE.
leave_open: bool = False¶: Flag for leaving the file open (e.g. to continue writing via DiskOut) or close it.
sample_format: SampleFormat | SupportsInt | str | None = 'int24'¶: The sample format to use, e.g. INT24 or FLOAT.
starting_frame: int | None = None¶: The starting frame in the buffer to start writing from.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

zero_buffer(buffer: Buffer, on_completion: Callable[[Context], None] | None = None) → Completion¶

Set a buffer’s contents to zero.

Emit /b_zero requests.

Parameters:

buffer: Buffer¶: The buffer to zero.
on_completion: Callable[[Context], None] | None = None¶: A callable with the buffer’s context as the only argument. Permits building an “on completion” argument to this method’s request without an active moment.

property audio_input_bus_group : BusGroup¶: Get the context’s audio output buses.

property audio_output_bus_group : BusGroup¶: Get the context’s audio input buses.

property client_id : int¶: Get the context’s client ID.

property latency : float¶: Get the context’s latency.

property options : Options¶: Get the context’s scsynth options.

property root_node : RootNode¶: Get the context’s root node.

class Moment(context: Context, seconds: float | None = None)¶

Bases: object

A context manager representing a moment in time when requests are made to an execution context.

Multiple requests made inside a moment are bundled together.

Parameters:

context: Context¶: The moment’s context.
seconds: float | None = None¶: The moment’s timestamp.

__enter__() → Moment¶: Set this moment the current “request context”.

__exit__(*args) → None¶: Unset this moment as the current “request context”.