entities¶

class Buffer(context: Context, id_: int, completion: Completion | None = None)¶

Bases: ContextObject

A buffer.

Parameters:

context: Context¶: The context object’s context.
id_: int¶: The context object’s context ID.
completion: Completion | None = None¶: The buffer’s allocation completion.

__enter__() → Completion¶: Enter the buffer’s allocation completion.

__exit__(*args) → None¶: Exit the buffer’s allocation completion.

__plot__() → tuple[numpy.ndarray, float]¶

__render_memo__(output_file_path: PathLike | None = None, render_directory_path: PathLike | None = None, **kwargs) → SupportsRender¶

close(on_completion: Callable[[Context], Any] | None = None) → Completion¶

Close the buffer.

Emit /b_close requests.

Parameters:

on_completion: Callable[[Context], Any] | 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(*, target_buffer: Buffer, starting_frame: int, target_starting_frame: int, frame_count: int) → None¶

Copy the buffer.

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

Parameters:

target_buffer: Buffer¶: The buffer to copy to.
starting_frame: int¶: The frame index in the this 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.

fill(starting_frame: int, frame_count: int, value: float) → None¶

Fill the buffer with a single value.

Emit /b_fill requests.

Parameters:

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.

free(on_completion: Callable[[Context], Any] | None = None) → Completion¶

Free the buffer.

Emit /b_free requests.

Parameters:

on_completion: Callable[[Context], Any] | 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.

generate(command_name: '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 the buffer.

Emit /b_gen requests.

Parameters:

command_name: '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.

get(*indices: int, sync: bool = True) → Awaitable[dict[int, float] | None] | dict[int, float] | None¶

Get a sample.

Emit /b_get requests.

Parameters:

*indices: int¶: The sample indices to read.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

get_range(index: int, count: int, sync: bool = True) → Awaitable[Sequence[float] | None] | Sequence[float] | None¶

Get a sample range.

Emit /b_getn requests.

Parameters:

index: int¶: The sample index to start reading at.
count: int¶: The number of samples to read.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

normalize(new_maximum: float = 1.0, as_wavetable: bool = False) → None¶

Normalize the buffer.

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

Parameters:

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

query(sync: bool = True) → Awaitable[BufferInfo | None] | BufferInfo | None¶

Query the buffer.

Emit /b_query requests.

Parameters:

sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

read(file_path: PathLike, *, buffer_starting_frame: int | None = None, channel_indices: list[int] | None = None, frame_count: int | None = None, leave_open: bool = False, on_completion: Callable[[Context], Any] | None = None, starting_frame: int | None = None) → Completion¶

Read a file into the buffer.

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

Parameters:

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], Any] | 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.

set(index: int, value: float) → None¶

Set a sample.

Emit /b_set requests.

Parameters:

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

set_range(index: int, values: Sequence[float]) → None¶

Set a sample range.

Emit /b_setn requests.

Parameters:

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

Write the buffer to disk.

Emit /b_write requests.

Parameters:

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], Any] | 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(on_completion: Callable[[Context], Any] | None = None) → Completion¶

Zero the buffer.

Emit /b_zero requests.

Parameters:

on_completion: Callable[[Context], Any] | 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.

class BufferGroup(context: Context, id_: int, count: int = 1)¶

Bases: ContextObject

A buffer group.

Parameters:

context: Context¶: The buffer group’s context.
id_: int¶: The buffer group’s context ID.
count: int = 1¶: The number of child buffers.

__getitem__(i: int) → Buffer¶
__getitem__(s: slice) → list[Buffer]

__iter__() → Iterator[Buffer]¶

__len__() → int¶

__post_init__() → None¶

free() → None¶

Free the buffer group.

Emit /b_free requests.

class Bus(context: Context, id_: int, calculation_rate: CalculationRate)¶

Bases: ContextObject

A bus.

Parameters:

context: Context¶: The bus’ context.
id_: int¶: The bus’ context ID.
calculation_rate: CalculationRate¶: The bus’ calculation rate.

