bevy/examples/audio/audio_control.rs
mgi388 90b2ba1859
Rename AudioSinkPlayback::toggle to toggle_playback (#16837)
# Objective

- #16813 added the ability to mute sinks and added a new method
`toggle_mute()`.
- Leaving `toggle()` as is creates inconsistency and a bit of confusion
about what is being toggled.

## Solution

- Rename `toggle()` to `toggle_playback()`.
- The choice to use the `_playback` suffix was easy because the method
comment was already telling us what is being toggled: `Toggles playback
of the sink.`
- [Raised in Discord] and got the OK from Alice.

[Raised in Discord]:
https://discord.com/channels/691052431525675048/749430447326625812/1318000355824504905

## Testing

- I ran the example and also updated the instruction text to make it
clear `Space` is toggling the playback not just pausing.
- I added a unit test for `toggle_playback()` because why not.

---

## Showcase

Example instructions:

<img width="292" alt="image"
src="https://github.com/user-attachments/assets/585c36c6-c4d7-428b-acbe-a92f3a37b460"
/>

## Migration Guide

- `AudioSinkPlayback`'s `toggle` method has been renamed to
`toggle_playback`. This was done to create consistency with the
`toggle_mute` method added in
https://github.com/bevyengine/bevy/pull/16813. Change instances of
`toggle` to `toggle_playback`. E.g.:

Before:

```rust
fn pause(keyboard_input: Res<ButtonInput<KeyCode>>, sink: Single<&AudioSink>) {
    if keyboard_input.just_pressed(KeyCode::Space) {
        sink.toggle();
    }
}
```

After:

```rust
fn pause(keyboard_input: Res<ButtonInput<KeyCode>>, sink: Single<&AudioSink>) {
    if keyboard_input.just_pressed(KeyCode::Space) {
        sink.toggle_playback();
    }
}
```
2024-12-16 19:28:24 +00:00

68 lines
1.8 KiB
Rust

//! This example illustrates how to load and play an audio file, and control how it's played.
use bevy::{math::ops, prelude::*};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, (update_speed, pause, mute, volume))
.run();
}
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
commands.spawn((
AudioPlayer::new(asset_server.load("sounds/Windless Slopes.ogg")),
MyMusic,
));
// example instructions
commands.spawn((
Text::new("-/=: Volume Down/Up\nSpace: Toggle Playback\nM: Toggle Mute"),
Node {
position_type: PositionType::Absolute,
bottom: Val::Px(12.0),
left: Val::Px(12.0),
..default()
},
));
// camera
commands.spawn(Camera3d::default());
}
#[derive(Component)]
struct MyMusic;
fn update_speed(sink: Single<&AudioSink, With<MyMusic>>, time: Res<Time>) {
sink.set_speed((ops::sin(time.elapsed_secs() / 5.0) + 1.0).max(0.1));
}
fn pause(keyboard_input: Res<ButtonInput<KeyCode>>, sink: Single<&AudioSink, With<MyMusic>>) {
if keyboard_input.just_pressed(KeyCode::Space) {
sink.toggle_playback();
}
}
fn mute(
keyboard_input: Res<ButtonInput<KeyCode>>,
mut sink: Single<&mut AudioSink, With<MyMusic>>,
) {
if keyboard_input.just_pressed(KeyCode::KeyM) {
sink.toggle_mute();
}
}
fn volume(
keyboard_input: Res<ButtonInput<KeyCode>>,
mut sink: Single<&mut AudioSink, With<MyMusic>>,
) {
if keyboard_input.just_pressed(KeyCode::Equal) {
let current_volume = sink.volume();
sink.set_volume(current_volume + 0.1);
} else if keyboard_input.just_pressed(KeyCode::Minus) {
let current_volume = sink.volume();
sink.set_volume(current_volume - 0.1);
}
}