avm1: Improve behavior of Sound when loadSound() has been called

[ChrisCPI]

Description

Fixes #5019
Fixes #22572

This fixes several of the behaviors of the Sound object when playing external sound via loadSound().

When loadSound is called on a Sound, it appears that it enters a state of being "separated" from its original owner (even when controlling global sound). This means it can no longer control any prior sounds that were added to it via attachSound (and can no longer attach new sounds in this way), and it inherits its own unique sound transform, not attached to any particular display object. This has now been implemented.

Some of the other changes include:

• Added a is_stopped flag to the native object, which is true when stop() has been called. Used to prevent external sound from playing when it has finished loading.
• When calling start(), per the docs, the second argument (loops) is now ignored when the sound is streaming.
• When loadSound is called again on the object, any external sounds it was playing are stopped, streaming or not.

Testing

Several tests added to cover this.

Checklist

• I, a human, have self-reviewed this PR and fully understand the changes within.
• I have made or updated tests where possible.
• All of my commits are properly scoped, compile successfully, and pass all tests.
• This PR does not make sense to split up into smaller PRs.
• An LLM was involved in the authoring of this code. (Used in authoring the added set_sound_transform_with_handle function)

[kjarosh]

Instead of giving multiple meanings to this field, can't you reuse the state enum?

[ChrisCPI]

I'm not sure how I would do that exactly?

Earlier I had a separate is_external field in the native object, but it seemed redundant since it should always be true when the transform is Some, and always false when transform is None.

[kjarosh]

You could have the transform in the state enum, e.g. a separate enum entry for when the sound is external. But that depends on how it plays with the loading/loaded states.

[ChrisCPI]

But doesn't it not make sense to have it be a part of the state enum? Because e.g. if a sound was still being loaded (in the Loading state), wouldn't that mean it can't access the transform being stored in a separate state, because it's not in that state at that time?

[Lord-McSweeney]

If both is_stopped and transform are only valid for external sounds, I would suggest adding a new struct called ExternalSound or ExternalSoundInfo that holds both pieces of information, and adding a single Option<ExternalSoundInfo> field to SoundData rather than the two new fields.

[ChrisCPI]

I can look into doing that if no one disagrees with the idea.

[ChrisCPI]

If both is_stopped and transform are only valid for external sounds, I would suggest adding a new struct called ExternalSound or ExternalSoundInfo that holds both pieces of information, and adding a single Option<ExternalSoundInfo> field to SoundData rather than the two new fields.

@kjarosh Thoughts on doing this idea? I think it could be helpful in using that to check whether the sound is external, rather than checking the transform.

[kjarosh]

It depends on how this plays with the loading state, if it's unrelated to the state then yes.

[ChrisCPI]

Putting this in draft for now - Need to do some refactoring, as it looks like the idea of the existence of a playback queue for loaded sounds is incorrect, and so I will likely remove it (effectively undoing most of #21163).

What actually appears to be happening is that in FP, local sounds are loaded synchronously, so that when loadSound() is called, it doesn't continue executing until the sound has been loaded. This is why the start() calls appeared to be queued, when they actually are not.

An easy way to observe this is to see that the onLoad listener can be fired in-between two traces before/after a loadSound() call. e.g.:

var s = new Sound();
s.onLoad = function() { trace("onLoad"); }
trace("before");
s.loadSound("sound.mp3");
trace("after");

In the local projector, this outputs:

before
onLoad
after

But when loading a remote file, it becomes asynchronous, and start() calls have no effect before the sound is fully loaded.