fill(count: int, value: float, use_shared_memory: bool = False) → None¶

Fill contiguous buses with a single value, starting with this bus.

Emit /c_fill requests.

Parameters:

count: int¶: The number of buses to fill.
value: float¶: The value to fill with.
use_shared_memory: bool = False¶: If true, use the shared memory interface. Skips bundling the request in any open moment.

free() → None¶

Free the bus.

Emit no requests.

get(sync: bool = True, use_shared_memory: bool = False) → Awaitable[float | None] | float | None¶

Get the control bus’ value.

Emit /c_get requests.

Parameters:

sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.
use_shared_memory: bool = False¶: If true and sync=True, use the shared memory interface.

get_range(count: int, sync: bool = True, use_shared_memory: bool = False) → Awaitable[Sequence[float] | None] | Sequence[float] | None¶

Get a range of control bus values.

Emit /c_getn requests.

Parameters:

count: int¶: The number of contiguous buses whose values to get.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.
use_shared_memory: bool = False¶: If true and sync=True, use the shared memory interface.

map_symbol() → str¶: Get the bus’ map symbol.

set(value: float, use_shared_memory: bool = False) → None¶

Set the control bus’s value.

Emit /c_set requests.

Parameters:

value: float¶: The value to set the control bus to.
use_shared_memory: bool = False¶: If true, use the shared memory interface. Skips bundling the request in any open moment.

set_range(values: Sequence[float], use_shared_memory: bool = False) → None¶

Set a range of control buses.

Emit /c_setn requests.

Parameters:

values: Sequence[float]¶: The values to write.
use_shared_memory: bool = False¶: If true, use the shared memory interface. Skips bundling the request in any open moment.

class BusGroup(context: Context, id_: int, calculation_rate: CalculationRate, count: int = 1)¶

Bases: ContextObject

A bus group.

Parameters:

context: Context¶: The bus group’s context.
id_: int¶: The bus group’s context ID.
calculation_rate: CalculationRate¶: The bus group’s calculation rate.
count: int = 1¶: The number of child buses.

__getitem__(i: int) → Bus¶
__getitem__(s: slice) → list[Bus]

__iter__() → Iterator[Bus]¶

__len__() → int¶

__post_init__() → None¶

free() → None¶

Free the bus group.

Emit no requests.

get(sync: bool = True, use_shared_memory: bool = False) → Awaitable[Sequence[float] | None] | Sequence[float] | None¶

Get the control bus group’s values.

Emit /c_getn requests.

Parameters:

sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

map_symbol() → str¶: Get the bus group’s map symbol.

set(values: float | Sequence[float], use_shared_memory: bool = False) → None¶

Set a range of control buses.

Emit /c_setn or /c_fill requests.

Parameters:

values: float | Sequence[float]¶: The values to write. If a float is passed, use that as a fill.
use_shared_memory: bool = False¶: If true, use the shared memory interface. Skips bundling the request in any open moment.

class ContextObject(context: Context, id_: int)¶

Bases: object

Base class for objects with context references.

Parameters:

context: Context¶: The context object’s context.
id_: int¶: The context object’s context ID.

__float__() → float¶: Get the context object’s ID as a float.

__int__() → int¶: Get the context object’s ID as an integer.

property allocated : bool¶: Get the context object’s allocation status.

class Group(context: Context, id_: int, parallel: bool = False)¶

Bases: Node

A group node.

Parameters:

context: Context¶: The group’s context.
id_: int¶: The group’s context ID.
parallel: bool = False¶: Flag for parallel vs non-parallel groups.

dump_tree(include_controls: bool = True, sync: bool = True) → Awaitable[QueryTreeGroup | None] | QueryTreeGroup | None¶

Dump the group’s node tree.

Emit /g_dumpTree requests.

Parameters:

include_controls: bool = True¶: Flag for including synth control values.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

free_children(synths_only: bool = False) → None¶

Free the group’s children.

Emit /g_deepFree or /g_freeAll requests depending on parameters.

Parameters:

