Struct Engine 

pub struct Engine { /* private fields */ }

The runtime mixer: owns patch resources and their live instances, and serves their mixed-down stereo through AudioSource::fill.

use tono_core::prelude::*;
use tono_core::dsl::Node;

let doc = SoundDoc::new("blip", Node::Sine { freq: 880.0.into() });
let mut engine = Engine::new(48_000);
let blip = engine.load(&doc);          // a reusable resource…
let _voice = engine.play(blip);        // …spawning independent instances

let mut out = vec![0.0f32; 512];       // interleaved stereo L,R,L,R…
engine.fill(&mut out);
assert!(out.iter().any(|s| s.abs() > 0.0), "the blip is sounding");

Threading

Mutating calls (play, set_param, stop, …) render the whole document synchronously — O(duration), with allocations — so they must never run on an audio callback thread. Real-time hosts use split to render on a pump thread joined to the callback by a wait-free ring. Note that set_param re-renders the whole doc per call with no coalescing — rate-limit parameter automation on the control side.

Implementations

impl Engine

pub fn new(sample_rate: u32) -> Self

A fresh engine that renders at sample_rate.

pub fn set_max_voices(&mut self, max: usize)

Cap the number of concurrently sounding instances. Once at the budget, a new play steals the lowest-Priority sounding instance (declicked, not hard-cut) — or is denied if every instance outranks it. Unset by default (unlimited). A max of 0 is treated as 1.

pub fn max_voices(&self) -> Option<usize>

The current polyphony budget, or None if unlimited.

pub fn sample_rate(&self) -> u32

The engine’s sample rate.

pub fn load(&mut self, doc: &SoundDoc) -> PatchId

Load a bare document as a patch resource (no named parameters).

pub fn load_patch(&mut self, patch: &Patch) -> PatchId

Load a parametric Patch as a resource; its named params become ParamIds via Engine::param.

pub fn param(&self, patch: PatchId, name: &str) -> Option<ParamId>

Resolve a named parameter of a patch to a typed handle (once, off the hot path). None if the patch has no such param.

pub fn layer(&self, patch: PatchId, name: &str) -> Option<LayerId>

Resolve a named mixer layer (a tracks entry) to a typed handle. None if the patch’s graph has no track with that id.

pub fn play(&mut self, patch: PatchId) -> InstanceHandle

Spawn a one-shot instance of a patch (plays once, then culls itself) at Priority::NORMAL.

pub fn play_looping(&mut self, patch: PatchId) -> InstanceHandle

Spawn a looping instance of a patch (plays until stopped) at Priority::NORMAL.

pub fn play_prioritized( &mut self, patch: PatchId, priority: Priority, ) -> InstanceHandle

Spawn a one-shot instance with an explicit Priority. Under a voice cap, a higher priority survives a steal; a voice outranked by every sounding instance is denied (returns an inert handle — is_active is false).

pub fn play_looping_prioritized( &mut self, patch: PatchId, priority: Priority, ) -> InstanceHandle

Spawn a looping instance with an explicit Priority — e.g. music at Priority::CRITICAL so it is never stolen by lower one-shots.

pub fn set_priority(&mut self, h: InstanceHandle, priority: Priority)

Change a live instance’s Priority (no-op for an unknown handle).

pub fn set_gain(&mut self, h: InstanceHandle, gain: f32, tw: Tween)

Set an instance’s linear gain, smoothed over tw (no-op if finished).

pub fn set_pan(&mut self, h: InstanceHandle, pan: f32, tw: Tween)

Set an instance’s stereo balance (−1 left … +1 right), smoothed over tw.

pub fn set_param( &mut self, h: InstanceHandle, param: ParamId, value: f32, tw: Tween, )

Set a named parameter on a live instance, crossfading over tw for a click-free swap. param must come from the same patch the instance plays.

pub fn set_layer_gain( &mut self, h: InstanceHandle, layer: LayerId, gain: f32, tw: Tween, )

Set a named layer’s gain on a live instance, crossfading over tw.

pub fn stop(&mut self, h: InstanceHandle, fade: Tween)

Stop an instance with a declick fade-out; it is culled once silent. A zero-length fade is bumped to a short default so stops never click.

pub fn active(&self) -> usize

Number of live instances.

pub fn is_active(&self, h: InstanceHandle) -> bool

Whether a handle still refers to a live instance.

impl Engine

pub fn split(self, ring_frames: usize) -> (Controller, Renderer)

Split into a Controller (control thread) and a Renderer (audio thread) joined by a wait-free ring ring_frames deep. Pump the controller off the audio thread; the renderer drains it in the callback.

Trait Implementations

impl AudioSource for Engine

fn fill(&mut self, out: &mut [f32]) -> usize

Fill out with the next block of interleaved-stereo audio.

fn reset(&mut self)

Rewind the source to its start (playback position / phase to zero). Defaults to a no-op; a looping source overrides it so a transport can restart it from the top. AdaptiveMusic::reset calls this on each layer.