Struct Mixer 

pub struct Mixer { /* private fields */ }

A routing stereo mixer of audio sources — instruments, the SFX Engine, StreamSources. Each source feeds a bus; buses carry live insert chains (reverb / EQ / compressor / …) and post-fader sends into shared FX/return buses, all summing through a master insert chain. It is itself an AudioSource, so it feeds one output callback (or nests).

With no buses or effects created, every source sits on the master bus at unity and the output is a plain additive sum — byte-identical to a bare mixer. Live effects need a sample rate: build with Mixer::new.

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

let mut mixer = Mixer::new(48_000);
let sfx = mixer.bus("sfx");

let mut engine = Engine::new(48_000);
let drone = engine.load(&SoundDoc::new("drone", Node::Sine { freq: 110.0.into() }));
engine.play_looping(drone);
mixer.add_to(sfx, engine);             // the engine feeds the sfx bus
mixer.set_bus_gain(sfx, 0.8);          // a live fader

let mut out = vec![0.0f32; 512];
mixer.fill(&mut out);                  // one callback serves the whole desk
assert!(out.iter().any(|s| s.abs() > 0.0));

Implementations

impl Mixer

pub fn new(sample_rate: u32) -> Self

An empty mixer that renders at sample_rate, so buses can carry live effect chains (every other runtime constructor — Engine::new, AdaptiveMusic::new, Instrument::new — takes the rate up front too).

Examples found in repository

examples/play_instrument.rs (line 64)

fn main() {
    let sr = 48_000;
    let design = InstrumentDesign::new(lead()).with_amp(Adsr {
        a: 0.01,
        d: 0.15,
        s: 0.6,
        r: 0.25,
        punch: 0.0,
    });
    let mut inst = Instrument::new(design, sr).expect("streamable instrument");

    // --- Play a C-major chord, hold, then release -------------------------
    inst.note_on(n("C4"), 0.9);
    inst.note_on(n("E4"), 0.8);
    inst.note_on(n("G4"), 0.7);
    println!("chord: {} voices", inst.active_voices());

    let mut block = vec![0.0f32; 512 * 2];
    let mut p = 0.0f32;
    for _ in 0..40 {
        inst.fill(&mut block);
        p = p.max(peak(&block));
    }
    inst.all_notes_off();
    for _ in 0..60 {
        inst.fill(&mut block);
    }
    println!(
        "after release: {} voices (chord peak {p:.3})",
        inst.active_voices()
    );

    // --- Host it in a mixer, and play a melody by reaching back in --------
    let mut mixer = Mixer::new(sr);
    let lead_id = mixer.add(inst);
    mixer.set_gain(lead_id, 0.8);

    let melody = ["C4", "E4", "G4", "C5", "G4", "E4"];
    let mut apeak = 0.0f32;
    for name in melody {
        let voice = mixer.get_mut::<Instrument>(lead_id).unwrap();
        voice.note_on(n(name), 0.85);
        // ~120 ms of audio per note.
        for _ in 0..11 {
            mixer.fill(&mut block);
            apeak = apeak.max(peak(&block));
        }
        mixer
            .get_mut::<Instrument>(lead_id)
            .unwrap()
            .note_off(n(name));
    }
    println!("melody through the mixer: peak {apeak:.3}");
}

