Struct Audio 

pub struct Audio { /* private fields */ }

The audio system. Reach it through ctx.audio.

Implementations

impl Audio

pub fn silent(sound_dir: impl Into<PathBuf>) -> Self

An audio system without an output device. Everything works, nothing is heard.

pub fn sample_rate(&self) -> u32

Sample rate of the output device in Hz.

pub fn has_output(&self) -> bool

Whether an output device is open (false means sounds are silently ignored).

pub fn set_sound_dir(&mut self, dir: impl Into<PathBuf>)

Changes the directory searched for sounds. See the module docs.

pub fn preload(&mut self, name: &str) -> Result<()>

Loads a sound into the cache now, so the first play has no delay.

pub fn preload_dir(&mut self, dir: impl AsRef<Path>) -> Result<usize>

Loads every sound file found in dir (not recursive). Names are the file paths relative to the sound directory without extension, e.g. "step". Returns how many files were loaded.

pub fn register(&mut self, name: impl Into<String>, data: impl Into<SoundData>)

Registers sound data generated in code (or a Synth) under a name, so it can be played like a file. Registering the same name again replaces the sound.

ctx.audio.register("beep", SoundData::tone(880.0, 0.1, 0.5));
ctx.audio.play("beep");

Examples found in repository

examples/bell_catcher.rs (line 24)

fn main() -> audio_code::Result<()> {
    Engine::new("Bell Catcher").run_with(|ctx| {
        ctx.audio.register("bell", Synth::sine(1568.0).with(Synth::sine(3136.0).volume(0.3)).length(0.35).decay(9.0).volume(0.6));
        ctx.audio.register("step", Synth::noise().length(0.05).decay(80.0).volume(0.5));
        ctx.audio.register("edge", Synth::sine(110.0).length(0.12).decay(30.0).volume(0.8));
        ctx.audio.register(
            "catch",
            Synth::sine(784.0).length(0.08).then(Synth::sine(1047.0).length(0.08)).then(Synth::sine(1568.0).length(0.2).decay(12.0)).volume(0.4),
        );
        ctx.audio.register("miss", Synth::saw(220.0).sweep_to(80.0).length(0.5).decay(5.0).volume(0.35));

        // Restore the speech settings from the last session.
        if let Some(voice) = ctx.storage.get::<String>("voice") {
            ctx.speech.set_voice(voice);
        }
        let rate: f32 = ctx.storage.get_or("rate", 50.0);
        if rate != 50.0 {
            ctx.speech.set_rate(rate / 100.0);
        }
        Title
    })
}

examples/beacon.rs (line 33)

    fn new(ctx: &mut Context) -> Self {
        ctx.audio.register("step", Synth::noise().length(0.08).decay(60.0));
        ctx.audio.register("wall", Synth::sine(90.0).length(0.15).decay(25.0).volume(0.8));
        ctx.audio.register("beacon", Synth::sine(1320.0).length(0.08).then(Synth::silence(0.04)).then(Synth::sine(1320.0).length(0.08)).then(Synth::silence(0.8)));
        ctx.audio.register("found", Synth::sine(440.0).sweep_to(1200.0).length(0.6).decay(4.0).volume(0.3));

        // Every character is a 2 meter tile: walls, the player start and three beacons.
        let level = ctx.physics.build_level(MAP, 2.0);
        let player = ctx.physics.add(Body::kinematic(level.point('P').unwrap()).with_sphere(0.4).with_tag("player"));
        ctx.follow(player); // the ears go wherever the player goes and face where it faces

        let mut beacons = Vec::new();
        for spot in level.points('B') {
            let beacon = ctx.physics.add(Body::sensor(spot).with_sphere(0.8).with_tag("beacon"));
            ctx.loop_on(beacon, "beacon"); // stops by itself when the beacon is removed
            beacons.push(beacon);
        }
        Self { player, beacons, clock: Timer::new() }
    }

