Rework FlxSound load methods

flixel/sound/FlxSound.hx

@@ -333,56 +333,96 @@ class FlxSound extends FlxBasic
 	}
 
 	/**
-	 * One of the main setup functions for sounds, this function loads a sound from an embedded MP3.
-	 *
+	 * Loads a sound from the provided sound asset.
+	 * The asset can be an OpenFL Sound instance, embedded sound, file path or byte array.
+	 * 
 	 * **Note:** If the `FLX_DEFAULT_SOUND_EXT` flag is enabled, you may omit the file extension
-	 *
-	 * @param	EmbeddedSound	An embedded Class object representing an MP3 file.
-	 * @param	Looped			Whether or not this sound should loop endlessly.
-	 * @param	AutoDestroy		Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
-	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.stream()` will set it to true by default.
-	 * @param	OnComplete		Called when the sound finished playing
-	 * @return	This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 * 
+	 * @param sound The sound asset to load.
+	 * @param looped Whether or not this sound should loop endlessly.
+	 * @param autoDestroy Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
+	 * @param onComplete Called when the sound finishes playing.
+	 * @return This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 * 
+	 * @since 6.2.0
 	 */
-	public function loadEmbedded(EmbeddedSound:FlxSoundAsset, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void):FlxSound
+	public function load(sound:FlxSoundAsset, looped:Bool = false, autoDestroy:Bool = false, ?onComplete:Void->Void):FlxSound
 	{
-		if (EmbeddedSound == null)
+		if (sound == null)
 			return this;
 
 		cleanup(true);
 
-		if ((EmbeddedSound is Sound))
+		if ((sound is Sound))
 		{
-			_sound = EmbeddedSound;
+			_sound = sound;
 		}
-		else if ((EmbeddedSound is Class))
+		else if ((sound is Class))
 		{
-			_sound = Type.createInstance(EmbeddedSound, []);
+			_sound = Type.createInstance(sound, []);
 		}
-		else if ((EmbeddedSound is String))
+		else if ((sound is String))
 		{
-			if (FlxG.assets.exists(EmbeddedSound, SOUND))
-				_sound = FlxG.assets.getSoundUnsafe(EmbeddedSound);
+			if (FlxG.assets.exists(sound, SOUND))
+				_sound = FlxG.assets.getSoundUnsafe(sound);
 			else
-				FlxG.log.error('Could not find a Sound asset with an ID of \'$EmbeddedSound\'.');
+				FlxG.log.error('Could not find a Sound asset with an ID of \'$sound\'.');
+		}
+		else if ((sound is ByteArrayData))
+		{
+			var bytes:ByteArray = cast sound;
+
+			_sound = new Sound();
+			_sound.addEventListener(Event.ID3, gotID3);
+			_sound.loadCompressedDataFromByteArray(bytes, bytes.length);
 		}
 
 		// NOTE: can't pull ID3 info from embedded sound currently
-		return init(Looped, AutoDestroy, OnComplete);
+		return init(looped, autoDestroy, onComplete);
 	}
-	
+
 	/**
-	 * One of the main setup functions for sounds, this function loads a sound from a URL.
-	 *
-	 * @param	SoundURL		A string representing the URL of the MP3 file you want to play.
-	 * @param	Looped			Whether or not this sound should loop endlessly.
-	 * @param	AutoDestroy		Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
-	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.stream()` will set it to true by default.
-	 * @param	OnComplete		Called when the sound finished playing
-	 * @param	OnLoad			Called when the sound finished loading.
-	 * @return	This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 * Loads a streamed sound from the provided file path.
+	 * This does not load sounds from web locations. Use `loadFromURL()` for that, instead.
+	 * 
+	 * If sound streaming is not supported, a normal sound will be returned.
+	 * 
+	 * **Note:** If the `FLX_DEFAULT_SOUND_EXT` flag is enabled, you may omit the file extension
+	 * 
+	 * @param path The path to the sound asset.
+	 * @param looped Whether or not this sound should loop endlessly.
+	 * @param autoDestroy Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
+	 * @param onComplete Called when the sound finishes playing.
+	 * @return This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 * 
+	 * @since 6.2.0
 	 */
