# 8. FSBank API Reference

- FSBank_Init Initialize the FSBank system.
- FSBank_Build Begin the building process for the provided subsound descriptions.
- FSBank_BuildCancel Halt the build in progress.
- FSBank_Release Release the FSBank system, clean up used resources.
- FSBank_ReleaseProgressItem Release memory associated with a progress item.
- FSBank_MemoryGetStats Query the current and maximum memory usage of the FSBank system.
- FSBank_MemoryInit Specifies a method for FSBank to allocate memory through callbacks.
- FSBank_FetchFSBMemory Fetch the built FSB data from memory.
- FSBank_FetchNextProgressItem Fetch build progress items that describe the current state of the build.
- FSBANK_MEMORY_ALLOC_CALLBACK Callback to allocate a block of memory.
- FSBANK_MEMORY_FREE_CALLBACK Callback to free a block of memory.
- FSBANK_MEMORY_REALLOC_CALLBACK Callback to re-allocate a block of memory to a different size.
- FSBANK_INITFLAGS Bit fields to control the general operation of the library.
- FSBANK_BUILDFLAGS Bit fields to control how subsounds are encoded.
- FSBANK_FORMAT Compression formats available for encoding
- FSBANK_FSBVERSION Version of FSB to write out.
- FSBANK_PROGRESSITEM Status information describing the progress of a build.
- FSBANK_RESULT Error codes returned from every function.
- FSBANK_STATE Current state during the build process.
- FSBANK_STATEDATA_FAILED Extra failed state data.
- FSBANK_STATEDATA_WARNING Extra warning state data.
- FSBANK_SUBSOUND Representation of how to encode a single subsound in the final FSB.

## 8.1 FSBank_Init

Initialize the FSBank system.

C

    FSBANK_RESULT FSBank_Init(
      FSBANK_FSBVERSION version,
      FSBANK_INITFLAGS flags,
      unsigned int numSimultaneousJobs,
      const char *cacheDirectory
    );

version
  FSB version, currently only FSBANK_FSBVERSION_FSB5 is supported. (FSBANK_FSBVERSION)
flags
  Initialization flags which control how the system behaves. (FSBANK_INITFLAGS)
numSimultaneousJobs
  The maximum number of threads to create for parallel encoding. Set this to your number of CPU 'cores' for best performance.
cacheDirectory Opt
  Location to store the temporary cache files, default is a directory off the current working directory.

See Also: FSBank_Release

## 8.2 FSBank_Build

Begin the building process for the provided subsound descriptions.

C

    FSBANK_RESULT FSBank_Build(
      const FSBANK_SUBSOUND *subSounds,
      unsigned int numSubSounds,
      FSBANK_FORMAT encodeFormat,
      FSBANK_BUILDFLAGS buildFlags,
      unsigned int quality,
      const char *encryptKey,
      const char *outputFileName
    );

subSounds
  Array of subsound descriptions each defining one subsound for the FSB. (FSBANK_SUBSOUND)
numSubSounds
  Number of elements in `subSounds`.
encodeFormat
  FSB encoding format. (FSBANK_FORMAT)
buildFlags
  Building flags which control how the sample data is encoded. (FSBANK_BUILDFLAGS)
quality
  Controls the post compression quality level. From 1 (high compression / low quality) to 100 (high quality / low compression), use 0 for default quality. See remarks for format specific usage.
encryptKey Opt
  Key used to encrypt the FSB. Same key is required at runtime for decryption.
outputFileName Out
  Path of the FSB to produce.

Format specific quality interpretation:

- AT9 - Bitrate (Kbps) depends on channel count, quality [1 to 100] maps linearly to the available options
- 1ch = [36, 48, 60, 72, 84, 96]
- 2ch = [72, 96, 120, 144, 168, 192]
- MPEG - Bitrate (Kbps) = FMOD quality * 3.2
- Vorbis - Vorbis quality [-0.1 to 1.0] maps linearly to FMOD quality [1 to 100] based on: `Vorbis_Quality = ((FMOD_Quality - 1) / 90.0f) - 0.1f`
- XMA - XMA quality = FMOD quality
- Opus - Opus per-channel bitrate (Kbps) [0.8 to 64] maps linearly to FMOD quality [1 to 80], then bitrate [67.2 to 128] to quality [81 to 100]

