## A beginner's guide to FMOD

### Written by Lachie Dazdarian (November, 2007)

### Introduction

This tutorial should introduce you with basics of using FMOD in FreeBASIC programs. It's pretty much the summary of FMOD subs and methods I use in my projects and does not represent the entire scope of FMOD in FreeBASIC. If your needs extend beyond this tutorial, you are encouraged to explore additional FMOD calls and its documentation.

Originally I planed to write a cross FMOD/FBSound tutorial, but as FBSound felt rather user-unfriendly to me I gave up on that. If someone likes and prefers FBSound, be so kind to write a tutorial about it in the style of this one if you wish to popularize the library in question.

### What is FMOD?

FMOD is a 32-bit sound library for Windows, Linux and Macintosh. It is free of charge for freeware products, but if you plan to use it in commercial products you'll have to buy a specific license. Visit www.fmod.org for more info on this.

### What do you need?

Well, you need FreeBASIC first. I assume you have one. As the code in this tutorial was written in FreeBASIC ver.0.18 or later, get that.

You also need FMOD.DLL placed in Windows/System32 directory or where you place the program source code. Get it here: http://www.fmod.org/index.php/download#FMOD3ProgrammersAPI

To test the example program in this tutorial download the following sound files: fmodtutfiles.zip

### Initiating FMOD

To use FMOD in your programs you need to include "fmod.bi" with:

>     #include "fmod.bi"

After this we'll declare several variables that will become necessary later.

>     CONST number_of_sound_effect = 10
>     CONST FALSE = 0
>     CONST TRUE = 1

>     DIM SHARED PlaySound AS INTEGER
>     DIM SHARED sample(number_of_sound_effect) AS INTEGER PTR
>     DIM SHARED music_handle AS INTEGER PTR
>     DIM SHARED SFXVolume AS INTEGER, MusicVolume AS INTEGER

PlaySound will be used to flag if FMOD functions should be used or not (if FMOD initiation failed), sample array will hold the sound effects and declare it like I did. number_of_sound_effect represent the number of sound effects you'll use in your program. Change this number to suit your own needs. music_handle will flag the current music track in memory which we'll stream. I advise streaming music files instead loading all of them into memory.

SFXVolume will flag the current sound effects volume, while MusicVolume the music volume.

The following code initiates FMOD:

>     PlaySound = TRUE

>     FSOUND_Init(44100, number_of_sound_effect+1, 0)
>     IF FSOUND_Init(44100, number_of_sound_effect+1, 0) = 0 THEN PlaySound = FALSE

PlaySound is set as TRUE by default, and then it's set to FALSE if FMOD fails to initiate. The first parameter in FMOD_Init is mixrate in Hz, usually set to 44100 as most sound files have that mixrate. The second parameter is the number of SOFTWARE channels available. I added one more channel on the number of sound effects I’ll use because I need one more for my music track. You can put any number here, just make sure it's more than the number of sound effects and music tracks you'll allocate at the same time in your program.

### Loading samples

To load a sound effect use FSOUND_Sample_Load function on the following way:

>     IF PlaySound = TRUE THEN
>     	sample(1) = FSOUND_SAMPLE_Load(FSOUND_FREE,"sound1.wav",0,0,0)
>     	sample(2) = FSOUND_SAMPLE_Load(FSOUND_FREE,"sound2.wav",0,0,0)
>     END IF

The first parameter flags the sample slot (index). FSOUND_FREE chooses an arbitrary one. The second parameter is the name of the sound file. You can load MP3, WAV, OGG, RAW, and other file formats with this function. With the third parameter you can set the mode for that sound effect (check FMOD documentation for the description of available modes), fourth one flags the offset inside the file, and the last one flags the length of a memory block for that sound effect. Unless having special requirements, use zeros for those parameters as I did.

Let's set the default music and sound effects volumes:

>     SFXVolume = 3
>     MusicVolume = 3

I use 4 steps volume but you can use more. In my method 4 represents maximum volume, 3 is 75 % of maximum volume, 2 is 50 %, 1 is 25 %, and 0 is mute.

To start streaming a music (or environmental) track I constructed the following subroutine:

>     SUB playStreamMusic (musc As String)

>         DIM SetVol AS INTEGER

>         IF PlaySound = TRUE THEN
>             music_handle = FSOUND_Stream_Open(musc, FSOUND_LOOP_NORMAL, 0, 0 )
>             FSOUND_Stream_Play(1, music_handle)
>             IF MusicVolume = 0 THEN SetVol = 0
>             IF MusicVolume = 1 THEN SetVol = 63
>             IF MusicVolume = 2 THEN SetVol = 126
>             IF MusicVolume = 3 THEN SetVol = 190
>             IF MusicVolume = 4 THEN SetVol = 255
>             FSOUND_SetVolumeAbsolute(1, SetVol)
>         END IF

>     END SUB

Be sure to declare this subroutine.

To use the subroutine in our specific example input the following line after sample loading:

>     playStreamMusic ("river.ogg")

