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.

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.

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.

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.

FSBANK_RESULT FSBank_Release();

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

8.5 FSBank_ReleaseProgressItem

Release memory associated with a progress item.

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.

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.

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.

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.

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.

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.

8.11 FSBANK_MEMORY_FREE_CALLBACK

Callback to free a block of memory.

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.

8.12 FSBANK_MEMORY_REALLOC_CALLBACK

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

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.

8.13 FSBANK_INITFLAGS

Bit fields to control the general operation of the library.

#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.

#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_ALIGN4K                 0x00000400
#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: Do not write out a names chunk to the FSB to reduce file size.
FSBANK_BUILD_NOGUID: Write out a null GUID for the FSB header. The engine will not use header caching for these FSB files.
FSBANK_BUILD_WRITEPEAKVOLUME: Write peak volume for all subsounds.
FSBANK_BUILD_ALIGN4K: Opus, Vorbis and FADPCM only. Align large sample data to a 4KB boundary to improve binary patching in distribution systems that operate in 4KB blocks (Microsoft).
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

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, PS5, and Switch. 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.

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.

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.

8.18 FSBANK_RESULT

Error codes returned from every function.

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_WARN_IGNORED_ALIGN4K,
} 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
FSBANK_WARN_IGNORED_ALIGN4K: FSBANK_BUILD_ALIGN4K flag ignored: feature only supported by Opus, Vorbis, and FADPCM formats.

8.19 FSBANK_STATE

Current state during the build process.

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.

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.

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.

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%.