audio queue manager for GMS2.3.7+

audio_queue_manager.gml

/// @description audio queue manager 0.1.0 alpha
/// Very early version tailored to my needs. It might get
/// heavy changes in the future. I might improve it in the
/// future. Any contribution or suggestions are welcome!
/// Consider each instance as a seperate audio channel
/// You can use more that one instance for multi-channel

/** @Instructions
* Create an empty wav file with your desired duration and name it snd_space
* This wav file will be used as a spacer between the sounds in the queue.
*
* Alternatively you can download the snd_space from here: 
* https://drive.google.com/drive/folders/1-y3s132qFRu0jTOPg9ZEvIbHjPKTjFPj?usp=sharing
*
*
*	//create event
*	aqc = new audio_queue_channel();
*
*	//step event
*	aqc.step();
*
*	//clean_up
*	aqc.clean_up();
*	delete aqc;
*
*	//add a sound into a new queue (will delete and overide any existing aqc queue)
*	aqc.audio_new_queue_add(your_sound);
*
*	//add a sound into queue
*	aqc.audio_queue_add(your_sound);
*
*	//check if the audio queue is currently playing
*	aqc.audio_queue_is_playing(); // will return true or false
*/

/** TODO:
*	allow multiple sounds to be queued in a single line of code
*	make it loop as optional preference 
*	make it pause
*	make it to allow sound duplicates
*	make the snd_space optional
*	replace snd_space with buffer
*	Better and more detailed comments, when more features from this list will be implemented 
*/

// @arg _prior	audio priority
function audio_queue_channel(_prior = 5) constructor {
	
	// the array that holds the queue
	audio_queue = [];
	// the mirror array that will be used to prevent sound duplicates
	audio_queue_ref = [];

	// the priority of the sound
	prior = _prior;
	// the current playing audio
	current_audio = noone;
	
///////////////////////////
//			API			//
/////////////////////////
	
	/// @desc Cleanups any existing queue and adds sound to audio queue
	// @arg sound
	function audio_new_queue_add(sound){
		
		clean_up();
		audio_queue_add(sound);
	}
	
	/// @desc Adds sound to audio queue
	// @arg sound
	function audio_queue_add(sound){
		
		show_debug_message("audio added");
		// If the sound is not in the audio_queue_ref...
		if _array_index_of(audio_queue_ref, sound) == -1
		{
			// add it in audio_queue_ref
			array_push(audio_queue_ref, sound);	
			// add it in audio_queue with a spacer
			array_push(audio_queue, sound, snd_space);
		}
		//else Debug("Dublicate sound found!");
	}

	/// @desc returns true if audio_queue_is_playing, false if not
	function audio_queue_is_playing(){
	
		return array_length(audio_queue) > 0;
	}

	/// @desc use this in the step event
	function step() {
		
		if audio_queue_is_playing()
		{
			// When the current audio finish playing, play the next one from the queue
			if not audio_is_playing(current_audio) 
			{
				
				current_audio = _array_shift();
				if current_audio != noone 
				{
					show_debug_message("playing" + audio_get_name(current_audio));
					audio_play_sound(current_audio, prior, false);
				}
			}
		}
		else 
		{
			current_audio = noone;
			audio_queue_ref = [];
		}
	}
	
	/// @desc Stops and empties the audio queue
	function clean_up() {
		
		if array_length(audio_queue) > 0
		{
			for (var i = 0; i < array_length(audio_queue); i++)
			{
				if audio_is_playing(audio_queue[i]) then audio_stop_sound(audio_queue[i]);
			}
			if audio_is_playing(current_audio) then audio_stop_sound(current_audio);
			current_audio = noone;

			audio_queue = [];
			audio_queue_ref = [];
		}
	}
	
///////////////////////////
//	private functions	//
/////////////////////////

	function _array_shift() {
		
		var value = noone;
		if array_length(audio_queue) > 0
		{
				value = audio_queue[0];
		 
				for(var i = 0; i < (array_length(audio_queue) - 1); i++)
				{
					audio_queue[i] = audio_queue[i + 1];
				}
				array_resize(audio_queue, array_length(audio_queue) - 1);
		}
		return value;
	}
	
	
	function _array_index_of(_arr, _val) {
	
		var result = -1;
	
		if not is_array(_arr) or array_length(_arr) == 0 then return result;
		
		var type = typeof(_val);
		for(var i = 0; i < array_length(_arr); i++)
		{
		    var av = _arr[i];
		    var avtype = typeof(av);
		    if avtype == type 
			{
		        if av == _val
				{
		            result = i;
		            return result;
		        }
		    }
		}
		return result;
	}

}