realtime¶

Tools for interacting with realtime execution contexts.

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

Bases: BaseServer

A realtime execution context with asyncio-based OSC and process protocols.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

async boot(*, options: Options | None = None, **kwargs) → AsyncServer¶

Boot the server.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

async connect(*, options: Options | None = None, **kwargs) → AsyncServer¶

Connect to a running server.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

async disconnect() → AsyncServer¶

Disconnect from a running server.

async get_buffer(buffer: Buffer, *indices: int, sync: bool = True) → Dict[int, float] | None¶

Get a buffer sample.

Emit /b_get requests.

Parameters:

buffer: Buffer¶

The buffer whose sample to get.

*indices: int¶

The sample indices to read.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async get_buffer_range(buffer: Buffer, index: int, count: int, sync: bool = True) → Sequence[float] | None¶

Get a buffer sample range.

Emit /b_getn requests.

Parameters:

buffer: Buffer¶

The buffer whose samples to get.

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.

async get_bus(bus: Bus, sync: bool = True) → float | None¶

Get a control bus value.

Emit /c_get requests.

Parameters:

bus: Bus¶

The control bus whose value to get.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async get_bus_range(bus: Bus, count: int, sync: bool = True) → Sequence[float] | None¶

Get a range of control bus values.

Emit /c_getn requests.

Parameters:

bus: Bus¶

The control bus to start reading at.

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.

async get_synth_control_range(synth: Synth, control: int | str, count: int, sync: bool = True) → Sequence[str | float] | None¶

Get a range of synth controls.

Emit /s_getn requests.

Parameters:

synth: Synth¶

The synth whose control to get.

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.

async get_synth_controls(synth: Synth, *controls: int | str, sync: bool = True) → Dict[int | str, float] | None¶

Get a synth control.

Emit /s_get requests.

Parameters:

synth: Synth¶

The synth whose control to get.

*controls: int | str¶

The controls to get.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async query_buffer(buffer: Buffer, sync: bool = True) → BufferInfo | None¶

Query a buffer.

Emit /b_query requests.

Parameters:

buffer: Buffer¶

The buffer to query.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async query_node(node: Node, sync: bool = True) → NodeInfo | None¶

Query a node.

Emit /n_query requests.

Parameters:

node: Node¶

The node to query.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async query_status(sync: bool = True) → StatusInfo | None¶

Query the server’s status.

Emit /status requests.

Parameters:

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async query_tree(group: Group | None = None, include_controls: bool = True, sync: bool = True) → QueryTreeGroup | QueryTreeSynth | None¶

Query the server’s node tree.

Emit /g_queryTree requests.

Parameters:

group: Group | None = None¶

The group whose tree to query. Defaults to the root node.

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.

async query_version(sync: bool = True) → VersionInfo | None¶

Query the server’s version.

Emit /version requests.

Parameters:

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

async quit(force: bool = False) → AsyncServer¶

Quit the server.

Emit /quit requests.

Parameters:

force: bool = False¶

Force the server to quit, even if this client doesn’t own the process.

async reboot() → AsyncServer¶

Reboot the server.

async reset() → AsyncServer¶

Reset the server’s state without quitting.

async sync(sync_id: int | None = None) → AsyncServer¶

Sync the server.

Emit /sync requests.

Parameters:

sync_id: int | None = None¶

The sync ID to wait on.

class BaseServer(options: Options | None, osc_protocol: OscProtocol, process_protocol: ProcessProtocol, **kwargs)¶

Bases: Context

Base class for realtime execution contexts.

Parameters:

options: Options | None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

__contains__(object_: ContextObject) → bool¶

send(message: SupportsOsc) → None¶

Send a message to the execution context.

Parameters:

message: SupportsOsc¶

The message to send.

set_latency(latency: float) → None¶

Set the context’s latency.

Parameters:

latency: float¶

The latency in seconds.

property boot_status : BootStatus¶

