### Example: Setup and Load MP3 Audio

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

A main function example demonstrating how to set up a Bevy application with the AudioPlugin and load an MP3 file. Ensure the 'mp3' feature is enabled in Cargo.toml.

```rust
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Make sure mp3 feature is enabled in Cargo.toml
        .add_plugins(AudioPlugin)
        .add_systems(Startup, load_mp3)
        .run();
}

fn load_mp3(asset_server: Res<AssetServer>, audio: Res<Audio>) {
    audio.play(asset_server.load("sounds/music.mp3"));
}
```

--------------------------------

### Complete Bevy App Setup with Audio

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/11-audio-settings.md

A full example of setting up a Bevy application, including inserting custom AudioSettings before adding the AudioPlugin and defining custom audio channels.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

fn main() {
    let mut app = App::new();
    
    // Add plugins
    app.add_plugins(DefaultPlugins);
    
    // Configure audio before adding the plugin
    app.insert_resource(AudioSettings {
        sound_capacity: 200,
    });
    
    // Add the audio plugin
    app.add_plugins(AudioPlugin);
    
    // Add custom channels
    app.add_audio_channel::<Music>()
        .add_audio_channel::<Effects>()
        .add_audio_channel::<Voice>();
    
    // Add systems
    app.add_systems(Startup, setup)
        .add_systems(Update, gameplay);
    
    app.run();
}

#[derive(Resource)]
struct Music;

#[derive(Resource)]
struct Effects;

#[derive(Resource)]
struct Voice;

fn setup(
    music: Res<AudioChannel<Music>>,
    effects: Res<AudioChannel<Effects>>,
    asset_server: Res<AssetServer>,
) {
    music.play(asset_server.load("bg_music.ogg"))
        .looped()
        .with_volume(-6.0);
}

fn gameplay(
    effects: Res<AudioChannel<Effects>>,
    asset_server: Res<AssetServer>,
    input: Res<ButtonInput<KeyCode>>,
) {
    if input.just_pressed(KeyCode::Space) {
        effects.play(asset_server.load("jump.ogg"));
    }
}
```

--------------------------------

### Multi-Channel Setup and Control Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/06-typed-channels.md

Demonstrates setting up and controlling multiple typed audio channels (Music, Effects, Voice) within a Bevy application. Includes startup logic and update systems for user input.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;
use std::time::Duration;
use kira::Easing;

#[derive(Resource)]
struct Music;

#[derive(Resource)]
struct Effects;

#[derive(Resource)]
struct Voice;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AudioPlugin))
        .add_audio_channel::<Music>()
        .add_audio_channel::<Effects>()
        .add_audio_channel::<Voice>()
        .add_systems(Startup, setup)
        .add_systems(Update, control_channels)
        .run();
}

fn setup(
    music: Res<AudioChannel<Music>>,
    effects: Res<AudioChannel<Effects>>,
    voice: Res<AudioChannel<Voice>>,
    asset_server: Res<AssetServer>
) {
    // Start background music
    music.play(asset_server.load("background.ogg"))
        .looped()
        .with_volume(-6.0);
    
    // Prepare voice channel (paused)
    voice.play(asset_server.load("dialog.ogg"))
        .paused();
    
    // Effects channel is ready for sound effects
}

fn control_channels(
    input: Res<ButtonInput<KeyCode>>,
    music: Res<AudioChannel<Music>>,
    effects: Res<AudioChannel<Effects>>,
    voice: Res<AudioChannel<Voice>>,
    asset_server: Res<AssetServer>
) {
    if input.just_pressed(KeyCode::KeyM) {
        // Mute/unmute music
        if music.is_playing_sound() {
            music.pause()
                .linear_fade_out(Duration::from_millis(500));
        } else {
            music.resume()
                .linear_fade_in(Duration::from_millis(500));
        }
    }
    
    if input.just_pressed(KeyCode::KeyE) {
        // Play a sound effect
        effects.play(asset_server.load("jump.ogg"))
            .with_volume(-3.0);
    }
    
    if input.just_pressed(KeyCode::KeyV) {
        // Start voice dialog
        voice.resume()
            .fade_in(AudioTween::new(
                Duration::from_millis(300),
                Easing::OutQuad
            ));
    }
}
```

--------------------------------

### Full Audio Playback Configuration Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/03-play-audio-command.md

Demonstrates chaining multiple PlayAudioCommand methods for comprehensive audio setup, including volume, looping, panning, fade-in, and obtaining a handle.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;
use std::time::Duration;
use kira::Easing;

