devela::_dep::kira

Module modulator

Available on crate feature dep_kira only.
Expand description

Global values that parameters (like volume and playback rate) can be linked to.

Any type that implements ModulatorBuilder can be added to an audio manager by using AudioManager::add_modulator.

If needed, you can create custom modulators by implementing the ModulatorBuilder and Modulator traits.

§Why modulators?

Many properties of things in Kira, like the volumes of sounds, can be smoothly transitioned from one value to another without the use of modulators. Modulators become handy when:

  • You want to control multiple properties of objects in lockstep
  • You need to change a property in a way that’s more complicated than a simple transition

§Tweener example

Let’s say we have a music track with two layers that play simultaneously: drums and piano. When the player character enters water, we want the music to sound “underwater”, so we’ll fade out the drums and make the piano sound more muffled using a low-pass filter.

For this situation, a tweener is appropriate. Tweeners hold a value that doesn’t change until we tell it to, and the value can be smoothly transitioned.

The tweener is an input value that will generate multiple output values: the drums volume and piano filter frequency. When the tweener is set to 0.0, that represents that the player is not underwater, and when it’s 1.0, the player is submerged. (These are arbitrary values.)

Tweener valueDrums volumePiano filter frequency
0.01.020,000 Hz
1.00.0500 Hz

First, let’s create the tweener:

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	modulator::tweener::TweenerBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let mut tweener = manager.add_modulator(TweenerBuilder { initial_value: 0.0 })?;

Next, we’ll create a mixer track with a low-pass filter effect. The piano will play on this track so we can make it sound more or less muffled.

use kira::{
	effect::filter::FilterBuilder,
	Mapping, Value, Easing,
	track::TrackBuilder,
};

let filter_builder = FilterBuilder::new()
	.cutoff(Value::from_modulator(&tweener, Mapping {
		input_range: (0.0, 1.0),
		output_range: (20_000.0, 500.0),
		easing: Easing::Linear,
	}));
let mut piano_track = manager.add_sub_track(TrackBuilder::new().with_effect(filter_builder))?;

We use a Mapping to map the input values of the tweener to the output values of the filter cutoff frequency.

Finally, we’ll play the sounds:

use kira::sound::static_sound::StaticSoundData;

piano_track.play(StaticSoundData::from_file("piano.ogg")?)?;
manager.play(
	StaticSoundData::from_file("drums.ogg")?
		.volume(Value::from_modulator(&tweener, Mapping {
			input_range: (0.0, 1.0),
			output_range: (Decibels::IDENTITY, Decibels::SILENCE),
			easing: Easing::Linear,
		}))
)?;

Notice how we also use a Mapping to map the input range of the tweener to the output values of the sound volume.

Once the player goes underwater, we can smoothly transition the tweener’s value from 0.0 to 1.0, which will automatically change the drum volume and piano filter frequency.

use kira::Tween;
use std::time::Duration;

tweener.set(1.0, Tween {
	duration: Duration::from_secs(3),
	..Default::default()
});

Modules§

  • lfo
    Oscillates back and forth.
  • tweener
    Smoothly transitions values to other values.

Structs§

Traits§