Get the server’s boot status.

property default_group : Group¶

Get the server’s default group.

property is_owner : bool¶

Get the server’s ownership flag.

property osc_protocol : OscProtocol¶

Get the server’s OSC protocol.

property process_protocol : ProcessProtocol¶

Get the server’s process protocol.

property status : StatusInfo | None¶

Get the server’s last received status.

class BootStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

__format__(format_spec, /)¶

Default object formatter.

BOOTING = 1¶

OFFLINE = 0¶

ONLINE = 2¶

QUITTING = 3¶

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

Bases: BaseServer

A realtime execution context with threading-based OSC and process protocols.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

boot(*, options: Options | None = None, **kwargs) → Server¶

Boot the server.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

connect(*, options: Options | None = None, **kwargs) → Server¶

Connect to a running server.

Parameters:

options: Options | None = None¶

The context’s options.

**kwargs¶

Keyword arguments for options.

disconnect() → Server¶

Disconnect from a running server.

get_buffer(buffer: Buffer, *indices: int, sync: bool = True) → Dict[int, float] | None¶

Get a buffer sample.

Emit /b_get requests.

Parameters:

buffer: Buffer¶

The buffer whose sample to get.

*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_buffer_range(buffer: Buffer, index: int, count: int, sync: bool = True) → Sequence[float] | None¶

Get a buffer sample range.

Emit /b_getn requests.

Parameters:

buffer: Buffer¶

The buffer whose samples to get.

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.

get_bus(bus: Bus, sync: bool = True) → float | None¶

Get a control bus value.

Emit /c_get requests.

Parameters:

bus: Bus¶

The control bus whose value to get.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

get_bus_range(bus: Bus, count: int, sync: bool = True) → Sequence[float] | None¶

Get a range of control bus values.

Emit /c_getn requests.

Parameters:

bus: Bus¶

The control bus to start reading at.

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.

get_synth_control_range(synth: Synth, control: int | str, count: int, sync: bool = True) → Sequence[str | float] | None¶

Get a range of synth controls.

Emit /s_getn requests.

Parameters:

synth: Synth¶

The synth whose control to get.

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.

get_synth_controls(synth: Synth, *controls: int | str, sync: bool = True) → Dict[int | str, float] | None¶

Get a synth control.

Emit /s_get requests.

Parameters:

synth: Synth¶

The synth whose control to get.

*controls: int | str¶

The controls to get.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

query_buffer(buffer: Buffer, sync: bool = True) → BufferInfo | None¶

Query a buffer.

Emit /b_query requests.

Parameters:

buffer: Buffer¶

The buffer to query.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

query_node(node: Node, sync: bool = True) → NodeInfo | None¶

Query a node.

Emit /n_query requests.

Parameters:

node: Node¶

The node to query.

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

query_status(sync: bool = True) → StatusInfo | None¶

Query the server’s status.

Emit /status requests.

Parameters:

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

query_tree(group: Group | None = None, include_controls: bool = True, sync: bool = True) → QueryTreeGroup | QueryTreeSynth | None¶

Query the server’s node tree.

Emit /g_queryTree requests.

Parameters:

group: Group | None = None¶

The group whose tree to query. Defaults to the root node.

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.

query_version(sync: bool = True) → VersionInfo | None¶

Query the server’s version.

Emit /version requests.

Parameters:

sync: bool = True¶

If true, communicate the request immediately. Otherwise bundle it with the current request context.

quit(force: bool = False) → Server¶

Quit the server.

Emit /quit requests.

Parameters:

force: bool = False¶

Force the server to quit, even if this client doesn’t own the process.

reboot() → Server¶

Reboot the server.

reset() → Server¶

Reset the server’s state without quitting.

sync(sync_id: int | None = None) → Server¶

Sync the server.

Emit /sync requests.

Parameters:

sync_id: int | None = None¶

The sync ID to wait on.

exception FailWarning¶