fn play_configured_audio(
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    let _instance = audio.play(asset_server.load("background.ogg"))
        .with_volume(-6.0)
        .loop_from(2.0)  // 2-second intro
        .with_playback_rate(1.0)
        .with_panning(0.2)  // Slight right pan
        .fade_in(AudioTween::new(
            Duration::from_secs(2),
            Easing::OutPowi(2)
        ))
        .handle();
}
```

--------------------------------

### Full Audio Resource Initialization Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/13-common-patterns.md

Demonstrates the complete setup for Bevy Kira Audio, including adding plugins, defining audio channels for music and sound effects, and initializing systems for input handling and audio monitoring.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

#[derive(Resource)]
struct Music;

#[derive(Resource)]
struct SoundEffects;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .insert_resource(
            AudioSettings {
                sound_capacity: 256,
            }
        )
        .add_plugins((AudioPlugin, SpatialAudioPlugin))
        .add_audio_channel::<Music>()
        .add_audio_channel::<SoundEffects>()
        .add_systems(Startup, setup)
        .add_systems(Update, (
            handle_input,
            monitor_audio,
        ))
        .run();
}

fn setup(
    music: Res<AudioChannel<Music>>,
    asset_server: Res<AssetServer>,
) {
    music.play(asset_server.load("theme.ogg"))
        .looped()
        .with_volume(-6.0);
}

fn handle_input(
    sfx: Res<AudioChannel<SoundEffects>>,
    asset_server: Res<AssetServer>,
    input: Res<ButtonInput<KeyCode>>,
) {
    if input.just_pressed(KeyCode::Space) {
        sfx.play(asset_server.load("jump.ogg"));
    }
}

fn monitor_audio(
    music: Res<AudioChannel<Music>>,
) {
    if !music.is_playing_sound() {
        println!("No music playing");
    }
}
```

--------------------------------

### Complete Example of Dynamic Audio Channels

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/07-dynamic-channels.md

A full Bevy application demonstrating the setup and management of dynamic audio channels, including creating channels on demand, playing sounds, and controlling playback.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;
use std::time::Duration;

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

fn setup(
    mut channels: ResMut<DynamicAudioChannels>,
    asset_server: Res<AssetServer>
) {
    // Create channels on demand
    let music = channels.create_channel("music");
    music.play(asset_server.load("background.ogg"))
        .looped()
        .with_volume(-6.0);
    
    let effects = channels.create_channel("effects");
    // Ready to play effects
}

fn manage_channels(
    mut channels: ResMut<DynamicAudioChannels>,
    input: Res<ButtonInput<KeyCode>>,
    asset_server: Res<AssetServer>
) {
    // Play sound effect on any available channel
    if input.just_pressed(KeyCode::Space) {
        // Create or access sfx channel
        let sfx = channels.create_channel("sfx");
        sfx.play(asset_server.load("beep.ogg"));
    }
    
    // Create channel for voice dynamically
    if input.just_pressed(KeyCode::KeyV) {
        let voice = channels.create_channel("voice");
        voice.play(asset_server.load("dialog.ogg"));
    }
    
    // Control specific channel
    if input.just_pressed(KeyCode::KeyM) {
        if let Some(music) = channels.get_channel("music") {
            music.pause()
                .linear_fade_out(Duration::from_millis(500));
        }
    }
    
    // Iterate over all channels
    if input.just_pressed(KeyCode::KeyP) {
        for (name, channel) in channels.iter() {
            println!("Channel '{}' is playing: {}", name, channel.is_playing_sound());
        }
    }
    
    // Remove temporary channel
    if input.just_pressed(KeyCode::KeyC) {
        channels.remove_channel("sfx");
    }
}
```

--------------------------------

### Scheduling Systems Before Audio Commands

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/01-audio-plugin.md

Example of scheduling a custom system to run before audio commands are processed. This ensures that any setup or logic in `my_audio_system` completes before the Bevy Kira Audio plugin handles playback or channel commands.

```rust
app.add_systems(
    PostUpdate,
    my_audio_system.before(AudioSystemSet::PlayTypedChannels)
);
```

--------------------------------

### AudioTween::new Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Example demonstrating how to create an AudioTween with a 2-second duration and OutCubic easing.

```rust
use bevy_kira_audio::prelude::*;
use kira::Easing;
use std::time::Duration;

