devela::_dep::kira

Module track

Available on crate feature dep_kira only.
Expand description

Organizes and applies effects to audio.

Kira has an internal mixer which works like a real-life mixing console. Sounds can be played on “tracks”, which are individual streams of audio that can optionally have effects that modify the audio.

Tracks can also be spatialized, which gives them a position in a 3D space relative to a listener. The distance from the listener can be used to drive settings on effects on that track.

§Creating and using tracks

The mixer has a “main” track by default, and you can add any number of sub-tracks. To add a sub-track, use AudioManager::add_sub_track.

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	track::TrackBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let mut track = manager.add_sub_track(TrackBuilder::default())?;

To play a sound on the track, use TrackHandle::play.

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

track.play(StaticSoundData::from_file("sound.ogg")?)?;

Tracks can themselves have sub-tracks. You can create them using TrackHandle::add_sub_track.

You can set the volume of a track using TrackHandle::set_volume. The volume setting will affect all sounds being played on the track as well as all child tracks.

You can pause all sounds (and child tracks) of a track using TrackHandle::pause and resume them using TrackHandle::resume or TrackHandle::resume_at.

§Effects

You can add effects to the track when creating it using TrackBuilder::with_effect. All sounds that are played on that track will have the effects applied sequentially.

In this example, we’ll use the filter effect, which in the low pass mode will remove high frequencies from sounds, making them sound muffled.

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	sound::static_sound::{StaticSoundData, StaticSoundSettings},
	track::TrackBuilder,
	effect::filter::FilterBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let mut track = manager.add_sub_track(
	TrackBuilder::new()
		.with_effect(FilterBuilder::new().cutoff(1000.0))
)?;
track.play(StaticSoundData::from_file("sound.ogg")?)?;

TrackBuilder::add_effect returns a handle that can be used to modify the effect after the track has been created.

let mut filter;
let track = manager.add_sub_track({
	let mut builder = TrackBuilder::new();
	filter = builder.add_effect(FilterBuilder::new().cutoff(1000.0));
	builder
})?;
filter.set_cutoff(4000.0, Tween::default());

§Send tracks

Sometimes, you may want to share effects across multiple tracks. For example, let’s say we have a game with a player and an enemy that both make sounds, so we have a “player” track and an “enemy” track. We want sounds for both of these tracks to have reverb applied. We could add a separate reverb effect to both the player and enemy track, but there’s a couple reasons this isn’t an optimal solution:

  • Since the player and enemy are in the same space, they should be using the same reverb settings. But if we have two reverb effects, we’re duplicating the settings.
  • Having more effects takes more CPU time, and it’s wasteful in this case because both reverb effects are doing the same thing.

This is where send tracks come in handy. Send tracks are non-hierarchical mixer tracks which you can’t play sounds on directly - instead, regular mixer tracks can have their output sent to the input of one or more send tracks. The output of the send tracks is then sent to the main mixer track.

In the following example, we’ll set up mixer tracks to have the following flow of audio:

┌──────┐         ┌──────────┐
│      ├─────────►          │
│Player├───────┐ │Main track│
│      │ ┌─────┼─►          │
└──────┘ │     │ └─────▲────┘
┌──────┐ │ ┌───▼──┐    │
│      ├─┘ │      │    │
│Enemy ├───►Reverb├────┘
│      │   │(send)│
└──────┘   └──────┘

To start, we’ll create the reverb send with AudioManager::add_send_track:

use kira::{
	effect::reverb::ReverbBuilder,
	AudioManager, AudioManagerSettings, DefaultBackend,
	track::SendTrackBuilder,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let reverb_send = manager
	.add_send_track(SendTrackBuilder::new().with_effect(ReverbBuilder::new().mix(1.0)))?;

Note that we set the mix of the reverb to 1.0, meaning only the reverberations will be output, not the dry signal. This is important because the player and enemy tracks will already be outputting the dry signal. If the reverb effect was also outputting the dry signal, the overall volume of the sound would be louder than we want.

Next, we’ll create the player and enemy tracks and route them to the reverb send using TrackBuilder::with_send:

use kira::track::TrackBuilder;

let player_track = manager.add_sub_track(TrackBuilder::new().with_send(&reverb_send, -6.0))?;
let enemy_track = manager.add_sub_track(TrackBuilder::new().with_send(&reverb_send, -12.0))?;

We can use the second argument of with_send to change the volume of the track before sending it to the send track. This allows the player and enemy to have different amounts of reverb without having to instantiate two separate effects.

§Spatial tracks

Oftentimes, it’s useful to give sounds a location in a 3D (or 2D) space and play back those sounds from the perspective of a character’s ears located somewhere else in that space. For example, as a player character gets closer to a waterfall, you may want the sound of the waterfall to get louder.

We can use spatial tracks as the sound source and listeners for the character’s ears.

First, let’s create a listener using AudioManager::add_listener:

use kira::{AudioManager, AudioManagerSettings, DefaultBackend};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let listener = manager.add_listener(glam::Vec3::ZERO, glam::Quat::IDENTITY)?;

This example uses glam, but you can use any math library that has interoperability with mint.

Next, we’ll create a spatial track that’s linked to the listener using AudioManager::add_spatial_sub_track:

use kira::track::SpatialTrackBuilder;

let spatial_track = manager.add_spatial_sub_track(
	&listener,
	glam::vec3(0.0, 0.0, 10.0), // track position
	SpatialTrackBuilder::new(),
)?;

Now any sounds played on the spatial track will automatically have the following behaviors:

  • Attenuation: sounds will get quieter the farther away they are from the listener
  • Spatialization: sounds will be panned left or right depending on their direction from the listener

We can customize or disable these behaviors using the methods on SpatialTrackBuilder.

We can also map any effect setting that uses Value to the distance between the spatial track and the listener using Value::FromListenerDistance. One common use for this is to change the amount of reverb a sound has based on distance:

use kira::{
	effect::reverb::ReverbBuilder,
	Easing, Mapping, Value,
	Mix,
};

manager.add_spatial_sub_track(
	&listener,
	glam::vec3(0.0, 0.0, 10.0),
	SpatialTrackBuilder::new().with_effect(ReverbBuilder::new().mix(
		Value::FromListenerDistance(
			Mapping {
				input_range: (0.0, 100.0),
				output_range: (Mix::DRY, Mix::WET),
				easing: Easing::Linear,
			},
		),
	)),
)?;

Structs§

Enums§