LuaSDL can play many sound samples at the same time by using mixing channels. This allows you to not only play more sounds simultaneously but also apply basic mixing functions to sound channels, such as volume control, panning, fade-in, and fade-out.
There are eight mixing channels by default, which is usually fine for simple games. You can increase the number of mixing channels by using the SDL.Mix_AllocateChannels function with one argument. The maximum number of channels is limited only by your memory.
This can be used in three ways. If you submit a positive number of channels in the argument, it will allocate channels to match the desired channel count. If the submitted number is lower than a number of currently allocated channels, it'll free up the unnecessary channels. A negative number will only return a number of currently allocated mixing channels. Zero number will free up all mixing channels. However, the background music channel will still be available.
The following line of code will allocate 32 mixing channels, which should be enough even for action games:
SDL.Mix_AllocateChannels(32)
Now, you are ready to load and play sound samples:
- In the first step, you'll need to load your sound file into the memory. This can be done with the
SDL.Mix_LoadWAVfunction. Regardless of its name, it can load sound format files such as WAV, AIFF, RIFF, OGG, and VOC.local fileName = 'sound_file.WAV' local soundSample = SDL.Mix_LoadWAV(fileName)
This will return a sound sample handle, which can be used later to play it. In case of failure or a nonexistent file, you'll get the
nilvalue. - After you finish using the sound sample, you should always free it by using the
SDL.Mix_FreeChunkfunction.SDL.Mix_FreeChunk(soundSample)
- To play the desired sound sample, you can use the
SDL.Mix_PlayChannelfunction. It accepts three arguments, namely, mixing channel number, sound sample handle, and a number of loops. Zero loops means that the sample will play only once:local channel = 0 local loops = 0 SDL.Mix_PlayChannel(channel, soundSample, loops)
- You can pause or resume the mixing channel with functions
SDL.Mix_PauseChannelandSDL.Mix_ResumeChannel.local channel = 0 SDL.Mix_PauseChannel(channel) SDl.Mix_ResumeChannel(channel)
Channel can be stopped with the
SDL.Mix_HaltChannelfunction, which accepts the channel number as the only argument. If you use -1 as the channel number, it'll stop all the available channels.
All functions in this recipe are channel oriented, which means you can control the sound playback for a specific channel. The SDL.Mix_LoadWAV function incorporates decoders for various sound formats.
You can either implement your own mechanism of free channel selection for playback or you can use the channel number -1 in the SDL.Mix_PlayChannel function, so LuaSDL will pick one for you automatically.
Sound playback is done asynchronously in the background thread, so once you start playing a sound sample, you can go ahead and continue executing the other parts of your application.
For more advanced uses there are two other functions to manage simple transitions between sound samples: SDL.Mix_FadeInChannel, SDL.Mix_ExpireChannel, and SDL.Mix_FadeOutChannel.
- The first one will start playing a sound sample while slowly increasing the sound volume from 0 up to full volume:
local channel = 0 local loops = 0 local time = 500 -- 500ms SDL.Mix_FadeInChannel(channel, soundSample, loops, time)
- The second one will stop playing the sound sample after a specified amount of time in milliseconds:
local channel = 0 local time = 500 -- 500ms SDL.Mix_ExpireChannel(channel, time)
- The last one will slowly fade out sound playback. This is used mostly for longer sound samples:
local channel = 0 local fadeOutTime = 500 -- 500ms SDL.Mix_FadeOutChannel(channel, time)
You can query specific channels for their status with the functions SDL.Mix_Playing, SDL.Mix_Paused, and SDL.Mix_FadingChannel.
The first one will tell you whether the channel is occupied with sound playback at the moment. It will return 1 if the channel is currently playing, or 0 if there's nothing to play. However, it can also return a number of channels currently used in playback if you use -1 instead of the number of a channel:
local channel = -1 local status = SDL.Mix_Playing(channel)
The SDL.Mix_Paused function uses a similar mechanism to determine whether the channel is currently in a paused state:
local channel = -1 local status = SDL.Mix_Paused(channel)
The last one, SDL.Mix_FadingChannel, will tell you whether the channel is fading in or fading out.
local channel = 0 local status = SDL.Mix_FadingChannel(channel) if status == SDL.MIX_NO_FADING then -- selected channel is not fading elseif status == SDL.MIX_FADING_IN then -- selected channel is currently fading in elseif status == SDL.MIX_FADING_OUT then -- selected channel is currently fading out end