let tween = AudioTween::new(
    Duration::from_secs(2),
    Easing::OutCubic
);
```

--------------------------------

### Complete Example: Music Crossfade with Bevy Kira Audio

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/08-audio-instance.md

Demonstrates a music crossfade system using Bevy Kira Audio. It handles fading out the current music and fading in new music with a specified duration and tweening. Includes components for tracking current music and systems for starting, crossfading, and cleaning up stopped music.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;
use std::time::Duration;

#[derive(Component)]
struct CurrentMusic {
    handle: Handle<AudioInstance>,
}

fn start_music(
    audio: Res<Audio>,
    asset_server: Res<AssetServer>,
    mut commands: Commands
) {
    let instance = audio.play(asset_server.load("theme.ogg"))
        .looped()
        .with_volume(-6.0)
        .handle();
    
    commands.spawn(CurrentMusic { handle: instance });
}

fn crossfade_music(
    query: Query<&CurrentMusic>,
    mut instances: ResMut<Assets<AudioInstance>>,
    asset_server: Res<AssetServer>,
    audio: Res<Audio>,
    input: Res<ButtonInput<KeyCode>>,
) {
    if !input.just_pressed(KeyCode::KeyN) {
        return;
    }
    
    // Fade out current music
    if let Ok(current) = query.get_single() {
        if let Some(instance) = instances.get_mut(&current.handle) {
            instance.set_decibels(
                -60.0,
                AudioTween::linear(Duration::from_secs(2))
            );
        }
    }
    
    // Fade in new music
    let new_instance = audio.play(asset_server.load("new_theme.ogg"))
        .looped()
        .with_volume(-60.0)  // Start silent
        .handle();
    
    if let Some(instance) = instances.get_mut(&new_instance) {
        instance.set_decibels(
            -6.0,
            AudioTween::linear(Duration::from_secs(2))
        );
    }
}

fn cleanup_stopped_music(
    query: Query<(Entity, &CurrentMusic)>,
    instances: Res<Assets<AudioInstance>>,
    mut commands: Commands
) {
    for (entity, current) in query.iter() {
        if let Some(instance) = instances.get(&current.handle) {
            if matches!(instance.state(), PlaybackState::Stopped) {
                commands.entity(entity).despawn();
            }
        }
    }
}
```

--------------------------------

### Smooth Panning Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/13-common-patterns.md

Adjusts audio panning dynamically based on elapsed time to create a smooth panning effect. No specific setup is required beyond having an Audio resource.

```rust
fn smooth_pan(
    audio: Res<Audio>,
    time: Res<Time>,
) {
    let elapsed = time.elapsed_secs();
    let pan = (elapsed * 0.5).sin();
    
    audio.set_panning(pan)
        .fade_in(AudioTween::default());
}
```

--------------------------------

### Basic Bevy Kira Audio Setup

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/14-quick-reference.md

Sets up a Bevy application with the AudioPlugin and plays a sound on startup. Ensure 'sound.ogg' is in the assets folder.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

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

fn setup(audio: Res<Audio>, asset_server: Res<AssetServer>) {
    audio.play(asset_server.load("sound.ogg"));
}
```

--------------------------------

### Example: Load OGG Audio Files

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Demonstrates loading OGG audio files using the asset server and playing them with the Audio resource.

```rust
fn load_ogg(asset_server: Res<AssetServer>, audio: Res<Audio>) {
    audio.play(asset_server.load("sounds/music.ogg"));
    audio.play(asset_server.load("sounds/effect.oga"));
}
```

--------------------------------

### Complete Audio Transition Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Demonstrates various audio transition commands including fade out, fade in with linear and custom easing, and linear fade out.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;
use kira::Easing;
use std::time::Duration;

fn handle_audio_transitions(audio: Res<Audio>) {
    // Fade out when stopping
    audio.stop()
        .fade_out(AudioTween::new(
            Duration::from_secs(2),
            Easing::InCubic
        ));
    
    // Fade in when resuming
    audio.resume()
        .fade_in(AudioTween::linear(Duration::from_millis(500)));
    
    // Fade in during volume change
    audio.set_volume(-10.0)
        .fade_in(AudioTween::new(
            Duration::from_millis(300),
            Easing::OutQuad
        ));
    
    // Simple linear fade (no easing)
    audio.pause()
        .linear_fade_out(Duration::from_secs(1));
}
```

--------------------------------

### Basic AudioPlugin Usage

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/01-audio-plugin.md

Example of adding the AudioPlugin to a Bevy app and playing a background audio file.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

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

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

--------------------------------

### play

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/02-audio-control.md

Starts playing an audio source on the channel and returns a command builder for further configuration.

```APIDOC
## play

### Description
Starts playing an audio source on this channel.

### Method
`play`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **audio_source** (Handle<AudioSource>) - Required - Handle to a loaded audio source asset

### Response
#### Success Response (200)
- Returns a `PlayAudioCommand<'_>` for further configuration.