Build function will block until complete.

## 8.3 FSBank_BuildCancel

Halt the build in progress.

C

    FSBANK_RESULT FSBank_BuildCancel();

Must be called from a different thread to FSBank_Build

See Also: FSBank_Build

## 8.4 FSBank_Release

Release the FSBank system, clean up used resources.

C

    FSBANK_RESULT FSBank_Release();

All progress items retrieved with FSBank_FetchNextProgressItem will be released by this function.

See Also: FSBank_Init, FSBank_FetchNextProgressItem

## 8.5 FSBank_ReleaseProgressItem

Release memory associated with a progress item.

C

    FSBANK_RESULT FSBank_ReleaseProgressItem(
      const FSBANK_PROGRESSITEM *progressItem
    );

progressItem
  One status update about the progress of a particular subsound. (FSBANK_PROGRESSITEM)

See Also: FSBank_FetchNextProgressItem

## 8.6 FSBank_MemoryGetStats

Query the current and maximum memory usage of the FSBank system.

C

    FSBANK_RESULT FSBank_MemoryGetStats(
      unsigned int *currentAllocated,
      unsigned int *maximumAllocated
    );

currentAllocated
  Address of a variable that receives the currently allocated memory at time of call. Optional. Specify 0 or NULL to ignore.
maximumAllocated
  Address of a variable that receives the maximum allocated memory since FSBank_Init. Optional. Specify 0 or NULL to ignore.

## 8.7 FSBank_MemoryInit

Specifies a method for FSBank to allocate memory through callbacks.

C

    FSBANK_RESULT FSBank_MemoryInit(
      FSBANK_MEMORY_ALLOC_CALLBACK userAlloc,
      FSBANK_MEMORY_REALLOC_CALLBACK userRealloc,
      FSBANK_MEMORY_FREE_CALLBACK userFree
    );

userAlloc
  Overrides the internal calls to alloc. Compatible with ANSI malloc(). (FSBANK_MEMORY_ALLOC_CALLBACK)
userRealloc
  Overrides the internal calls to realloc. Compatible with ANSI realloc(). (FSBANK_MEMORY_REALLOC_CALLBACK)
userFree
  Overrides the internal calls to free. Compatible with ANSI free(). (FSBANK_MEMORY_FREE_CALLBACK)

## 8.8 FSBank_FetchFSBMemory

Fetch the built FSB data from memory.

C

    FSBANK_RESULT FSBank_FetchFSBMemory(
      const void **data,
      unsigned int *length
    );

data
  Built FSB data.
length

  Length of 'data'.

  - Units: Bytes

Requires FSBank_Build to be called with outputFileName is set to NULL.

The memory allocated as part of FSBank_Build will be freed automatically by the next FSBank_Build or FSBank_Release.

See Also: FSBank_Build, FSBank_Release

## 8.9 FSBank_FetchNextProgressItem

Fetch build progress items that describe the current state of the build.

C

    FSBANK_RESULT FSBank_FetchNextProgressItem(
      const FSBANK_PROGRESSITEM **progressItem
    );

progressItem
  One status update about the progress of a particular subsound. (FSBANK_PROGRESSITEM)

Can be called while the build is in progress to get realtime updates or after the build for a report. Call FSBank_ReleaseProgressItem to free allocated memory.

## 8.10 FSBANK_MEMORY_ALLOC_CALLBACK

Callback to allocate a block of memory.

C

    void * FSBANK_CALLBACK FSBANK_MEMORY_ALLOC_CALLBACK(
      unsigned int size,
      unsigned int type,
      const char *sourceStr
    );

size
  Size in bytes of the memory block to be allocated and returned.
type
  Type of memory allocation.
sourceStr
  Only valid (not null) in logging versions of FMOD. Gives a string with the fmod source code filename and line number in it, for better resource tracking.

