Struct Patch 

pub struct Patch { /* private fields */ }

The main patch graph containing modules and connections

Implementations

impl Patch

pub fn new(sample_rate: f64) -> Self

Create a new empty patch

pub fn meta(&self) -> &PatchMeta

Read the patch’s editable metadata (name, author, description, tags).

pub fn meta_mut(&mut self) -> &mut PatchMeta

Mutable access to the patch metadata (see PatchMeta).

pub fn set_meta(&mut self, meta: PatchMeta)

Replace the patch metadata wholesale.

pub fn set_validation_mode(&mut self, mode: ValidationMode)

Set the signal validation mode

pub fn validation_mode(&self) -> ValidationMode

Get the current validation mode

pub fn warnings(&self) -> &[String]

Get all warnings generated during patching

pub fn clear_warnings(&mut self)

Clear all warnings

pub fn sample_rate(&self) -> f64

Get the sample rate

pub fn add<M: GraphModule + 'static>( &mut self, name: impl Into<String>, module: M, ) -> NodeHandle

Add a module to the patch

pub fn add_boxed( &mut self, name: impl Into<String>, module: Box<dyn GraphModule>, ) -> NodeHandle

Add a boxed module to the patch

pub fn remove(&mut self, node: NodeId) -> Result<(), PatchError>

Remove a module from the patch

pub fn connect( &mut self, from: PortRef, to: PortRef, ) -> Result<CableId, PatchError>

Connect an output port to an input port.

Returns a stable CableId that remains valid for disconnect even after other cables are removed.

pub fn connect_attenuated( &mut self, from: PortRef, to: PortRef, attenuation: f64, ) -> Result<CableId, PatchError>

Connect with attenuation (0.0-1.0 range for backwards compatibility)

pub fn connect_modulated( &mut self, from: PortRef, to: PortRef, attenuation: f64, offset: f64, ) -> Result<CableId, PatchError>

Connect with full modulation controls (attenuverter and offset) attenuation: -2.0 to 2.0 (negative inverts, >1.0 amplifies) offset: -10.0 to 10.0V DC offset added after attenuation

pub fn mult( &mut self, from: PortRef, to: &[PortRef], ) -> Result<Vec<CableId>, PatchError>

Connect one output to multiple inputs (mult)

pub fn disconnect(&mut self, cable_id: CableId) -> Result<(), PatchError>

Disconnect a cable by its stable CableId.

Scans for the cable whose id matches (patch cable counts are small), so previously returned ids stay valid regardless of how many other cables have been removed.

pub fn set_output(&mut self, node: NodeId)

Set the output node for the patch (infallible convenience).

Marks the patch dirty so the next tick reflects the new routing. If node is invalid or exposes no output ports, tick simply reads silence; use try_set_output for a validated, fallible alternative.

pub fn output_node(&self) -> Option<NodeId>

The node currently designated as the patch’s stereo output, if any.

pub fn try_set_output(&mut self, node: NodeId) -> Result<(), PatchError>

Set the output node, validating that it exists and exposes at least one output port.

The checked companion to set_output, for callers (e.g. GUIs or loaders) that prefer a Result over silent misrouting.

pub fn set_param(&mut self, node: NodeId, param: ParamId, value: f64)

Set a parameter on a module

pub fn get_param(&self, node: NodeId, param: ParamId) -> Option<f64>

Get a parameter value from a module

pub fn set_position(&mut self, node: NodeId, position: (f32, f32))

Set module position (for UI)

pub fn get_position(&self, node: NodeId) -> Option<(f32, f32)>

Get module position (for UI/serialization)

pub fn get_name(&self, node: NodeId) -> Option<&str>

Get module name

pub fn node_count(&self) -> usize

Get number of nodes

pub fn cable_count(&self) -> usize

Get number of cables

pub fn cables(&self) -> &[Cable]

Get all cables

pub fn execution_order(&self) -> &[NodeId]

Get execution order (after compile)

pub fn compile(&mut self) -> Result<(), PatchError>

Compile the patch into an executable order.

On success clears the dirty flag and any previous compile error. On failure (e.g. an unbroken feedback cycle) the stale schedule and buffers are dropped so a subsequent tick outputs silence, the error is stored (retrievable via last_compile_error), and the same error is returned.

pub fn last_compile_error(&self) -> Option<&PatchError>

The error from the most recent failed compile (auto or explicit), if any.

Cleared by the next successful compile or tick. After tick unexpectedly returns silence, check this to learn why the graph did not compile (e.g. PatchError::CycleDetected).

pub fn tick(&mut self) -> (f64, f64)

