Micro MusicBox

Play some tunes

What?

This library provides a convenience wrapper around bevy_kira_audio, handling all the setup for the common game audio scenario. This includes channel management, giving you control of the audio levels for your music, ambiance, sound effects and UI separately from the start.

Channel Types

Musicbox is configured with 4 channels, which a re split into two types:

• Main channels; Play a single looped audio track. Starting another track on this channel will stop the currently active one. Supports cross-fade between the current track and the next track. This includes the "Music" and "Ambiance" channels
• Background Channels; Plays any number of one-shot sounds. The sounds will not interfere with each other or the main channels. This includes the "SFX" and "UI SFX" channels

Volume

Volume is calculated by multiplying a given channel's volume setting by the master volume setting. This means you can let players adjust either the overall game volume, or each of the three types individually. The 4 channels are assigned as such:

• "music" -> music volume * master volume
• "ambiance" & "sfx" -> sfx volume * master volume
• "ui sfx" -> ui volume * master volume

There are two types of channel: Singleton "main" channels, and multi-sound channels. Audio played on a main channel will loop until stopped, and will replace any currently playing audio on that same channel. multi-sound channels work exactly as they, well, sound - play one-off sounds without worrying about coordinating them with other sources.

Main channels also expose a cross-fade feature - either a basic cross-fade, in which the same audio tween is applied to the outgoing and incoming music tracks, or an in-out fade where the two tracks can have independent tweens.

How?

Quickstart

• Implement SuppliesAudio for a resource (or use the built-in impl on AssetServer)
• Include the MusixBocPlugin plugin, or the CombinedAudioPlugins plugin group in your app, providing your SuppliesAudio impl as the generic parameter
• Use MusicBox<T: SuppliesAudio> as a parameter on a system
• Call one of the MusicBox::play_* methods to play sounds

fn main() {
    App::new()
        .add_plugins(CombinedAudioPlugins::<AssetServer>::new())
        .add_startup_system(|mut music_box: MusicBox<AssetServer>| {
            music_box.play_music("music/bing_bong.mp3");
        });
}

In-Depth

There is a plugin that just provides the layering on top of bevy_kira_audio if you are already integrating with it, and a plugin group that will setup and configure bevy_kira_audio for you if not. Some bevy_ira_audio types are re-exported, so you can depend solely on micro_bevy_musicbox if you don't have any advanced needs.

use micro_bevy_musicbox::{CombinedAudioPlugins, MusicBoxPlugin};

// Either
fn main() {
    App::new()
        .add_plugin(MusicBoxPlugin);
}

// Or
fn main() {
    App::new()
        .add_plugins(CombinedAudioPlugins);
}

In order to use the the MusicBox type, you will need to implement the SuppliesAudio trait on a resource. This resource will need to be able to retrieve the requested audio track by name, although the specifics of what that name represents will depend on how you implement the trait.

Out of the box, there is a SuppliesAudio impl for AssetServer, allowing you to use resource paths. It is, however, recommended that you create your own impl for your own resource type.

/// An example storage resource that allows assets to be retrieved by name,
/// rather than by file path
#[derive(Resource)]
pub struct AssetHandles {
    // ...Other types...
    pub sounds: HashMap<String, Handle<AudioSource>>,
}

impl SuppliesAudio for AssetHandles {
	fn get_audio_track<T: ToString>(&self, name: T) -> Option<Handle<AudioSource>> {
		self.sounds.get(&name.to_string()).map(Handle::clone_weak)
	}
}

Finally, you need to use the MusicBox type as a SystemParam, alongside your SuppliesAudio impl. There is no binding of between MusicBox and SuppliesAudio, so you can use different impls in different systems as you please, as long as the SuppliesAudio resource has been added to your world

/// A simple event that causes a sound effect to be played.
/// N.B. In a real game, you probably just want to directly play a sound without events
pub struct PlaySoundEvent {
    pub sound: String,
}

// ...Register your event to your app...

/// A system that reads PlaySoundEvent events and plays the sound effect, using the
/// previously created `AssetHandles` resource as a supplier
pub fn play_sounds(
    mut events: EventReader<PlaySoundEvent>,
    music_box: MusicBox<AssetHandles>,
) {
    for PlaySoundEvent { sound } in events.iter() {
        music_box.play_effect_once(sound);
    }
}

Asset Licenses

The examples in this repository use assets available under the following licenses:

• The-Great-Madeja.mp3 by Rolemusic is licensed under a CC-BY-4.0 Attribution License.
• The-White-Kitty.mp3 by Rolemusic is licensed under a CC-BY-4.0 Attribution License.
• KenneyBlocks.ttf by Kenney is licensed under a CC-0 Public Domain License

Compatibility