Chapter 9 – Music and Sound

ATTENTION: You need the most recent Pascal translations by Tim Blume  for this chapter to work properly. Version 1.72 of Tim Blume’s Pascal translations will not work! Check step 2) in Chapter 2 for details.

This chapter will introduce you on how to load music and sounds since these are key features of every game and many applications.

SDL_mixer 2.0 for easy music and sound support

Although SDL 2.0 supports music and sound handling natively, there is an easier way to play music and sound files. The official unit SDL_mixer 2.0 (unit’s name SDL2_mixer) has been created exactly for this purpose and is maintained by the same authors (Sam Lantinga, Stephane Peter, Ryan Gordon) as SDL 2.0 itself. The Pascal translation is fortunately available, too in Tim Blume’s header translations.

Supported music and sound file formats in SDL 2.0

According to the official SDL2_mixer documentation the following music and sound formats are supported:

  • WAVE/RIFF (.wav)
  • AIFF (.aiff)
  • VOC (.voc)
  • MOD (.mod .xm .s3m .669 .it .med and more) requiring libmikmod on system
  • MIDI (.mid) using timidity or native midi hardware
  • OggVorbis (.ogg) requiring ogg/vorbis libraries on system
  • MP3 (.mp3) requiring SMPEG or MAD library on system
  • FLAC (.flac) requiring the FLAC library on system

You’ll need these files:

Software
Version
File name
Link
Description
SDL2_mixer dynamic link library
2.0.1
SDL2_mixer-2.0.1-win32-x86.zip (32-bit Windows)
SDL2_mixer-2.0.1-win32-x64.zip (64-bit Windows)
https://www.libsdl.org/projects/SDL_mixer/
This is the corresponding dynamic link library file for the unit for Windows. Note: Mac OS X and Linux versions are also available.
dial.wav sound file dial.wav
dial.wav
A simple telephone dial sound. Source: pdsounds. License: Public domain.
In my mind.ogg music file In my mind.ogg
In my mind.ogg
A nice music sample. Source/Creator: First. License: CC BY-ND 3.0.

You should extract the zip-file and get several files. These are four license text files and a readme text file, furthermore you have eight dll files including the important SDL2_mixer.dll. The other dll files are necessary to play the different sound and music formats. Copy all the files to the Windows system32-folder (or the corresponding place). If you forget this and run the examples below you will get an error with exitcode = 309.

Now that you are prepared, let’s have an overview of the code.

When running this program, you’ll get two windows. A simple SDL 2.0 window without any content (white) and the title “Music and Sound window” and a console window showing a simple menu (list) of possible actions to play around with the music and sound. Keep in mind that the focus has to be on the SDL 2.0 window for the key recognition to work.

Chapter 9 application preview

Let’s start with the first part of the code.

The program is called “chap9_SDL2”. It uses the SDL2 and the new SDL2_mixer unit.

We’re going to use event handling as discussed in Chapter 8 to check what keys have been pressed. Consequently we need a variable “sdlWindow1” for the SDL 2.0 application window (for the focus) and an event variable “sdlEvent”.

The pointer variable “music” is of the new type PMix_Music and points at the loaded music file data later. The “sound” pointer variable is of type PMix_Chunk and points at the loaded sound file data later. Note: Each song is referenced by an own PMix_Music pointer and each sound effect (e.g. explosions, shots, …) is referenced by an own PMix_Chunk pointer.

What is the difference between music and sound?

Music is associated with PMix_Music pointers and sounds are associated with PMix_Chunk pointers, but why distinguish them at all? – Well, it is convenient to have them separated since they have rather different properties. Music is usually several minutes long, sounds are usually just a few seconds short. It is usually just one song played at a time, sounds need to mix up if necessary. For music it usually doesn’t plays a role if it is sligthly delayed to when it should start, for sounds a larger delay usually means a strange feeling for the player. So, for music there is exactly one channel reserved where the music is played. For sounds eight sound channels are available to make it possible for them to mix up. Now let’s get back to the code.

The variable “exitloop” is a boolean variable to determine when the main loop of the program should be exited.

The program is initialized by SDL_Init as known. Note though that not only SDL_INIT_VIDEO but additionally SDL_INIT_AUDIO is set. They are combined by the or operator (not the and operator :-)!).  The window is set up afterwards by SDL_CreateWindow as known.

To initialize SDL2_mixer the function

function Mix_OpenAudio(frequency: Integer; format: UInt16; channels: Integer; chunksize: Integer): Integer

has to be called. It requests four parameters. These are the frequency, the audio format, the channels (mono or audio) and the chunksize. All these parameters are of Integer type. Function Mix_OpenAudio returns 0 on success and -1 on errors.

