Bevy Audio Systems Agent Skill

Bevy audio systems

When to use

Load this when a clip should start, loop, pause, or change volume. bevy::audio in Bevy 0.20 and the audio_control example are the sources.

ECS shape

• Play: spawn AudioPlayer::new(asset_server.load(...)). AudioPlayer<Source> holds Handle<Source> where Source: Asset + Decodable. If the asset is not ready, playback starts when it is. AudioPlayer requires PlaybackSettings.
• Settings: PlaybackSettings configures the start. PlaybackSettings::LOOP and .with_spatial(true) appear in the spatial examples. Changes to PlaybackSettings do not affect audio that is already playing. PlaybackMode is Once, Loop, Despawn, or Remove.
• Control: when playback begins, Bevy inserts AudioSink. The control example queries AudioSink and calls pause, toggle_mute, set_volume, set_speed, and position. SpatialAudioSink is the spatial counterpart named on the playback page.
• Replay: after a non-looping sound finishes and the sink is drained, that AudioPlayer cannot be reused. Remove the audio components and add them again.
• Schedule: spawn on Startup or from a system that has Res<AssetServer> and Commands. Control systems in the example run where they read ButtonInput<KeyCode> and Res<Time>.

Playback pieces

| Need | Bevy idiom |

| --- | --- |

| Start a file | AudioPlayer::new plus AssetServer::load |

| Loop | PlaybackSettings::LOOP |

| Pause, mute, or volume while playing | AudioSink methods on the same entity |

| One-shot that should leave the world | PlaybackMode::Despawn or Remove |

| Positional emitter | PlaybackSettings with with_spatial(true) and SpatialAudioSink |

Examples

[dependencies]
bevy = "0.20"

AudioPlayer starts when the handle is ready. PlaybackSettings applies only at that start. AudioSink is inserted once playback begins and is the live control.

use bevy::audio::{AudioSinkPlayback, Volume};

fn spawn_music(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/music.ogg")),
        PlaybackSettings::LOOP.with_volume(Volume::Linear(0.6)),
    ));
}

fn spawn_oneshot(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/ui.ogg")),
        PlaybackSettings::DESPAWN,
    ));
}

fn duck_music(mut sinks: Query<&mut AudioSink>) {
    for mut sink in &mut sinks {
        sink.set_volume(Volume::Linear(0.25));
        sink.pause();
    }
}

A positional emitter sets with_spatial(true) and a Transform. Live control of that emitter uses SpatialAudioSink.

use bevy::audio::{AudioSinkPlayback, Volume};

fn spawn_footstep(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/step.ogg")),
        PlaybackSettings::ONCE.with_spatial(true),
        Transform::from_xyz(3.0, 0.0, 1.0),
    ));
}

fn quiet_nearby(mut sinks: Query<&mut SpatialAudioSink>) {
    for mut sink in &mut sinks {
        sink.set_volume(Volume::Linear(0.5));
    }
}

A finished non-looping player cannot be reused. Drop the player and the sink, then insert them again with the same handle.

use bevy::audio::AudioSinkPlayback;

fn replay_when_empty(mut commands: Commands, playing: Query<(Entity, &AudioPlayer, &AudioSink)>) {
    for (entity, player, sink) in &playing {
        if !sink.empty() {
            continue;
        }
        let handle = player.0.clone();
        commands.entity(entity).remove::<AudioPlayer>().remove::<AudioSink>();
        commands.entity(entity).insert((
            AudioPlayer::new(handle),
            PlaybackSettings::ONCE,
        ));
    }
}

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

| Piece | Owner | Who may mutate | Schedule |

| --- | --- | --- | --- |

| Data on one entity | Component | One system via Query | Update or FixedMain |

| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |

| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |

| Order that must not race | .chain() | The chained systems only | Same schedule |

| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

| If you need | Do this | Do not |

| --- | --- | --- |

| Per-entity data | Component + Query | A plain struct stored outside the world |

| App-wide config or clock | Resource | Copy the value onto every entity |

| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |

| Startup spawn | Commands in Startup | Spawn from a render system |

| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |

| An API outside the documented set | Check the official docs first | A made-up crate or API |

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.
• Do not mutably query the same component from two unordered systems. WHY: the schedule runs systems in parallel unless .chain() orders them.
• Do not invent a physics, navigation, networking, or XR crate here. WHY: this skill only names documented Bevy crates and modules.

• Do not change PlaybackSettings to retune audio that is already playing. WHY: those settings apply only when playback starts; live control is AudioSink.
• No volume curves or mixer nodes this file did not open. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No third-party audio crates. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

The library pin on bevy-master stays 0.20.0. Permalinks stay unversioned.

Official Documentation

• Assets - Official asset catalog.
• Examples - Example tree on the latest branch.
• Audio examples - Playback, spatial, and control samples.
• ECS - Component, systems, Query, Startup, Update, and .chain().

Related Skills

Prerequisites

• bevy-master - Who owns which piece of state.
• bevy-asset-scenes - AssetServer and Handle.

Complements

• bevy-input-handling - Keys the control example uses.

Downstream / consumers

• None yet. Genre skills that play stingers should route here when they exist.

Master

• bevy-master - Bevy router.