Add sound activeInstancesCount property (#17368)

Partially addresses feature request:
https://forum.babylonjs.com/t/allow-to-reject-sound-plays-if-maxinstances-number-is-reached/60433

Author: docEdub

packages/dev/core/src/AudioV2/abstractAudio/abstractSound.ts

@@ -67,6 +67,13 @@ export abstract class AbstractSound extends AbstractSoundSource {
         super(name, engine, AudioNodeType.HAS_INPUTS_AND_OUTPUTS); // Inputs are for instances.
     }
 
+    /**
+     * The number of active instances of the sound that are currently playing.
+     */
+    public get activeInstancesCount(): number {
+        return this._instances.size;
+    }
+
     /**
      * Whether the sound should start playing automatically. Defaults to `false`.
      */

packages/dev/core/src/AudioV2/abstractAudio/abstractSoundInstance.ts

@@ -60,5 +60,9 @@ export abstract class _AbstractSoundInstance extends AbstractAudioNode {
 
         this._state = value;
         this.onStateChangedObservable.notifyObservers(this);
+
+        if (this._state === SoundState.Stopped) {
+            this.onEndedObservable.notifyObservers(this);
+        }
     }
 }

packages/dev/core/src/AudioV2/webAudio/webAudioStreamingSound.ts

@@ -239,7 +239,7 @@ class _WebAudioStreamingSoundInstance extends _StreamingSoundInstance implements
 
         if (restart) {
             this._mediaElement.pause();
-            this._setState(SoundState.Stopped);
+            this._state = SoundState.Stopped;
         }
 
         this._options.startOffset = value;

packages/tools/tests/test/audioV2/shared/abstractSound.activeInstancesCount.ts

@@ -0,0 +1,68 @@
+import { EvaluateTestAsync } from "../utils/abstractSound.utils";
+import { SoundType } from "../utils/audioV2.utils";
+
+import { expect, test } from "@playwright/test";
+
+export const AddSharedAbstractSoundActiveInstancesCountTests = (soundType: SoundType) => {
+    test.describe(`${soundType} activeInstancesCount`, () => {
+        test("The `activeInstancesCount` property should equal 1 while playing", async ({ page }) => {
+            const result = await EvaluateTestAsync(page, soundType, async ({ soundType }) => {
+                await AudioV2Test.CreateAudioEngineAsync(soundType);
+                const sound = await AudioV2Test.CreateAbstractSoundAsync(soundType, audioTestConfig.pulsed3CountSoundFile);
+
+                sound.play();
+                await AudioV2Test.WaitAsync(1);
+
+                return sound.activeInstancesCount;
+            });
+
+            expect(result).toBe(1);
+        });
+
+        test("The `activeInstancesCount` property should equal 0 when stopped", async ({ page }) => {
+            const result = await EvaluateTestAsync(page, soundType, async ({ soundType }) => {
+                await AudioV2Test.CreateAudioEngineAsync(soundType);
+                const sound = await AudioV2Test.CreateAbstractSoundAsync(soundType, audioTestConfig.pulsed3CountSoundFile);
+
+                sound.play();
+                await AudioV2Test.WaitAsync(1);
+                sound.stop();
+
+                return sound.activeInstancesCount;
+            });
+
+            expect(result).toBe(0);
+        });
+
+        test("The `activeInstancesCount` property should equal 2 when played twice", async ({ page }) => {
+            const result = await EvaluateTestAsync(page, soundType, async ({ soundType }) => {
+                await AudioV2Test.CreateAudioEngineAsync(soundType);
+                const sound = await AudioV2Test.CreateAbstractSoundAsync(soundType, audioTestConfig.pulsed3CountSoundFile);
+
+                sound.play();
+                sound.play();
+                await AudioV2Test.WaitAsync(1);
+
+                return sound.activeInstancesCount;
+            });
+
+            expect(result).toBe(2);
+        });
+
+        test("The `activeInstancesCount` property should equal 0 when played twice and stopped", async ({ page }) => {
+            const result = await EvaluateTestAsync(page, soundType, async ({ soundType }) => {
+                await AudioV2Test.CreateAudioEngineAsync(soundType);
+                const sound = await AudioV2Test.CreateAbstractSoundAsync(soundType, audioTestConfig.pulsed3CountSoundFile);
+
+                sound.play();
+                sound.play();
+                await AudioV2Test.WaitAsync(1);
+                sound.stop();
+
+                return sound.activeInstancesCount;
+            });
+
+            expect(result).toBe(0);
+        });
+    });
+};

packages/tools/tests/test/audioV2/staticSound.activeInstancesCount.test.ts

@@ -0,0 +1,5 @@
+import { AddSharedAbstractSoundActiveInstancesCountTests } from "./shared/abstractSound.activeInstancesCount";
+import { InitAudioV2Tests } from "./utils/audioV2.utils";
+
+InitAudioV2Tests();
+AddSharedAbstractSoundActiveInstancesCountTests("StaticSound");

packages/tools/tests/test/audioV2/streamingSound.activeInstancesCount.test.ts

@@ -0,0 +1,5 @@
+import { AddSharedAbstractSoundActiveInstancesCountTests } from "./shared/abstractSound.activeInstancesCount";
+import { InitAudioV2Tests } from "./utils/audioV2.utils";
+
+InitAudioV2Tests();
+AddSharedAbstractSoundActiveInstancesCountTests("StreamingSound");