### Request Example
```rust
fn play_sound(audio: Res<Audio>, asset_server: Res<AssetServer>) {
    let instance = audio.play(asset_server.load("sound.ogg"))
        .with_volume(-6.0)
        .with_playback_rate(1.5)
        .handle();
}
```
```

--------------------------------

### Play Audio with Configuration

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/02-audio-control.md

Starts playing an audio source and allows for immediate configuration of volume and playback rate before handling the playback instance.

```rust
fn play_sound(audio: Res<Audio>, asset_server: Res<AssetServer>) {
    let instance = audio.play(asset_server.load("sound.ogg"))
        .with_volume(-6.0)
        .with_playback_rate(1.5)
        .handle();
}
```

--------------------------------

### Basic Audio Playback Setup

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/README.md

Sets up the Bevy application with the AudioPlugin and plays a background audio file on startup. Ensure the 'bevy_audio' and 'vorbis' features are disabled for Bevy.

```rust
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();
}
```

--------------------------------

### Minimal Bevy Kira Audio Setup

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Sets up the Bevy application with the default audio plugin and plays a looped sound on startup. Requires `bevy_kira_audio::prelude::*` and `bevy::prelude::*`.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

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

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

--------------------------------

### Obtaining an AudioInstance Handle

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/08-audio-instance.md

Shows how to get a handle to an AudioInstance when playing audio, allowing for later control.

```rust
let instance = audio.play(asset_server.load("sound.ogg"))
    .with_volume(-5.0)
    .handle();
```

--------------------------------

### Configure Audio Playback with Options

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Demonstrates configuring audio playback with various options like looping, volume, panning, playback rate, and fade-in effects. The `.handle()` method can be used to get an instance handle for further control.

```rust
audio.play(handle)
    .looped()
    .with_volume(-6.0)
    .with_panning(0.5)
    .with_playback_rate(1.2)
    .fade_in(tween)
    .handle()  // Get instance handle
```

--------------------------------

### AudioTween::linear Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Example of creating a linear tween with a 500ms duration.

```rust
let tween = AudioTween::linear(Duration::from_millis(500));
```

--------------------------------

### Complete Bevy App with Spatial Audio

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Sets up a Bevy application with default plugins, audio, and spatial audio plugins, including systems for setup and entity movement.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(( 
            DefaultPlugins,
            AudioPlugin,
            SpatialAudioPlugin,
        ))
        .add_systems(Startup, setup)
        .add_systems(Update, move_entities)
        .run();
}

fn setup(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>,
) {
    // Receiver (player/camera)
    commands.spawn(( 
        Camera3d::default(),
        Transform::from_xyz(0.0, 2.0, 0.0),
        SpatialAudioReceiver,
    ));

    // Emitter 1: Ambient sound nearby
    let ambient = audio.play(asset_server.load("wind.ogg"))
        .looped()
        .handle();
    
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![ambient],
        },
        SpatialRadius { radius: 15.0 },
        Transform::from_xyz(5.0, 0.0, 5.0),
        Visibility::default(),
    ));

    // Emitter 2: Music from distant speaker
    let music = audio.play(asset_server.load("music.ogg"))
        .looped()
        .with_volume(-3.0)
        .handle();
    
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![music],
        },
        SpatialRadius { radius: 100.0 },  // Can be heard from far away
        Transform::from_xyz(-30.0, 5.0, 0.0),
        Visibility::default(),
    ));
}

fn move_entities(
    mut transforms: Query<&mut Transform, With<SpatialAudioEmitter>>,
    time: Res<Time>,
) {
    // Move emitters around to demonstrate spatial audio
    for mut transform in transforms.iter_mut() {
        transform.translation.x += (time.elapsed_secs().sin()) * 0.5;
    }
}
```

--------------------------------

### AudioTween::with_easing Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Demonstrates chaining a linear tween with a subsequent change to InOutQuad easing.

```rust
let tween = AudioTween::linear(Duration::from_secs(1))
    .with_easing(Easing::InOutQuad);
```

--------------------------------

### Spatial Audio Setup Snippets

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/14-quick-reference.md

Includes snippets for setting up and configuring spatial audio. This involves adding the `SpatialAudioPlugin` and defining components for receivers and emitters.

```rust
.add_plugins(SpatialAudioPlugin)
```

```rust
SpatialAudioReceiver component
```

```rust
SpatialAudioEmitter { instances: vec![...] }
```

```rust
DefaultSpatialRadius { radius: 50.0 }
```

```rust
SpatialRadius { radius: 100.0 } component
```

--------------------------------

### Play Audio with Asset Server

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Example of loading an audio source using Bevy's asset server and playing it. Ensure the audio asset is placed in the appropriate assets directory.

```rust
fn play_audio(
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    let source = asset_server.load("sounds/music.ogg");
    audio.play(source).looped();
}
```

--------------------------------

### Direct Audio Playback

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Simple example of playing an audio file directly using the audio system and asset server.

```rust
audio.play(asset_server.load("sounds/jump.ogg"));
```

--------------------------------

### RON Configuration for Audio Playback

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Example of a RON file to configure audio playback settings like looping and volume.