examples/flight.rs (line 32)

    fn new(ctx: &mut Context) -> Self {
        ctx.audio.register("bird", Synth::sine(2200.0).sweep_to(3200.0).length(0.07).then(Synth::silence(0.05)).then(Synth::sine(2600.0).length(0.06)).then(Synth::silence(0.7)));
        ctx.audio.register("hum", Synth::saw(70.0).length(1.0).volume(0.08));
        ctx.audio.register("bump", Synth::sine(80.0).length(0.15).decay(25.0).volume(0.8));
        ctx.audio.register("found", Synth::triangle(660.0).sweep_to(1320.0).length(0.4).decay(6.0).volume(0.3));

        // A hall of 40 x 40 meters and 16 meters high: floor, roof and four walls.
        // A box is given by its center and its full width (x), depth (y) and height (z).
        let physics = &mut ctx.physics;
        physics.add(Body::fixed(vec3(0.0, 0.0, -0.5)).with_box(40.0, 40.0, 1.0).with_tag("floor"));
        physics.add(Body::fixed(vec3(0.0, 0.0, 16.5)).with_box(40.0, 40.0, 1.0).with_tag("roof"));
        physics.add(Body::fixed(vec3(0.0, 20.5, 8.0)).with_box(40.0, 1.0, 16.0).with_tag("north wall"));
        physics.add(Body::fixed(vec3(0.0, -20.5, 8.0)).with_box(40.0, 1.0, 16.0).with_tag("south wall"));
        physics.add(Body::fixed(vec3(20.5, 0.0, 8.0)).with_box(1.0, 40.0, 16.0).with_tag("east wall"));
        physics.add(Body::fixed(vec3(-20.5, 0.0, 8.0)).with_box(1.0, 40.0, 16.0).with_tag("west wall"));

        // The drone starts in the middle, 2 meters above the floor. No gravity: it hovers.
        let drone = ctx.physics.add(Body::kinematic(vec3(0.0, 0.0, 2.0)).with_sphere(0.5).with_tag("drone"));
        ctx.follow(drone); // the ears use the drone's position, facing and pitch
        ctx.audio.play_looped("hum");

        for spot in BIRDS {
            let bird = ctx.physics.add(Body::sensor(spot).with_sphere(1.0).with_tag("bird"));
            ctx.loop_on(bird, "bird");
        }
        Self { drone, birds: BIRDS.len(), blocked: false }
    }

examples/driving.rs (line 33)

    fn new(ctx: &mut Context) -> Self {
        // Engine: a low buzz that loops without clicks (whole cycles, no fades).
        let engine = Synth::saw(55.0).length(1.0).attack(0.0).release(0.0).volume(0.25)
            .with(Synth::square(110.0).length(1.0).attack(0.0).release(0.0).volume(0.08));
        ctx.audio.register("engine", engine);
        ctx.audio.register("horn", Synth::square(415.0).length(0.5).volume(0.25).with(Synth::square(523.0).length(0.5).volume(0.2)));
        ctx.audio.register("shift", Synth::noise().length(0.04).decay(90.0).volume(0.3));
        ctx.audio.register("crash", Synth::noise().length(0.4).decay(10.0).volume(0.8).with(Synth::sine(80.0).sweep_to(30.0).length(0.3)));
        ctx.audio.register("start", Synth::saw(40.0).sweep_to(55.0).length(0.6).volume(0.3));
        ctx.audio.register("garage", Synth::sine(880.0).length(0.15).decay(10.0));

        let level = ctx.physics.build_level(MAP, 6.0);
        let sounds = |v: Vehicle| {
            v.with_engine_sound("engine")
                .with_horn_sound("horn")
                .with_shift_sound("shift")
                .with_crash_sound("crash")
                .with_start_sound("start")
        };
        let car_start = level.point('P').unwrap_or(Vec3::ZERO);
        let car = ctx.physics.add(Body::car(car_start).with_facing(90.0).with_vehicle(sounds(Vehicle::car().with_fuel(5.0, 8.0))));
        let truck_start = level.point('T').unwrap_or(Vec3::ZERO);
        let truck = ctx.physics.add(
            Body::truck(truck_start).with_facing(90.0).with_vehicle(sounds(Vehicle::truck()).engine_off()),
        );
        let garage_at = level.point('G').unwrap_or(Vec3::ZERO);
        let garage = ctx.physics.add(Body::sensor(garage_at).with_box(6.0, 6.0, 3.0).with_tag("garage"));
        ctx.loop_on(garage, "garage");
        ctx.follow(car);
        Self { car, truck, driving: car, garage }
    }

