Implement audio absolute time (DSP time) and scheduled play

doc/classes/AudioServer.xml

@@ -35,6 +35,14 @@
 				Generates an [AudioBusLayout] using the available buses and effects.
 			</description>
 		</method>
+		<method name="get_absolute_time" qualifiers="const" experimental="">
+			<return type="float" />
+			<description>
+				Returns the absolute time in seconds of the [AudioServer]'s timeline, based on the number of audio frames mixed. Used to schedule sounds to be played with high precision timing, such as with [method ScheduledAudioStreamPlayer.play_scheduled].
+				See also [AudioStreamPlaybackScheduled].
+				[b]Note:[/b] This value only updates each time an audio chunk is mixed and should not be relied on as an accurate "current" time of the [AudioServer].
+			</description>
+		</method>
 		<method name="get_bus_channels" qualifiers="const">
 			<return type="int" />
 			<param index="0" name="bus_idx" type="int" />

doc/classes/AudioStreamPlaybackScheduled.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AudioStreamPlaybackScheduled" inherits="AudioStreamPlayback" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Wrapper around [AudioStreamPlayback] that schedules it to be played in the future.
+	</brief_description>
+	<description>
+		Wrapper around [AudioStreamPlayback] that schedules it to be played in the future.
+		An [AudioStreamPlaybackScheduled] instance is created from [method ScheduledAudioStreamPlayer.play_scheduled], [method ScheduledAudioStreamPlayer2D.play_scheduled], or [method ScheduledAudioStreamPlayer3D.play_scheduled].
+		[codeblocks]
+		[gdscript]
+		var audio_time = AudioServer.get_absolute_time()
+
+		# Play the sound roughly 1 second in the future, then stop it after exactly 3 seconds.
+		var playback_scheduled = player.play_scheduled(audio_time + 1)
+		playback_scheduled.scheduled_end_time = audio_time + 4
+
+		# Cancel the playback
+		playback_scheduled.cancel()
+		[/gdscript]
+		[csharp]
+		double audioTime = AudioServer.GetAbsoluteTime();
+
+		// Play the sound roughly 1 second in the future, then stop it after exactly 3 seconds.
+		AudioStreamPlaybackScheduled playbackScheduled = player.PlayScheduled(audioTime + 1);
+		playbackScheduled.ScheduledEndTime = audioTime + 4;
+
+		// Cancel the playback
+		playbackScheduled.Cancel();
+		[/csharp]
+		[/codeblocks]
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="cancel">
+			<return type="void" />
+			<description>
+				Cancels the currently scheduled playback.
+				If the playback is actively playing, this method does nothing. Use [method AudioStreamPlayback.stop] instead to both stop and cancel the scheduled playback.
+			</description>
+		</method>
+		<method name="is_scheduled" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if the playback is scheduled and has not yet started.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="base_playback" type="AudioStreamPlayback" setter="set_base_playback" getter="get_base_playback">
+			The wrapped [AudioStreamPlayback] to be scheduled. If set, the previously scheduled playback will be cancelled/stopped.
+		</member>
+		<member name="scheduled_end_time" type="float" setter="set_scheduled_end_time" getter="get_scheduled_end_time" default="0.0">
+			The time the playback is scheduled to stop playing in seconds. This is based on the [AudioServer]'s timeline (see [method AudioServer.get_absolute_time]).
+		</member>
+		<member name="scheduled_start_time" type="float" setter="set_scheduled_start_time" getter="get_scheduled_start_time" default="0.0">
+			The time the playback is scheduled to start playing in seconds. This is based on the [AudioServer]'s timeline (see [method AudioServer.get_absolute_time]).
+		</member>
+	</members>
+</class>

doc/classes/ScheduledAudioStreamPlayer.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="ScheduledAudioStreamPlayer" inherits="AudioStreamPlayer" experimental="" keywords="sound, music, song" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A node for scheduled audio playback.
+	</brief_description>
+	<description>
+		Behaves similarly to [AudioStreamPlayer] but can schedule audio to play in the future.
+		If you need to play scheduled audio at a specific position, use [ScheduledAudioStreamPlayer2D] or [ScheduledAudioStreamPlayer3D] instead.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="play_scheduled">
+			<return type="AudioStreamPlaybackScheduled" />
+			<param index="0" name="absolute_time" type="float" />
+			<param index="1" name="from_position" type="float" default="0.0" />
+			<description>
+				Schedules a sound to be played on the [AudioServer]'s timeline at [param absolute_time] in seconds. If the sound is scheduled to play earlier than the value returned by [method AudioServer.get_absolute_time], it will be played immediately. The sound starts from the given [param from_position] in seconds.
+				Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
+				Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
+				[b]Note:[/b] Calling this method after [member AudioStreamPlayer.max_polyphony] is reached will cut off the oldest sound playing on this node.
+				[b]Note:[/b] On the Web platform, [member AudioStreamPlayer.playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method AudioStreamPlayer.play].
+			</description>
+		</method>
+	</methods>
+</class>