```ron
(
    file: "sounds/background.ogg",
    loop_region: Some((start: 2.0, end: Some(15.0))),
    volume: -6.0,
    fade_in_tween: Some(2000),
)
```

--------------------------------

### Start Audio Paused

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/03-play-audio-command.md

Starts the audio in a paused state. Playback can be resumed later by calling resume() on the channel. This is useful for preloading audio without immediate playback.

```rust
let handle = audio.play(asset_server.load("sound.ogg"))
    .paused()
    .handle();
```

--------------------------------

### Install SpatialAudioPlugin

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Add SpatialAudioPlugin to your Bevy application along with DefaultPlugins and AudioPlugin. This enables spatial audio processing.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

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

--------------------------------

### Bevy Kira Audio Setup with Custom Channels

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Configures the Bevy application with custom, type-safe audio channels for music and effects. Requires defining resources for each channel type and adding them using `.add_audio_channel::<T>()`.

```rust
#[derive(Resource)]
struct Music;

#[derive(Resource)]
struct Effects;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AudioPlugin))
        .add_audio_channel::<Music>()
        .add_audio_channel::<Effects>()
        .add_systems(Startup, setup)
        .run();
}

fn setup(
    music: Res<AudioChannel<Music>>,
    effects: Res<AudioChannel<Effects>>,
    asset_server: Res<AssetServer>,
) {
    music.play(asset_server.load("theme.ogg")).looped();
    // Effects channel ready for dynamic sounds
}
```

--------------------------------

### TweenCommand::fade_out Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Example of pausing audio with a 500ms fade-out using InCubic easing.

```rust
use bevy_kira_audio::prelude::*;
use kira::Easing;
use std::time::Duration;

audio.pause()
    .fade_out(AudioTween::new(
        Duration::from_millis(500),
        Easing::InCubic
    ));
```

--------------------------------

### Start Playback from Position

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/03-play-audio-command.md

Begins audio playback from a specified position in seconds. This is useful for resuming playback at a particular point in a track.

```rust
audio.play(asset_server.load("sound.ogg"))
    .start_from(5.0);
```

--------------------------------

### AudioInstanceAssetsExt

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/12-types-reference.md

Provides a convenience method to get the playback state of an AudioInstance using its handle.

```APIDOC
## AudioInstanceAssetsExt

### Description
Provides a convenience method to get the playback state of an AudioInstance using its handle.

### Provides convenience method
`Assets<AudioInstance>::state(handle)`
```

--------------------------------

### Setup Mixed Emitters with Custom Radius

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Spawns entities with spatial audio emitters, demonstrating the use of both default and custom radii for attenuation.

```rust
fn setup_mixed_emitters(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    // Uses DefaultSpatialRadius (25.0 units)
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![audio.play(asset_server.load("normal.ogg")).handle()],
        },
        Transform::from_xyz(10.0, 0.0, 0.0),
        Visibility::default(),
    ));
    
    // Uses custom radius (100.0 units)
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![audio.play(asset_server.load("loudspeaker.ogg")).handle()],
        },
        SpatialRadius { radius: 100.0 },
        Transform::from_xyz(-10.0, 0.0, 0.0),
        Visibility::default(),
    ));
}
```

--------------------------------

### Setup Far Away Emitter

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Spawns an entity with a spatial audio emitter that can be heard from a significant distance.

```rust
fn setup_far_away_emitter(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    let sound = audio.play(asset_server.load("distant_thunder.ogg"))
        .looped()
        .handle();
    
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![sound],
        },
        SpatialRadius { radius: 200.0 },  // Heard from far away
        Transform::from_xyz(100.0, 0.0, 0.0),
        Visibility::default(),
    ));
}
```

--------------------------------

### Setup SpatialAudioEmitter with Sound

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Spawns an entity with a SpatialAudioEmitter component, attaching a looped sound instance to it. The entity also requires Transform and Visibility components.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

fn setup_emitter(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    let sound_instance = audio.play(asset_server.load("footsteps.ogg"))
        .looped()
        .handle();
    
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![sound_instance],
        },
        Transform::from_xyz(5.0, 0.0, 0.0),
        Visibility::default(),
    ));
}
```

--------------------------------

### Setup Spatial Audio Emitter and Receiver

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/13-common-patterns.md

Configures a 3D camera as the spatial audio receiver and spawns an entity with an `SpatialAudioEmitter` component as the sound source. Requires `Camera3d`, `SpatialAudioReceiver`, `SpatialAudioEmitter`, and `SpatialRadius` components.

```rust
#[derive(Component)]
struct SoundEmitter;