pub fn add(&mut self, source: impl AudioSource + Send + 'static) -> SourceId

Add a source to the master bus at unity gain; returns its handle.

Examples found in repository

examples/play_instrument.rs (line 65)

fn main() {
    let sr = 48_000;
    let design = InstrumentDesign::new(lead()).with_amp(Adsr {
        a: 0.01,
        d: 0.15,
        s: 0.6,
        r: 0.25,
        punch: 0.0,
    });
    let mut inst = Instrument::new(design, sr).expect("streamable instrument");

    // --- Play a C-major chord, hold, then release -------------------------
    inst.note_on(n("C4"), 0.9);
    inst.note_on(n("E4"), 0.8);
    inst.note_on(n("G4"), 0.7);
    println!("chord: {} voices", inst.active_voices());

    let mut block = vec![0.0f32; 512 * 2];
    let mut p = 0.0f32;
    for _ in 0..40 {
        inst.fill(&mut block);
        p = p.max(peak(&block));
    }
    inst.all_notes_off();
    for _ in 0..60 {
        inst.fill(&mut block);
    }
    println!(
        "after release: {} voices (chord peak {p:.3})",
        inst.active_voices()
    );

    // --- Host it in a mixer, and play a melody by reaching back in --------
    let mut mixer = Mixer::new(sr);
    let lead_id = mixer.add(inst);
    mixer.set_gain(lead_id, 0.8);

    let melody = ["C4", "E4", "G4", "C5", "G4", "E4"];
    let mut apeak = 0.0f32;
    for name in melody {
        let voice = mixer.get_mut::<Instrument>(lead_id).unwrap();
        voice.note_on(n(name), 0.85);
        // ~120 ms of audio per note.
        for _ in 0..11 {
            mixer.fill(&mut block);
            apeak = apeak.max(peak(&block));
        }
        mixer
            .get_mut::<Instrument>(lead_id)
            .unwrap()
            .note_off(n(name));
    }
    println!("melody through the mixer: peak {apeak:.3}");
}

pub fn add_to( &mut self, bus: BusId, source: impl AudioSource + Send + 'static, ) -> SourceId

Add a source to a specific bus at unity gain; returns its handle. An unknown bus falls back to master.

pub fn bus(&mut self, name: impl Into<String>) -> BusId

Create an input bus (sources → inserts → master, with optional sends).

pub fn fx_bus( &mut self, name: impl Into<String>, effects: Vec<Node>, ) -> Result<BusId, MixerError>

Create an FX/return bus with an insert chain fed only by sends. Returns MixerError if the effects aren’t streamable or the mixer has no rate.

pub fn bus_named(&self, name: &str) -> Option<BusId>

Look up a bus by name.

pub fn set_bus_effects( &mut self, bus: BusId, effects: Vec<Node>, ) -> Result<(), MixerError>

Set (or clear, with an empty list) a bus’s insert chain. Works on any bus, including master. Returns MixerError::UnknownBus for a foreign/stale handle (it used to build the chain and silently discard it).

pub fn master_effects(&mut self, effects: Vec<Node>) -> Result<(), MixerError>

Set the master insert chain (a convenience for set_bus_effects(MASTER, …)).

pub fn set_send(&mut self, from: BusId, to_fx: BusId, level: f32)

Set a post-fader send from an input bus into an FX bus. A no-op unless from is an input bus and to_fx is an FX bus.

pub fn set_bus_gain(&mut self, bus: BusId, gain: f32)

Set a bus fader (0 = silent). Applies to the bus’s dry output and its sends.

pub fn set_bus_dry(&mut self, bus: BusId, level: f32)

Set a bus’s dry level into master (0 = send-only). No-op for master.

pub fn set_gain(&mut self, id: SourceId, gain: f32)

Set a source’s gain (no-op for an unknown handle).

Examples found in repository

examples/play_instrument.rs (line 66)

fn main() {
    let sr = 48_000;
    let design = InstrumentDesign::new(lead()).with_amp(Adsr {
        a: 0.01,
        d: 0.15,
        s: 0.6,
        r: 0.25,
        punch: 0.0,
    });
    let mut inst = Instrument::new(design, sr).expect("streamable instrument");

    // --- Play a C-major chord, hold, then release -------------------------
    inst.note_on(n("C4"), 0.9);
    inst.note_on(n("E4"), 0.8);
    inst.note_on(n("G4"), 0.7);
    println!("chord: {} voices", inst.active_voices());

    let mut block = vec![0.0f32; 512 * 2];
    let mut p = 0.0f32;
    for _ in 0..40 {
        inst.fill(&mut block);
        p = p.max(peak(&block));
    }
    inst.all_notes_off();
    for _ in 0..60 {
        inst.fill(&mut block);
    }
    println!(
        "after release: {} voices (chord peak {p:.3})",
        inst.active_voices()
    );

    // --- Host it in a mixer, and play a melody by reaching back in --------
    let mut mixer = Mixer::new(sr);
    let lead_id = mixer.add(inst);
    mixer.set_gain(lead_id, 0.8);

    let melody = ["C4", "E4", "G4", "C5", "G4", "E4"];
    let mut apeak = 0.0f32;
    for name in melody {
        let voice = mixer.get_mut::<Instrument>(lead_id).unwrap();
        voice.note_on(n(name), 0.85);
        // ~120 ms of audio per note.
        for _ in 0..11 {
            mixer.fill(&mut block);
            apeak = apeak.max(peak(&block));
        }
        mixer
            .get_mut::<Instrument>(lead_id)
            .unwrap()
            .note_off(n(name));
    }
    println!("melody through the mixer: peak {apeak:.3}");
}

pub fn get_mut<T: AudioSource + 'static>( &mut self, id: SourceId, ) -> Option<&mut T>

Mutable access to an added source, downcast to its concrete type — e.g. to call Instrument::note_on.

Examples found in repository

examples/play_instrument.rs (line 71)

fn main() {
    let sr = 48_000;
    let design = InstrumentDesign::new(lead()).with_amp(Adsr {
        a: 0.01,
        d: 0.15,
        s: 0.6,
        r: 0.25,
        punch: 0.0,
    });
    let mut inst = Instrument::new(design, sr).expect("streamable instrument");

    // --- Play a C-major chord, hold, then release -------------------------
    inst.note_on(n("C4"), 0.9);
    inst.note_on(n("E4"), 0.8);
    inst.note_on(n("G4"), 0.7);
    println!("chord: {} voices", inst.active_voices());

    let mut block = vec![0.0f32; 512 * 2];
    let mut p = 0.0f32;
    for _ in 0..40 {
        inst.fill(&mut block);
        p = p.max(peak(&block));
    }
    inst.all_notes_off();
    for _ in 0..60 {
        inst.fill(&mut block);
    }
    println!(
        "after release: {} voices (chord peak {p:.3})",
        inst.active_voices()
    );

    // --- Host it in a mixer, and play a melody by reaching back in --------
    let mut mixer = Mixer::new(sr);
    let lead_id = mixer.add(inst);
    mixer.set_gain(lead_id, 0.8);

    let melody = ["C4", "E4", "G4", "C5", "G4", "E4"];
    let mut apeak = 0.0f32;
    for name in melody {
        let voice = mixer.get_mut::<Instrument>(lead_id).unwrap();
        voice.note_on(n(name), 0.85);
        // ~120 ms of audio per note.
        for _ in 0..11 {
            mixer.fill(&mut block);
            apeak = apeak.max(peak(&block));
        }
        mixer
            .get_mut::<Instrument>(lead_id)
            .unwrap()
            .note_off(n(name));
    }
    println!("melody through the mixer: peak {apeak:.3}");
}

pub fn remove(&mut self, id: SourceId)

Remove a source.

pub fn source_count(&self) -> usize

Number of sources in the mix.

pub fn contains(&self, id: SourceId) -> bool

Whether id still refers to a source in the mix.

Trait Implementations

impl AudioSource for Mixer

fn reset(&mut self)

Rewind every source so a transport restart replays the mix from the top. Bus insert/send state (reverb tails, delay lines) is left ringing.

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

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