You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
v2 Implement audio absolute time and scheduled play
This is a rewrite of godotengine#105510 that moves the silence frames logic into a separate AudioStreamPlaybackScheduled class. The rewrite allows both the AudioServer and the player (mostly) to treat it as if it were a generic playback. It also simplifies the addition of new features.
Main differences:
- play_scheduled returns an AudioStreamPlaybackScheduled instance, which is tied to the player that created it.
- The start time can be changed after scheduling.
- You can now set an end time for the playback.
- The scheduled playback can be cancelled separately from other playbacks on the player.
Co-authored-by: K. S. Ernest (iFire) Lee <ernest.lee@chibifire.com>
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 AudioStreamPlayer.play_scheduled].
42
+
See also [AudioStreamPlaybackScheduled].
43
+
[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].
Wrapper around [AudioStreamPlayback] that schedules it to be played in the future.
5
+
</brief_description>
6
+
<description>
7
+
Wrapper around [AudioStreamPlayback] that schedules it to be played in the future.
8
+
An [AudioStreamPlaybackScheduled] instance is created from [method AudioStreamPlayer.play_scheduled], [method AudioStreamPlayer2D.play_scheduled], or [method AudioStreamPlayer3D.play_scheduled].
9
+
[codeblocks]
10
+
[gdscript]
11
+
var audio_time = AudioServer.get_absolute_time()
12
+
13
+
# Play the sound roughly 1 second in the future, then stop it after exactly 3 seconds.
14
+
var playback_scheduled = player.play_scheduled(audio_time + 1)
If the sound is already playing, this method does nothing. Use [method stop] instead to both stop the ongoing or cancel the scheduled playback.
40
+
</description>
41
+
</method>
42
+
<methodname="is_playing"qualifiers="const">
43
+
<returntype="bool" />
44
+
<description>
45
+
Returns [code]true[/code] if the playback is actively playing. Returns [code]false[/code] for scheduled playbacks that have not yet started, or playbacks that have ended.
46
+
</description>
47
+
</method>
48
+
<methodname="is_scheduled"qualifiers="const">
49
+
<returntype="bool" />
50
+
<description>
51
+
Returns [code]true[/code] if the playback is scheduled and has not yet started.
52
+
</description>
53
+
</method>
54
+
<methodname="start">
55
+
<returntype="void" />
56
+
<paramindex="0"name="from_pos"type="float" />
57
+
<description>
58
+
Schedules the playback. Once the [AudioServer]'s timeline reaches [member scheduled_start_time], the playback will begin playing from [param from_pos].
59
+
</description>
60
+
</method>
61
+
<methodname="stop">
62
+
<returntype="void" />
63
+
<description>
64
+
Stops the playback if it has started, or cancels the currently scheduled playback if it has not yet started.
Copy file name to clipboardExpand all lines: doc/classes/AudioStreamPlayer.xml
+14-2Lines changed: 14 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@
28
28
<methodname="get_stream_playback">
29
29
<returntype="AudioStreamPlayback" />
30
30
<description>
31
-
Returns the latest [AudioStreamPlayback] of this node, usually the most recently created by [method play]. If no sounds are playing, this method fails and returns an empty playback.
31
+
Returns the latest [AudioStreamPlayback] of this node, usually the most recently created by [method play] or [method play_scheduled]. If no sounds are playing, this method fails and returns an empty playback.
32
32
</description>
33
33
</method>
34
34
<methodname="has_stream_playback">
@@ -44,6 +44,18 @@
44
44
Plays a sound from the beginning, or the given [param from_position] in seconds.
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.
53
+
Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
54
+
Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
55
+
[b]Note:[/b] Calling this method after [member max_polyphony] is reached will cut off the oldest sound playing on this node.
56
+
[b]Note:[/b] On the Web platform, [member playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method play].
57
+
</description>
58
+
</method>
47
59
<methodname="seek">
48
60
<returntype="void" />
49
61
<paramindex="0"name="to_position"type="float" />
@@ -67,7 +79,7 @@
67
79
[b]Note:[/b] At runtime, if no bus with the given name exists, all sounds will fall back on [code]"Master"[/code]. See also [method AudioServer.get_bus_name].
The maximum number of sounds this node can play at the same time. Calling [method play] after this value is reached will cut off the oldest sounds.
82
+
The maximum number of sounds this node can play and schedule at the same time. Calling [method play] or [method play_scheduled] after this value is reached will cut off the oldest sounds.
The mix target channels, as one of the [enum MixTarget] constants. Has no effect when two speakers or less are detected (see [enum AudioServer.SpeakerMode]).
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.
47
+
Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
48
+
Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
49
+
[b]Note:[/b] Calling this method after [member max_polyphony] is reached will cut off the oldest sound playing on this node.
50
+
[b]Note:[/b] On the Web platform, [member playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method play].
51
+
</description>
52
+
</method>
41
53
<methodname="seek">
42
54
<returntype="void" />
43
55
<paramindex="0"name="to_position"type="float" />
@@ -70,7 +82,7 @@
70
82
Maximum distance from which audio is still hearable.
The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.
85
+
The maximum number of sounds this node can play and schedule at the same time. Calling [method play] or [method play_scheduled] after this value is reached will cut off the oldest sounds.
Scales the panning strength for this node by multiplying the base [member ProjectSettings.audio/general/2d_panning_strength] with this factor. Higher values will pan audio from left to right more dramatically than lower values.
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.
47
+
Returns an [AudioStreamPlaybackScheduled] instance representing the scheduled playback of the sound.
48
+
Use this method for high precision playbacks, such as a metronome or other rhythm-based sounds.
49
+
[b]Note:[/b] Calling this method after [member max_polyphony] is reached will cut off the oldest sound playing on this node.
50
+
[b]Note:[/b] On the Web platform, [member playback_type] must be set to [constant AudioServer.PLAYBACK_TYPE_STREAM]. Otherwise, this method will behave like [method play].
51
+
</description>
52
+
</method>
41
53
<methodname="seek">
42
54
<returntype="void" />
43
55
<paramindex="0"name="to_position"type="float" />
@@ -91,7 +103,7 @@
91
103
The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than [code]0.0[/code]. [member max_distance] works in tandem with [member unit_size]. However, unlike [member unit_size] whose behavior depends on the [member attenuation_model], [member max_distance] always works in a linear fashion. This can be used to prevent the [AudioStreamPlayer3D] from requiring audio mixing when the listener is far away, which saves CPU resources.
The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.
106
+
The maximum number of sounds this node can play and schedule at the same time. Calling [method play] or [method play_scheduled] after this value is reached will cut off the oldest sounds.
Scales the panning strength for this node by multiplying the base [member ProjectSettings.audio/general/3d_panning_strength] by this factor. If the product is [code]0.0[/code] then stereo panning is disabled and the volume is the same for all channels. If the product is [code]1.0[/code] then one of the channels will be muted when the sound is located exactly to the left (or right) of the listener.
0 commit comments