fn setup_spatial(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>,
) {
    // Receiver (player/camera)
    commands.spawn(( 
        Camera3d::default(),
        Transform::from_xyz(0.0, 5.0, 0.0),
        SpatialAudioReceiver,
    ));
    
    // Emitter
    let sound = audio.play(asset_server.load("ambient.ogg"))
        .looped()
        .handle();
    
    commands.spawn(( 
        SpatialAudioEmitter {
            instances: vec![sound],
        },
        SpatialRadius { radius: 30.0 },
        Transform::from_xyz(10.0, 0.0, 10.0),
        SoundEmitter,
    ));
}
```

--------------------------------

### Setup SpatialAudioReceiver

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Spawns an entity with the SpatialAudioReceiver component, typically associated with the camera. Ensure only one receiver exists per scene to avoid panics.

```rust
fn setup_receiver(mut commands: Commands) {
    commands.spawn(( 
        Camera3d::default(),
        Transform::from_xyz(0.0, 5.0, 0.0),
        SpatialAudioReceiver,
    ));
}
```

--------------------------------

### Custom Audio Channel Usage with AudioApp

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/01-audio-plugin.md

Example of using the add_audio_channel method to create and use custom audio channels for background music and sound effects.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

#[derive(Resource)]
struct BackgroundMusic;

#[derive(Resource)]
struct SoundEffects;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AudioPlugin))
        .add_audio_channel::<BackgroundMusic>()
        .add_audio_channel::<SoundEffects>()
        .add_systems(Startup, setup)
        .run();
}

fn setup(
    music: Res<AudioChannel<BackgroundMusic>>,
    sfx: Res<AudioChannel<SoundEffects>>,
    asset_server: Res<AssetServer>
) {
    music.play(asset_server.load("music.ogg")).looped();
    sfx.play(asset_server.load("jump.ogg"));
}
```

--------------------------------

### RON Configuration Format for SettingsLoader

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Example of a RON configuration file used with SettingsLoader to specify audio playback parameters such as file path, loop region, volume, and playback rate.

```ron
(
    file: "sounds/background.ogg",
    start_position: 0.0,
    loop_region: Some((start: 2.0, end: Some(10.0))),
    volume: -6.0,
    playback_rate: 1.0,
    panning: 0.0,
    reverse: false,
    fade_in_tween: Some(2000),  // milliseconds
)
```

--------------------------------

### Adding a Custom Typed Audio Channel

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/06-typed-channels.md

Demonstrates how to add a custom typed audio channel (MyChannel) to a Bevy application during setup. This involves using add_audio_channel::<T>().

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

#[derive(Resource)]
struct MyChannel;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AudioPlugin))
        .add_audio_channel::<MyChannel>()
        .add_systems(Startup, play_audio)
        .run();
}

fn play_audio(channel: Res<AudioChannel<MyChannel>>, asset_server: Res<AssetServer>) {
    channel.play(asset_server.load("sound.ogg"));
}
```

--------------------------------

### Configuring Sound Playback Settings

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/README.md

Plays an audio file with custom settings including loop start, fade-in, panning, playback rate, volume, and reverse playback. Requires the 'ogg' feature to be enabled.

```rust
use bevy_kira_audio::prelude::*
use bevy::prelude::*
use std::time::Duration;

fn play_audio(asset_server: Res<AssetServer>, audio: Res<Audio>) {
    audio.play(asset_server.load("background_audio.ogg"))
        // The first 0.5 seconds will not be looped and are the "intro"
        .loop_from(0.5)
        // Fade-in with a dynamic easing
        .fade_in(AudioTween::new(Duration::from_secs(2), AudioEasing::OutPowi(2)))
        // Only play on our right ear
        .with_panning(1.0)
        // Increase playback rate by 50% (this also increases the pitch)
        .with_playback_rate(1.5)
        // Play at lower volume (-10dB)
        .with_volume(-10.)
        // play the track reversed
        .reverse();
}
```

--------------------------------

### Control Audio Channels

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Provides examples for controlling audio channels, including setting volume, panning, playback rate, and managing playback state (pause, resume, stop).

```rust
audio.set_volume(-10.0)
audio.set_panning(0.5)
audio.set_playback_rate(1.5)
audio.pause()
audio.resume()
audio.stop()
```

--------------------------------

### Control Individual Audio Instance

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Shows how to get a handle to an individual audio instance and later control its properties such as volume and playback position. Requires mutable access to the instances collection.

```rust
let instance = audio.play(handle).handle();
// Later...
if let Some(sound) = instances.get_mut(&instance) {
    sound.set_decibels(-3.0, tween);
    sound.seek_to(5.0);
}
```

--------------------------------

### Get Handle for Audio Instance Control

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/03-play-audio-command.md

Retrieve a handle to control the audio instance directly. This handle can be used to check the audio state later.

```rust
pub fn handle(&mut self) -> Handle<AudioInstance>;
```

```rust
let instance = audio.play(asset_server.load("sound.ogg"))
    .with_volume(-5.0)
    .handle();

