Struct SpatialTrackBuilder

pub struct SpatialTrackBuilder { /* private fields */ }

Available on crate feature dep_kira only.

Configures a spatial mixer track.

Implementations

impl SpatialTrackBuilder

pub fn new() -> SpatialTrackBuilder

Creates a new SpatialTrackBuilder with the default settings.

pub fn volume(self, volume: impl Into<Value<Decibels>>) -> SpatialTrackBuilder

Sets the volume of the track.

Examples

Set the volume to a fixed decibel value:

let builder = SpatialTrackBuilder::new().volume(-6.0);

Link the volume to a modulator:

use kira::{
	AudioManager, AudioManagerSettings, DefaultBackend,
	modulator::tweener::TweenerBuilder,
	track::SpatialTrackBuilder,
	Easing, Value, Mapping,
	Decibels,
};

let mut manager = AudioManager::<DefaultBackend>::new(AudioManagerSettings::default())?;
let tweener = manager.add_modulator(TweenerBuilder {
	initial_value: 0.5,
})?;
let builder = SpatialTrackBuilder::new().volume(Value::FromModulator {
	id: tweener.id(),
	mapping: Mapping {
		input_range: (0.0, 1.0),
		output_range: (Decibels::SILENCE, Decibels::IDENTITY),
		easing: Easing::Linear,
	},
});

pub fn sub_track_capacity(self, capacity: usize) -> SpatialTrackBuilder

Sets the maximum number of sub-tracks this track can have.

pub fn sound_capacity(self, capacity: usize) -> SpatialTrackBuilder

Sets the maximum number of sounds that can be played simultaneously on this track.

pub fn with_send( self, track: impl Into<SendTrackId>, volume: impl Into<Value<Decibels>>, ) -> SpatialTrackBuilder

Routes this track to the given send track with the given volume.

pub fn add_effect<B>(&mut self, builder: B) -> <B as EffectBuilder>::Handle

where B: EffectBuilder,

Adds an effect to the track.

Examples

use kira::{track::SpatialTrackBuilder, effect::delay::DelayBuilder};

let mut builder = SpatialTrackBuilder::new();
let delay_handle = builder.add_effect(DelayBuilder::new());

pub fn with_effect<B>(self, builder: B) -> SpatialTrackBuilder

where B: EffectBuilder,

Adds an effect to the track and returns the SpatialTrackBuilder.

If you need to modify the effect later, use add_effect, which returns the effect handle.

Examples

use kira::{
	track::SpatialTrackBuilder,
	effect::{filter::FilterBuilder, reverb::ReverbBuilder},
};

let mut builder = SpatialTrackBuilder::new()
	.with_effect(FilterBuilder::new())
	.with_effect(ReverbBuilder::new());

pub fn add_built_effect(&mut self, effect: Box<dyn Effect>)

Adds an already built effect into this track.

Box<dyn Effect> values are created when calling build on an effect builder, which gives you an effect handle, as well as this boxed effect, which is the actual audio effect.

This is a lower-level method than Self::add_effect, and you should probably use it rather than this method, unless you have a reason to.

Examples

use kira::track::SpatialTrackBuilder;
use kira::effect::{EffectBuilder, delay::DelayBuilder};

let mut builder = SpatialTrackBuilder::new();
let delay_builder = DelayBuilder::new();
let (effect, delay_handle) = delay_builder.build();
let delay_handle = builder.add_built_effect(effect);

pub fn with_built_effect(self, effect: Box<dyn Effect>) -> SpatialTrackBuilder

Add an already-built effect and return the SpatialTrackBuilder.

Box<dyn Effect> values are created when calling build on an effect builder, which gives you an effect handle, as well as this boxed effect, which is the actual audio effect.

This is a lower-level method than Self::with_effect, and you should probably use it rather than this method, unless you have a reason to.

Examples

use kira::{
	track::SpatialTrackBuilder,
	effect::{filter::FilterBuilder, reverb::ReverbBuilder, EffectBuilder},
};

let (filter_effect, filter_handle) = FilterBuilder::new().build();
let (reverb_effect, reverb_handle) = ReverbBuilder::new().build();
let mut builder = SpatialTrackBuilder::new()
	.with_built_effect(filter_effect)
	.with_built_effect(reverb_effect);

pub fn persist_until_sounds_finish(self, persist: bool) -> SpatialTrackBuilder

Sets whether the track should stay alive while sounds are playing on it.

By default, as soon as a track’s handle is dropped, the track is unloaded. If this is set to true, the track will wait until all sounds on the track are finished before unloading.

pub fn distances( self, distances: impl Into<SpatialTrackDistances>, ) -> SpatialTrackBuilder

Sets the distances from a listener at which the emitter is loudest and quietest.

pub fn attenuation_function( self, attenuation_function: impl Into<Option<Easing>>, ) -> SpatialTrackBuilder

Sets how the emitter’s volume will change with distance.

If None, the emitter will output at a constant volume.

pub fn spatialization_strength( self, spatialization_strength: impl Into<Value<f32>>, ) -> SpatialTrackBuilder

Sets how much the track’s output should be panned left or right depending on its direction from the listener.

This value should be between 0.0 and 1.0. 0.0 disables spatialization entirely.

Trait Implementations

impl Default for SpatialTrackBuilder

fn default() -> SpatialTrackBuilder

Returns the “default value” for a type.