synths_only: bool = False¶: Flag for freeing only child synths, or all children.

query_tree(include_controls: bool = True, sync: bool = True) → Awaitable[QueryTreeGroup | None] | QueryTreeGroup | None¶

Query the group’s node tree.

Emit /g_queryTree requests.

Parameters:

include_controls: bool = True¶: Flag for including synth control values.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

property children : list[Node]¶: Get the group’s children, as currently cached on the context.

class Node(context: Context, id_: int)¶

Bases: ContextObject

A node.

Parameters:

context: Context¶: The node’s context.
id_: int¶: The node’s context ID.

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

Add a new group relative to this node.

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.
parallel: bool = False¶: Flag for parallel vs non-parallel groups.
permanent: bool = False¶: Flag for using a permanent node ID.

Add a new synth relative to this node.

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.
permanent: bool = False¶: Flag for using a permanent node ID.
**settings: SupportsFloat | str | Sequence[SupportsFloat | str]¶: The new synth’s control settings.

free(force: bool = False) → None¶

Free the 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:

force: bool = False¶: Flag for force-freeing, without releasing.

map(**settings: Bus | str | None) → None¶

Map the node’s controls to buses.

Emit /n_map and /n_mapa requests.

Parameters:

**settings: Bus | str | None¶: A mapping of control names to buses (or to None to unmap the control).

move(target_node: Node, add_action: AddAction | SupportsInt | str | None = None) → None¶

Move the node.

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

Parameters:

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

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

Re-order nodes relative to the node.

Emit /n_order requests.

Parameters:

*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() → None¶

Pause the node.

Emit /n_run <node.id_> 0 requests.

query(sync: bool = True) → Awaitable[NodeInfo | None] | NodeInfo | None¶

Query the node.

Emit /n_query requests.

Parameters:

sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

set(*indexed_settings: tuple[int, SupportsFloat | Sequence[SupportsFloat]], **settings: SupportsFloat | Sequence[SupportsFloat]) → None¶

Set the node’s controls.

Parameters:

*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_range(*indexed_settings: tuple[int, Sequence[SupportsFloat]], **settings: Sequence[SupportsFloat]) → None¶

Set a range of the node’s controls.

Parameters:

*indexed_settings: tuple[int, Sequence[SupportsFloat]]¶: A sequence of control indices to values.
**settings: Sequence[SupportsFloat]¶: A mapping of control names to values.

trace() → Awaitable[None] | None¶

Trace the node

Emit /n_trace requests.

unpause() → None¶

Unpause the node.

Emit /n_run <node.id_> 1 requests.

property active : bool¶: Get the node’s paused/unpaused status.

property parent : Group | None¶: Get the node’s parent, as currently cached on the context.

property parentage : Sequence[Node]¶: Get the node’s parentage, as currently cached on the context.

class RootNode(context: Context, id_: int, parallel: bool = False)¶

Bases: Group

A root node.

Parameters:

context: Context¶: The root node’s context.

__post_init__() → None¶: Force id_ to 0, and parallel to False.

class ScopeBuffer(context: Context, id_: int)¶

Bases: ContextObject

A scope buffer.

For use with the ScopeOut2 UGen for powering shared-memory scopes and spectrograms.

Parameters:

context: Context¶: The context object’s context.
id_: int¶: The context object’s context ID.

free() → None¶

Free the buffer group.

Emit /b_free requests.

class Synth(context: Context, id_: int, synthdef: SynthDef)¶

Bases: Node

A synth node.

Parameters:

context: Context¶: The synth’s context.
id_: int¶: The synth’s context ID.
synthdef: SynthDef¶: The synth’s SynthDef.

Get a control.

Emit /s_get requests.

Parameters:

*controls: int | str¶: The control to get.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.

Get a range of controls.

Emit /s_get requests.

Parameters:

control: int | str¶: The control to start reading at.
count: int¶: The number of contiguous controls to get.
sync: bool = True¶: If true, communicate the request immediately. Otherwise bundle it with the current request context.