Doppler effect

.gitignore

@@ -1,3 +1,4 @@
 Cargo.lock
 target
 .idea/
+.vscode/

Cargo.toml

@@ -2,6 +2,7 @@
 members = [
 	"crates/kira",
 	"crates/benchmarks",
+	"crates/examples/doppler-effect",
 	"crates/examples/dynamic-music",
 	"crates/examples/ghost-noise",
 	"crates/examples/metronome",

crates/examples/doppler-effect/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "doppler-effect"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+glam = { version = "0.27", features = ["mint"] }
+kira = { path = "../../kira" }
+macroquad = { version = "0.4.13", default-features = false }

crates/examples/doppler-effect/src/main.rs

@@ -0,0 +1,197 @@
+use kira::{
+	backend::DefaultBackend, sound::static_sound::StaticSoundData, track::{SpatialTrackBuilder, SpatialTrackDistances}, AudioManager, AudioManagerSettings, Decibels, Easing, Mapping, Tween, Value
+};
+use macroquad::prelude::*;
+
+const CAMERA_MAX_SPEED: f32 = 160.0;
+const CAMERA_ACCEL: f32 = 1000.0;
+const CAMERA_DRAG: f32 = 8.0;
+
+const LOOK_SPEED: f32 = 0.005;
+const WORLD_UP: Vec3 = vec3(0.0, 1.0, 0.0);
+const SPATIAL_TRACK_POSITION: Vec3 = vec3(0.0, 1.0, 6.0);
+const OSCILLATION_AMPLITUDE: f32 = 40.0;
+const OSCILLATION_SPEED: f32 = 4.0;
+
+fn conf() -> Conf {
+	Conf {
+		window_title: String::from("Macroquad"),
+		window_width: 1260,
+		window_height: 768,
+		fullscreen: false,
+		..Default::default()
+	}
+}
+
+#[macroquad::main(conf)]
+async fn main() {
+	let mut camera_controller = CameraController::new();
+
+	let mut last_mouse_position: Vec2 = mouse_position().into();
+
+	let mut audio_manager =
+		AudioManager::<DefaultBackend>::new(AudioManagerSettings::default()).unwrap();
+
+	let mut listener = audio_manager
+		.add_listener(camera_controller.position, camera_controller.orientation())
+		.unwrap();
+
+	let mut spatial_track = audio_manager
+		.add_spatial_sub_track(
+			&listener,
+			SPATIAL_TRACK_POSITION,
+			SpatialTrackBuilder::new()
+				.distances(SpatialTrackDistances {
+					min_distance: 1.0,
+					max_distance: 400.0,
+				})
+				// NOTE: Even though the doppler effect is enabled, the sound will not be affected by it
+				// until the listener and the spatial track have set the game loop delta time. See below!
+				.doppler_effect(true)
+		)
+		.unwrap();
+
+	spatial_track
+		.play(
+			// motor_loop.wav: https://freesound.org/people/soundjoao/sounds/325809/
+			StaticSoundData::from_file("crates/examples/assets/motor_loop.wav")
+				.unwrap()
+				.loop_region(0.0..),
+		)
+		.unwrap();
+
+	let mut time = 0.0f32;
+
+	loop {
+		let delta_time = get_frame_time();
+		time += delta_time;
+
+		if is_key_pressed(KeyCode::Escape) {
+			break;
+		}
+
+		let mouse_position: Vec2 = mouse_position().into();
+		let mouse_delta = mouse_position - last_mouse_position;
+		last_mouse_position = mouse_position;
+		camera_controller.update(delta_time, mouse_delta);
+		listener.set_position(camera_controller.position, Tween::default());
+		listener.set_orientation(camera_controller.orientation(), Tween::default());
+
+		clear_background(LIGHTGRAY);
+
+		// Going 3d!
+		set_camera(&camera_controller.camera());
+
+		draw_grid(20, 1., BLACK, GRAY);
+
+		let source_position = Vec3::new(
+			SPATIAL_TRACK_POSITION.x,
+			SPATIAL_TRACK_POSITION.y,
+			SPATIAL_TRACK_POSITION.z + (time * OSCILLATION_SPEED).sin() * OSCILLATION_AMPLITUDE
+		);
+
+		spatial_track.set_position(source_position, Tween::default());
+
+		// need to set these every frame unless you're dealing with a fixed timestep
+		listener.set_game_loop_delta_time(delta_time as f64);
+		spatial_track.set_game_loop_delta_time(delta_time as f64);
+
+		draw_cube_wires(source_position, vec3(2., 2., 2.), GREEN);
+
+		// Back to screen space, render some text
+		set_default_camera();
+
+		draw_text(
+			&format!("FPS: {}", get_fps()),
+			20.0,
+			40.0,
+			30.0,
+			BLACK,
+		);
+
+		next_frame().await
+	}
+}
+
+struct CameraController {
+	position: Vec3,
+	yaw: f32,
+	pitch: f32,
+	velocity: Vec3,
+}
+
+impl CameraController {
+	fn new() -> Self {
+		Self {
+			position: vec3(0.0, 1.0, 50.0),
+			yaw: 0.0,
+			pitch: 0.0,
+			velocity: Vec3::ZERO,
+		}
+	}
+
+	fn update(&mut self, delta_time: f32, mouse_delta: Vec2) {
+		let forward = self.front();
+		let right = self.right();
+
+		let mut desired_dir = Vec3::ZERO;
+		if is_key_down(KeyCode::W) {
+			desired_dir += forward;
+		}
+		if is_key_down(KeyCode::S) {
+			desired_dir -= forward;
+		}
+		if is_key_down(KeyCode::A) {
+			desired_dir -= right;
+		}
+		if is_key_down(KeyCode::D) {
+			desired_dir += right;
+		}
+
+		if is_key_down(KeyCode::Left) {
+			self.yaw += 2.0 * delta_time;
+		}
+		if is_key_down(KeyCode::Right) {
+			self.yaw -= 2.0 * delta_time;
+		}
+
+		if is_key_down(KeyCode::Up) {
+			self.pitch += 2.0 * delta_time;
+		}
+		if is_key_down(KeyCode::Down) {
+			self.pitch -= 2.0 * delta_time;
+		}
+
+		let desired_dir = desired_dir.normalize_or_zero();
+		self.velocity += desired_dir * CAMERA_ACCEL * delta_time;
+		self.velocity *= 1.0 - CAMERA_DRAG * delta_time;
+		if self.velocity.length() > CAMERA_MAX_SPEED {
+			self.velocity = self.velocity.normalize() * CAMERA_MAX_SPEED;
+		}
+
+		self.position += self.velocity * delta_time;
+		self.yaw -= mouse_delta.x * LOOK_SPEED;
+		self.pitch = (self.pitch - mouse_delta.y * LOOK_SPEED).clamp(-1.5, 1.5);
+	}
+
+	fn orientation(&self) -> Quat {
+		Quat::from_rotation_y(self.yaw) * Quat::from_rotation_x(self.pitch)
+	}
+
+	fn camera(&self) -> Camera3D {
+		Camera3D {
+			position: self.position,
+			target: self.position + self.front(),
+			up: WORLD_UP,
+			..Default::default()
+		}
+	}
+
+	fn front(&self) -> Vec3 {
+		-self.orientation().mul_vec3(Vec3::Z).normalize()
+	}
+
+	fn right(&self) -> Vec3 {
+		self.orientation().mul_vec3(Vec3::X).normalize()
+	}
+}

crates/examples/spatial-audio/src/main.rs

@@ -79,9 +79,10 @@ async fn main() {
 		let mouse_delta = mouse_position - last_mouse_position;
 		last_mouse_position = mouse_position;
 		camera_controller.update(delta_time, mouse_delta);
+
 		listener.set_position(camera_controller.position, Tween::default());
 		listener.set_orientation(camera_controller.orientation(), Tween::default());
-
+		
 		clear_background(LIGHTGRAY);
 
 		// Going 3d!

crates/kira/src/command.rs

@@ -163,7 +163,7 @@ macro_rules! read_commands_into_parameters {
 macro_rules! handle_param_setters {
 	($($(#[$m:meta])* $name:ident: $type:ty),*$(,)?) => {
 		paste::paste! {
-			$(
+		$(
 				$(#[$m])*
 				pub fn [<set_ $name>](&mut self, $name: impl Into<$crate::Value<$type>>, tween: $crate::tween::Tween) {
 					self.command_writers.[<set_ $name>].write($crate::command::ValueChangeCommand {

crates/kira/src/effect/doppler/builder.rs

@@ -0,0 +1,50 @@
+use crate::{
+	effect::{Effect, EffectBuilder},
+	Value,
+};
+
+use super::{command_writers_and_readers, Doppler, DopplerHandle, DEFAULT_SPEED};
+
+/// Configures a doppler effect.
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub struct DopplerBuilder {
+	/// The speed of sound in m/s.
+	pub speed: Value<f64>,
+}
+
+impl DopplerBuilder {
+	/// Creates a new [`DopplerBuilder`] with the default settings.
+	#[must_use]
+	pub fn new() -> Self {
+		Self::default()
+	}
+
+	/// Sets the speed of sound in m/s.
+	#[must_use = "This method consumes self and returns a modified DopplerBuilder, so the return value should be used"]
+	pub fn speed(self, speed: impl Into<Value<f64>>) -> Self {
+		Self {
+			speed: speed.into(),
+			..self
+		}
+	}
+}
+
+impl Default for DopplerBuilder {
+	fn default() -> Self {
+		Self {
+			speed: Value::Fixed(DEFAULT_SPEED),
+		}
+	}
+}
+
+impl EffectBuilder for DopplerBuilder {
+	type Handle = DopplerHandle;
+
+	fn build(self) -> (Box<dyn Effect>, Self::Handle) {
+		let (command_writers, command_readers) = command_writers_and_readers();
+		(
+			Box::new(Doppler::new(self, command_readers)),
+			DopplerHandle { command_writers },
+		)
+	}
+}

crates/kira/src/effect/doppler/handle.rs

@@ -0,0 +1,16 @@
+use crate::command::handle_param_setters;
+
+use super::CommandWriters;
+
+/// Controls a reverb effect.
+#[derive(Debug)]
+pub struct DopplerHandle {
+	pub(super) command_writers: CommandWriters,
+}
+
+impl DopplerHandle {
+	handle_param_setters! {
+		/// Sets the speed of sound in m/s.
+		speed: f64,
+	}
+}

crates/kira/src/info.rs

@@ -5,8 +5,10 @@
  * like [`Sound`](crate::sound::Sound) or [`Effect`](crate::effect::Effect).
  */
 
+use std::time::Instant;
+
 use atomic_arena::Arena;
-use glam::{Quat, Vec3};
+use glam::{DVec3, Quat, Vec3};
 
 use crate::{
 	clock::{Clock, ClockId, ClockTime, State as ClockState},
@@ -108,6 +110,7 @@ impl<'a> Info<'a> {
 						orientation: listener.orientation.value().into(),
 						previous_position: listener.position.previous_value().into(),
 						previous_orientation: listener.orientation.previous_value().into(),
+						game_loop_delta_time: listener.game_loop_delta_time.value(),
 					})
 				}
 				InfoKind::Mock { listener_info, .. } => listener_info.get(listener_id.0).copied(),
@@ -124,6 +127,12 @@ impl<'a> Info<'a> {
 			},
 		)
 	}
+
+	/// Gets information about the current spatial track
+	/// if there is one.
+	pub(crate) fn spatial_track_info(&self) -> Option<&SpatialTrackInfo> {
+		self.spatial_track_info.as_ref()
+	}
 }
 
 /// Information about the current state of a [clock](super::clock).
@@ -164,6 +173,8 @@ pub struct ListenerInfo {
 	pub previous_position: mint::Vector3<f32>,
 	/// The rotation of the listener prior to the last update.
 	pub previous_orientation: mint::Quaternion<f32>,
+	/// The delta time of the game loop.
+	pub game_loop_delta_time: f64,
 }
 
 impl ListenerInfo {
@@ -182,6 +193,15 @@ impl ListenerInfo {
 		let previous_orientation: Quat = self.previous_orientation.into();
 		previous_orientation.lerp(orientation, amount).into()
 	}
+
+	/// Returns the velocity of the listener.
+	pub fn velocity(&self) -> DVec3 {
+		let current: Vec3 = self.position.into();
+		let current: DVec3 = current.into();
+		let previous: Vec3 = self.previous_position.into();
+		let previous: DVec3 = previous.into();
+		(current - previous) / self.game_loop_delta_time
+	}
 }
 
 /// Generates a fake `Info` with arbitrary data. Useful for writing unit tests.
@@ -288,6 +308,17 @@ enum InfoKind<'a> {
 
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub(crate) struct SpatialTrackInfo {
+	pub previous_position: Vec3,
 	pub position: Vec3,
 	pub listener_id: ListenerId,
+	pub game_loop_delta_time: f64,
+}
+
+impl SpatialTrackInfo {
+	/// Returns the velocity of the spatial track. Make sure you correctly set the game loop delta time.
+	pub fn velocity(&self) -> DVec3 {
+		let position: DVec3 = self.position.into();
+		let previous_position: DVec3 = self.previous_position.into();
+		(position - previous_position) / self.game_loop_delta_time
+	}
 }