// Later, check the state
let state = audio.state(&instance);
```

--------------------------------

### Get Playback Position Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/05-playback-state.md

Demonstrates how to retrieve the current playback position from an audio state. Returns None for Queued or Stopped states.

```rust
let state = audio.state(&instance);
if let Some(pos) = state.position() {
    println!("Current position: {:.2}s", pos);
} else {
    println!("Position unknown");
}
```

--------------------------------

### Get Dynamic Audio Channel by Key (Panics on Not Found)

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/07-dynamic-channels.md

Retrieves a reference to a dynamic audio channel using its string key. This method will panic if a channel with the specified key does not exist.

```rust
fn play_music(channels: Res<DynamicAudioChannels>, asset_server: Res<AssetServer>) {
    let music = channels.channel("music");
    music.play(asset_server.load("theme.ogg")).looped();
}
```

--------------------------------

### TweenCommand::linear_fade_out Example

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/04-tween-command.md

Example of stopping audio with a 1-second linear fade-out.

```rust
audio.stop()
    .linear_fade_out(Duration::from_secs(1));
```

--------------------------------

### Configure AudioSettings Before Plugin Addition

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/01-audio-plugin.md

Demonstrates how to configure audio backend settings by inserting an AudioSettings resource before adding the AudioPlugin.

```rust
use bevy_kira_audio::prelude::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .insert_resource(AudioSettings {
            sound_capacity: 256,  // Increase maximum simultaneous sounds
        })
        .add_plugins(AudioPlugin)
        .run();
}
```

--------------------------------

### Get Current Audio Position

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/05-playback-state.md

A utility function to get the current playback position of an audio instance, returning an Option<f64>.

```rust
fn get_position(audio: Res<Audio>, instance: &Handle<AudioInstance>) -> Option<f64> {
    audio.state(instance).position()
}
```

--------------------------------

### Play Audio with Options

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/README.md

Demonstrates playing an audio handle with various options such as looping, setting volume, and applying a fade-in effect.

```rust
audio.play(handle)
    .looped()
    .with_volume(-6.0)
    .fade_in(tween)
    .handle()
```

--------------------------------

### AudioInstanceAssetsExt Trait

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/12-types-reference.md

Provides a convenience method for getting the state of an AudioInstance.

```rust
pub trait AudioInstanceAssetsExt {
    fn state(&self, &Handle<AudioInstance>) -> PlaybackState;
}

impl AudioInstanceAssetsExt for Assets<AudioInstance> { }
```

--------------------------------

### Loading Configured Audio in Rust

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/09-audio-source.md

Demonstrates how to load an audio file using its RON configuration in a Bevy application.

```rust
fn load_configured_audio(
    audio: Res<Audio>,
    asset_server: Res<AssetServer>
) {
    // Loads background.ogg with pre-configured settings
    audio.play(asset_server.load("sounds/background.ogg.ron"));
}
```

--------------------------------

### Get AudioInstance Playback State

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/08-audio-instance.md

Retrieves the current playback state of an audio instance, such as Playing or Stopped.

```rust
fn check_status(
    instance_handle: &Handle<AudioInstance>,
    instances: Res<Assets<AudioInstance>>,
) {
    if let Some(instance) = instances.get(instance_handle) {
        match instance.state() {
            PlaybackState::Playing { position } => {
                println!("Playing at {:.2}s", position);
            }
            PlaybackState::Stopped => {
                println!("Playback finished");
            }
            _ => {}
        }
    }
}
```

--------------------------------

### Handling Audio Manager Initialization Failure

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/11-audio-settings.md

Illustrates how the system logs a warning if the audio backend fails to initialize, allowing the application to continue running without audio.

```rust
// From audio_output.rs
if let Err(ref setup_error) = manager {
    warn!("Failed to setup audio: {:?}", setup_error);
}
```

--------------------------------

### Inserting and Consuming AudioSettings

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/11-audio-settings.md

Demonstrates inserting the AudioSettings resource and how it is consumed by the AudioPlugin. Accessing AudioSettings after the plugin is added will result in a panic.

```rust
fn main() {
    App::new()
        .insert_resource(AudioSettings {
            sound_capacity: 200,
        })
        .add_plugins(AudioPlugin);  // AudioSettings consumed here
        // AudioSettings no longer available after this point
        .run();
}
```

```rust
fn check_settings(settings: Res<AudioSettings>) {
    // This will panic because AudioSettings was consumed by AudioPlugin
}