-	public function loadStream(SoundURL:String, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void, ?OnLoad:Void->Void):FlxSound
+	public function loadStreamed(path:String, looped:Bool = false, autoDestroy:Bool = false, ?onComplete:Void->Void):FlxSound
+	{
+		cleanup(true);
+
+		if (FlxG.assets.exists(path, MUSIC))
+			_sound = FlxG.assets.getMusicUnsafe(path);
+		else
+			FlxG.log.error('Could not find a Sound asset with an ID of \'$path\'.');
+
+		// NOTE: can't pull ID3 info from embedded sound currently
+		return init(looped, autoDestroy, onComplete);
+	}
+
+	/**
+	 * Loads a sound from the provided URL.
+	 * 
+	 * @param soundURL A string representing the URL of the sound you want to play.
+	 * @param looped Whether or not this sound should loop endlessly.
+	 * @param autoDestroy Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
+	 * @param onComplete Called when the sound finishes playing.
+	 * @param onLoad Called when the sound finishes loading.
+	 * @return This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 * 
+	 * @since 6.2.0
+	 */
+	public function loadFromURL(soundURL:String, looped:Bool = false, autoDestroy:Bool = false, ?onComplete:Void->Void, ?onLoad:Void->Void):FlxSound
 	{
 		cleanup(true);
 
@@ -396,15 +436,50 @@ class FlxSound extends FlxBasic
 			if (_sound == e.target)
 			{
 				_length = _sound.length;
-				if (OnLoad != null)
-					OnLoad();
+				if (onLoad != null)
+					onLoad();
 			}
 		}
 		// Use a weak reference so this can be garbage collected if destroyed before loading.
 		_sound.addEventListener(Event.COMPLETE, loadCallback, false, 0, true);
-		_sound.load(new URLRequest(SoundURL));
+		_sound.load(new URLRequest(soundURL));
 
-		return init(Looped, AutoDestroy, OnComplete);
+		return init(looped, autoDestroy, onComplete);
+	}
+
+	/**
+	 * One of the main setup functions for sounds, this function loads a sound from an embedded MP3.
+	 *
+	 * **Note:** If the `FLX_DEFAULT_SOUND_EXT` flag is enabled, you may omit the file extension
+	 *
+	 * @param	EmbeddedSound	An embedded Class object representing an MP3 file.
+	 * @param	Looped			Whether or not this sound should loop endlessly.
+	 * @param	AutoDestroy		Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
+	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.loadFromURL()` will set it to true by default.
+	 * @param	OnComplete		Called when the sound finished playing
+	 * @return	This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 */
+	@:deprecated("loadEmbedded() is deprecated, use load() instead.")
+	public function loadEmbedded(EmbeddedSound:FlxSoundAsset, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void):FlxSound
+	{
+		return load(EmbeddedSound, Looped, AutoDestroy, OnComplete);
+	}
+
+	/**
+	 * One of the main setup functions for sounds, this function loads a sound from a URL.
+	 *
+	 * @param	SoundURL		A string representing the URL of the MP3 file you want to play.
+	 * @param	Looped			Whether or not this sound should loop endlessly.
+	 * @param	AutoDestroy		Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
+	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.loadFromURL()` will set it to true by default.
+	 * @param	OnComplete		Called when the sound finished playing
+	 * @param	OnLoad			Called when the sound finished loading.
+	 * @return	This FlxSound instance (nice for chaining stuff together, if you're into that).
+	 */
+	@:deprecated("loadStream() is deprecated, use loadFromURL() instead.")
+	public function loadStream(SoundURL:String, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void, ?OnLoad:Void->Void):FlxSound
+	{
+		return loadFromURL(SoundURL, Looped, AutoDestroy, OnComplete, OnLoad);
 	}
 
 	/**
@@ -413,18 +488,13 @@ class FlxSound extends FlxBasic
 	 * @param	Bytes 			A ByteArray object.
 	 * @param	Looped			Whether or not this sound should loop endlessly.
 	 * @param	AutoDestroy		Whether or not this FlxSound instance should be destroyed when the sound finishes playing.
-	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.stream()` will set it to true by default.
+	 * 							Default value is false, but `FlxG.sound.play()` and `FlxG.sound.loadFromURL()` will set it to true by default.
 	 * @return	This FlxSound instance (nice for chaining stuff together, if you're into that).
 	 */
+	@:deprecated("loadByteArray() is deprecated, use load() instead.")
 	public function loadByteArray(Bytes:ByteArray, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void):FlxSound
 	{
-		cleanup(true);
-
-		_sound = new Sound();
-		_sound.addEventListener(Event.ID3, gotID3);
-		_sound.loadCompressedDataFromByteArray(Bytes, Bytes.length);
-
-		return init(Looped, AutoDestroy, OnComplete);
+		return load(Bytes, Looped, AutoDestroy, OnComplete);
 	}
 
 	function init(Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:Void->Void):FlxSound

flixel/system/FlxAssets.hx

@@ -35,7 +35,7 @@ class VirtualInputData extends #if nme ByteArray #else ByteArrayData #end {}
 
 typedef FlxTexturePackerJsonAsset = FlxJsonAsset<TexturePackerAtlas>;
 typedef FlxAsepriteJsonAsset = FlxJsonAsset<AseAtlas>;
-typedef FlxSoundAsset = OneOfThree<String, Sound, Class<Sound>>;
+typedef FlxSoundAsset = OneOfFour<String, Sound, Class<Sound>, ByteArray>;
 typedef FlxGraphicAsset = OneOfThree<FlxGraphic, BitmapData, String>;
 typedef FlxTilemapGraphicAsset = OneOfFour<FlxFramesCollection, FlxGraphic, BitmapData, String>;
 typedef FlxBitmapFontGraphicAsset = OneOfFour<FlxFrame, FlxGraphic, BitmapData, String>;