# THE BASICS

Introduction

This is the first place to look if you have no idea what to do when downloading FMOD, or those with some idea but need a little bit of help. It will give you a step by step introduction and tutorial on what to call, what to link and where to call stuff so you can easily get on your way to great sounding audio!

The package

The first thing you will do is unzip fmod and find the following directory structure.
/api
The files you are interested in for your own projects are held here
This holds
- FMOD.DLL,
- The import library (fmodvc.lib, fmodbc.lib etc) you need to link (for C users), and
- The header (fmod.h, fmod.pas, fmod.bas depending on language) you need to include.
C Users
- MSVC - #include "fmod.h" into your source code and link fmodvc.lib by putting it into your link section/makefile/project.
- Codewarrior - #include "fmod.h" into your source code and link fmodvc.lib by putting it into your link section/makefile/project.
- Watcom - #include "fmod.h" into your source code and link fmodwc.lib by putting it into your link section/makefile/project.
- Borland - #include "fmod.h" into your source code and link fmodbc.lib by putting it into your link section/makefile/project.
- LCC-WIN32 - #include "fmod.h" into your source code and link fmodlcc.lib by putting it into your link section/makefile/project.
- Mingw and CygWin - #include "fmod.h" into your source code and link libfmod.a by putting it into your link section/makefile/project.
- Linux / GCC - #include "fmod.h" into your source code and link with libfmod-X-Y.so (i.e gcc file.c -lfmod-3.5)
  Note there is no DJGPP support. If you ask for this you are looking in the wrong place. DJGPP is DOS only and to find a similar free WIN32 compiler try LCC-WIN32 or CygWin.
  Delphi Users
- You need to have uses FMOD in your source code somewhere. If delphi cannot find the FMOD header you need to have the path to fmod.pas in your library path. Go to Tools\Environment Options\Library. Add the path, eg. C:\fmodapi340\api\delphi (of course, use the path that you have on your system), to Library Path and it should be happy.
  Visual Basic Users
- Add fmod.bas to your project.
  /documentation
  You must know about this already if you are reading this!
  /media
  This directory holds some wav files and songs that the examples use. For example jbtennis.wav which contains loop points and wav sync markers that fmod can read
  /samples
  This folder is for C programmers and contains a variety of samples to demonstrate 3D sound, dsp effects, recording, streams and more
  To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.
  /samplesdelphi
  This folder is for Delphi programmers and contains a variety of samples to demonstrate using FMOD with Delphi. Written by Steve Williams
  To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.
  /samplesvb
  This folder is for Visual Basic programmers and contains examples of using FMOD with Visual Basic.
  To run the precompiled executables, first copy the FMOD.DLL file from /api into the relevant sample directory to make it accessable for the program.
  /tools
  This folder contains asioconfig.exe.
  This program simply configures any asio devices you have on your system by bringing up the driver's native configuration screen.
  If you run it and no entries are in the list, your asio drivers are not installed properly.
  If you select or doubleclick an entry that does exist and no config screen appears then your asio drivers are not installed correctly or you have selected the wrong driver to configure. Take note of this when selecting the device from the FMOD api.

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.