examples/platformer.rs (line 21)

    fn new(ctx: &mut Context) -> Self {
        let audio = &mut ctx.audio;
        audio.register("jump", Synth::square(300.0).sweep_to(700.0).length(0.15).decay(10.0).volume(0.2));
        audio.register("land", Synth::noise().length(0.1).decay(40.0).with(Synth::sine(90.0).length(0.1).decay(30.0)));
        audio.register("coin", Synth::triangle(988.0).length(0.08).then(Synth::triangle(1319.0).length(0.17).decay(15.0)));
        audio.register("run", Synth::noise().length(0.06).decay(60.0).volume(0.3).then(Synth::silence(0.09)));
        audio.register("lift", Synth::saw(55.0).length(1.0).volume(0.1));
        audio.register("push", Synth::noise().length(0.3).volume(0.15));

        let physics = &mut ctx.physics;
        physics.add(Body::fixed(vec3(0.0, 0.0, -0.5)).with_box(200.0, 4.0, 1.0).with_tag("ground"));
        for (x, z) in [(8.0, 2.0), (14.0, 4.0), (20.0, 2.5)] {
            physics.add(Body::fixed(vec3(x, 0.0, z)).with_box(4.0, 4.0, 0.5).with_tag("platform"));
        }
        // A lift going up and down at x = 40, and a heavy crate at x = 30.
        let lift = physics.add(Body::kinematic(vec3(40.0, 0.0, 0.0)).with_box(3.0, 4.0, 0.5).with_tag("lift"));
        physics.add(Body::dynamic(vec3(30.0, 0.0, 0.5)).with_box(1.0, 1.0, 1.0).with_mass(5.0).with_tag("crate"));
        // Facing north, so x maps to left and right in the ears.
        let player = physics
            .add(Body::dynamic(vec3(0.0, 0.0, 1.0)).with_box(0.8, 0.8, 1.6).with_max_speed(25.0).with_tag("player"));

        ctx.follow(player);
        ctx.loop_on(lift, "lift");
        // Coins are sensors with a looping sound, so you can hear where they are.
        for (x, z) in [(5.0, 1.0), (14.0, 5.5), (25.0, 1.0), (40.0, 8.0)] {
            let coin = ctx.physics.add(Body::sensor(vec3(x, 0.0, z)).with_sphere(0.6).with_tag("coin"));
            ctx.loop_on(coin, "coin").set_volume(0.3);
        }

        let run_sound = ctx.audio.sound("run").looped().volume(0.0).play();
        Self { player, lift, run_sound, score: 0 }
    }

pub fn is_loaded(&self, name: &str) -> bool

Whether a sound with this name is loaded or registered.

pub fn unload(&mut self, name: &str)

Removes a sound from the cache to free memory. Playing sounds are not affected.

pub fn duration(&mut self, name: &str) -> Option<f32>

Length of a sound in seconds (loads it if needed).

pub fn sound(&mut self, name: &str) -> SoundBuilder<'_>

Starts building a sound with full control over its settings. Finish with SoundBuilder::play.

Examples found in repository