The frequency in Hertz (1/s) usually is 22050 Hz or MIX_DEFAULT_FREQUENCY in games but double as high for CD quality sound (44100 Hz). The higher the frequency, the more CPU power is needed.

Next we have to define the audio format. It determines how the audio data is stored. MIX_DEFAULT_FORMAT equals AUDIO_S16SYS. Different values are given in the following list (from official SDL2_mixer documentation):

  • Format constant name Description
  • AUDIO_U8 Unsigned 8-bit samples
  • AUDIO_S8 Signed 8-bit samples
  • AUDIO_U16LSB Unsigned 16-bit samples, in little-endian byte order
  • AUDIO_S16LSB Signed 16-bit samples, in little-endian byte order
  • AUDIO_U16MSB Unsigned 16-bit samples, in big-endian byte order
  • AUDIO_S16MSB Signed 16-bit samples, in big-endian byte order
  • AUDIO_U16 same as AUDIO_U16LSB (for backwards compatability probably)
  • AUDIO_S16 same as AUDIO_S16LSB (for backwards compatability probably)
  • AUDIO_U16SYS Unsigned 16-bit samples, in system byte order
  • AUDIO_S16SYS Signed 16-bit samples, in system byte order

Then we decide for a sound channel type, which means either stereo or mono. For stereo sound we choose 2 and for mono we choose 1 as value. MIX_DEFAULT_CHANNELS equals stereo output.

Finally the chunksize has to be set, where 4096 bytes per sample is a good and default value. Too low values may lead to skipping samples. Too high values may lead to delayed playing.

Loading music and sounds from files in SDL 2.0

We will load the music by

function Mix_LoadMUS(_file: PAnsiChar): PMix_Music.

_file can be the absolute path. If the Pascal file and the music file are in the same folder the file name is sufficient (as shown in the example). If the loading was unsuccessful, the function returns nil. The volume can be set by

function Mix_VolumeMusic(volume: Integer): Integer.

The volume can be set between 0 (silence) to 128 (maximum volume). The latter equals MIX_MAX_VOLUME. By the way, if you set -1 as argument, the return value corresponds to the set volume.

Quite similar sound files are loaded by

function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk.

Although the function’s name doesn’t indicate this, use this function to load the sound files of any format (Wave, Aiff, Riff, Ogg, Voc), not only for .wav sound files. It return nil on error. There is alittle difference when setting the volume by

function Mix_VolumeChunk(chunk: PMix_Chunk; volume: Integer): Integer.

Instead of just setting a general volume, the volume is bound to a certain sound. In the example case the sound is in variable “sound”. Just to mention it here, there is a third possibility, to set the volume for a certain channel:

function Mix_Volume(channel: Integer; volume: Integer): Integer.

This can be quite handy, anyway, channels are discussed a little bit later below. If your argument is -1 the average volume will be returned.

Here nothing new can be found. The menu is printed out and some memory is allocated to the event pointer. Let’s proceed.

Playing, pausing, resuming music and sounds

The main application loop is entered and should be left if variable “exitloop” is true.

As known from previous Chapter 8 about event handling, we firstly poll for events by SDL_PollEvent() and enter a further loop. Secondly, if there are events found waiting to be processed, we check by a case statement what exact key has been pressed.

For each key a different music or sound related function is used to do something. Let’s discuss them now in detail. We start with the functions used for keys 1-4:

function Mix_PlayMusic(music: PMix_Music; loops: Integer): Integer

procedure Mix_PauseMusic

procedure Mix_ResumeMusic

procedure Mix_RewindMusic

Mix_PlayMusic plays music. The first argument is the music itself which we previously got from the example .ogg music file and associated with the “music” pointer of PMix_Music type. The second argument determines how often the music is played. Additionally -1 means infinite repetition. This function returns 0 on success and -1 on error.

The meaning of the three procedures Mix_PauseMusic, Mix_ResumeMusic and Mix_RewindMusic ist obvious from their names. They are used to pause, resume (if paused before) and rewind the played music.

The analogous function and procedures for sound channels are shown now:

function Mix_PlayChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer): Integer

procedure Mix_Pause(channel: Integer)

procedure Mix_Resume(channel: Integer)

As you can see the function Mix_PlayChannel has three parameters. The first parameter asks for a channel with which the sound should be associated. SDL2_mixer provides eight sound channels. Usually you should use -1 which means the first free channel will be used to play the sound. Anyway, you could specifiy a certain channel here if you like. The second parameter asks for a sound pointer of PMix_Chunk type. The  third parameter is the same as for music, -1 means an infinite loop. Attention though for specific repetitions. The value for loops is increased by 1. So, if you want a sound to be played once, you need the argument to be 0. The return value corresponds to the sound channel the sound is played on, it is -1 on error.

