Cutting Your Teeth on FMOD Part 1: Build environment, initialization and playing sounds

FMOD by Firelight Technologies Pty Ltd. is a cross-platform audio API used in – among other things – many commercial games such as Crysis, Diablo 3, Guild Wars, Guitar Hero, League of Legends, Second Life, StarCraft II, Tomb Raider, World of Warcraft and many others. It is in many ways an indsutry-wide gold standard in audio engines, and as such, knowing how to use it will come in very handy if you are coding games professionally. In the first part of this series, we’ll look at how to get C++ applications using FMOD to compile, how to set up the sound system at the start of your application, and how to play MP3s (although you can use any supported format you wish).

Note: The SimpleFMOD library contains all of the source code and pre-compiled executables for the examples in this series.

Getting Started

Figure 1. Adding the include and library directories for FMOD’s dependencies

First, download the FMOD Ex Programmers API. You’ll want the latest Stable version. After the installation completes, open Visual Studio and create an empty Win32 console project.

Right-click on the project node in Solution Explorer, select Properties, choose VC++ Directories in the left-hand pane and add the following directory paths:

Include Directories: C:\Program Files (x86)\FMOD SoundSystem\FMOD Programmers API Windows\api\inc

Library Directories: C:\Program Files (x86)\FMOD SoundSystem\FMOD Programmers API Windows\api\lib

In the Linker -> Input section, add fmodex_vc.lib to the Additional Dependencies.

Finally, when your application runs, you’ll need fmodex.dll to be in the same folder as your exe file, so to make things simple you can add a post-build event to copy this automatically from the FMOD API directory to your target folder when the build succeeds. Go to Build Events -> Post-build Event and set the Command Line as follows:

copy /y “C:\Program Files (x86)\FMOD SoundSystem\FMOD Programmers API Windows\api\fmodex.dll” “$(OutputPath)”

When you start writing your application, you’ll want to include the following headers:

#include "fmod.hpp"
#include "fmod_errors.h"
#include

Since most FMOD functions return an error code, it is also handy to have some kind of error checking function you can wrap around all the calls, like this:

void FMODErrorCheck(FMOD_RESULT result)
{
    if (result != FMOD_OK)
    {
        std::cout << "FMOD error! (" << result << ") " << FMOD_ErrorString(result) << std::endl;
        exit(-1);
    }
}

Initializing FMOD

The following code is adapted from the ‘Getting Started with FMOD for Windows’ PDF file which is included with the API and can be found in your Windows Start Menu under FMOD Sound System. I have made some small tweaks and added further explanation below.

First we’ll want to get a pointer to FMOD::System, which is the base interface from which all the other FMOD objects are created:

FMOD::System *system;
FMOD_RESULT result;
unsigned int version;
int numDrivers;
FMOD_SPEAKERMODE speakerMode;
FMOD_CAPS caps;
char name[256];

// Create FMOD interface object
result = FMOD::System_Create(&system);
FMODErrorCheck(result);

Then we want to check that the version of the DLL is the same as the libraries we compiled against:

// Check version
result = system->getVersion(&version);
FMODErrorCheck(result);

if (version < FMOD_VERSION)
{
	std::cout << "Error! You are using an old version of FMOD " << version << ". This program requires " << FMOD_VERSION << std::endl; 	return 0; } 

Next, count the number of sound cards in the system, and if there are no sound cards present, disable sound output altogether:

 // Get number of sound cards result = system->getNumDrivers(&numDrivers);
FMODErrorCheck(result);

// No sound cards (disable sound)
if (numDrivers == 0)
{
	result = system->setOutput(FMOD_OUTPUTTYPE_NOSOUND);
	FMODErrorCheck(result);
}

If there is one sound card, get the speaker mode (stereo, 5.1, 7.1 etc.) that the user has selected in Control Panel, and set FMOD’s speaker output mode to match. The first parameter is the driver ID – where 0 is the first enumerated sound card (driver) and numDrivers - 1 is the last. The third parameter receives the default sound frequency; we have set this to zero here as we’re not interested in retrieving this data.