examples/bell_catcher.rs (line 183)

    fn ring(&mut self, ctx: &mut Context) {
        // 0.0 when the bell starts falling, 1.0 when it lands.
        let progress = 1.0 - self.left / self.fall;
        let position = self.bell_position();
        ctx.audio.sound("bell").at(position).pitch(1.0 + progress * 0.6).play();
        self.next_ring = 0.12 + 0.45 * (1.0 - progress);
    }

    fn land(&mut self, ctx: &mut Context) {
        if self.lane == self.bell_lane {
            self.score += 1;
            self.fall = (self.fall * 0.93).max(FASTEST_FALL);
            ctx.play("catch");
            if self.score.is_multiple_of(5) {
                ctx.speak(format!("{} bells!", self.score));
            }
        } else {
            self.lives -= 1;
            ctx.play("miss");
            match self.lives {
                0 => return self.game_over(ctx),
                1 => ctx.speak("Missed! Last life."),
                n => ctx.speak(format!("Missed! {n} lives left.")),
            }
        }
        // A short break before the next bell.
        self.left = -0.8;
    }

    fn game_over(&mut self, ctx: &mut Context) {
        self.over = true;
        let best: u32 = ctx.storage.get_or("best", 0);
        let text = if self.score > best {
            ctx.storage.set("best", self.score);
            format!("Game over. {} bells, a new best score!", self.score)
        } else {
            format!("Game over. {} bells. Your best is {best}.", self.score)
        };
        ctx.ui.message("over", text);
    }
}

impl Scene for Game {
    fn start(&mut self, ctx: &mut Context) {
        ctx.speak("Catch the bells! Left and right to move.");
        // Give the player a moment to listen to the first bell.
        self.left = -1.5;
    }

    fn update(&mut self, ctx: &mut Context) {
        if self.over {
            if ctx.ui.closed("over") {
                ctx.switch_scene(Title);
            }
            return;
        }
        if ctx.pressed(Key::Escape) {
            ctx.switch_scene(Title);
            return;
        }
        if ctx.pressed(Key::S) {
            ctx.speak(format!("{} bells, {} lives", self.score, self.lives));
        }
        for (key, step) in [(Key::Left, -1), (Key::Right, 1)] {
            if ctx.input.repeating(key, 0.3, 0.15) {
                let lane = (self.lane + step).clamp(-LANES, LANES);
                if lane == self.lane {
                    ctx.play("edge");
                } else {
                    self.lane = lane;
                    ctx.audio.sound("step").at(vec3(step as f32 * 0.5, 0.0, 0.0)).random_pitch(0.9, 1.1).play();
                }
            }
        }

        let dt = ctx.time.delta();
        if self.left < 0.0 {
            self.left += dt;
            if self.left >= 0.0 {
                self.drop_bell();
            }
            return;
        }
        self.left -= dt;
        self.next_ring -= dt;
        if self.left <= 0.0 {
            self.land(ctx);
        } else if self.next_ring <= 0.0 {
            self.ring(ctx);
        }
    }

examples/beacon.rs (line 75)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.pressed(Key::Escape) {
            ctx.push_scene(Pause);
        }
        if ctx.pressed(Key::Left) || ctx.pressed(Key::Right) {
            let degrees = if ctx.pressed(Key::Left) { -45.0 } else { 45.0 };
            let facing = ctx.physics.turn(self.player, degrees);
            ctx.speak(math::direction_name(facing));
        }

        let forward = ctx.input.repeating(Key::Up, 0.35, 0.35);
        let backward = ctx.input.repeating(Key::Down, 0.35, 0.35);
        if forward || backward {
            let step = if forward { 1.0 } else { -1.0 };
            if ctx.physics.move_forward(self.player, step).blocked {
                ctx.play("wall");
            } else {
                ctx.audio.sound("step").random_pitch(0.85, 1.15).play();
            }
        }