Returning an aligned pointer, of 16 byte alignment is recommended for speed purposes.

See Also: FSBank_MemoryInit, FSBANK_MEMORY_REALLOC_CALLBACK, FSBANK_MEMORY_FREE_CALLBACK

## 8.11 FSBANK_MEMORY_FREE_CALLBACK

Callback to free a block of memory.

C

    void FSBANK_CALLBACK FSBANK_MEMORY_FREE_CALLBACK(
      void *ptr,
      unsigned int type,
      const char *sourceStr
    );

ptr
  Pointer to a pre-existing block of memory to be freed.
type
  Type of memory to be freed.
sourceStr
  Only valid (not null) in logging versions of FMOD. Gives a string with the fmod source code filename and line number in it, for better resource tracking.

See Also: FSBank_MemoryInit, FSBANK_MEMORY_ALLOC_CALLBACK, FSBANK_MEMORY_REALLOC_CALLBACK

## 8.12 FSBANK_MEMORY_REALLOC_CALLBACK

Callback to re-allocate a block of memory to a different size.

C

    void * FSBANK_CALLBACK FSBANK_MEMORY_REALLOC_CALLBACK(
      void *ptr,
      unsigned int size,
      unsigned int type,
      const char *sourceStr
    );

ptr
  Pointer to a block of memory to be resized. If this is NULL then a new block of memory is simply allocated.
size
  Size of the memory to be reallocated. The original memory must be preserved.
type
  Type of memory allocation.
sourceStr
  Only valid (not null) in logging versions of FMOD. Gives a string with the fmod source code filename and line number in it, for better resource tracking.

Returning an aligned pointer, of 16 byte alignment is recommended for speed purposes.

See Also: FSBank_MemoryInit, FSBANK_MEMORY_ALLOC_CALLBACK, FSBANK_MEMORY_FREE_CALLBACK

## 8.13 FSBANK_INITFLAGS

Bit fields to control the general operation of the library.

C

    #define FSBANK_INIT_NORMAL                  0x00000000
    #define FSBANK_INIT_IGNOREERRORS            0x00000001
    #define FSBANK_INIT_WARNINGSASERRORS        0x00000002
    #define FSBANK_INIT_CREATEINCLUDEHEADER     0x00000004
    #define FSBANK_INIT_DONTLOADCACHEFILES      0x00000008
    #define FSBANK_INIT_GENERATEPROGRESSITEMS   0x00000010

FSBANK_INIT_NORMAL
  Initialize normally.
FSBANK_INIT_IGNOREERRORS
  Ignore individual subsound build errors, continue building for as long as possible.
FSBANK_INIT_WARNINGSASERRORS
  Treat any warnings issued as errors.
FSBANK_INIT_CREATEINCLUDEHEADER
  Create C header files with #defines defining indices for each member of the FSB.
FSBANK_INIT_DONTLOADCACHEFILES
  Ignore existing cache files.
FSBANK_INIT_GENERATEPROGRESSITEMS
  Generate status items that can be queried by another thread to monitor the build progress and give detailed error messages.

See Also: FSBank_Init

## 8.14 FSBANK_BUILDFLAGS

Bit fields to control how subsounds are encoded.

C

    #define FSBANK_BUILD_DEFAULT                 0x00000000
    #define FSBANK_BUILD_DISABLESYNCPOINTS       0x00000001
    #define FSBANK_BUILD_DONTLOOP                0x00000002
    #define FSBANK_BUILD_FILTERHIGHFREQ          0x00000004
    #define FSBANK_BUILD_DISABLESEEKING          0x00000008
    #define FSBANK_BUILD_OPTIMIZESAMPLERATE      0x00000010
    #define FSBANK_BUILD_FSB5_DONTWRITENAMES     0x00000080
    #define FSBANK_BUILD_NOGUID                  0x00000100
    #define FSBANK_BUILD_WRITEPEAKVOLUME         0x00000200
    #define FSBANK_BUILD_OVERRIDE_MASK           (FSBANK_BUILD_DISABLESYNCPOINTS | FSBANK_BUILD_DONTLOOP | FSBANK_BUILD_FILTERHIGHFREQ | FSBANK_BUILD_DISABLESEEKING | FSBANK_BUILD_OPTIMIZESAMPLERATE | FSBANK_BUILD_WRITEPEAKVOLUME)
    #define FSBANK_BUILD_CACHE_VALIDATION_MASK   (FSBANK_BUILD_DONTLOOP | FSBANK_BUILD_FILTERHIGHFREQ | FSBANK_BUILD_OPTIMIZESAMPLERATE)

