Allow a stream keep playing after its owner AudioStreamPlayer gets freed

[Lazy-Rabbit-2001]

Describe the project you are working on

Godot games

Describe the problem or limitation you are having in your project

This has been bothering me, maybe most of us, for a very long period when a stream gets cut off and stopped unexpected when its player gets freed from the scene tree. Sometimes we hope there is a way to solve that problem -- allowing the stream to keep playing even though its owner player is freed before.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Introduce a playback_keep_after_deletion property (maybe other names but I cannot think of a better one, XP), including:

PLAYBACK_KEEP_DEFAULT # Default behavior, gets stopped when the player gets freed.
PLAYBACK_KEEP_TILL_FINISHED # Will stop when it is finished.
PLAYBACK_KEEP_TILL_SCENE_REMOVED # Will stop when it is finished or the scene is changed.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

I checked the code, and found that there is a AudioStreamPlayerInternal, and maybe we can tweak its NOTIFICATION_EXIT_TREE, NOTIFICATION_PREDELETE to have better control of the behavior other than default one.

• To avoid it gets stopped, only when the keeping mode is default can the sound be paused in NOTIFICATION_EXIT_TREE.
• To avoid clearing the stream_playbacks that will lead to unexpected stop, we can check if it is default mode. If it is, do default behavior; otherwise, do special control of the internal player.
• Since the player node will be freed before the internal player will be done so, we must change the process source, when the node is about to be freed, from the node to its scene tree so that the internal player will keep playing the sound correctly.
• For PLAYBACK_KEEP_TILL_SCENE_REMOVED mode, we probably have to connect its signal that will be emitted on the current scene getting deleted, to the corresponding method.
• Since the destructor of the audio stream player will also delete the internal player, which will cause unexpected stop as well, we have to declare and define a special free method for the internal player to safely free it rather than direct deletion.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Yes, as you can reparent an audio stream player to other nodes that is existing. However, I don't think it worth making wheels and boilerplates for a frequently needed feature. So why not integrate it and make this feature out-of-box?

Is there a reason why this should be core and not an add-on in the asset library?

It's part of core features.

[Meorge]

I'm a bit split on this idea.

On one hand, I know I've certainly run into the "issue" in the past of trying to, say, play a "death" sound effect for an enemy at the same time I'm freeing them. Since their death sound's stream player is a child of themselves, and they're getting freed, the sound never gets played:

func _on_body_entered(body: Node2D):
    %DeathSound.play()  # Never hear it
    queue_free()

The solutions to this, such as visibly disabling the enemy then waiting for the sound effect to finish before actually freeing it, can feel "hacky".

On the other hand, though, once I understand the reason for the stream no longer being audible once its player is freed, it makes total sense. The player is what's processing the stream and making sound in the scene.

To put it in physical terms, I'd think of it a bit like putting a CD (the stream itself) in a jukebox (the stream player) and pressing the jukebox's "play" button. Since the jukebox is there to read the CD and make the sounds, you can hear it. But if you then press "stop" on the jukebox, take the CD out, and throw the jukebox away (free the stream player), all you're left with is the CD - nothing to process its data and make sound out of it.

Back to Godot's AudioStreamPlayers, while I'm not 100% sure on this (so correct me if I'm wrong), I could also see there being issues with certain properties being undefined. For example, if a sound is being played on an AudioStreamPlayer2D/3D and then the player is freed, how would the position of the sound be calculated? Would it remain in the same world location, or would it stay in the same location relative to the listener?

---

The need to play one-shot sound effects is pretty common in games, so IMO it'd make sense to introduce a built-in static method that could instantiate an AudioStreamPlayer with given settings, allow it to play out, and then self-destruct once it is finished. Some rough GDScript pseudocode for a function like this:

func play_one_shot(stream: AudioStream):
    var new_node = AudioStreamPlayer.new()
    new_node.stream = stream
    get_tree().root.add_child(new_node)
    new_node.play()
    await new_node.finished
    new_node.queue_free()

With something like this, the user could play one-off sound effects without worrying about timing their queue_free() calls, while the stream player's purpose remains untouched.

[KoBeWi]

Related: #4569

If this enhancement will not be used often, can it be worked around with a few lines of script?
No.

Yes.

This is what I'm using in my project:

func kill_audio(player: AudioStreamPlayer2D):
	player.reparent(player.get_parent().get_parent())
	player.finished.connect(player.queue_free)

(I wrote it long time ago, it can be improved)

[Lazy-Rabbit-2001]

Thanks for your comments. Yeah actually I've ever used reparent and static methods (or autoload methods) to achieve the same effect. But i still think it more valuable to integrate the feature into the engine so that everybody can enjoy such a out-of-box feature, reducing wheels and boilerplates.

[AThousandShips]

I think this opens up a lot of potential confusion and error cases, especially for pretty niche applications IMO

I struggle to find good examples of cases where sounds that aren't death/despawn/destruction specific that anyone would want to keep playing, any case specific to that would be trivial to play with some other means (a global player with polyphony handling explosions etc.), so good examples of that would really help the demand for this IMO

On the other hand I can see some usability issues here:

• No ability at all to stop this sound "out of the box", i.e. ways that don't already require some centralized storage that can easily be used to handle the sound anyway, as there's no reference to the stream any longer with the node gone
• Either the risk of causing an unrecoverable state if playing a looping sound, or potential confusion over the seemingly arbitrary limitation that a looping sound can't be played with this case
• Confusion among the assumed target audience (i.e. those who would need an "out of the box" solution, who we can assume are inexperienced) over missing features, like positional sound, as sound position handling is not done on the server but in the (now freed) node, as well as potentially other features that are specific to the player

So to me this is both very niche, and would require sacrificing a lot of features that are specific to the audio stream player classes that would, I assume, be expected to be needed, given that we care about playing the sound from the player itself (if that wasn't relevant the sound would be much easier to play from a central, non-positional, player, without any of the other hassle)

For things like the abrupt ending of some sounds (especially somewhat loud, or noisy sounds, like for example a thruster for a spaceship) I'd say the better solution is to solve it by more intentional game design, for example you don't have to free the node immediately, many games don't remove a node immediately when it is killed etc., you often have for example spaceships go through animations where you get a lot of little explosions all over it, so you can always delay the actual removal a bit to ensure everything is done. You can also cover any abrupt changes in sound by for example an explosion that will effectively mask the end of the thruster sound

Also a very trivial workaround to retain all the functionality I mentioned above is a simple sound object, a scene that's just an audio player node, configured with the appropriate sound (either on spawn, or prefabricated), and with a simple script that frees it on finishing the sound, this can even be given other features like giving it a velocity to follow any debris etc.