Struct AudioEngine 

pub struct AudioEngine { /* private fields */ }

A mixing audio player backed by a platform output device.

The device is opened lazily, on the first call that actually makes sound, so an app that installs the engine but never plays anything costs no audio thread and no battery. Loading clips is not such a call: a clip load is a queue push, and the queue exists from construction, so a title screen can have its whole sound bank resident with the output device still shut.

The device does not stay open either. When nothing has sounded for IDLE_GRACE_SECONDS the mixer gives the stream up and the next play starts it again, so a silent screen costs nothing however it was reached.

Implementations

impl AudioEngine

pub fn new() -> AudioEngine

Creates an engine that opens the platform output device on first use.

pub fn with_sink_opener( open_sink: Box<dyn Fn(MixerSeed) -> Result<Box<dyn AudioSink>, AudioError>>, ) -> AudioEngine

Creates an engine over a caller-supplied device opener. The platform backends and the crate’s own tests both go through this.

pub fn take_last_error(&self) -> Option<AudioError>

The most recent failure, if the device refused to open or a call was rejected. Cleared by reading it.

pub fn leaked_clips(&self) -> u32

How many clips the mixer could not hand back for dropping. Any value above zero means the app stopped calling the engine while clips were being replaced; it is reported rather than hidden.

pub fn underruns(&self) -> u32

How many times the device asked for a buffer the mixer could not fill.

pub fn is_running(&self) -> bool

Whether the output device is open.

Open is not the same as running: a device that has been open for a while spends most of a quiet screen stopped. See is_streaming.

pub fn is_streaming(&self) -> bool

Whether the output stream is live rather than given up as idle.

false with is_running true is the steady state of a silent screen: the device object and every loaded clip are still there, the stream is not, and the next play starts it again. A stream paused by suspend still counts as live — the app took it away, not the mixer, and it comes back on resume.

Trait Implementations

impl AudioPlayer for AudioEngine

fn load_clip(&self, clip: AudioClip) -> Result<SoundId, AudioError>

Takes a clip table slot and queues the clip for the mixer.

This deliberately does not open the output device. Loading a bank of cues is what an app does on the way into a screen, long before it plays anything, and opening the device there was costing a silent title screen an audio thread and an always-on DSP rail for as long as it was on display. The command ring outlives every mixer, so the load waits in it and is drained by the first mixer to start.

The consequence is a narrower error contract than this used to have. The only failure it can still report is the one it can determine here, AudioError::ClipTableFull; a device that is missing or refuses to open is no longer a load-time error, because finding that out means opening it. Callers that need to know ask is_available, and the failure itself is available from take_last_error once a play has tried. That also makes this agree with NoopAudioPlayer, which hands out real SoundIds on a machine with no audio at all so app logic does not have to branch.

fn unload(&self, id: SoundId)

Releases a clip. Voices already playing it are stopped.

fn play(&self, id: SoundId, params: PlaybackParams)

Starts a one-shot voice. Re-triggering the same clip layers a new voice rather than restarting the old one.

fn play_loop(&self, id: SoundId, params: PlaybackParams) -> VoiceId

Starts a looping voice and returns its handle.

fn stop(&self, id: SoundId)

Stops every voice playing id.

fn stop_voice(&self, voice: VoiceId)

Stops one voice.

fn stop_all(&self)

Stops every voice on every bus.

fn set_voice_params(&self, voice: VoiceId, params: PlaybackParams)

Retunes a voice while it plays — a looping engine note that follows speed, for instance.

fn set_master_volume(&self, volume: f32)

Sets the gain applied to every bus.

fn master_volume(&self) -> f32

The current master gain.

fn set_bus_volume(&self, bus: AudioBus, volume: f32)

Sets one bus’s gain.

fn bus_volume(&self, bus: AudioBus) -> f32

One bus’s gain.

fn set_bus_enabled(&self, bus: AudioBus, enabled: bool)

Mutes or unmutes a bus. This is the “sound on” / “music on” toggle; muting leaves voices running so unmuting resumes mid-track.

fn bus_enabled(&self, bus: AudioBus) -> bool

Whether a bus is audible.

fn suspend(&self)

Releases the output device without discarding loaded clips — call it when the app goes to the background.

fn resume(&self)

Re-acquires the output device after suspend.

fn is_available(&self) -> bool

Whether a real device is behind this handle. The no-op default reports false, so an app can honestly grey out its audio settings.

fn load(&self, bytes: &[u8]) -> Result<SoundId, AudioError>

Decodes bytes and loads the result.

impl Default for AudioEngine

fn default() -> AudioEngine

Returns the “default value” for a type.