(For more resources related to this topic, see here.)

Understanding FMOD

One of the main reasons why I chose FMOD for this book is that it contains two separate APIs—the FMOD Ex Programmer's API, for low-level audio playback, and FMOD Designer, for high-level data-driven audio. This will allow us to cover game audio programming at different levels of abstraction without having to use entirely different technologies.

Besides that reason, FMOD is also an excellent piece of software, with several advantages to game developers:

License: It is free for non-commercial use, and has reasonable licenses for commercial projects.
Cross-platform: It works across an impressive number of platforms. You can run it on Windows, Mac, Linux, Android, iOS, and on most of the modern video game consoles by Sony, Microsoft, and Nintendo.
Supported formats: It has native support for a huge range of audio file formats, which saves you the trouble of having to include other external libraries and decoders.
Programming languages: Not only can you use FMOD with C and C++, there are also bindings available for other programming languages, such as C# and Python.
Popularity: It is extremely popular, being widely considered as the industry standard nowadays. It was used in games such as BioShock, Crysis, Diablo 3, Guitar Hero, Start Craft II, and World of Warcraft. It is also used to power several popular game engines, such as Unity3D and CryEngine.
Features: It is packed with features, covering everything from simple audio playback, streaming and 3D sound, to interactive music, DSP effects and low-level audio programming.

Installing FMOD Ex Programmer's API

Installing a C++ library can be a bit daunting at first. The good side is that once you have done it for the first time, the process is usually the same for every other library. Here are the steps that you should follow if you are using Microsoft Visual Studio:

Download the FMOD Ex Programmer's API from http://www.fmod.org and install it to a folder that you can remember, such as C:FMOD.
Create a new empty project, and add at least one .cpp file to it. Then, right-click on the project node on the Solution Explorer , and select Properties from the list. For all the steps that follow, make sure that the Configuration option is set to All Configurations .
Navigate to C/C++ | General , and add C:FMODapiinc to the list of Additional Include Directories (entries are separated by semicolons).
Navigate to Linker | General , and add C:FMODapilib to the list of Additional Library Directories .
Navigate to Linker | Input , and add fmodex_vc.lib to the list of Additional Dependencies .
Navigate to Build Events | Post-Build Event , and add xcopy /y "C:FMODapifmodex.dll" "$(OutDir)" to the Command Lin e list.
Include the <fmod.hpp> header file from your code.

Creating and managing the audio system

Everything that happens inside FMOD is managed by a class named FMOD::System, which we must start by instantiating with the FMOD::Syste m_Create() function:

FMOD::System* system;
FMOD::System_Create(&system);

Notice that the function returns the system object through a parameter. You will see this pattern every time one of the FMOD functions needs to return a value, because they all reserve the regular return value for an error code. We will discuss error checking in a bit, but for now let us get the audio engine up and running.

Now that we have a system object instantiated, we also need to initialize it by calling the init() method:

system->init(100, FMOD_INIT_NORMAL, 0);

The first parameter specifies the maximum number of channels to allocate. This controls how many sounds you are able to play simultaneously. You can choose any number for this parameter because the system performs some clever priority management behind the scenes and distributes the channels using the available resources. The second and third parameters customize the initialization process, and you can usually leave them as shown in the example.

Many features that we will use work properly only if we update the system object every frame. This is done by calling the update() method from inside your game loop:

system->update();

You should also remember to shutdown the system object before your game ends, so that it can dispose of all resources. This is done by calling the release() method:

system->release();

Loading and streaming audio files

One of the greatest things about FMOD is that you can load virtually any audio file format with a single method call. To load an audio file into memory, use the createSound() method:

FMOD::Sound* sound;
system->createSound("sfx.wav", FMOD_DEFAULT, 0, &sound);

To stream an audio file from disk without having to store it in memory, use the createStream() method:

FMOD::Sound* stream;
system->createStream("song.ogg", FMOD_DEFAULT, 0, &stream);