// At least one sound card
else
{
	// Get the capabilities of the default (0) sound card
	result = system->getDriverCaps(0, &caps, 0, &speakerMode);
	FMODErrorCheck(result);

	// Set the speaker mode to match that in Control Panel
	result = system->setSpeakerMode(speakerMode);
	FMODErrorCheck(result);

If hardware acceleration is disabled in Control Panel, we need to make the software buffer larger than the default to help guard against skipping and stuttering. The first parameter specifies the number of samples in the buffer, and the second parameter specifies the number of buffers (which are used in a ring). Therefore the total number of samples to be used for software buffering is the product (multiplication) of the two numbers.

	// Increase buffer size if user has Acceleration slider set to off
	if (caps & FMOD_CAPS_HARDWARE_EMULATED)
	{
		result = system->setDSPBufferSize(1024, 10);
		FMODErrorCheck(result);
	}

The following is a kludge for SigmaTel sound drivers. We first get the name of the first enumerated sound card driver by specifying zero as the first parameter to getDriverInfo (the 4th parameter receives the device GUID which we ignore here). If it contains the string ‘SigmaTel’, the output format is changed to PCM floating point, and all the other format settings are left as the sound card’s current settings.

	// Get name of driver
	result = system->getDriverInfo(0, name, 256, 0);
	FMODErrorCheck(result);

	// SigmaTel sound devices crackle for some reason if the format is PCM 16-bit.
	// PCM floating point output seems to solve it.
	if (strstr(name, "SigmaTel"))
	{
		result = system->setSoftwareFormat(48000, FMOD_SOUND_FORMAT_PCMFLOAT, 0, 0, FMOD_DSP_RESAMPLER_LINEAR);
		FMODErrorCheck(result);
	}
}

We have now done all the necessary pre-requisite legwork and we can now initialize the sound system:

// Initialise FMOD
result = system->init(100, FMOD_INIT_NORMAL, 0);

The first parameter defines the number of virtual channels to use. This can essentially be any number: whenever you start to play a new sound or stream, FMOD will (by default) pick any available free channel. The number of actual hardware channels (voices) available is irrelevant as FMOD will downmix where needed to give the illusion of more channels playing than there actually are in the hardware. So just pick any number that is more than the total amount of sounds that will ever be playing simultaneously in your application. If you choose a number lower than this, channels will get re-used and already running sounds will get cut off and replaced by new ones if you try to start a sound when all channels are busy (the oldest used channel is re-used first).

The second parameter gives initialization parameters and the third number specifies driver-specific information (the example given in the documentation is a filename when using the WAV-writer). The initialization parameter will usually be FMOD_INIT_NORMAL, but for example if you are developing for PlayStation 3, you might use a parameter like FMOD_INIT_PS3_PREFERDTS to prefer DTS output over Dolby Digital.

If the speaker mode we selected earlier is for some strange reason invalid, init() will return FMOD_ERR_OUTPUT_CREATEBUFFER. In this case, we reset the speaker mode to a safe fallback option – namely stereo sound – and call init() again.

// If the selected speaker mode isn't supported by this sound card, switch it back to stereo
if (result == FMOD_ERR_OUTPUT_CREATEBUFFER)
{
	result = system->setSpeakerMode(FMOD_SPEAKERMODE_STEREO);
	FMODErrorCheck(result);

	result = system->init(100, FMOD_INIT_NORMAL, 0);
}
FMODErrorCheck(result);

All of the code above should be included in every application you write which uses FMOD. With this boilerplate code out of the way, we can get to the business of making some noise!

Playing sounds and songs

There are two main ways to get audio into FMOD – createSound and createStream. createSound loads a sound file into memory in its entirety, and decompresses it if necessary, whereas createStream opens a file and just buffers it a piece at a time, decompressing each buffered segment on the fly during playback. Each option has its advantages and disadvantages, but in general music should be streamed since decompressing an MP3 or Vorbis file of some minutes length in memory will consume some 10s of megabytes, whereas sound effects that will be used repeatedly and are relatively short can be loaded into memory for quick access.

To load a sound into memory:

FMOD::Sound *audio;
system->createSound("Audio.mp3", FMOD_DEFAULT, 0, &audio);

To open a stream:

FMOD::Sound *audioStream;
system->createStream("Audio.mp3", FMOD_DEFAULT, 0, &audioStream);

The first parameter is the relative pathname of the file to open and the 4th parameter is a pointer to an FMOD::Sound pointer that receives the resource handle of the audio. Under normal circumstances the 2nd and 3rd parameters should be left as FMOD_DEFAULT and 0 (the 2nd is the mode in which to open the audio, the 3rd is an extended information structure used in special cases – we will come to this in Part 3 of the series).

Playing a one-shot sound

To play a sound that doesn’t loop and which you don’t otherwise need any control over, call:

system->playSound(FMOD_CHANNEL_FREE, audio, false, 0);

This is the same whether you are playing a sound or a stream; you use playSound in both cases. FMOD_CHANNEL_FREE causes FMOD to choose any available unused virtual channel on which to play the sound as mentioned earlier. The 2nd parameter is the audio to play. The third parameter specifies whether the sound should be started paused or not. This is useful when you wish to make changes to the sound before it begins to play.

