audio_bus API

pub struct Bus { bs_name: text, bs_parent: text = "", bs_volume: float = 1.0, bs_before: float = -1.0 }

One level in the tree: a name, a level, and what it hangs under.

pub struct Voice { vc_sink: integer, vc_bus: text = "", vc_volume: float = 1.0 }

One playing sound, and the bus it answers to.

pub struct Mixer { buses: hash<Bus[bs_name]>, voices: hash<Voice[vc_sink]> }

The mixer: the bus tree, and every voice currently on it.

pub fn mixer() -> Mixer

A mixer with nothing on it but the master bus.

pub fn add(m: Mixer, name: text, parent: text = MASTER, volume: float = 1.0) -> boolean

Add a bus under parent, at volume.

Answers false — changing nothing — when the name is already taken, when the parent does not exist, or when the name is empty. A mixer that silently accepts a second "music" has two of them and obeys neither.

pub fn gain(m: const Mixer, name: text) -> float

The gain a sound on this bus is multiplied by: the bus's own level times every level above it.

A name no bus has answers 0.0 rather than 1.0. Silence is the answer a caller can hear; a missing bus that plays at full volume is one they cannot.

pub fn level(m: const Mixer, sink: integer) -> float

What a voice's sink should be set to: the sound's own level times its bus.

pub fn attach(m: Mixer, sink: integer, bus: text, volume: float = 1.0) -> boolean

Put an already-playing sink on a bus at its own level.

The seam this package is built around: play is graphics::audio_play followed by this, and a caller who plays a sound their own way — a procedural effect, a clip started before the mixer existed — gets the same bus.

pub fn detach(m: Mixer, sink: integer)

Forget a sink without stopping it — it keeps whatever level it has.

pub fn play(m: Mixer, bus: text, clip: integer, volume: float = 1.0, looping: boolean = false, pan: float = 0.0, start: float = 0.0) -> integer

Play a clip on a bus. The arguments past volume are graphics::audio_play's and mean exactly what they mean there.

Answers the sink handle, or -1 when the sound did not start — in which case nothing is attached, so a mixer never carries a voice that is not playing.

pub fn set_volume(m: Mixer, name: text, volume: float) -> boolean

Set a bus's level, and move every sound under it.

Answers false for a bus that does not exist. A level below 0 is clamped: a negative gain inverts a waveform rather than quietening it, which is not what any caller of a volume control means.

pub fn volume(m: const Mixer, name: text) -> float

This bus's own level — not counting the buses above it.

pub fn duck(m: Mixer, name: text, to: float) -> boolean

Duck a bus to to — speech over music, a menu over a battle.

The level it replaces is REMEMBERED, so unduck restores it exactly. Ducking an already-ducked bus moves it again and keeps the ORIGINAL level to come home to: a duck inside a duck must not make the first one's restore a guess.

Answers false for a bus that does not exist.

pub fn unduck(m: Mixer, name: text) -> boolean

Lift a duck, putting back the exact level it replaced.

Answers false for a bus that does not exist or is not ducked — the second is worth an answer rather than a shrug, because an unduck that finds nothing to lift means a duck and its lift have come apart somewhere.

pub fn ducked(m: const Mixer, name: text) -> boolean

Is this bus ducked right now?

pub fn pan(m: const Mixer, sink: integer, position: float)

Move one playing sound across the stereo field. The mixer keeps the voice list, so this is where a caller already is.

pub fn stop(m: Mixer, sink: integer)

Stop one sound and forget it.

pub fn stop_bus(m: Mixer, name: text) -> integer

Stop every sound on a bus — and on the buses under it.

Answers how many it stopped, because "the scene is over, silence its sounds" is a claim a caller may want to check rather than assume.

pub fn stop_all(m: Mixer) -> integer

Stop everything, on every bus.

pub fn under(m: const Mixer, name: text, ancestor: text) -> boolean

Is name at or below ancestor in the tree?