        if ctx.pressed(Key::C) {
            let position = ctx.physics.position(self.player);
            match ctx.physics.nearest_with_tag(position, "beacon") {
                Some(beacon) => {
                    let text = ctx.physics.describe(self.player, beacon);
                    ctx.speak(text);
                }
                None => ctx.speak("No beacons left"),
            }
        }
        if ctx.pressed(Key::F) {
            let facing = ctx.physics.facing(self.player);
            ctx.speak(format!("Facing {}", math::direction_name(facing)));
        }

        if let Some(beacon) = ctx.physics.entered_tag(self.player, "beacon") {
            ctx.physics.remove(beacon);
            self.beacons.retain(|b| *b != beacon);
            ctx.play("found");
            if self.beacons.is_empty() {
                self.finish(ctx);
            } else {
                ctx.speak(format!("Beacon found! {} left.", self.beacons.len()));
            }
        }
        if ctx.ui.closed("done") {
            ctx.quit();
        }
    }

examples/platformer.rs (line 48)

    fn new(ctx: &mut Context) -> Self {
        let audio = &mut ctx.audio;
        audio.register("jump", Synth::square(300.0).sweep_to(700.0).length(0.15).decay(10.0).volume(0.2));
        audio.register("land", Synth::noise().length(0.1).decay(40.0).with(Synth::sine(90.0).length(0.1).decay(30.0)));
        audio.register("coin", Synth::triangle(988.0).length(0.08).then(Synth::triangle(1319.0).length(0.17).decay(15.0)));
        audio.register("run", Synth::noise().length(0.06).decay(60.0).volume(0.3).then(Synth::silence(0.09)));
        audio.register("lift", Synth::saw(55.0).length(1.0).volume(0.1));
        audio.register("push", Synth::noise().length(0.3).volume(0.15));

        let physics = &mut ctx.physics;
        physics.add(Body::fixed(vec3(0.0, 0.0, -0.5)).with_box(200.0, 4.0, 1.0).with_tag("ground"));
        for (x, z) in [(8.0, 2.0), (14.0, 4.0), (20.0, 2.5)] {
            physics.add(Body::fixed(vec3(x, 0.0, z)).with_box(4.0, 4.0, 0.5).with_tag("platform"));
        }
        // A lift going up and down at x = 40, and a heavy crate at x = 30.
        let lift = physics.add(Body::kinematic(vec3(40.0, 0.0, 0.0)).with_box(3.0, 4.0, 0.5).with_tag("lift"));
        physics.add(Body::dynamic(vec3(30.0, 0.0, 0.5)).with_box(1.0, 1.0, 1.0).with_mass(5.0).with_tag("crate"));
        // Facing north, so x maps to left and right in the ears.
        let player = physics
            .add(Body::dynamic(vec3(0.0, 0.0, 1.0)).with_box(0.8, 0.8, 1.6).with_max_speed(25.0).with_tag("player"));

        ctx.follow(player);
        ctx.loop_on(lift, "lift");
        // Coins are sensors with a looping sound, so you can hear where they are.
        for (x, z) in [(5.0, 1.0), (14.0, 5.5), (25.0, 1.0), (40.0, 8.0)] {
            let coin = ctx.physics.add(Body::sensor(vec3(x, 0.0, z)).with_sphere(0.6).with_tag("coin"));
            ctx.loop_on(coin, "coin").set_volume(0.3);
        }

        let run_sound = ctx.audio.sound("run").looped().volume(0.0).play();
        Self { player, lift, run_sound, score: 0 }
    }
}

impl Scene for Platformer {
    fn start(&mut self, ctx: &mut Context) {
        ctx.speak("Collect the coins. Left and right to run, space to jump, S for score, escape to quit.");
    }