FSBANK_BUILD_DEFAULT
  Build with default settings.
FSBANK_BUILD_DISABLESYNCPOINTS
  Disable the storing of syncpoints in the output
FSBANK_BUILD_DONTLOOP
  Disable perfect loop encoding and sound stretching. Removes chirps from the start of oneshot MP2, MP3 and IMAADPCM sounds.
FSBANK_BUILD_FILTERHIGHFREQ
  XMA only. Enable high frequency filtering.
FSBANK_BUILD_DISABLESEEKING
  XMA only. Disable seek tables to save memory.
FSBANK_BUILD_OPTIMIZESAMPLERATE
  Attempt to optimize the sample rate down. Ignored if format is MP2, MP3 or if FSB4 basic headers flag is used.
FSBANK_BUILD_FSB5_DONTWRITENAMES
  FSB5 format only. Do not write out a names chunk to the FSB to reduce file size.
FSBANK_BUILD_NOGUID
  FSB5 format only. Write out a null GUID for the FSB header. The engine will not use header caching for these FSB files.
FSBANK_BUILD_WRITEPEAKVOLUME
  FSB5 format only. Write peak volume for all subsounds.
FSBANK_BUILD_OVERRIDE_MASK
  Build flag mask that specifies which settings can be overridden per subsound.
FSBANK_BUILD_CACHE_VALIDATION_MASK
  Build flag mask that specifies which settings (when changed) invalidate a cache file.

See Also: FSBank_Init, FSBANK_SUBSOUND

## 8.15 FSBANK_FORMAT

Compression formats available for encoding

C

    typedef enum FSBANK_FORMAT {
      FSBANK_FORMAT_PCM,
      FSBANK_FORMAT_XMA,
      FSBANK_FORMAT_AT9,
      FSBANK_FORMAT_VORBIS,
      FSBANK_FORMAT_FADPCM,
      FSBANK_FORMAT_OPUS,
      FSBANK_FORMAT_MAX
    } FSBANK_FORMAT;

FSBANK_FORMAT_PCM
  PCM (1:1) All platforms.
FSBANK_FORMAT_XMA
  XMA (VBR) XboxOne and Xbox Series X|S only (hardware). Depends on xmaencoder.
FSBANK_FORMAT_AT9
  ATRAC9 (CBR) PS4 and PS5 only (hardware). Depends on libatrac9.
FSBANK_FORMAT_VORBIS
  Vorbis (VBR) All platforms. Depends on libvorbis.
FSBANK_FORMAT_FADPCM
  FMOD ADPCM (3.5:1) All platforms.
FSBANK_FORMAT_OPUS
  Opus (VBR) Xbox Series X|S. Depends on opus.
FSBANK_FORMAT_MAX
  Upper bound for this enumeration, for use with validation.

See Also: FSBank_Build

## 8.16 FSBANK_FSBVERSION

Version of FSB to write out.

C

    typedef enum FSBANK_FSBVERSION {
      FSBANK_FSBVERSION_FSB5,
      FSBANK_FSBVERSION_MAX
    } FSBANK_FSBVERSION;

FSBANK_FSBVERSION_FSB5
  Produce FSB version 5 files.
FSBANK_FSBVERSION_MAX
  Upper bound for this enumeration, for use with validation.

See Also: FSBank_Init

## 8.17 FSBANK_PROGRESSITEM

Status information describing the progress of a build.

C

    typedef struct FSBANK_PROGRESSITEM {
      int            subSoundIndex;
      int            threadIndex;
      FSBANK_STATE   state;
      const void    *stateData;
    } FSBANK_PROGRESSITEM;

