bevy_kira_audio

The plugin provides two primary ways to manage audio:

1. Audio Channels: You can control an entire channel. Changes to a channel (like volume, panning, or playback speed) affect all sounds playing within that channel. Channels can be customized and accessed via Bevy's ECS.
2. Audio Instances: You can control a single, specific instance of a playing sound independently of its channel.

Both methods support audio transitions using Tweens and various easing functions.

You can explore the capabilities of bevy_kira_audio by running the provided examples. Use the following command to run a specific example:

cargo run --example <example_name>

Available examples include:

• basic: Basic functionality display.
• channel_control: Controlling an audio channel.
• custom_channel: Adding and using a custom audio channel.
• dynamic_channels: Using dynamic audio channels.
• instance_control: Controlling a single audio instance.
• multiple_channels: GUI application with control over three different audio channels.
• settings: Supported settings when playing a sound.
• settings_loader: Loading a sound with applied settings.
• spatial: Limited support for spatial audio.
• status: Continuously getting the playback state of a sound.
• stress_test: Playing a high number of sounds every frame.

cargo run --example basic

To use bevy_kira_audio, you must disable Bevy's default audio feature, as it is incompatible. When configuring your Bevy dependencies, ensure you use the default features minus audio (e.g., "2d", "3d", "ui").

To play audio files, you must enable the corresponding format features in bevy_kira_audio: ogg (enabled by default), mp3, wav, or flac.

use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

fn main() {
   App::new()
        .add_plugins((DefaultPlugins, AudioPlugin))
        .add_systems(Startup, start_background_audio)
        .run();
}

fn start_background_audio(asset_server: Res<AssetServer>, audio: Res<Audio>) {
    audio.play(asset_server.load("background_audio.ogg")).looped();
}

The audio engine is organized into channels. By default, the plugin provides a MainTrack which is exposed via the Audio type alias (type Audio = AudioChannel<MainTrack>;).

• MainTrack: The default channel used for general audio playback.
• AudioChannel<T>: A resource used to play and control sounds on a specific track. You can define your own custom channels using AudioApp::add_audio_channel.

Audio can be organized into channels to allow for grouped control. The Channel enum supports two types of identification:

1. Typed(TypeId): Uses a Rust TypeId for type-safe channel identification.
2. Dynamic(String): Uses a string identifier for flexible, name-based channel management.

#[derive(Clone, PartialEq, Eq, Hash)]
pub enum Channel {
    Typed(TypeId),
    Dynamic(String),
}

If the settings_loader feature is enabled, you can define audio settings in .ron files. This allows you to load an AudioSource that already has specific behaviors (like looping or intros) applied by default.

Example .ron configuration for a looping sound with a 3-second intro:

(
    // The actual sound asset in your assets directory
    asset: "sounds/loop.ogg",

    loop_behavior: Some(3.0),
)

To use bevy_kira_audio, add the AudioPlugin to your Bevy App. This initializes the Audio resource (the default MainTrack), asset loaders for supported formats (MP3, OGG, WAV, FLAC, etc.), and the internal audio management systems.

Note that you must also include Bevy's AssetPlugin for the audio assets to load correctly.

use bevy_kira_audio::prelude easily;
use bevy::prelude easily;
use bevy::asset::AssetPlugin;

fn main() {
    App::new()
        .add_plugins(MinimalPlugins)
        .add_plugins(AssetPlugin::default())
        .add_plugins(AudioPlugin)
        .add_systems(Startup, start_background_audio)
        .run();
}

fn start_background_audio(asset_server: Res<AssetServer>, audio: Res<Audio>) {
    // Play a looped background track
    audio.play(asset_server.load("background_audio.mp3")).looped();
}

To enable spatial audio in your Bevy application, add the SpatialAudioPlugin to your App. This plugin manages the relationship between audio emitters and a receiver, calculating volume attenuation and panning based on their relative positions in 3D space.

use bevy::prelude::*;
use bevy_kira_audio::SpatialAudioPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(SpatialAudioPlugin)
        .run();
}

To use typed audio channels, use the add_audio_channel::<T>() extension method on your Bevy App. This registers the necessary systems and inserts the AudioChannel<T> resource.

1. Define a marker struct for your channel.
2. Call .add_audio_channel::<YourMarker>() during app setup.
3. Access the channel via Res<AudioChannel<YourMarker>> in your systems.

use bevy::prelude::*;
use bevy_kira_audio::prelude::*;

#[derive(Resource)]
struct Background;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AudioPlugin)
        .add_audio_channel::<Background>() // Register the channel
        .add_systems(Startup, setup_audio)
        .run();
}

fn setup_audio(mut background: ResMut<AudioChannel<Background>>, asset_server: Res<AssetServer>) {
    // Use the channel to play a sound
    background.play(asset_server.load("sounds/loop.ogg"));
}