doc/classes/ScheduledAudioStreamPlayer2D.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="ScheduledAudioStreamPlayer2D" inherits="AudioStreamPlayer2D" experimental="" keywords="sound, music, song" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A node for scheduled audio playback.
+	</brief_description>
+	<description>
+		Behaves similarly to [AudioStreamPlayer2D] but can schedule audio to play in the future.
+		See also [ScheduledAudioStreamPlayer] to play a scheduled sound non-positionally.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="play_scheduled">
+			<return type="AudioStreamPlaybackScheduled" />
+			<param index="0" name="absolute_time" type="float" />
+			<param index="1" name="from_position" type="float" default="0.0" />
+			<description>
+				Schedules a sound to be played on the [AudioServer]'s timeline at [param absolute_time] in seconds. If the sound is scheduled to play earlier than the value returned by [method AudioServer.get_absolute_time], it will be played immediately. The sound starts from the given [param from_position] in seconds.
+				Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
+				Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
+				[b]Note:[/b] Calling this method after [member AudioStreamPlayer2D.max_polyphony] is reached will cut off the oldest sound playing on this node.
+				[b]Note:[/b] On the Web platform, [member AudioStreamPlayer2D.playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method AudioStreamPlayer2D.play].
+			</description>
+		</method>
+	</methods>
+</class>

doc/classes/ScheduledAudioStreamPlayer3D.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="ScheduledAudioStreamPlayer3D" inherits="AudioStreamPlayer3D" experimental="" keywords="sound, music, song" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A node for scheduled audio playback.
+	</brief_description>
+	<description>
+		Behaves similarly to [AudioStreamPlayer3D] but can schedule audio to play in the future.
+		See also [ScheduledAudioStreamPlayer] to play a scheduled sound non-positionally.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="play_scheduled">
+			<return type="AudioStreamPlaybackScheduled" />
+			<param index="0" name="absolute_time" type="float" />
+			<param index="1" name="from_position" type="float" default="0.0" />
+			<description>
+				Schedules a sound to be played on the [AudioServer]'s timeline at [param absolute_time] in seconds. If the sound is scheduled to play earlier than the value returned by [method AudioServer.get_absolute_time], it will be played immediately. The sound starts from the given [param from_position] in seconds.
+				Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
+				Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
+				[b]Note:[/b] Calling this method after [member AudioStreamPlayer3D.max_polyphony] is reached will cut off the oldest sound playing on this node.
+				[b]Note:[/b] On the Web platform, [member AudioStreamPlayer3D.playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method AudioStreamPlayer3D.play].
+			</description>
+		</method>
+	</methods>
+</class>

scene/2d/audio_stream_player_2d.cpp

@@ -231,11 +231,7 @@ float AudioStreamPlayer2D::get_pitch_scale() const {
 	return internal->pitch_scale;
 }
 
