Audio Playback Ended

This event is triggered whenever playback ends for a sound instance played using the audio_play_sound_ functions.

Playback of a sound ends in the following situations: 

• The sound reaches its end position. Pausing a sound using audio_pause_sound, changing its track position using audio_sound_set_track_position or looping a section of it by changing the Audio Loop Points postpones the end of playback as the sound doesn't reach the end position this way.
• The sound is stopped, through a call to audio_stop_sound or audio_stop_all. I.e. stopping a sound also always means it ends playback.
• The sound is forced to stop due to voice stealing: when another sound is played using any of the audio_play_sound_ functions and all channels are used (see audio_channel_num), a channel playing a sound with a lower priority than the new one will be used to play the new sound, i.e. the channel is stolen by the new sound. An Audio Playback Ended event is triggered for the sound that was forced to stop playing.

The event will trigger in all objects that have it, for any sound played in the game (even when it's not played by the same object).

The event returns information in the async_load ds_map. The map contains the following keys in case of an Audio Playback Ended event: 

• "sound_id" - the Sound Instance ID that ended playback.
• "asset_id" - the index of the Sound Asset.
• "was_stopped" - this is set to false, unless the sound was stopped manually using the audio_stop_ functions or when it was forced to stop playing.

NOTE Pausing a sound does not end playback, as playback can still be resumed afterwards.

Example

Suppose you play a sound using any of the audio_play_sound_ functions: 

ins_snd_bgm = audio_play_sound(snd_music, 100, false);

If you call no other sound functions on this sound, it will play until the end. At that point, the Audio Playback Ended event is triggered for the sound. The async_load ds_map will contain the following values in that case: 

• "sound_id" - the sound ID returned by audio_play_sound and stored in ins_snd_bgm
• "asset_id" - snd_music
• "was_stopped" - false (the sound wasn't stopped or forced to stop)

If you stop the sound before it reaches its end, the Audio Playback Ended event is triggered as well. This can be done using any of the following lines of code: 

// Stop the sound instance
audio_stop_sound(ins_snd_bgm);

// Stop all instances of the sound asset
audio_stop_sound(snd_relaxed);

// Stop all sounds that are playing
audio_stop_all();

In this case, the sound was stopped through a call to one of the audio_stop_ functions, so instead of being false, "was_stopped" will be true here.

Finally, if you start playing additional sounds with a higher priority while this sound is playing, these will also take up a channel (or a voice). If no free channels are left then ins_snd_bgm may be forced to stop and the Audio Playback Ended event is triggered. In this case, "was_stopped" is also set to true.