Cleanup: Streamline the AudioSource primitive

Author: rdw-software

Core/API/WebAudio/AudioSource.js

@@ -1,5 +1,7 @@
 // todo eliminate auxiliary classes
 class AudioSource {
+	static ERROR_INVALID_PLAYBACK_RATE = "Cannot set negative or zero playback rate; only positive values are supported";
+
 	playbackOptions = {
 		autoplay: true,
 		loop: true,
@@ -34,6 +36,9 @@ class AudioSource {
 		this.playbackOptions = playbackOptions;
 		this.filePath = filePath;
 
+		// BJS doesn't expose this, so we have to store it at this level (at the risk of being wrong)
+		this.playbackRate = 1;
+
 		const resource = C_Decoding.decodeFile(filePath); // May be fetched from disk (TODO: It's blocking, use async?)
 		this.uniqueID = new UniqueID();
 
@@ -66,7 +71,7 @@ class AudioSource {
 		// validatePositiveInteger(newVolumePercentage);
 		// validatePositiveInteger(timeToFullyApplyChangeInMilliseconds);
 		this.sound.setVolume(newVolumePercentage, timeToFullyApplyChangeInMilliseconds / 1000); // ms to sec
-		// todo write all this up to the audio options for easier manual testing?
+		// TODO write all this up to the audio options for easier manual testing?
 	}
 	getVolume() {
 		return this.sound.getVolume();
@@ -86,39 +91,26 @@ class AudioSource {
 		// TODO fade in to set volume (take from settings)
 		this.setVolume(volumeGain, timeToFadeInCompletelyInMilliseconds);
 	}
-	// scene switch while scene is loading?
-	// combining looped/nonlooped sounds, use different tracks and AudioTrack.stopAllSounds
-	// analyzer
-	// playback rate
-	setPlaybackRate(newRateAsPercentage) {
-		// validatePositiveInteger(newRateAsPercentage);
-		this.sound.setPlaybackRate(newRateAsPercentage);
-	}
-	attachToUnit(unitID) {
-		// validateUnitID(unitID);
-		throw new NotYetImplementedError("AudioSource.attachToUnit");
-	}
-	attachToCamera() {
-		throw new NotYetImplementedError("AudioSource.attachToCamera");
-	}
-	attachToSprite(animatedSprite) {
-		throw new NotYetImplementedError("AudioSource.attachToSprite");
+	getPlaybackRate() {
+		return this.playbackRate;
 	}
-	attachToModel(animatedModel) {
-		throw new NotYetImplementedError("AudioSource.attachToMesh");
-	}
-	setWorldPosition(worldX, worldY, worldZ) {
-		// validateWorldPosition(worldX, worldY, worldZ);
-		throw new NotYetImplementedError("AudioSource.setWorldPosition");
-	}
-	setMapPosition(mapU, mapV) {
-		// validateMapPosition(mapU, mapV);
-		throw new NotYetImplementedError("AudioSource.setMapPosition");
+	setPlaybackRate(newPlaybackRate) {
+		validateNumber(newPlaybackRate, "Usage: AudioSource.setPlaybackRate(Number newPlaybackRate)");
+
+		if (newPlaybackRate <= 0) throw new RangeError(AudioSource.ERROR_INVALID_PLAYBACK_RATE);
+
+		this.playbackRate = newPlaybackRate;
+		this.sound.setPlaybackRate(newPlaybackRate);
 	}
-	getSoundHandle() {
+	getUniqueID() {
 		return this.uniqueID.toString();
 	}
 	destroy() {
+		if (this.sound === null) return false; // Already destroyed; all operations should fail
+
 		this.sound.dispose();
+		this.sound = null;
+
+		return true;
 	}
 }