If you need control of the sound after it starts, use the 4th parameter to receive the handle of the channel that the sound was assigned to:

FMOD::Channel *channel;
system->playSound(FMOD_CHANNEL_FREE, audio, false, &channel);

These calls are non-blocking so they return as soon as they are processed and the sound plays in the background (in a separate thread).

Manipulating the channel

Once a sound is playing and you have the channel handle, all future interactions with that sound take place through the channel. For example, to make a sound loop repeatedly:

channel->setMode(FMOD_LOOP_NORMAL);
channel->setLoopCount(-1);

To toggle the pause state of the sound:

bool isPaused;
channel->getPaused(&isPaused);
channel->setPaused(!isPaused);

To change the sound volume, specify a float value from 0.0 to 1.0, eg for half volume:

channel->setVolume(0.5f);

Per-frame update

Although it’s only needed on certain devices and in certain environments, it is best to call FMOD’s update function on each frame (or cycle of your application’s main loop):

system->update();

This causes OSs such as Android to be able to accept incoming phone calls and other notifications.

Releasing resources

Release the FMOD interface when you are finished with it (generally, when the application is exiting):

system->release();

This will cause all channels to stop playing, and for the channels and main interface to be released. Channels therefore don’t need to be released when the application ends, but sounds should be released when you’re done with them (thanks to David Gouveia for the correction!):

audio->release();

Don’t forget to error check

Everything above should be wrapped in calls to our FMODErrorCheck() function above or some other error-trapping construct. I have just omitted this in the examples for clarity.

Demo application

All of the techniques shown in this article can be seen in this FMOD Demo console application, which shows how to open and play sounds and streams and how to do a smooth volume fade from one track to another. Full source code and the compiled executable are included. The source code can also be seen here for your convenience:

#include "fmod.hpp"
#include "fmod_errors.h"
#include <iostream>
#include <Windows.h>

#define _USE_MATH_DEFINES

#include <math.h>

void FMODErrorCheck(FMOD_RESULT result)
{
    if (result != FMOD_OK)
    {
        std::cout << "FMOD error! (" << result << ") " << FMOD_ErrorString(result) << std::endl;
        exit(-1);
    }
}

