View source

class FlxSound

package flixel.sound

extends FlxBasic

@:directlyUsed

This is the universal flixel sound object, used for streaming, music, and sound effects.

Constructor

new()

The FlxSound constructor gets all the variables initialized, but NOT ready to play a sound yet.

Variables

read onlyamplitude:Float

Stores the average wave amplitude of both stereo channels

read onlyamplitudeLeft:Float

Just the amplitude of the left stereo channel

read onlyamplitudeRight:Float

Just the amplitude of the right stereo channel

read onlyartist:String

The ID3 artist name. Defaults to null. Currently only works for streamed sounds.

autoDestroy:Bool

Whether to call destroy() when the sound has finished playing.

endTime:Null<Float>

At which point to stop playing the sound, in milliseconds. If not set / null, the sound completes normally.

Available since

4.2.0

.

fadeTween:FlxTween

The tween used to fade this sound's volume in and out (set via fadeIn() and fadeOut())

Available since

4.1.0

.

group:FlxSoundGroup

The sound group this sound belongs to, can only be in one group. NOTE: This setter is deprecated, use group.add(sound) or group.remove(sound).

read onlylength:Float

The length of the sound in milliseconds.

Available since

4.2.0

.

@:value(0)loopTime:Float = 0

In case of looping, the point (in milliseconds) from where to restart the sound when it loops back

Available since

4.1.0

.

looped:Bool

Whether or not this sound should loop.

read onlyname:String

The ID3 song name. Defaults to null. Currently only works for streamed sounds.

pan:Float

Pan amount. -1 = full left, 1 = full right. Proximity based panning overrides this.

Note: On desktop targets this only works with mono sounds, due to limitations of OpenAL. More info: OpenFL Forums - SoundTransform.pan does not work

persist:Bool

Whether or not this sound should be automatically destroyed when you switch states.

read onlyplaying:Bool

Whether or not the sound is currently playing.

time:Float

The position in runtime of the music playback in milliseconds. If set while paused, changes only come into effect after a resume() call.

volume:Float

Set volume to a value between 0 and 1 to change how this sound is.

x:Float

The x position of this sound in world coordinates. Only really matters if you are doing proximity/panning stuff.

y:Float

The y position of this sound in world coordinates. Only really matters if you are doing proximity/panning stuff.

onComplete:() ‑> Void

Tracker for sound complete callback. If assigned, will be called each time when sound reaches its end.

Methods

@:value({ To : 1, From : 0, Duration : 1 })inlinefadeIn(Duration:Float = 1, From:Float = 0, To:Float = 1, ?onComplete:FlxTween ‑> Void):FlxSound

Helper function that tweens this sound's volume.

Parameters:

Duration

The amount of time the fade-in operation should take.

From

The volume to tween from, 0 by default.

To

The volume to tween to, 1 by default.

@:value({ To : 0, Duration : 1 })inlinefadeOut(Duration:Float = 1, To:Float = 0, ?onComplete:FlxTween ‑> Void):FlxSound

Helper function that tweens this sound's volume.

Parameters:

Duration

The amount of time the fade-out operation should take.

To

The volume to tween to, 0 by default.

inlinegetActualVolume():Float

Returns the currently selected "real" volume of the sound (takes fades and proximity into account).

Returns:

The adjusted volume of the sound.

@:value({ AutoDestroy : false, Looped : false })loadByteArray(Bytes:ByteArray, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:() ‑> Void):FlxSound

One of the main setup functions for sounds, this function loads a sound from a ByteArray.

Parameters:

Bytes

A ByteArray object.

Looped

Whether or not this sound should loop endlessly.

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.

Returns:

This FlxSound instance (nice for chaining stuff together, if you're into that).

@:value({ AutoDestroy : false, Looped : false })loadEmbedded(EmbeddedSound:FlxSoundAsset, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:() ‑> Void):FlxSound

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

Parameters:

EmbeddedSound

An embedded Class object representing an MP3 file.

Looped

Whether or not this sound should loop endlessly.

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.

OnComplete

Called when the sound finished playing

Returns:

This FlxSound instance (nice for chaining stuff together, if you're into that).

@:value({ AutoDestroy : false, Looped : false })loadStream(SoundURL:String, Looped:Bool = false, AutoDestroy:Bool = false, ?OnComplete:() ‑> Void, ?OnLoad:() ‑> Void):FlxSound

One of the main setup functions for sounds, this function loads a sound from a URL.

Parameters:

SoundURL

A string representing the URL of the MP3 file you want to play.

Looped

Whether or not this sound should loop endlessly.

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.

OnComplete

Called when the sound finished playing

OnLoad

Called when the sound finished loading.

Returns:

This FlxSound instance (nice for chaining stuff together, if you're into that).

pause():FlxSound

Call this function to pause this sound.

@:value({ StartTime : 0.0, ForceRestart : false })play(ForceRestart:Bool = false, StartTime:Float = 0.0, ?EndTime:Float):FlxSound

Call this function to play the sound - also works on paused sounds.

Parameters:

ForceRestart

Whether to start the sound over or not. Default value is false, meaning if the sound is already playing or was paused when you call play(), it will continue playing from its current position, NOT start again from the beginning.

StartTime

At which point to start playing the sound, in milliseconds.

EndTime

At which point to stop playing the sound, in milliseconds. If not set / null, the sound completes normally.

@:value({ Pan : true })proximity(X:Float, Y:Float, TargetObject:FlxObject, Radius:Float, Pan:Bool = true):FlxSound

Call this function if you want this sound's volume to change based on distance from a particular FlxObject.

Parameters:

X

The X position of the sound.

Y

The Y position of the sound.

TargetObject

The object you want to track.

Radius

The maximum distance this sound can travel.

Pan

Whether panning should be used in addition to the volume changes.

Returns:

This FlxSound instance (nice for chaining stuff together, if you're into that).

resume():FlxSound

Unpause a sound. Only works on sounds that have been paused.

@:value({ Y : 0, X : 0 })inlinesetPosition(X:Float = 0, Y:Float = 0):Void

Helper function to set the coordinates of this object. Sound positioning is used in conjunction with proximity/panning.

Parameters:

X

The new x position

Y

The new y position

inlinestop():FlxSound

Call this function to stop this sound.

update(elapsed:Float):Void

Handles fade out, fade in, panning, proximity, and amplitude operations each frame.

Inherited Variables

Defined by FlxBasic

@:value(idEnumerator++)ID:Int = idEnumerator++

A unique ID starting from 0 and increasing by 1 for each subsequent FlxBasic that is created.

@:value(true)active:Bool = true

Controls whether update() is automatically called by FlxState/FlxGroup.

@:value(true)alive:Bool = true

Useful state for many game objects - "dead" (!alive) vs alive. kill() and revive() both flip this switch (along with exists, but you can override that).

camera:FlxCamera

Gets or sets the first camera of this object.

cameras:Array<FlxCamera>

This determines on which FlxCameras this object will be drawn. If it is null / has not been set, it uses the list of default draw targets, which is controlled via FlxG.camera.setDefaultDrawTarget as well as the DefaultDrawTarget argument of FlxG.camera.add.

read onlycontainer:Null<FlxContainer>

The parent containing this basic, typically if you check this recursively you should reach the state

Available since

5.7.0

.

@:value(true)exists:Bool = true

Controls whether update() and draw() are automatically called by FlxState/FlxGroup.

@:value(true)visible:Bool = true

Controls whether draw() is automatically called by FlxState/FlxGroup.

Inherited Methods

Defined by FlxBasic

draw():Void

Override this function to control how the object is drawn. Doing so is rarely necessary, but can be very useful.

getCameras():Array<FlxCamera>

The cameras that will draw this. Use this.cameras to set specific cameras for this object, otherwise the container's cameras are used, or the container's container and so on. If there is no container, say, if this is inside FlxGroups rather than a FlxContainer then the default draw cameras are returned.

Available since

5.7.0

.

getDefaultCamera():FlxCamera

The main camera that will draw this. Use this.cameras to set specific cameras for this object, otherwise the container's camera is used, or the container's container and so on. If there is no container, say, if this is inside FlxGroups rather than a FlxContainer then FlxG.camera is returned.

Available since

5.7.0

.

revive():Void

Handy function for bringing game objects "back to life". Just sets alive and exists back to true. In practice, this function is most often called by FlxObject#reset().