subSoundIndex
  Index into the subsound list passed to FSBank_Build that this update relates to (-1 indicates no specific subsound).
threadIndex
  Which thread index is serving this update (-1 indicates FSBank_Build / main thread).
state
  Progress through the encoding process. (FSBANK_STATE)
stateData
  Cast to state specific data structure for extra information.

See Also: FSBank_Build, FSBank_FetchNextProgressItem, FSBank_ReleaseProgressItem, FSBANK_STATE

## 8.18 FSBANK_RESULT

Error codes returned from every function.

C

    typedef enum FSBANK_RESULT {
      FSBANK_OK,
      FSBANK_ERR_CACHE_CHUNKNOTFOUND,
      FSBANK_ERR_CANCELLED,
      FSBANK_ERR_CANNOT_CONTINUE,
      FSBANK_ERR_ENCODER,
      FSBANK_ERR_ENCODER_INIT,
      FSBANK_ERR_ENCODER_NOTSUPPORTED,
      FSBANK_ERR_FILE_OS,
      FSBANK_ERR_FILE_NOTFOUND,
      FSBANK_ERR_FMOD,
      FSBANK_ERR_INITIALIZED,
      FSBANK_ERR_INVALID_FORMAT,
      FSBANK_ERR_INVALID_PARAM,
      FSBANK_ERR_MEMORY,
      FSBANK_ERR_UNINITIALIZED,
      FSBANK_ERR_WRITER_FORMAT,
      FSBANK_WARN_CANNOTLOOP,
      FSBANK_WARN_IGNORED_FILTERHIGHFREQ,
      FSBANK_WARN_IGNORED_DISABLESEEKING,
      FSBANK_WARN_FORCED_DONTWRITENAMES,
      FSBANK_ERR_ENCODER_FILE_NOTFOUND,
      FSBANK_ERR_ENCODER_FILE_BAD
    } FSBANK_RESULT;

FSBANK_OK
  No errors.
FSBANK_ERR_CACHE_CHUNKNOTFOUND
  An expected chunk is missing from the cache, perhaps try deleting cache files.
FSBANK_ERR_CANCELLED
  The build process was cancelled during compilation by the user.
FSBANK_ERR_CANNOT_CONTINUE
  The build process cannot continue due to previously ignored errors.
FSBANK_ERR_ENCODER
  Encoder for chosen format has encountered an unexpected error.
FSBANK_ERR_ENCODER_INIT
  Encoder initialization failed.
FSBANK_ERR_ENCODER_NOTSUPPORTED
  Encoder for chosen format is not supported on this platform.
FSBANK_ERR_FILE_OS
  An operating system based file error was encountered.
FSBANK_ERR_FILE_NOTFOUND
  A specified file could not be found.
FSBANK_ERR_FMOD
  Internal error from FMOD sub-system.
FSBANK_ERR_INITIALIZED
  Already initialized.
FSBANK_ERR_INVALID_FORMAT
  The format of the source file is invalid.
FSBANK_ERR_INVALID_PARAM
  An invalid parameter has been passed to this function.
FSBANK_ERR_MEMORY
  Ran out of memory.
FSBANK_ERR_UNINITIALIZED
  Not initialized yet.
FSBANK_ERR_WRITER_FORMAT
  Chosen encode format is not supported by this FSB version.
FSBANK_WARN_CANNOTLOOP
  Source file is too short for seamless looping. Looping disabled.
FSBANK_WARN_IGNORED_FILTERHIGHFREQ
  FSBANK_BUILD_FILTERHIGHFREQ flag ignored: feature only supported by XMA format.
FSBANK_WARN_IGNORED_DISABLESEEKING
  FSBANK_BUILD_DISABLESEEKING flag ignored: feature only supported by XMA format.
FSBANK_WARN_FORCED_DONTWRITENAMES
  FSBANK_BUILD_FSB5_DONTWRITENAMES flag forced: cannot write names when source is from memory.
FSBANK_ERR_ENCODER_FILE_NOTFOUND
  External encoder dynamic library not found
