Creating a Fmod Sound Bank
--------------------------
By: Brandon Rohrer

(turn Word Wrap off)

Introduction
------------

1.  What is an FSB?

I guess the first question here is 'what exactly is an FSB file?'.  Basically, it's a storage file
to hold multiple external sounds in a single file.  This FSB file can be encrypted as well to not
only make it easier to keep all your external sounds in one place, but keep them relatively safe from
resource hacking.

2.  What is fsbankex.exe and how will I use it?

To create an FSB file, you need to use the supplied program called fsbankex.exe.  It should be located
in the same directory as you found this document.  The rest of this text will explain how to build a
FSB file and how to load this FSB file in your program.


Building an FSB
---------------

I will do this in a step by step fashion.  If you see a 'NOTE', this is key information you should be
aware of.  For sake of the documentation, we will assume you plan to make an FSB to hold multiple
sound files in a single/streamable form.  Not only is this the most simple of route, but it's also
the easiest to understand.


1.)  Open fsbankex.exe

Before we go any further, go to the top where it says 'Build mode'.  Enter this menu and select
'Generate Single FSB file' (it's the first option).

Now, go to the 'Other' menu, and make sure 'Create C header' is checked.  If not, check it.  I will
explain the purpose of this setting later.


2.)  Select a source directory

Go to where it says 'Source Data Directory' near the top.  This is the DIRECTORY where all the files
you wish to include in the FSB are located.  You can either manually type it in or click the [...]
button on the right for an 'open directory dialog'.

ex:  c:\music\

Make sure 'Open file list' is NOT checked.

NOTE: Any audio supported file in this directory will be added into the FSB file.  So make sure only
the files you want in the FSB are located in this directory.


3.)  Select a save file

Below the source is the 'Destination File' field.  This must be the path and filename to save.  This
tool does NOT automatically add an extention, so make sure to include it.

ex:  c:\music\mybank.fsb

NOTE:  If you leave out or use a different extention, it will save it out using the indicated extention
instead (the internal file format is still FSB).


4.)  Select a Platform

Near the bottom left is a platform selector menu.  Make sure this says 'PC / Mac / Linux'.


5.)  Setting the Format

Just below the platform menu is the Format one.

PCM - raw (like .wav), this has no compression.
IMA ADPCM - raw, just like PCM with minor compression.
MPEG Layer 3 - MP3, uses compression.

NOTE:
PCM / IMA ADPCM should be used for sounds banks containing mainly small filesize sound effects.
If you use MPEG Layer 3 with small sound effects, you may actually increase the size of the resulting
FSB.  Never use PCM / IMA ADPCM if your source files are compressed formats like mp3, ogg, etc.  As
this will only make each file 10x bigger when stored in the FSB.

MPEG Layer 3 should ONLY be used if the sound bank contains large music files (like mp3 or ogg).
Otherwise, stick with the PCM / IMA ADPCM formats.


6.)  Options

To the bottom right is additional options you can set.  I recommend that you UNCHECK 'Small sample
headers' as this will make sure the source files remain with correct information.

If using the MPEG Layer 3 format, you'll see 'Quality' setting, the lower the quality the less
filesize used.  I generally leave this at 75, but you can adjust accordingly if you want better quality
or smaller filesize.

The Encryption Key is optional.  If you specify a key, the FSB bank will be encrypted and can only
be opened in your program if you pass the key.  Even people with other copies of SXMS/Fmod Ex can't
load the FSB unless they know this key.


7.)  Build

Once you got everything as you want, press the big 'Build' button on the top right.  It should show
the files to be included in the middle and show a pulsing red rectangle under the button.  Depending
on the saving format, the source files or number of files, it could take the tool quite some time
to finish the process.  So be patient.  You may cancel at anytime if you wish to make a change.


8.) After building

Once the build is complete, a dialog box will appear showing detailed information.  After you read
over this, go to the location of your FSB file.  You should see your FSB file along with a file ending
with .h

This .h file is the 'C header' which lets you know which song is assigned to what number value.
You see, when you load an FSB file, each song is assigned a number so that you can reference to it.
Kinda imagine this FSB file being a CD, with each song inside being a 'track' on the CD.  The only way
to play the track you want is by knowing it's track number.

The header is mainly for your own information (as it, you don't need to include it with your program).
To view the info, open it in notepad.  You'll see something along the lines of this.

---------------------------------
#ifndef _TEST_H
#define _TEST_H

#define INTRO_TUNE		0
#define CAR_HORN		1
#define BIRD			2


#endif
---------------------------------

The only info your concerned with are the #define lines with numbers following.
You will notice the 'filename' of each sound in all caps.  The number needed to get to this sound
is on the right.  Just remember this information as we go into the next section about getting your
FSB into your project.

NOTE:  Remember, the header file (.h) is not needed with your application.  It's only purpose is to
let YOU know what the index of each sound is so you can pull the sounds in your program.


Loading a FSB
-------------
In this documentation, I am going to assume you know how to setup SXMS correctly and have used it before
for creating/playing sounds.  So all I'm going to explain is how to load up an FSB, get the sounds
included in it and then play them.


1.)  Load/Create the FSB sound using sxfmod_system_createSound()

Just like any other audio, you need to use the createSound function to make it a sound in Fmod.

Now, if your sound bank includes streams (like mp3/ogg) then you should also pass the
sxms.FMOD_CREATESTREAM flag so that files are streamed.


2.)  Pull a sub sound from the FSB sound.

Now that we have our FSB sound bank in, we need to pull the sub sounds we want from this bank of sounds.
To do this, we need to use the function sxfmod_sound_getSubSound().

For the first argument, use the sound index of your FSB sound bank.  The second index is the sub sound
you want.  Remember that 'C Header' earlier?  Well, this is where that number comes into play.  The
number beside the sound in that header is the number you want for the second argument.

For the last argument, this is a sound index to place the sub sound into.  This sound index is what
you will use to play/edit the sound from this point on.


Conclusion
----------
And that's pretty much it.  Not to complex I hope ;).

As a final note, if you wish to load an encrypted FSB file, you need to set a variable BEFORE creating
the FSB sound.  To do this, use the following code just before creating a sound from the FSB file.

sxms.FMOD_CREATESOUNDEXINFO[15] = "MyPassword";

Then in the sxfmod_system_createSound() function, set argument2 to 1 instead of 0.

This will have the create function check this variable for the password before loading the FSB.
If the password is incorrect for the FSB, the sound will fail to create.