Process a single sample, returning stereo output.

Lazy (re)compilation

tick is self-healing. Every structural mutation (add/connect/disconnect/remove/set_output) marks the patch dirty; tick detects this and recompiles automatically before processing, so the output always reflects the current graph — you never have to remember to call compile again after an edit, and a tick before the first compile works too.

If the automatic recompile fails (for example a mutation introduced a feedback cycle with no delay to break it), tick outputs silence (0.0, 0.0) and the error is retained in last_compile_error. A patch with no output node, or an empty graph, likewise ticks to silence.

pub fn tick_block(&mut self, out_left: &mut [f64], out_right: &mut [f64])

Process a block of samples into stereo out_left/out_right slices with no per-frame heap allocation.

This is the allocation-free block entry point (in contrast to the default GraphModule::process_block, which builds a fresh PortValues per frame). It (re)compiles once if needed, then drives the same per-sample engine over n = out_left.len().min(out_right.len()) frames, reusing the preallocated routing buffers across every frame. Full SIMD-vectorized block execution is not performed; the guarantee here is zero allocation, not vectorization.

pub fn reset(&mut self)

Reset all modules in the patch

pub fn nodes(&self) -> impl Iterator<Item = (NodeId, &str, &dyn GraphModule)>

Iterate over all nodes

pub fn get_node_id_by_name(&self, name: &str) -> Option<NodeId>

Get a NodeId by module name

pub fn get_handle_by_name(&self, name: &str) -> Option<NodeHandle>

Get a NodeHandle by module name

pub fn disconnect_ports( &mut self, from: PortRef, to: PortRef, ) -> Result<(), PatchError>

Disconnect a cable by finding matching port refs

pub fn module_names(&self) -> Vec<&str>

Get all module names

pub fn get_output_value(&self, node: NodeId, port: PortId) -> Option<f64>

Get the current output buffer value for a specific port

This is used by the observer to collect real-time values for metering, scope display, and other visualizations.

pub fn get_output_signal_kind( &self, node: NodeId, port: PortId, ) -> Option<SignalKind>

Get the signal kind for an output port by node ID and port ID

impl Patch

Introspection / parameter dispatch for a live patch (alloc tier).

A node’s parameters come from two places, unified here:

• Control-input ports — any non-audio input. Its base (unpatched) value is a knob, overridable per node; the override is applied at compile.
• Internal state — parameters that are not ports (waveform tables, scales, oversample factor, …), reached through the module’s ModuleIntrospection via the introspect hook.

Port parameters take precedence when an id names both, because in a compiled graph the module reads the injected port value, not any mirrored internal field.

pub fn param_infos(&self, node: NodeId) -> Vec<ParamInfo>

Available on crate feature alloc only.

All UI-exposable parameters for a node.

Returns internal-state parameters (from ModuleIntrospection, minus any shadowed by a same-named port) followed by one entry per control-input port with its current effective value. Empty if node is unknown.

pub fn get_param_by_id(&self, node: NodeId, id: &str) -> Option<f64>

Available on crate feature alloc only.

Read a single parameter’s current value by id (port name or internal param id).

pub fn set_param_by_id(&mut self, node: NodeId, id: &str, value: f64) -> bool

Available on crate feature alloc only.

Set a parameter by id. Returns true if the id was recognized.

A control-input port id sets a per-node base-value override (and marks the graph for recompile so the next tick observes it). Otherwise the module’s ModuleIntrospection is asked to set internal state.

pub fn deserialize_module_state( &mut self, node: NodeId, state: &Value, ) -> Result<(), String>

Available on crate feature alloc only.

Restore opaque, non-scalar module state captured by GraphModule::serialize_state (e.g. a ScaleQuantizer custom/Scala tuning table that does not fit the scalar parameter surface). Used by Patch::from_def to reconstruct such state on load.

Returns the module’s own error string if the state is malformed; an unknown node is a no-op (Ok). Internal state, not routing — no recompile is triggered.

impl Patch

Extension methods for Patch to support serialization

pub fn to_def(&self, name: &str) -> PatchDef

Available on crate feature alloc only.

Convert patch to a serializable definition

pub fn from_def( def: &PatchDef, registry: &ModuleRegistry, sample_rate: f64, ) -> Result<Self, PatchError>

Available on crate feature alloc only.

Load a patch from a definition

Trait Implementations

impl Debug for Patch

Manual Debug for Patch so println!("{:?}", patch) works for inspection without requiring GraphModule: Debug. Prints each node’s name and type_id, the cable list, the output node, validation mode, dirty flag, and warning count.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.