fn main() {
    App::new()
        .insert_resource(AudioSettings { sound_capacity: 200 })
        .add_plugins(AudioPlugin)
        .add_systems(Startup, check_settings)  // Will panic!
        .run();
}
```

--------------------------------

### Storage Pattern for Audio Instance Handles

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/08-audio-instance.md

Illustrates a common pattern for storing `Handle<AudioInstance>` within Bevy components. This allows for easy querying and control of individual audio instances, such as applying volume changes.

```rust
#[derive(Component)]
struct SoundEffect {
    instance: Handle<AudioInstance>,
}

#[derive(Component)]
struct Music {
    instance: Handle<AudioInstance>,
}
```

```rust
fn fade_music(
    query: Query<&Music>,
    mut instances: ResMut<Assets<AudioInstance>>
) {
    for music in query.iter() {
        if let Some(instance) = instances.get_mut(&music.instance) {
            instance.set_decibels(-3.0, AudioTween::default());
        }
    }
}
```

--------------------------------

### Audio Configuration Snippet

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/14-quick-reference.md

Configures the audio system by setting the sound capacity. The default capacity is 128 sounds.

```rust
.insert_resource(AudioSettings { sound_capacity: 256 })
```

--------------------------------

### Loop from Specific Position

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/03-play-audio-command.md

Enables looping of audio, starting from a specified position in seconds. This is useful for music tracks with intros that should be played once before looping.

```rust
audio.play(asset_server.load("music.ogg"))
    .loop_from(2.0);
```

--------------------------------

### Store Audio Instance Handle

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/13-common-patterns.md

Play audio and store its `Handle<AudioInstance>` in a Bevy component for later control. This is useful for managing individual sounds, like background music. Requires `Commands`, `Audio`, and `AssetServer` resources.

```rust
#[derive(Component)]
struct CurrentMusic {
    instance: Handle<AudioInstance>,
}

fn play_music(
    mut commands: Commands,
    audio: Res<Audio>,
    asset_server: Res<AssetServer>,
) {
    let instance = audio.play(asset_server.load("music.ogg"))
        .looped()
        .handle();
    
    commands.spawn(CurrentMusic { instance });
}
```

--------------------------------

### Playing Audio Snippets

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/14-quick-reference.md

Demonstrates various ways to play audio, including looping, setting volume, speed, and panning. These methods are called on an `Audio` resource.

```rust
audio.play(handle)
```

```rust
audio.play(handle).looped()
```

```rust
audio.play(handle).paused()
```

```rust
audio.play(handle).with_volume(-6.0)
```

```rust
audio.play(handle).with_playback_rate(1.5)
```

```rust
audio.play(handle).with_panning(0.5)
```

```rust
audio.play(handle).fade_in(tween)
```

```rust
audio.play(handle).handle()
```

--------------------------------

### Accessing and Controlling an AudioInstance

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/08-audio-instance.md

Demonstrates how to access an AudioInstance from the Assets collection using its handle to perform control operations.

```rust
fn control_instance(
    instance_handle: &Handle<AudioInstance>,
    mut instances: ResMut<Assets<AudioInstance>>,
) {
    if let Some(instance) = instances.get_mut(instance_handle) {
        // Control the instance
    }
}
```

--------------------------------

### Configuration and Settings

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/INDEX.txt

Information on configuring the audio system, including settings for sound capacity, feature flags for format support, and system scheduling.

```APIDOC
## Configuration and Settings

### Description
Allows customization of the audio plugin's behavior and resource management.

### Configuration Options

- **AudioSettings**: Configures the capacity and behavior of the audio system.
- **Feature flags**: Enable or disable support for specific audio formats (ogg, mp3, wav, flac) and features like settings loading.
- **System scheduling**: Defines the order and conditions under which audio systems run using `AudioSystemSet`.
```

--------------------------------

### Change Default Spatial Radius

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/10-spatial-audio.md

Modifies the DefaultSpatialRadius resource to alter the attenuation range for all spatial audio emitters. This can be done during setup or at app initialization.

```rust
fn setup(mut spatial_config: ResMut<DefaultSpatialRadius>) {
    spatial_config.radius = 50.0;  // Double the default range
}
```

```rust
fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AudioPlugin, SpatialAudioPlugin))
        .insert_resource(DefaultSpatialRadius { radius: 40.0 })
        .add_systems(Startup, setup)
        .run();
}
```

--------------------------------

### Storing AudioSettings Configuration Separately

Source: https://github.com/niklasei/bevy_kira_audio/blob/main/_autodocs/11-audio-settings.md

Shows how to store the audio capacity in a custom resource before adding the AudioPlugin to retain access to the configuration.

```rust
#[derive(Resource)]
struct AudioConfig {
    capacity: usize,
}

fn main() {
    let capacity = 200;
    
    App::new()
        .insert_resource(AudioSettings { sound_capacity: capacity })
        .insert_resource(AudioConfig { capacity })  // Store it separately
        .add_plugins(AudioPlugin)
        .run();
}
```