Both methods take the path of the audio file as the first parameter, and return a pointer to an FMOD::Sound object through the fourth parameter, which you can use to play the sound. The paths in the previous examples are relative to the application path. If you are running these examples in Visual Studio, make sure that you copy the audio files into the output folder (for example, using a post-build event such as xcopy /y "$(ProjectDir)*.ogg" "$(OutDir)").

The choice between loading and streaming is mostly a tradeoff between memory and processing power. When you load an audio file, all of its data is uncompressed and stored in memory, which can take up a lot of space, but the computer can play it without much effort. Streaming, on the other hand, barely uses any memory, but the computer has to access the disk constantly, and decode the audio data on the fly. Another difference (in FMOD at least) is that when you stream a sound, you can only have one instance of it playing at any time. This limitation exists because there is only one decode buffer per stream. Therefore, for sound effects that have to be played multiple times simultaneously, you have to either load them into memory, or open multiple concurrent streams. As a rule of thumb, streaming is great for music tracks, voice cues, and ambient tracks, while most sound effects should be loaded into memory.

The second and third parameters allow us to customize the behavior of the sound. There are many different options available, but the following list summarizes the ones we will be using the most. Using FMOD_DEFAULT is equivalent to combining the first option of each of these categories:

FMOD_LOOP_OFF and FMOD_LOOP_NORMAL: These modes control whether the sound should only play once, or loop once it reaches the end
FMOD_HARDWARE and FMOD_SOFTWARE: These modes control whether the sound should be mixed in hardware (better performance) or software (more features)
FMOD_2D and FMOD_3D: These modes control whether to use 3D sound

We can combine multiple modes using the bitwise OR operator (for instance, FMOD_DEFAULT | FMOD_LOOP_NORMAL | FMOD_SOFTWARE). We can also tell the system to stream a sound even when we are using the createSound() method, by setting the FMOD_CREATESTREAM flag. In fact, the createStream() method is simply a shortcut for this.

When we do not need a sound anymore (or at the end of the game) we should dispose of it by calling the release() method of the sound object. We should always release the sounds we create, regardless of the audio system also being released.

sound->release();

Playing sounds

With the sounds loaded into memory or prepared for streaming, all that is left is telling the system to play them using the playSound() method:

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

The first parameter selects in which channel the sound will play. You should usually let FMOD handle it automatically, by passing FMOD_CHANNEL_FREE as the parameter.

The second parameter is a pointer to the FMOD::Sound object that you want to play.

The third parameter controls whether the sound should start in a paused state, giving you a chance to modify some of its properties without the changes being audible. If you set this to true, you will also need to use the next parameter so that you can unpause it later.

The fourth parameter is an output parameter that returns a pointer to the FMOD::Channel object in which the sound will play. You can use this handle to control the sound in multiple ways, which will be the main topic of the next chapter.

You can ignore this last parameter if you do not need any control over the sound, and simply pass in 0 in its place. This can be useful for non-lopping one-shot sounds.

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

Checking for errors

So far, we have assumed that every operation will always work without errors. However, in a real scenario, there is room for a lot to go wrong. For example, we could try to load an audio file that does not exist.

In order to report errors, every function and method in FMOD has a return value of type FMOD_RESULT, which will only be equal to FMOD_OK if everything went right. It is up to the user to check this value and react accordingly:

