View source

final class Sound

package defold

@:native("_G.sound")
  • Functions and messages for controlling sound components and mixer groups.

See SoundMessages for related messages.

Static methods

@:native("get_group_gain")staticgetGroupGain(group:HashOrString):Float

  • Get mixer group gain

Note that gain is in linear scale.

Parameters:

group

group name

Returns:

gain in linear scale

@:native("get_group_name")staticgetGroupName(group:HashOrString):String

  • Get a mixer group name as a string.

Note that this function does not return correct group name in release mode

Parameters:

group

group name

Returns:

group name

@:native("get_groups")staticgetGroups():LuaArray<Hash>

  • Get all mixer group names

Returns:

table of mixer groups names

@:native("get_peak")staticgetPeak(group:HashOrString, window:Float):SoundLeftRight<Float>

  • Get peak value from mixer group.

Note that the returned value might be an approximation and in particular the effective window might be larger than specified.

Parameters:

group

group name

window

window length in seconds

@:native("get_rms")staticgetRms(group:HashOrString, window:Float):SoundLeftRight<Float>

  • Get RMS (Root Mean Square) value from mixer group.

Note that the returned value might be an approximation and in particular the effective window might be larger than specified.

Parameters:

group

group name

window

window length in seconds

@:native("is_music_playing")staticisMusicPlaying():Bool

  • Checks if background music is playing, e.g. from iTunes.

On non mobile platforms, this function always return false.

On Android you can only get a correct reading of this state if your game is not playing any sounds itself. This is a limitation in the Android SDK. If your game is playing any sounds, even with a gain of zero, this function will return false.

The best time to call this function is:

	* In the `init` function of your main collection script before any sounds are triggered
	* In a window listener callback when the window.WINDOW_EVENT_FOCUS_GAINED event is received

Both those times will give you a correct reading of the state even when your application is swapped out and in while playing sounds and it works equally well on Android and iOS.

Returns:

true if music is playing

@:native("is_phone_call_active")staticisPhoneCallActive():Bool

  • Checks if a phone call is active. If there is an active phone call all other sounds will be muted until the phone call is finished.

Returns:

true if there is an active phone call

staticpause(url:HashOrStringOrUrl, pause:Bool):Void

  • Pause all active voices.

Parameters:

url

the sound that should pause

pause

true if the sound should pause

@:has_untypedstaticinlineplay(url:HashOrStringOrUrl, ?playProperties:Null<SoundPlayOptions>, ?completeFunction:(messageId:Hash, message:SoundMessageSoundDone, sender:Url) ‑> Void):SoundPlayId

  • Plays a sound.

Make the sound component play its sound. Multiple voices are supported. The limit is set to 32 voices per sound component.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10<sup>db/20</sup>.

A sound will continue to play even if the game object the sound component belonged to is deleted. You can send a stop_sound to stop the sound.

Parameters:

url

the sound that should play

playProperties

optional table with properties

completeFunction

function to call when the sound has finished playing

Returns:

The play_id of the sound that was played.

@:native("set_gain")staticsetGain(url:HashOrStringOrUrl, ?gain:Float):Void

  • Set gain on all active playing voices of a sound.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10<sup>db/20</sup>.

Parameters:

url

the sound to set the gain of

gain

sound gain between 0 and 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.

@:native("set_group_gain")staticsetGroupGain(group:HashOrString, gain:Float):Bool

  • Set mixer group gain

Note that gain is in linear scale.

Parameters:

group

group name

gain

gain in linear scale

@:native("set_pan")staticsetPan(url:HashOrStringOrUrl, pan:Float):Void

  • Set panning on all active playing voices of a sound.

The valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right.

Parameters:

url

the sound to set the panning value to

pan

sound panning between -1.0 and 1.0

staticstop(url:HashOrStringOrUrl, ?properties:Null<SoundStopOptions>):Void

  • Stop a playing a sound(s).

Stop playing all active voices

Parameters:

url

the sound that should stop

properties

optional sound stopping options