FSBANK_ERR_ENCODER_FILE_BAD
  External encoder dynamic library could not be loaded, possibly incorrect binary format, incorrect architecture, file corruption

## 8.19 FSBANK_STATE

Current state during the build process.

C

    typedef enum FSBANK_STATE {
      FSBANK_STATE_DECODING,
      FSBANK_STATE_ANALYSING,
      FSBANK_STATE_PREPROCESSING,
      FSBANK_STATE_ENCODING,
      FSBANK_STATE_WRITING,
      FSBANK_STATE_FINISHED,
      FSBANK_STATE_FAILED,
      FSBANK_STATE_WARNING
    } FSBANK_STATE;

FSBANK_STATE_DECODING
  Decode a file to usable raw sample data.
FSBANK_STATE_ANALYSING
  Scan sound data for details (such as optimized sample rate).
FSBANK_STATE_PREPROCESSING
  Prepares sound data for encoder.
FSBANK_STATE_ENCODING
  Pass the sample data to the chosen encoder.
FSBANK_STATE_WRITING
  Write encoded data into an FSB.
FSBANK_STATE_FINISHED
  Process complete.
FSBANK_STATE_FAILED
  An error has occurred, check data (as FSBANK_STATEDATA_FAILED) for details.
FSBANK_STATE_WARNING
  A warning has been issued, check data (as FSBANK_STATEDATA_WARNING) for details.

See Also: FSBANK_PROGRESSITEM

## 8.20 FSBANK_STATEDATA_FAILED

Extra failed state data.

C

    typedef struct FSBANK_STATEDATA_FAILED {
      FSBANK_RESULT   errorCode;
      char            errorString[256];
    } FSBANK_STATEDATA_FAILED;

errorCode
  Error result code. (FSBANK_RESULT)
errorString
  Description for error code.

Cast stateData in FSBANK_PROGRESSITEM to this struct if the state is FSBANK_STATE_FAILED

## 8.21 FSBANK_STATEDATA_WARNING

Extra warning state data.

C

    typedef struct FSBANK_STATEDATA_WARNING {
      FSBANK_RESULT   warnCode;
      char            warningString[256];
    } FSBANK_STATEDATA_WARNING;

warnCode
  Warning result code. (FSBANK_RESULT)
warningString
  Description for warning code.

Cast stateData in FSBANK_PROGRESSITEM to this struct if the state is FSBANK_STATE_WARNING

## 8.22 FSBANK_SUBSOUND

Representation of how to encode a single subsound in the final FSB.

C

    typedef struct FSBANK_SUBSOUND {
      const char* const   *fileNames;
      const void* const   *fileData;
      const unsigned int   *fileDataLengths;
      unsigned int         numFiles;
      FSBANK_BUILDFLAGS    overrideFlags;
      unsigned int         overrideQuality;
      float                desiredSampleRate;
      float                percentOptimizedRate;
    } FSBANK_SUBSOUND;

fileNames
  List of file names (instead of FSBANK_SUBSOUND::fileData) used to produce an interleaved sound. (UTF-8 string)
fileData
  List of file data pointers (instead of FSBANK_SUBSOUND::fileNames) used to produce an interleaved sound.
fileDataLengths
  List of file data lengths corresponding to the items in the FSBANK_SUBSOUND::fileData list.
numFiles
  Number of items in either FSBANK_SUBSOUND::fileData / FSBANK_SUBSOUND::fileDataLengths or FSBANK_SUBSOUND::fileNames.
overrideFlags
  Flags that will reverse the equivalent flags passed to FSBank_Build. (FSBANK_BUILDFLAGS)
overrideQuality
  Override the quality setting passed to FSBank_Build.
desiredSampleRate
  Resample to this sample rate (ignores optimize sample rate setting), up to 192000Hz.
percentOptimizedRate
  If using FSBANK_BUILD_OPTIMIZESAMPLERATE, this is the percentage of that rate to be used, up to 100.0%.

See Also: FSBank_Build, FSBANK_BUILD_OPTIMIZESAMPLERATE, FSBANK_BUILDFLAGS