The procedures Mix_Pause and Mix_Resume are self-explanatory. Use them to pause or resume a certain channel, which is the argument. If the argument is -1 (as in the example code) you pause or resume all channels. By the way, you may have noticed that there is not a rewind analogue, because sounds are not expected to be rewound.

Fading and distance effects

Important to know about effects like fading. They are performed on the fly to your data, so the more effects you use, the more computational power they require. It is important to unregister effects you don’t need anymore.

These are the four fade functions triggered by the next keys (A-F):

function Mix_FadeInMusic(music: PMix_Music; loops: Integer; ms: Integer): Integer

function Mix_FadeOutMusic(ms: Integer): Integer

function Mix_FadeInChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer; ms: Integer): Integer

function Mix_FadeOutChannel(which: Integer; ms: Integer): Integer

The function Mix_FadeInMusic works the very same way as Mix_PlayMusic above, but there is a further parameter which allows for a fade in effect in milliseconds. 3000 milliseconds equals 3 seconds. It returns 0 on success and -1 on error.

Mix_FadeOutMusic fades out the playing music within the given time in milliseconds in the moment the function is called (hence the key is pressed in the example program). Attention, it returns 1 on success and 0 on error.

Quite similar the functions Mix_FadeInChannel and Mix_FadeOutChannel work. Instead of the music pointer, the sound pointer has to be given. Additionally the channel has to be given. By the way, also here the number of times the sound is played is increased by 1, so if you want to play a sound with fade in effect once, the argument has to be 0. Both functions return 0 on success and -1 on error.

The functions triggered by the keys G-M are:

function Mix_SetPanning(channel: Integer; left: UInt8; right: UInt8): Integer

For setting the panning you need the channel to which panning should be applied and the volume values which may vary from 0 (quiet) to 255 (loudest). For a consistent panning effect you may substract the left value from the right value (left: volume, right: 255-volume). To unregister this effect, you should set both values to 255, which is recommended to be done if you don’t need panning anymore. The function returns 0 on errors.

function Mix_SetDistance(channel: Integer; distance: UInt8): Integer

The higher the distance the quieter the sound appears. The value can range between 0 (near) and 255 (far). If distance is set to 0 the effect is unregistered. It returns 0 on errors.

function Mix_SetPosition(channel: Integer; angle: SInt16; distance: UInt8): Integer

This function adjusts volumes according to an angle and a distance value, hence it combines the effects of the two functions discussed before for panning and distance. The distance value works the same way as discussed for Mix_SetDistance. Angle of 0 (degree) means in front of you, 90 means directly to the right, 180 means directly behind, 270 means directly to the left.

Finally, if the SDLK_ESCAPE has been pressed, the loop stopping variable “exitloop” is set to true, which will stop the main loop.

Within the main loop a short delay of 5 milliseconds is used to prevent the application from running an empty loop no events are waiting.

The clean up means freeing sdlEvent, and use the procedures Mix_FreeMusic and Mix_FreeChunk to free the music and sound data.

procedure Mix_FreeMusic(music: PMix_Music)

procedure Mix_FreeChunk(chunk: PMix_Chunk)

The arguments have to be the music and sound pointer respectively.

SDL_mixer 2.0 has to be closed by

procedure Mix_CloseAudio.

Finally SDL 2.0 and the application are shut down as known.

← Chapter 8, Part 2 | Chapter 10 →

4 thoughts on “Chapter 9 – Music and Sound

  1. Ok – I found the problem. Forget what I said above about Mix_QuerySpec() – that only works after a successful open.

    I was a victim of this bug:
    https://bugzilla.libsdl.org/show_bug.cgi?id=2089

    The workaround is decribed here:
    https://forums.libsdl.org/viewtopic.php?t=12172&sid=522dc90f6e9e8c3e26c7b34c4aa6b538

    I needed to add this line before any SDL initialization and now it works fine:
    SDL_SetHint(SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING, ‘1’);

    1. Hi Frank,

      I’m glad it works now :-)! And thanks a lot for letting us know in detail how to circumvent this issue. I really appreciate that.

      Matthias

  2. I managed to run the whole tutorial with the latest Lazarus (Win64, with i386 target) and SDL2 (2.0.5) on Windows, and the tutorials are working great! (Nice job!) Until this one…If I call Mix_OpenAudio() I get an exception class ‘External: ?’ in the Lazarus debugger. If I run from the command line I get a heap dump:
    C:\outside\SDLtest>SDLtest.exe
    Heap dump by heaptrc unit
    0 memory blocks allocated : 0/0
    0 memory blocks freed : 0/0
    0 unfreed memory blocks : 0
    True heap size : 32768
    True free heap : 32672
    Should be : 32768

    I tried to call Mix_Init() first, just to see if I had a problem with the SDL2_mixer.DLL but that call works. I wonder if there is a problem with the latest Pascal headers?

Leave a Reply