[![crates.io](https://img.shields.io/crates/v/bevy_seedling)](https://crates.io/crates/bevy_seedling)
[![docs.rs](https://docs.rs/bevy_seedling/badge.svg)](https://docs.rs/bevy_seedling)

A sprouting integration of the [Firewheel](https://github.com/BillyDM/firewheel)
audio engine for [Bevy](https://bevyengine.org/).

`bevy_seedling` is powerful, flexible, and
[fast](https://github.com/CorvusPrudens/rust-audio-demo?tab=readme-ov-file#performance).
You can play sounds, apply effects,
and route audio anywhere. Creating
and integrating custom audio processors
is simple.

## Getting started

First, you'll need to add the dependency to your `Cargo.toml`.
Note that you'll need to disable Bevy's `bevy_audio` feature,
meaning you'll need to specify quite a few features
manually!

<details>
<summary>Example `Cargo.toml`</summary>

```toml
[dependencies]
bevy_seedling = "0.7.2"
bevy = { version = "0.18.0", default-features = false, features = [
  # 2d
  "2d_bevy_render",
  "default_app",
  "picking",
  "scene",

  # 3d
  "3d_bevy_render",

  # ui
  "ui_api",
  "ui_bevy_render",

  # default_platform
  "android-game-activity",
  "bevy_gilrs",
  "bevy_winit",
  "default_font",
  "multi_threaded",
  "std",
  "sysinfo_plugin",
  "wayland",
  "webgl2",
  "x11",
] }
```

</details>

Then, you'll need to add the `SeedlingPlugin` to your app.

```rs
use bevy::prelude::*;
use bevy_seedling::prelude::*;

fn main() {
    App::default()
        .add_plugins((DefaultPlugins, SeedlingPlugin::default()))
        .run();
}
```

Once you've set it all up, playing sounds is easy!

```rs
fn play_sound(mut commands: Commands, server: Res<AssetServer>) {
    // Play a sound!
    commands.spawn(SamplePlayer::new(server.load("my_sample.wav")));

    // Play a sound... with effects :O
    commands.spawn((
        SamplePlayer::new(server.load("my_ambience.wav")).looping(),
        sample_effects![FastLowpassNode::<2>::from_cutoff_hz(500.0)],
    ));
}
```

[The crate docs](https://docs.rs/bevy_seedling/latest) provide an overview of
`bevy_seedling`'s features, and
[the repository's examples](https://github.com/CorvusPrudens/bevy_seedling/tree/master/examples)
should help you get up to speed on common usage patterns.

## Feature flags

| Flag              | Description                                | Default |
| ----------------- | ------------------------------------------ | ------- |
| `reflect`         | Enable `bevy_reflect` derive macros.       | Yes     |
| `rand`            | Enable the `RandomPitch` component.        | Yes     |
| `symphonia`       | Enable symphonia and default asset loader. | Yes     |
| `diagnostics`     | Enable audio thread diagnostics.           | Yes     |
| `wav`             | Enable WAV format and PCM encoding.        | Yes     |
| `ogg`             | Enable Ogg format and Vorbis encoding.     | Yes     |
| `mp3`             | Enable mp3 format and encoding.            | No      |
| `mkv`             | Enable mkv format.                         | No      |
| `adpcm`           | Enable adpcm encoding.                     | No      |
| `flac`            | Enable FLAC format and encoding.           | No      |
| `web_audio`       | Enable the multi-threading web backend.    | No      |
| `rtaudio`         | Enable the native RtAudio backend.         | No      |
| `hrtf`            | Enable HRTF Spatialization.                | No      |
| `hrtf_subjects`   | Enable all HRTF embedded data.             | No      |
| `loudness`        | Enable LUFS analyzer node.                 | No      |
| `effects`         | Enable extra effects and analyzers.        | No      |
| `resample_inputs` | Enable audio input resampling.             | No      |
| `dev`             | Enable helpful features for development.   | No      |
| `entity_names`    | Add `Name`s to node and sample entities.   | No      |
| `track_location`  | Track caller locations in diagnostics.     | No      |

## Bevy version compatibility

| `bevy` | `bevy_seedling` |
| ------ | --------------- |
| 0.18   | 0.7             |
| 0.17   | 0.6             |
| 0.16   | 0.4, 0.5        |
| 0.15   | 0.3             |

#### License

<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>

<br>

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