Before using your audio card, you'll need to initialize the sound playback parameters. These parameters are:
- Sampling frequency
- Output audio format
- Number of audio channels and buffer size
It's important to note that LuaSDL can play many sound samples at the same time, where each sound sample uses exactly one sound channel. This is often used for relatively short sounds. Longer sounds such as a game music can be played in the background. However, there's only one background channel, so there is no easy way to mix two songs together.
First, you'll need to initialize the LuaSDL library with its subsystems. It's common practice to just initialize all subsystems at the start.
You can achieve this with two lines of Lua code:
require 'LuaSDL' assert(SDL.SDL_Init(SDL.SDL_INIT_EVERYTHING) >= 0)
This will prepare all subsystems to be fully operational.
To initialize the audio subsystem, follow these steps:
- Normally, you would use the
SDL.SDL_OpenAudiofunction to prepare your audio device for playback. Unfortunately, this would expect you to submit your audio callback function, which isn't very usable in the Lua language environment. You'd need to submit raw audio data as well as mix it up to play any sound at all. - You can use the
SDL.Mix_OpenAudiofunction instead to get basic sound playback to work. This function accepts four parameters: sampling frequency, audio format, channels count and a size of audio buffer.local frequency = 44100 local audioFormat = SDL.MIX_DEFAULT_FORMAT local audioChannels = 2 local bufferSize = 4096 assert(SDL.Mix_OpenAudio(frequency, audioFormat, audioChannels, bufferSize) == 0)
- After this step, you'll be able to play sound samples.
- The audio device should always be closed after you finish playing sound samples. You can do this with the
SDL.Mix_CloseAudiofunction without any parameters.SDL.Mix_CloseAudio()
This function is usually used just before closing your application.
The LibSDL library is divided into a set of subsystems that includes timers, audio, video, CD-ROM, and joystick. Each of these subsystems takes a small amount of computer memory and can be enabled when needed. Notably, the audio subsystem reserves internal memory for audio processing and audio buffers upon initialization. Without the SDL_Mixer extension, you will need to prepare your own audio mixing routine and do audio format decoding by yourself. The Lua language isn't very appropriate for such tasks, since it uses the garbage collector, which adds latention to code execution. This can be quite notable during audio playback. The SDL_Mixer extension handles this for you, so you can simply choose how many audio mixing channels you need and use the available audio decoding functions to play various audio formats.
The SDL.Mix_OpenAudio function will set up the correct audio format and prepares the audio mixing channels. By default, there are eight mixing channels. This means you can play eight sounds in parallel and this should be sufficient for simple games. One channel can be occupied by one sound at a time. More complex games can use up all eight channels quite quickly and would result in sound skipping. Many games today commonly use 32 mixing channels.
Another important thing is the sound buffer size. This will determine the minimal latency accompanied by sound mixing. A larger sound buffer can result in smoother playback; however, there's a price for that in the form of greater latency. So, the response to a quick change of sounds can be slower. This is especially true with digital sound processing (DSP), where the size of the sound buffer should be as small as possible. On the other hand, if the buffer is too small, your computer might not be fast enough to process all incoming data and can result in notable pops and clicks in the sound output. The usual size of the sound buffer is between 512 and 4,096 bytes.
The audio format can be left at its default value, SDL.MIX_DEFAULT_FORMAT, which means that each sound sample will be described by a 16-bit signed integer. A list of applicable sample formats can be found in the following table:
|
Sound format identifier |
Description |
|---|---|
|
|
These are unsigned 8-bit samples |
|
|
These are signed 8-bit samples |
|
|
These are unsigned 16-bit samples with little-endian byte order |
|
|
These are signed 16-bit samples with little-endian byte order |
|
|
These are unsigned 16-bit samples with big-endian byte order |
|
|
These are signed 16-bit samples with big-endian byte order |
|
|
This is the same as SDL.AUDIO_U16LSB |
|
|
This is the same as SDL.AUDIO_S16LSB |
|
|
These are unsigned 16-bit samples with system byte order |
|
|
These are signed 16-bit samples with system byte order |
The last important thing is the number of output channels. The SDL.Mix_OpenAudio function accepts one or two channels, so you can have mono or stereo output.