-void AudioStreamPlayer2D::play(float p_from_pos) {
-	Ref<AudioStreamPlayback> stream_playback = internal->play_basic();
-	if (stream_playback.is_null()) {
-		return;
-	}
+void AudioStreamPlayer2D::_play_internal(Ref<AudioStreamPlayback> stream_playback, double p_from_pos) {
 	setplayback = stream_playback;
 	setplay.set(p_from_pos);
 
@@ -249,6 +245,14 @@ void AudioStreamPlayer2D::play(float p_from_pos) {
 	}
 }
 
+void AudioStreamPlayer2D::play(float p_from_pos) {
+	Ref<AudioStreamPlayback> stream_playback = internal->play_basic();
+	if (stream_playback.is_null()) {
+		return;
+	}
+	_play_internal(stream_playback, p_from_pos);
+}
+
 void AudioStreamPlayer2D::seek(float p_seconds) {
 	internal->seek(p_seconds);
 }

scene/2d/audio_stream_player_2d.h

@@ -41,15 +41,16 @@ class AudioStreamPlayerInternal;
 class AudioStreamPlayer2D : public Node2D {
 	GDCLASS(AudioStreamPlayer2D, Node2D);
 
+protected:
+	AudioStreamPlayerInternal *internal = nullptr;
+
 private:
 	enum {
 		MAX_OUTPUTS = 8,
 		MAX_INTERSECT_AREAS = 32
 
 	};
 
-	AudioStreamPlayerInternal *internal = nullptr;
-
 	SafeNumeric<float> setplay{ -1.0 };
 	Ref<AudioStreamPlayback> setplayback;
 
@@ -85,6 +86,8 @@ class AudioStreamPlayer2D : public Node2D {
 	bool _get(const StringName &p_name, Variant &r_ret) const;
 	void _get_property_list(List<PropertyInfo> *p_list) const;
 
+	void _play_internal(Ref<AudioStreamPlayback> stream_playback, double p_from_pos = 0.0);
+
 #ifndef DISABLE_DEPRECATED
 	bool _is_autoplay_enabled_bind_compat_86907();
 	static void _bind_compatibility_methods();

scene/2d/scheduled_audio_stream_player_2d.cpp

@@ -0,0 +1,49 @@
+/**************************************************************************/
+/*  scheduled_audio_stream_player_2d.cpp                                  */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#include "scheduled_audio_stream_player_2d.h"
+
+#include "scene/audio/audio_stream_player_internal.h"
+#include "scene/resources/audio_stream_playback_scheduled.h"
+
+Ref<AudioStreamPlaybackScheduled> ScheduledAudioStreamPlayer2D::play_scheduled(double p_abs_time, double p_from_pos) {
+	Ref<AudioStreamPlaybackScheduled> stream_playback_scheduled = internal->play_scheduled_basic();
+	if (stream_playback_scheduled.is_null()) {
+		return stream_playback_scheduled;
+	}
+	stream_playback_scheduled->set_scheduled_start_time(p_abs_time);
+	_play_internal(stream_playback_scheduled, p_from_pos);
+
+	return stream_playback_scheduled;
+}
+
+void ScheduledAudioStreamPlayer2D::_bind_methods() {
+	ClassDB::bind_method(D_METHOD("play_scheduled", "absolute_time", "from_position"), &ScheduledAudioStreamPlayer2D::play_scheduled, DEFVAL(0.0));
+}

scene/2d/scheduled_audio_stream_player_2d.h

@@ -0,0 +1,45 @@
+/**************************************************************************/
+/*  scheduled_audio_stream_player_2d.h                                    */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#pragma once
+
+#include "audio_stream_player_2d.h"
+
+class AudioStreamPlaybackScheduled;
+
+class ScheduledAudioStreamPlayer2D : public AudioStreamPlayer2D {
+	GDCLASS(ScheduledAudioStreamPlayer2D, AudioStreamPlayer2D);
+
+protected:
+	static void _bind_methods();
+
+public:
+	Ref<AudioStreamPlaybackScheduled> play_scheduled(double p_abs_time, double p_from_pos = 0.0);
+};

scene/3d/audio_stream_player_3d.cpp

@@ -591,11 +591,7 @@ float AudioStreamPlayer3D::get_pitch_scale() const {
 	return internal->pitch_scale;
 }
 
-void AudioStreamPlayer3D::play(float p_from_pos) {
-	Ref<AudioStreamPlayback> stream_playback = internal->play_basic();
-	if (stream_playback.is_null()) {
-		return;
-	}
+void AudioStreamPlayer3D::_play_internal(Ref<AudioStreamPlayback> stream_playback, double p_from_pos) {
 	setplayback = stream_playback;
 	setplay.set(p_from_pos);
 
@@ -609,6 +605,14 @@ void AudioStreamPlayer3D::play(float p_from_pos) {
 	}
 }
 
+void AudioStreamPlayer3D::play(float p_from_pos) {
+	Ref<AudioStreamPlayback> stream_playback = internal->play_basic();
+	if (stream_playback.is_null()) {
+		return;
+	}
+	_play_internal(stream_playback, p_from_pos);
+}
+
 void AudioStreamPlayer3D::seek(float p_seconds) {
 	internal->seek(p_seconds);
 }

scene/3d/audio_stream_player_3d.h

@@ -59,15 +59,16 @@ class AudioStreamPlayer3D : public Node3D {
 		DOPPLER_TRACKING_PHYSICS_STEP
 	};
 
+protected:
+	AudioStreamPlayerInternal *internal = nullptr;
+
 private:
 	enum {
 		MAX_OUTPUTS = 8,
 		MAX_INTERSECT_AREAS = 32
 
 	};
 
-	AudioStreamPlayerInternal *internal = nullptr;
-
 	SafeNumeric<float> setplay{ -1.0 };
 	Ref<AudioStreamPlayback> setplayback;
 
@@ -130,6 +131,8 @@ class AudioStreamPlayer3D : public Node3D {
 	bool _get(const StringName &p_name, Variant &r_ret) const;
 	void _get_property_list(List<PropertyInfo> *p_list) const;
 
+	void _play_internal(Ref<AudioStreamPlayback> stream_playback, double p_from_pos = 0.0);
+
 #ifndef DISABLE_DEPRECATED
 	bool _is_autoplay_enabled_bind_compat_86907();
 	static void _bind_compatibility_methods();