FMOD_RESULT result = system->init(100, FMOD_INIT_NORMAL, 0); if (result != FMOD_OK) { // There was an error, do something about it }

For starters, it would be useful to know what the error was. However, since FMOD_RESULT is an enumeration, you will only see a number if you try to print it. Fortunately, there is a function called FMOD_ErrorString() inside the fmod_errors.h header file which will give you a complete description of the error.

You might also want to create a helper function to simplify the error checking process. For instance, the following function will check for errors, print a description of the error to the standard output, and exit the application:

#include <iostream>
#include <fmod_errors.h>

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

You could then use that function to check for any critical errors that should cause the application to abort:

ExitOnError(system->init(100, FMOD_INIT_NORMAL, 0));

The initialization process described earlier also assumes that everything will go as planned, but a real game should be prepared to deal with any errors. Fortunately, there is a template provided in the FMOD documentation which shows you how to write a robust initialization sequence. It is a bit long to cover here, so I urge you to refer to the file named Getting started with FMOD for Windows.pdf inside the documentation folder for more information.

For clarity, all of the code examples will continue to be presented without error checking, but you should always check for errors in a real project.

Project 1 building a simple audio manager

In this project, we will be creating a SimpleAudioManager class that combines everything that was covered in this chapter. Creating a wrapper for an underlying system that only exposes the operations that we need is known as the façade design pattern , and is very useful in order to keep things nice and simple.

Since we have not seen how to manipulate sound yet, do not expect this class to be powerful enough to be used in a complex game. Its main purpose will be to let you load and play one-shot sound effects with very little code (which could in fact be enough for very simple games).

It will also free you from the responsibility of dealing with sound objects directly (and having to release them) by allowing you to refer to any loaded sound by its filename. The following is an example of how to use the class:

SimpleAudioManager audio;
audio.Load("explosion.wav");
audio.Play("explosion.wav");

From an educational point of view, what is perhaps even more important is that you use this exercise as a way to get some ideas on how to adapt the technology to your needs. It will also form the basis of the next chapters in the book, where we will build systems that are more complex.

Class definition

Let us start by examining the class definition:

#include <string>
#include <map>
#include <fmod.hpp>

typedef std::map<std::string, FMOD::Sound*> SoundMap;

class SimpleAudioManager {
 public:
  SimpleAudioManager();
  ~SimpleAudioManager();
  void Update(float elapsed);
  void Load(const std::string& path);
  void Stream(const std::string& path);
  void Play(const std::string& path);
 private:
  void LoadOrStream(const std::string& path, bool stream);
  FMOD::System* system;
  SoundMap sounds;
};

From browsing through the list of public class members, it should be easy to deduce what it is capable of doing:

The class can load audio files (given a path) using the Load() method
The class can stream audio files (given a path) using the Stream() method
The class can play audio files (given a path) using the Play() method (granted that they have been previously loaded or streamed)
There is also an Update() method and a constructor/destructor pair to manage the sound system

The private class members, on the other hand, can tell us a lot about the inner workings of the class:

At the core of the class is an instance of FMOD::System responsible for driving the entire sound engine. The class initializes the sound system on the constructor, and releases it on the destructor.
Sounds are stored inside an associative container, which allows us to search for a sound given its file path. For this purpose, we will be relying on one of the C++ Standard Template Library (STL ) associative containers, the std::map class, as well as the std::string class for storing the keys. Looking up a string key is a bit inefficient (compared to an integer, for example), but it should be fast enough for our needs. An advantage of having all the sounds stored on a single container is that we can easily iterate over them and release them from the class destructor.
Since the code for loading and streaming audio file is almost the same, the common functionality has been extracted into a private method called LoadOrStream(), to which Load() and Stream() delegate all of the work. This prevents us from repeating the code needlessly.

Initialization and destruction

Now, let us walk through the implementation of each of these methods. First we have the class constructor, which is extremely simple, as the only thing that it needs to do is initialize the system object.

SimpleAudioManager::SimpleAudioManager() {
  FMOD::System_Create(&system);
  system->init(100, FMOD_INIT_NORMAL, 0);
}

Updating is even simpler, consisting of a single method call:

void SimpleAudioManager::Update(float elapsed) {
  system->update();
}

The destructor, on the other hand, needs to take care of releasing the system object, as well as all the sound objects that were created. This process is not that complicated though. First, we iterate over the map of sounds, releasing each one in turn, and clearing the map at the end. The syntax might seem a bit strange if you have never used an STL iterator before, but all that it means is to start at the beginning of the container, and keep advancing until we reach its end. Then we finish off by releasing the system object as usual.

SimpleAudioManager::~SimpleAudioManager() {
  // Release every sound object and clear the map
  SoundMap::iterator iter;
  for (iter = sounds.begin(); iter != sounds.end(); ++iter)
    iter->second->release();
  sounds.clear();

  // Release the system object
  system->release();
  system = 0;
}

Loading or streaming sounds

Next in line are the Load() and Stream() methods, but let us examine the private LoadOrStream() method first. This method takes the path of the audio file as a parameter, and checks if it has already been loaded (by querying the sound map). If the sound has already been loaded there is no need to do it again, so the method returns. Otherwise, the file is loaded (or streamed, depending on the value of the second parameter) and stored in the sound map under the appropriate key.

void SimpleAudioManager::LoadOrStream(const std::string& path, bool stream) {
  // Ignore call if sound is already loaded
  if (sounds.find(path) != sounds.end()) return;

  // Load (or stream) file into a sound object
  FMOD::Sound* sound;
  if (stream)
    system->createStream(path.c_str(), FMOD_DEFAULT, 0, &sound);
  else
    system->createSound(path.c_str(), FMOD_DEFAULT, 0, &sound);

  // Store the sound object in the map using the path as key
  sounds.insert(std::make_pair(path, sound));
}

With the previous method in place, both the Load() and the Stream() methods can be trivially implemented as follows:

void SimpleAudioManager::Load(const std::string& path) {
  LoadOrStream(path, false);
}
void SimpleAudioManager::Stream(const std::string& path) {
  LoadOrStream(path, true);
}

Playing sounds

Finally, there is the Play() method, which works the other way around. It starts by checking if the sound has already been loaded, and does nothing if the sound is not found on the map. Otherwise, the sound is played using the default parameters.

void SimpleAudioManager::Play(const std::string& path) {
  // Search for a matching sound in the map
  SoundMap::iterator sound = sounds.find(path);

  // Ignore call if no sound was found
  if (sound == sounds.end()) return;

  // Otherwise play the sound
  system->playSound(FMOD_CHANNEL_FREE, sound->second, false, 0);
}

We could have tried to automatically load the sound in the case when it was not found. In general, this is not a good idea, because loading a sound is a costly operation, and we do not want that happening during a critical gameplay section where it could slow the game down. Instead, we should stick to having separate load and play operations.

A note about the code samples

Although this is a book about audio, all the samples need an environment to run on. In order to keep the audio portion of the samples as clear as possible, we will also be using the Simple and Fast Multimedia Library 2.0 (SFML ) (http://www.sfml-dev.org). This library can very easily take care of all the miscellaneous tasks, such as window creation, timing, graphics, and user input, which you will find in any game.

For example, here is a complete sample using SFML and the SimpleAudioManager class. It creates a new window, loads a sound, runs a game loop at 60 frames per second, and plays the sound whenever the user presses the space key.

#include <SFML/Window.hpp>
#include "SimpleAudioManager.h"

int main() {
  sf::Window window(sf::VideoMode(320, 240), "AudioPlayback");
  sf::Clock clock;
  
  // Place your initialization logic here
  SimpleAudioManager audio;

  audio.Load("explosion.wav");

  
  // Start the game loop
  while (window.isOpen()) {
    // Only run approx 60 times per second
    float elapsed = clock.getElapsedTime().asSeconds();
    if (elapsed < 1.0f / 60.0f) continue;
    clock.restart();
    sf::Event event;
    while (window.pollEvent(event)) {
      // Handle window events
      if (event.type == sf::Event::Closed) 
        window.close();

      // Handle user input
      if (event.type == sf::Event::KeyPressed &&
          event.key.code == sf::Keyboard::Space)
        audio.Play("explosion.wav");

    }
    // Place your update and draw logic here
    audio.Update(elapsed);

  }
  // Place your shutdown logic here
  return 0;
}

Summary

In this article, we have seen some of the advantages of using the FMOD audio engine. We saw how to install the FMOD Ex Programmer's API in Visual Studio, how to initialize, manage, and release the FMOD sound system, how to load or stream an audio file of any type from disk, how to play a sound that has been previously loaded by FMOD, how to check for errors in every FMOD function, and how to create a simple audio manager that encapsulates the act of loading and playing audio files behind a simple interface.