Bevy Audio Controller

An extremely convenient plugin that provides a solid audio controller for Bevy with very minimal boilerplate!

Features

Event Orientated

• Playing a sound is usually the result of a trigger, spawning audio via an event feels natural!
• Avoids unnecessary spawns/inserts of audio components, increasing performance
• Still includes support for ECS design patterns

Automatic Audio File Detection at Build Time

• The build script traverses through your Bevy assets folder and builds convenient structs, enums, component markers, and traits based on the audio files that are compatible with the specified Cargo features
• Removes the need to ever use the AssetServer directly and provides a convenient enum so you can avoid "magic strings" in your code

Channels

• Provides register_audio_channel trait to allow you to easily add multiple audio channels to your app
• Each channel gets its own settings, events, and can be controlled independently with convenient APIs
• AudioChannel derive macro adds convenient methods to the channel marker struct

Tracks

• Defaults for individual tracks can be set per channel
• Settings can still be overridden on a per event basis

Usage

use bevy::{prelude::*, audio::PlaybackSettings};
use bevy_audio_controller::prelude::*;

#[derive(Component, Default, AudioChannel)]
struct SfxChannel;

type SfxEvent = PlayEvent<SfxChannel>;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AudioControllerPlugin)
        .register_audio_channel::<SfxChannel>()
        .add_systems(Update, play_fire)
        .run();
}

fn play_fire(mut ew: EventWriter<SfxEvent>) {
    // even though this is called on every frame, it will only be played once the previous clip has finished
    ew.send(SfxEvent::new(AudioFiles::FireOGG).with_settings(PlaybackSettings::DESPAWN));
}

Cargo Features

default

None

inspect

Adds additional reflection traits to the structs used by this plugin to make them available in bevy-egui-inspector

Requires that channel components must also derive Reflect

// If you are using the `inspect` feature conditionally, you can use the following pattern
#[derive(Component, Default, AudioChannel)]
#[cfg_attr(feature = "inspect", derive(Reflect))]
#[cfg_attr(feature = "inspect", reflect(Component))]
struct SfxChannel;

// Otherwise, this is fine
#[derive(Component, Default, AudioChannel, Reflect)]
#[reflect(Component)]
struct MusicChannel;

mp3

Enables support for MP3 audio files.

ogg

Enables support for OGG audio files

flac

Enables support for FLAC audio files

wav

Enables support for WAV audio files

all-codecs

Enables support for all audio codecs

Examples

All examples require --features="ogg" flag to work. If you would like to view more details with bevy-egui-inspector, run with --all-features instead.

Basic

Demonstrates:

• Utilizing the global audio channel
• Playing an audio clip using the plugin

Inputs:

• Space Bar: Toggles between using the plugin and the standard Bevy audio spawn

  cargo run --example basic --features="ogg"

Channels

Demonstrates:

• Spawning multiple audio channels
• Playing an audio clip using the plugin

  cargo run --example channels --features="ogg"

Event Options

Demonstrates:

• Set the volume for a channel
• Set the default PlaybackSettings for a channel
• Set individual PlaybackSettings for a track
• Insert a track into an entity
• Add a track as a child to another entity
• Override cache with an immediate play event

Inputs:

• Space Bar: Sends an event to ignore the cache and immediate play a track

  cargo run --example event_options --features="ogg"

ECS

Demonstrates:

• How to use this plugin with a more traditional ECS design pattern

Inputs:

• Space Bar: Toggles how not to use DelayMode::Immediate

  cargo run --example ecs --features="ogg"

Delays

Demonstrates:

• Demonstrates how to use the Percent & Milliseconds variations of the DelayMode enum for finer control over when a track is played

  cargo run --example delays --features="ogg"

Volume

Demonstrates:

• Includes a full UI for controlling the volumes of individual channels

Inputs:

• Clicking buttons to adjust volumes

  cargo run --example volume --features="ogg"

Querying

Demonstrates:

• Query for audio components after they've been inserted if you want to use or modify their components in some way
• Use the unique markers that are generated by the build script at compile time for each audio file

  cargo run --example querying --features="ogg"

Bevy support table

bevy	bevy_audio_controller
0.15	0.3
0.14	0.2

Credits

• bevy_embedded_assets for inspiration with the build.rs script
• Assets used in the examples