    fn update(&mut self, ctx: &mut Context) {
        if ctx.pressed(Key::Escape) {
            ctx.quit();
        }

        // The lift goes up for 4 seconds and down for 4 seconds.
        let lift_up = (ctx.time.elapsed() % 8.0) < 4.0;
        ctx.physics.set_velocity(self.lift, vec3(0.0, 0.0, if lift_up { 2.0 } else { -2.0 }));

        let run = ctx.input.axis(Key::Left, Key::Right);
        let mut velocity = ctx.physics.velocity(self.player);
        velocity.x = run * 6.0;
        ctx.physics.set_velocity(self.player, velocity);
        if ctx.pressed(Key::Space) && ctx.physics.jump(self.player, 2.5) {
            ctx.play("jump");
        }
        let running = ctx.physics.on_ground(self.player) && run != 0.0;
        self.run_sound.set_volume(if running { 0.6 } else { 0.0 });

        if let Some(speed) = ctx.physics.landed(self.player) {
            ctx.audio.sound("land").volume((speed / 12.0).clamp(0.2, 1.0)).play();
            if speed > 15.0 {
                ctx.speak("Ouch!");
            }
        }
        if let Some((other, _)) = ctx.physics.collided(self.player)
            && ctx.physics.tag(other) == "crate"
        {
            ctx.play_on(other, "push");
        }
        if let Some(coin) = ctx.physics.entered_tag(self.player, "coin") {
            ctx.physics.remove(coin); // its looping sound stops by itself
            self.score += 1;
            ctx.audio.sound("coin").pitch(1.5).play();
            ctx.speak(format!("{} of {COINS} coins", self.score));
            if self.score == COINS {
                ctx.ui.message("won", "You collected every coin! Press enter to quit.");
            }
        }
        if ctx.ui.closed("won") {
            ctx.quit();
        }

        if ctx.pressed(Key::S) {
            let x = ctx.physics.position(self.player).x;
            ctx.speak(format!("Score {}, position {x:.0}", self.score));
        }
    }

pub fn play(&mut self, name: &str) -> Sound

Plays a sound once, centered. Returns a handle you may keep or ignore.

pub fn play_at(&mut self, name: &str, position: Vec3) -> Sound

Plays a sound once at a position in the world.

pub fn play_looped(&mut self, name: &str) -> Sound

Plays a sound in an endless loop. Stop it with Sound::stop.

Examples found in repository

examples/flight.rs (line 50)

    fn new(ctx: &mut Context) -> Self {
        ctx.audio.register("bird", Synth::sine(2200.0).sweep_to(3200.0).length(0.07).then(Synth::silence(0.05)).then(Synth::sine(2600.0).length(0.06)).then(Synth::silence(0.7)));
        ctx.audio.register("hum", Synth::saw(70.0).length(1.0).volume(0.08));
        ctx.audio.register("bump", Synth::sine(80.0).length(0.15).decay(25.0).volume(0.8));
        ctx.audio.register("found", Synth::triangle(660.0).sweep_to(1320.0).length(0.4).decay(6.0).volume(0.3));

        // A hall of 40 x 40 meters and 16 meters high: floor, roof and four walls.
        // A box is given by its center and its full width (x), depth (y) and height (z).
        let physics = &mut ctx.physics;
        physics.add(Body::fixed(vec3(0.0, 0.0, -0.5)).with_box(40.0, 40.0, 1.0).with_tag("floor"));
        physics.add(Body::fixed(vec3(0.0, 0.0, 16.5)).with_box(40.0, 40.0, 1.0).with_tag("roof"));
        physics.add(Body::fixed(vec3(0.0, 20.5, 8.0)).with_box(40.0, 1.0, 16.0).with_tag("north wall"));
        physics.add(Body::fixed(vec3(0.0, -20.5, 8.0)).with_box(40.0, 1.0, 16.0).with_tag("south wall"));
        physics.add(Body::fixed(vec3(20.5, 0.0, 8.0)).with_box(1.0, 40.0, 16.0).with_tag("east wall"));
        physics.add(Body::fixed(vec3(-20.5, 0.0, 8.0)).with_box(1.0, 40.0, 16.0).with_tag("west wall"));

        // The drone starts in the middle, 2 meters above the floor. No gravity: it hovers.
        let drone = ctx.physics.add(Body::kinematic(vec3(0.0, 0.0, 2.0)).with_sphere(0.5).with_tag("drone"));
        ctx.follow(drone); // the ears use the drone's position, facing and pitch
        ctx.audio.play_looped("hum");

        for spot in BIRDS {
            let bird = ctx.physics.add(Body::sensor(spot).with_sphere(1.0).with_tag("bird"));
            ctx.loop_on(bird, "bird");
        }
        Self { drone, birds: BIRDS.len(), blocked: false }
    }

pub fn play_looped_at(&mut self, name: &str, position: Vec3) -> Sound

Plays a looping sound at a position in the world.

pub fn play_random(&mut self, names: &[&str]) -> Sound

Plays one of several sounds picked at random, e.g. footstep variations.

pub fn play_random_at(&mut self, names: &[&str], position: Vec3) -> Sound

Plays one of several sounds picked at random at a position.

pub fn play_tone(&mut self, frequency: f32, seconds: f32) -> Sound

Plays a generated sine beep of frequency hertz (e.g. 880.0) for seconds. Great for prototyping before you have sound files.

Examples found in repository

examples/hello.rs (line 18)

