Music playback works similarly to the sound sample playback with one exception that there's only one music channel and it's controlled separately from the other mixing channels.
What's more, music playback can be moved into a specific position, so it can be used as a simple music player if that's your intention.
The music channel is allocated automatically, so there's no need to allocate more mixing channels to play music.
The first step in playing music is:
- To load a sound file into memory with the
SDL.Mix_LoadMUSfunction. In this case, you can use a different set of file formats, such as WAV, MOD, MIDI, OGG, MP3, or even FLAC. This function returns a handle upon success similar to sound samples. If there's a problem loading sound files, it returns thenilvalue:local fileName = 'sound_file.MP3' local musicHandle = SDL.Mix_LoadMUS(fileName)
- From this moment, you can use various functions to control music. The first one,
SDL.Mix_PlayMusic, is to start music playback. The following lines of code show how to play music twice.local loops = 1 SDL.Mix_PlayMusic(musicHandle, loops)
- You can pause and resume music playback by calling the
SDL.Mix_PauseMusicorSDL.Mix_ResumeMusicfunction without any parameters.SDL.Mix_PauseMusic() SDL.Mix_ResumeMusic()
- Music playback can be stopped in two ways. Either you stop the music immediately or slowly fade the volume down. For the first case, there is the
SDL.Mix_HaltMusicfunction, and for the fade out effect, you can use theSDL.Mix_FadeOutMusicfunction:local time = 500 -- 500ms SDL.Mix_HaltMusic() SDl.Mix_FadeOutMusic(time)
There is a fade-in effect for the music as well. This can be achieved with the
SDL.Mix_FadeInMusicfunction:local loops = 0 local time = 500 -- 500ms SDL.Mix_FadeInMusic(musicHandle, loops, time)
- The music position can be controlled with a set of two functions:
SDL.Mix_RewindMusicandSDL.Mix_SetMusicPosition. You can either rewind the position to the beginning of the song or move to a specific time. The latter one can be tricky becauseSDL.Mix_SetMusicPositionwill interpret the time value differently depending on the type of song. OGG files use the time value as a position from the beginning of the song in seconds. MP3 files use it as a relative position in seconds. And lastly, MOD files will cast the value into 16-bit unsigned integers that mark a pattern number.local position = 1.5 -- 1.5s SDL.Mix_RewindMusic(musicHandle) SDL.Mix_SetMusicPosition(position)
- Don't forget to free up the allocated resources after use with the
SDL.Mix_FreeMUSfunction:SDL.Mix_FreeMUS(musicHandle)
LuaSDL always reserves one special audio mixing channel for music playback. It's controlled by a separate set of functions, so it's guaranteed that sound samples won't disturb the music playback.
The SDL.Mix_LoadMUS function can decode other kinds of sound formats, such as MP3 and FLAC. You can't use these formats for sound playback because of the design decisions behind the SDL_Mixer library. These sound formats are better suited for streaming of audio data mainly because of the latency incorporated in audio decoding routines.
Handling of position change in music is not an easy problem to solve because you can easily disturb music playback by a sudden change in sound buffer content. Audio decoding works with chunks of sound data with various sizes depending on the used bit rate of the encoded audio file. That's one of the reasons why you can't use this feature with sound samples.