Struct Synth 

pub struct Synth { /* private fields */ }

Incremental, allocation-free rendering of a Score or FrameScore into mono or stereo frames.

All memory is allocated by the constructors, including Synth::from_frames. Synth::fill allocates nothing, takes no lock and does not block, so it can run on an audio thread. The samples do not depend on how the output is split into chunks, and are identical on every platform: pitch and vibrato use the crate’s own polynomials, not sin or exp.

At the song’s end it continues from the loop point while loops remain. A note that sounds across the loop point restarts there on every repeat. After the last pass it renders the release of the sounding notes, then finishes.

Implementations

impl Synth

pub fn new( score: &Score, sample_rate: u32, options: &RenderOptions, ) -> Result<Self>

pub fn new_stereo( score: &Score, sample_rate: u32, options: &RenderOptions, ) -> Result<Self>

Builds a stereo renderer, with interleaved output through fill and the mixer’s Stream adapter. Preparation may allocate; fill/reset do not.

pub fn from_frames( score: &FrameScore, map: &TempoMap, options: &RenderOptions, ) -> Result<Self>

Prepare absolute note frames for mono output, using existing instruments and allocation-free fill. Unlike Score, the map supports fractional and changing tempo. Preparation is bounded to 8 tracks, 256 instruments, 200000 notes and a 1200-second body. Map changes must be within that body.

Notes require on < off <= end_frame, ordered onsets, a valid instrument, volume 0..=15 and velocity 0..=127. Invalid arguments return InvalidArgument, resource limits LimitExceeded. Expand repetitions before preparation; options.loops must be Some(0) on this path.

At each frame, onsets run first in track/input order, followed by gate-offs on the remaining held voices, as on Score. Single-voice replacement and pooled stealing retain their semantics. A tie is one extended FrameNote; it preserves oscillator/envelope/filter state across tempo boundaries.

Beat LFO phase integrates scheduled tempos continuously from frame zero; tick macros integrate it relative to note start. Other clocks retain their original units. Release tails drain after the exclusive body end; no leading latency, post-render retiming or automatic limiting is added.

pub fn from_frames_stereo( score: &FrameScore, map: &TempoMap, options: &RenderOptions, ) -> Result<Self>

Stereo counterpart of Self::from_frames, including existing synthwave spread/pan. Multiple prepared sources can use the existing mixer Stream adapter, with a common map and a shared scheduled start.

pub fn prepare_controls( &mut self, events: &[ControlEvent], capacity: usize, ) -> Result<()>

Prepare a replayable control plan before the first fill (or after reset). Events must be frame-ordered; equal frames follow input order after note onsets/gate-offs. Capacity includes retained history for reset, up to 65536 events/results. Zero capacity with no events disables controls. Preparation allocates; rejection preserves the current plan and renderer. Implicit loops must be disabled. Controls start before the body end and ramps end by it; held/releasing voices retain final values afterward.

pub fn schedule_control(&mut self, event: ControlEvent) -> Result<ControlId>

Add/retarget future control under exclusive source ownership, between fills. This is a control-thread operation: it may allocate and recompile queued ramps. Past frames, unsupported/missing targets, invalid ranges or exponential endpoints fail atomically. A full retained plan is LimitExceeded. Same-frame ordering is submission order; IDs stay stable.

pub fn controls_len(&self) -> usize

pub fn controls_capacity(&self) -> usize

pub fn poll_control_event(&mut self) -> Option<ControlReport>

One result for every executed event. An authored note stolen/ended before its event reports TargetInactive without changing any other voice/lane.

pub fn control_value( &self, target: ControlTarget, parameter: ControlParameter, ) -> Result<f64>

Applied controller value at the next source frame (frames_rendered), before queued events at that frame execute. Note targets must be active. Returns base values until their first event. Requires a prepared plan.

pub fn sample_rate(&self) -> u32

pub fn channels(&self) -> usize

1 for mono constructors, 2 for stereo constructors.

pub fn is_finished(&self) -> bool

pub fn frames_rendered(&self) -> u64

Frames rendered since the start or the last Synth::reset.

pub fn max_frames(&self) -> Option<u64>

An upper bound on the frames this synthesizer renders, or None if it loops forever.

pub fn reset(&mut self)

Starts again from the beginning, as if newly created.

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

Fills whole interleaved frames and returns their count. Mono uses one sample per frame, stereo two. Unused samples (including an incomplete frame) are untouched.

Trait Implementations

impl Clone for Synth

fn clone(&self) -> Synth

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Synth

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

Formats the value using the given formatter.

impl From<Synth> for Sound

Available on crate feature synth only.

fn from(synth: Synth) -> Self

Converts to this type from the input type.

impl Stream for Synth

Available on crate feature synth only.

A synthesizer plays as a mono or stereo stream. It loops by itself when its RenderOptions::loops is None; as a voice loop it can only return to its start.

fn sample_rate(&self) -> u32

fn channels(&self) -> usize

1 or 2.

fn read(&mut self, out: &mut [f32]) -> Result<usize>

Fills out with interleaved frames and returns how many; 0 at the end. ErrorCode::Underrun is temporary: the mixer emits silence and retries next render segment, preserving source position. Other errors fail the voice.

fn seek(&mut self, frame: u64) -> Result<()>

Moves to frame, for loops.

fn frames(&self) -> Option<u64>

The stream’s length in frames, if known.