THE BASICS

Introduction         
The package         
Getting started         
  • The first thing you need to do is make sure FMOD.DLL is accessable from your program. Otherwise you will get an error something like the one below when you try and run your executable.


    Copy the FMOD.DLL file out of the /api directory and into the directory where your executable will be. If they are in the same directory then it will work as expected.
    Now you are ready to start coding, you need to initialize FMOD first! You do this once at the start of your program.

  • Do this with FSOUND_Init.
    • The simplest way to do this is to tell FMOD to mix at 44100hz, and use 32 software channels. This is done like so.

    FSOUND_Init(44100, 32, 0);

    To get more detailed control please see the fmod.h file to see what pre-FSOUND_Init functions can be called to control things like mixer type, output device etc. Also FSOUND_Init itself has flags which you can find out more about in the relevant documentation.
    Note that you don't have to actually use the pre-init functions as FMOD automatically detects the best settings for you.
    If this function succeeds, (see error code if it doesnt), then FMOD is now running and some more interesting things can be done.
Samples, Streams and Songs         
    You have a music file or a sound you want to play. What FMOD API should you use to load and play it?
    Here's a guide.

  • If it is a sequenced music file such as .MOD, .S3M, .XM, .IT or .MID, then use the FMUSIC API. You will want to use FMUSIC_LoadSong to load it into memory. When this gives you a valid return handle, use that handle with FMUSIC_PlaySong to play it! The handle type for this type of file when loaded is FMUSIC_MODULE.
  • If it is a PCM based or compressed file such as .WAV, .MP2, .MP3, .OGG or .RAW then you have a choice to make. Will it use too much memory if you load it in and decompress it into memory? or is it small enough to fit?
    - For small sounds such as sound effects that you want to trigger multiple times at once (for example a gunshot), then you will want to use FSOUND_Sample_Load. When it gives you a valid return handle, use that handle with FSOUND_PlaySound or FSOUND_PlaySoundEx. This is the fastest way to replay sounds, as they are decompressed into memory (at load time) first before being played. The handle type for this type of file when loaded is FSOUND_SAMPLE.
    - If the file is going to be big, and doesnt need to be played multiple times at once (note the next option cannot be played multiple times at once), then the other choice is to use FSOUND_Stream_Open. This opens a file, and prepares it for playing. When it gives you a valid return handle, use that handle with FSOUND_Stream_Play or FSOUND_Stream_PlayEx. This streams the file from the disk in realtime and decompresses the file on the fly. This option uses less memory than samples when the file is past a certain size. Note that this option uses a lot more cpu time than a sample as it has to access the disk, and if nescessary, decompress the data on the fly. FMOD decompression routines are usually fairly efficient but it can be significant on slow machines (especially CE devices), or if multiple streams are played together at once. You can of course measure this with FSOUND_GetCPUUsage or just see how it affects your framerate. The handle type for this type of file when loaded is FSOUND_STREAM.


    • Note : Use FSOUND_FREE when choosing a channel to play a sample or stream on. It makes the best choice for you. If you must use a value such as 0-31 etc, then carefully read the channel mapping/index informatiomn in the remarks section of FSOUND_PlaySound.
Manipulation         
    Finally the last most basic things you might want to do are change the song's volume or speed or any other variety of attributes

  • For FMUSIC_MODULE handles you can use the FMUSIC API for commands like FMUSIC_SetPaused and FMUSIC_SetMasterVolume. See fmod.h (or equivalent) or the documentation for a list of these commands you can use.
  • For FSOUND_SAMPLE handles you can use a variety of commands on a playing sound from the channel handle returned from FSOUND_PlaySound or FSOUND_PlaySoundEx. These include such commands as FSOUND_SetVolume or FSOUND_SetFrequency or a whole host of commands.
  • For FSOUND_STREAM handles you can use a variety of commands on a playing stream, also from the channel handle returned from FSOUND_Stream_Play or FSOUND_Stream_PlayEx. Because these also use channels to play on, they can use the channel functions just as a sample would. You can pause a stream with FSOUND_SetPaused for example.