    fn update(&mut self, ctx: &mut Context) {
        if ctx.input.pressed(Key::Space) {
            // A pitch that rises over time, so every beep sounds different.
            let pitch = 300.0 + (ctx.time.elapsed() as f32 * 50.0) % 900.0;
            ctx.audio.play_tone(pitch.round(), 0.15);
        }
        if ctx.input.pressed(Key::F1) {
            ctx.speech.repeat_last();
        }
        if ctx.input.pressed(Key::Escape) {
            ctx.quit();
        }
    }

examples/clicker.rs (line 20)

fn main() -> audio_code::Result<()> {
    let mut score = 0;

    audio_code::run("Clicker", move |ctx| {
        if ctx.once("intro") {
            let best: u32 = ctx.storage.get_or("best", 0);
            ctx.speak(format!("Press space as often as you can in ten seconds. Your best is {best}. Go!"));
            ctx.time.after("end", 10.0);
        }

        if ctx.time.is_scheduled("end") && ctx.pressed(Key::Space) {
            score += 1;
            ctx.audio.play_tone(300.0 + score as f32 * 15.0, 0.05);
        }

        if ctx.time.fired("end") {
            let best: u32 = ctx.storage.get_or("best", 0);
            if score > best {
                ctx.storage.set("best", score);
                ctx.ui.message("result", format!("{score} presses. New record!"));
            } else {
                ctx.ui.message("result", format!("{score} presses. Your best is {best}."));
            }
        }

        if ctx.ui.closed("result") || ctx.pressed(Key::Escape) {
            ctx.quit();
        }
    })
}

pub fn play_music(&mut self, name: &str) -> Sound

Plays background music in a loop. The file is decoded in the background so the game does not stutter. Any previous music fades out while the new one fades in. Calling it again with the music that is already playing does nothing.

pub fn play_music_with_fade(&mut self, name: &str, fade: f32) -> Sound

Like Audio::play_music with a custom cross fade time in seconds.

pub fn stop_music(&mut self, fade: f32)

Fades out the current music over fade seconds.

pub fn music(&self) -> Option<&Sound>

Handle of the current music, if any.

pub fn music_name(&self) -> Option<&str>

Name of the current music, as passed to Audio::play_music.

pub fn set_listener(&mut self, position: Vec3, yaw: f32)

Places the listener (the player’s ears) in the world. yaw is the compass direction the player faces (0 = north, 90 = east). Call this whenever the player moves or turns. The listener looks level with the horizon; use Audio::set_listener_3d to also look up or down.

pub fn set_listener_3d(&mut self, position: Vec3, yaw: f32, pitch: f32)

Like Audio::set_listener, plus pitch: how far the player looks up (positive, 90 = straight up) or down (negative, -90 = straight down), in degrees. For flying, swimming or space games.

pub fn listener_position(&self) -> Vec3

Current listener position.

pub fn listener_yaw(&self) -> f32

Current listener facing in compass degrees.

pub fn listener_pitch(&self) -> f32

Current listener pitch in degrees (0 = level, 90 = straight up).

pub fn set_default_distance(&mut self, min: f32, max: f32)

Default audible range for positioned sounds in meters: full volume up to min, silent from max on. The default is 1.0 and 30.0.

pub fn set_default_rolloff(&mut self, rolloff: f32)

Default rolloff for positioned sounds: how fast the volume drops between min and max distance. 1.0 is physically accurate (twice the distance, half the volume), lower values keep distant sounds louder, 0.0 keeps full volume until shortly before max. Default is 0.7, which is at 32 % volume at 5 m and 18 % at 10 m.

pub fn set_master_volume(&mut self, volume: f32)

Sets the overall volume as a linear factor: 1.0 = unchanged (default), 0.5 = half, 0.0 = silent. Higher values amplify and may distort.

Examples found in repository

examples/menus.rs (line 76)