int main()
{
	// ================================================================================================
	// Application-independent initialization
	// ================================================================================================

	FMOD::System *system;
	FMOD_RESULT result;
	unsigned int version;
	int numDrivers;
	FMOD_SPEAKERMODE speakerMode;
	FMOD_CAPS caps;
	char name[256];

	// Create FMOD interface object
	result = FMOD::System_Create(&system);
	FMODErrorCheck(result);

	// Check version
	result = system->getVersion(&version);
	FMODErrorCheck(result);

	if (version < FMOD_VERSION)
	{
		std::cout << "Error! You are using an old version of FMOD " << version << ". This program requires " << FMOD_VERSION << std::endl;
		return 0;
	}

	// Get number of sound cards
	result = system->getNumDrivers(&numDrivers);
	FMODErrorCheck(result);

	// No sound cards (disable sound)
	if (numDrivers == 0)
	{
		result = system->setOutput(FMOD_OUTPUTTYPE_NOSOUND);
		FMODErrorCheck(result);
	}

	// At least one sound card
	else
	{
		// Get the capabilities of the default (0) sound card
		result = system->getDriverCaps(0, &caps, 0, &speakerMode);
		FMODErrorCheck(result);

		// Set the speaker mode to match that in Control Panel
		result = system->setSpeakerMode(speakerMode);
		FMODErrorCheck(result);

		// Increase buffer size if user has Acceleration slider set to off
		if (caps & FMOD_CAPS_HARDWARE_EMULATED)
		{
			result = system->setDSPBufferSize(1024, 10);
			FMODErrorCheck(result);
		}

		// Get name of driver
		result = system->getDriverInfo(0, name, 256, 0);
		FMODErrorCheck(result);

		// SigmaTel sound devices crackle for some reason if the format is PCM 16-bit.
		// PCM floating point output seems to solve it.
		if (strstr(name, "SigmaTel"))
		{
			result = system->setSoftwareFormat(48000, FMOD_SOUND_FORMAT_PCMFLOAT, 0, 0, FMOD_DSP_RESAMPLER_LINEAR);
			FMODErrorCheck(result);
		}
	}

	// Initialise FMOD
	result = system->init(100, FMOD_INIT_NORMAL, 0);

	// If the selected speaker mode isn't supported by this sound card, switch it back to stereo
	if (result == FMOD_ERR_OUTPUT_CREATEBUFFER)
	{
		result = system->setSpeakerMode(FMOD_SPEAKERMODE_STEREO);
		FMODErrorCheck(result);

		result = system->init(100, FMOD_INIT_NORMAL, 0);
	}
	FMODErrorCheck(result);

	// ================================================================================================
	// Application-specific code
	// ================================================================================================

	bool quit = false;
	bool fading = false;
	int fadeLength = 3000;
	int fadeStartTick;

	// Open music as a stream
	FMOD::Sound *song1, *song2, *effect;
	result = system->createStream("Song1.mp3", FMOD_DEFAULT, 0, &song1);
	FMODErrorCheck(result);
	result = system->createStream("Song2.mp3", FMOD_DEFAULT, 0, &song2);
	FMODErrorCheck(result);

	// Load sound effects into memory (not streaming)
	result = system->createSound("Effect.mp3", FMOD_DEFAULT, 0, &effect);
	FMODErrorCheck(result);

	// Assign each song to a channel and start them paused
	FMOD::Channel *channel1, *channel2;
	result = system->playSound(FMOD_CHANNEL_FREE, song1, true, &channel1);
	FMODErrorCheck(result);
	result = system->playSound(FMOD_CHANNEL_FREE, song2, true, &channel2);
	FMODErrorCheck(result);

	// Songs should repeat forever
	channel1->setLoopCount(-1);
	channel2->setLoopCount(-1);

	// Print instructions
	std::cout <<
		"FMOD Simple Demo - (c) Katy Coe 2012 - www.djkaty.com" << std::endl <<
		"=====================================================" << std::endl << std::endl <<
		"Press:" << std::endl << std::endl <<
		"  1 - Toggle song 1 pause on/off" << std::endl <<
		"  2 - Toggle song 2 pause on/off" << std::endl <<
		"  F - Fade from song 1 to song 2" << std::endl <<
		"  S - Play one-shot sound effect" << std::endl <<
		"  Q - Quit" << std::endl;

	while (!quit)
	{
		// Per-frame FMOD update
		FMODErrorCheck(system->update());

		// Q - Quit
		if (GetAsyncKeyState('Q'))
			quit = true;

		// 1 - Toggle song 1 pause state
		if (GetAsyncKeyState('1'))
		{
			bool isPaused;
			channel1->getPaused(&isPaused);
			channel1->setPaused(!isPaused);
			while (GetAsyncKeyState('1'));
		}

		// 2 - Toggle song 2 pause state
		if (GetAsyncKeyState('2'))
		{
			bool isPaused;
			channel2->getPaused(&isPaused);
			channel2->setPaused(!isPaused);
			while (GetAsyncKeyState('2'));
		}

		// F - Begin fade from song 1 to song 2
		if (GetAsyncKeyState('F'))
		{
			channel1->setVolume(1.0f);
			channel2->setVolume(0.0f);
			channel1->setPaused(false);
			channel2->setPaused(false);
			fading = true;
			fadeStartTick = GetTickCount();

			while (GetAsyncKeyState('F'));
		}

		// Play one-shot sound effect (without storing channel handle)
		if (GetAsyncKeyState('S'))
		{
			system->playSound(FMOD_CHANNEL_FREE, effect, false, 0);

			while (GetAsyncKeyState('S'));
		}

		// Fade function if fade is in progress
		if (fading)
		{
			// Get volume from 0.0f - 1.0f depending on number of milliseconds elapsed since fade started
			float volume = min(static_cast<float>(GetTickCount() - fadeStartTick) / fadeLength, 1.0f);

			// Fade is over if song 2 has reached full volume
			if (volume == 1.0f)
			{
				fading = false;
				channel1->setPaused(true);
				channel1->setVolume(1.0f);
			}

			// Translate linear volume into a smooth sine-squared fade effect
			volume = static_cast<float>(sin(volume * M_PI / 2));
			volume *= volume;

			// Fade song 1 out and song 2 in
			channel1->setVolume(1.0f - volume);
			channel2->setVolume(volume);
		}
	}

	// Free resources
	FMODErrorCheck(song1->release());
	FMODErrorCheck(song2->release());
	FMODErrorCheck(effect->release());
	FMODErrorCheck(system->release());
}

For A Quick & Dirty Solution

I have made a simple FMOD library which wraps all of the code above and the code in subsequent parts of the series up into an easy-to-use class. Check out the link for more information.

Coming Up…

In Part 2 of our series on FMOD we will take a look at channel groups. I hope you found this tutorial introduction useful!

I’m a software developer with very limited work capacity due to having the debilitating illness M.E. – please read my article Dying with M.E. as a Software Developer and donate to the crowdfund to help me with my bucket list if you found this article useful. Thank you so much!

Advertisement