FSOUND_Stream_Open opens a sound file for streaming. The first parameter flags the sound file (string), the second parameter flags the mode of streaming (how the file should be played; refer to FMOD documentation for more info on this), and the last two parameters are 0 by default and flag the offset and length of a memory block for the streamed sound file. FSOUND_Stream_Play starts streaming the file flagged with music_handle. I used channel index 1 because we'll use the same to control the volume of the streamed music track (a way to divide the volume of sound effects and music). Note how I used MusicVolume to set the volume of the streamed track (255 max, 0 mute). FSOUND_SetVolumeAbsolute sets a channel volume linearly. This function is NOT affected by master volume. It is used when you want to quiet everything down using FSOUND_SetSFXMasterVolume, but make a channel prominent.

To stop streaming a sound file (which is usually a music track) I use the following subroutine:

>     SUB stopStreamMusic()
>         IF PlaySound = TRUE THEN
>             FSOUND_Stream_Stop music_handle
>             FSOUND_Stream_Close music_handle
>         END IF
>     END SUB

I recommend you to stop streaming a file before you change it to another one. If you are more imaginative, you can come up with volume fade in / fade out effects when tracks are changed, but I don't want to complicate this tutorial with that.

For playing sound effects I use the following subroutine in conjunction with a volume setting subroutine:

>     SUB playsample (plsnd as integer ptr)

>         IF PlaySound = TRUE THEN
>             FSOUND_PlaySound (FSOUND_FREE, plsnd)
>             setSoundVolume
>         END IF

>     END SUB

>     SUB setSoundVolume

>         DIM SetVol AS INTEGER

>         IF PlaySound = TRUE THEN
>             IF SFXVolume = 0 THEN SetVol = 0
>             IF SFXVolume = 1 THEN SetVol = 63
>             IF SFXVolume = 2 THEN SetVol = 126
>             IF SFXVolume = 3 THEN SetVol = 190
>             IF SFXVolume = 4 THEN SetVol = 255
>             FSOUND_SetSFXMasterVolume(SetVol)

>             IF MusicVolume = 0 THEN SetVol = 0
>             IF MusicVolume = 1 THEN SetVol = 63
>             IF MusicVolume = 2 THEN SetVol = 126
>             IF MusicVolume = 3 THEN SetVol = 190
>             IF MusicVolume = 4 THEN SetVol = 255
>             FSOUND_SetVolumeAbsolute(1, SetVol)
>         END IF

>     END SUB

Note how the sound effects volume is set every time a sound effect if played, and how in the same time the music volume (channel 1 volume) needs to be RESET.

To play sound effect 1 use:

>     playsample (sample(1))

You don't have to use a sample array like it did. If you for example create an integer pointer named splash and properly load a sound effect with it, then you'll use:

>     playsample (splash)

To test all this code create a loop like this one:

>     SCREENRES 640, 480, 32, 1, GFX_WINDOWED

>     DO

>     IF PlaySound = TRUE THEN FSOUND_Update

>     LOCATE 1,1
>     PRINT "PUSH ESC TO END PROGRAM"
>     PRINT "PUSH 1 AND 2 TO TEST SOUND EFFECTS"
>     PRINT "PUSH F1 AND F2 TO CHANGE THE WATER SOUND VOLUME"

>     IF MULTIKEY(SC_1) THEN
>         playsample (sample(1))
>         SLEEP 1000
>     END IF
>     IF MULTIKEY(SC_2) THEN
>         playsample (sample(2))
>         SLEEP 1000
>     END IF
>     IF MULTIKEY(SC_F1) THEN
>         MusicVolume = MusicVolume - 1
>         IF MusicVolume < 0 THEN MusicVolume = 0
>         setSoundVolume
>         SLEEP 1000
>     END IF
>     IF MULTIKEY(SC_F2) THEN
>         MusicVolume = MusicVolume + 1
>         IF MusicVolume > 4 THEN MusicVolume = 4
>         setSoundVolume
>         SLEEP 1000
>     END IF

>     SLEEP 10

>     LOOP UNTIL MULTIKEY(SC_ESCAPE)
>     FSOUND_Close

Use 1 and 2 to test the two sound effects, F1 and F2 to change the music volume. I've been told that using FSound_Update is not necessary, but heck, it doesn't hurt. Note how FSound_Close is used before the program ends. Always be sure to close FMOD when you end your program.

The entire code so far: codever1.txt

Few more statements I want to show you.

To pause currently streamed music track use:

>     FSOUND_SetPaused (1, 1)

Note that the first parameter is the channel, so this will work only if you are streaming the music track in that channel.

To start streaming it again use:

>     FSOUND_SetPaused (1, 0)

And this should cover the basics.

Download the final code with all the necessary files: fmod_example_program.zip

Anyway, this is just the surface of FMOD. I warmly recommend you to explore "fmod.bi" and FMOD documentation and expand on these basics.

Happy coding!

A tutorial written by Lachie D. (lachie13@yahoo.com ; The Maker Of Stuff)