    fn on_ui(&mut self, event: &UiEvent, ctx: &mut Context) {
        match event {
            UiEvent::Activated { menu, item } => match (menu.as_str(), item.as_str()) {
                ("main", "play") => {
                    let s = ctx.get::<Settings>().expect("settings exist");
                    let text = format!("Good luck, {}! (this is where your game would start)", s.name);
                    ctx.ui.message("intro", text);
                }
                ("main", "options") => {
                    let menu = options_menu(ctx.get::<Settings>().expect("settings exist"));
                    ctx.ui.open(menu);
                }
                ("main", "name") => ctx.ui.open(TextInput::new("name", "Enter your name").max_length(20).required()),
                ("main", "quit") => ctx.ui.open(Confirm::new("quit", "Do you really want to quit?").default_no()),
                ("options", "back") => ctx.ui.close(),
                _ => {}
            },
            UiEvent::Changed { menu, item, value } if menu == "options" => {
                let s = ctx.get_mut::<Settings>().expect("settings exist");
                match item.as_str() {
                    "volume" => s.volume = value.as_f32() / 100.0,
                    "difficulty" => s.difficulty = value.as_index(),
                    "name" => s.name = value.as_str().to_string(),
                    _ => {}
                }
                let volume = s.volume;
                ctx.audio.set_master_volume(volume);
            }
            UiEvent::TextSubmitted { id, text } if id == "name" => {
                ctx.get_mut::<Settings>().expect("settings exist").name = text.clone();
                ctx.speech.speak_queued(format!("Hello, {text}"));
            }
            UiEvent::Confirmed { id, yes: true } if id == "quit" => ctx.quit(),
            _ => {}
        }
    }

pub fn master_volume(&self) -> f32

Overall volume.

pub fn set_group_volume(&mut self, group: Group, volume: f32)

Sets the volume of one group (sound effects, music or UI) as a linear factor, 1.0 = unchanged (default). It is multiplied with each sound’s own volume and the master volume.

pub fn group_volume(&self, group: Group) -> f32

Volume of one group.

pub fn set_music_volume(&mut self, volume: f32)

Shortcut for set_group_volume(Group::Music, volume).

pub fn set_sound_volume(&mut self, volume: f32)

Shortcut for set_group_volume(Group::Sound, volume).

pub fn stop_all(&mut self)

Stops every sound immediately (including music).

pub fn stop_group(&mut self, group: Group, fade: f32)

Fades out all sounds of a group over fade seconds and stops them.

Trait Implementations

impl Debug for Audio

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

Formats the value using the given formatter.