This function plays any Sound Asset in your game.
NOTE An Audio Playback Ended event is triggered for the sound when it stops playing.
You provide the sound asset and assign it a priority, which is then used to determine how sounds are dealt with when the number of sounds playing is over the limit set by the function audio_channel_num(). Lower priority sounds will be stopped in favour of higher priority sounds, and the priority value can be any real number (the actual value is arbitrary, and can be from 0 to 1 or 0 to 100, as GameMaker will prioritise them the same). The higher the number the higher the priority, so a sound with priority 100 will be favoured over a sound with priority 1.
The third argument is for making the sound loop and setting it to true will make the sound repeat until it's stopped manually, and setting it to false will play the sound once only.
This function will also return a unique index for the sound being played, which can be stored in a variable so you can later pause it or stop it. This means that if you have multiple instances of the same sound playing at any one time, you can target just one instance of that sound using the audio functions.
There are four optional arguments that allow you to change the Audio Properties of the sound being played at the instance/voice level:
... [gain], [offset], [pitch], [listener_mask]
They are applied to the sound immediately. This fixes the issues you would face when calling a separate function to change any of these values, which could cause an undesired delay in the change.
These properties are multiplied by their corresponding value of the sound asset. See Audio Properties Overview for a full overview.
NOTE To change the value of any of these properties after playback of a sound has been started, see audio_sound_gain for gain, audio_sound_set_track_position for offset, audio_sound_pitch for pitch and audio_sound_set_listener_mask for listener mask.
audio_play_sound(index, priority, loop, [gain], [offset], [pitch], [listener_mask]);
| Argument | Type | Description |
|---|---|---|
| index | Sound Asset or Audio Queue ID | The index of the sound to play. |
| priority | Real | Set the channel priority for the sound. |
| loop | Boolean | Sets the sound to loop or not. |
| gain | Real | OPTIONAL The gain of the sound instance (defaults to 1). |
| offset | Real | OPTIONAL The time (in seconds) to start playing. Values beyond the end of the sound are clamped to its length. The default value is the asset-level offset, this value overrides it when provided. |
| pitch | Real | OPTIONAL The pitch multiplier (defaults to 1). |
| listener_mask | Real | OPTIONAL The bitmask data to set for the sound. On the HTML5 target this will have no effect as the target does not support more than one listener. |
if (health <= 0)
{
lives -= 1;
audio_play_sound(snd_PlayerDead, 10, false);
}
The above code checks the "health" global variable and if it is less than or equal to 0, it will remove 1 from the "lives" global variable and play a sound.
if (bbox_left > room_width)
{
audio_play_sound(snd_Goodbye, 10, false, 1.1, 0, 2);
}
The above code checks if the instance is past the right bound of the room and plays a sound with a gain of 1.1 and a pitch of 2 (twice the normal pitch).
audio_sound_gain(snd_Explosion, 0.7);
audio_sound_set_track_position(snd_Explosion, 2);
audio_play_sound(snd_Explosion, 10, false, 0.5);
audio_play_sound(snd_Explosion, 20, false, 1, 0);
The above code plays the same sound multiple times.
First, the gain for the sound asset snd_Explosion is set to 0.7. Next, its track position (the position from which to start playing) is set to 2 seconds.
After that, two instances of the sound are played. The first gets an instance-level gain of 0.5 and no offset. This sound instance starts playing at 2 seconds and will be heard with a gain of 0.5 * 0.7 = 0.35. The second instance keeps the instance-level gain at 1 and will be heard with a gain of 0.7 * 1 = 0.7. Its offset is provided, which overrides the 2-second offset set for the asset. This instance plays from the start.