yjpark / bevy_kira_audio

A Bevy plugin to use Kira for game audio

Bevy Kira audio

This bevy plugin is intended to test an integration of Kira into Bevy. The goal is to replace or update bevy_audio, if Kira turns out to be a good approach. Currently, this plugin can play ogg, mp3, flac, and wav formats and supports web builds.

Sound can be played in channels. Each channel has controls to pause or stop playback and can change the volume, playback speed, and panning of all sounds playing in it. You can easily add new channels and access them through Bevy's ECS (see the custom_channel example).

Usage

Note: the Bevy feature bevy_audio is enabled by default and not compatible with this plugin. Make sure to not have the bevy_audio feature enabled if you want to use bevy_kira_audio. The same goes for Bevy's vorbis feature. See Bevys' Cargo file for a list of all default features of version 0.8 and list them manually in your Cargo file excluding the ones you do not want. Make sure to set default-features to false for the Bevy dependency. You can take a look at bevy_game_template's cargo file as an example.

To play audio, you usually want to load audio files as assets. This requires AssetLoaders. bevy_kira_audio comes with loaders for most common audio formats. You can enable them with the features ogg (enabled by default), mp3, wav, or flac. The following example assumes that the feature ogg is enabled.

use bevy_kira_audio::{Audio, AudioPlugin};
use bevy::prelude::*;

fn main() {
   App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(AudioPlugin)
        .add_startup_system(start_background_audio)
        .run();
}

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

Sound with custom settings

Requires feature settings_loader

It is possible to load sounds with custom settings from ron files. A common example would be a loop with an intro. Loading a ron file like this:

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

    loop_behavior: Some(3.0),
)

would make the loaded sound loop by default and start each repeated playback three seconds into the sound (the three seconds are the intro).

More settings are available. See the settings_loader example for all options.

Current and planned features

• play common audio formats
  • ogg
  • mp3
  • wav
  • flac
• web support
  • There are some differences between browsers:
    • Chrome requires an interaction with the website to play audio (e.g. a button click). This issue can be resolved with a script in your index.html file (usage example).
    • Firefox: The audio might sound distorted (this could be related to overall performance; see issue #9)
• pause/resume and stop tracks
• play a track on repeat
• control volume
• control playback rate
• control pitch (no change in playback rate)
• control panning
• get the current status and position of a track (see the status example)
• audio streaming

Compatible Bevy versions

The main branch is compatible with the latest Bevy release.

Compatibility of bevy_kira_audio versions:

bevy_kira_audio	bevy
0.11	0.8
0.9 - 0.10	0.7
0.8	0.6
0.4 - 0.7	0.5
0.3	0.4
main	0.8
bevy_main	main

License

Dual-licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Assets in the examples might be distributed under different terms. See the readme in the examples directory.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.