BASS_MIDI_FontLoadEx

Preloads and/or unloads presets from a soundfont.

BOOL BASS_MIDI_FontLoadEx(
    HSOUNDFONT handle,
    int preset,
    int bank,
    DWORD length,
    DWORD flags
);

Parameters

handle

The soundfont handle.

preset

Preset number to load... -1 = all presets.

bank

Bank number to load... -1 = all banks.

length

Maximum amount of data (in sample frames or milliseconds) to load... 0 = all (or none when compacting).

flags

Any combination of these flags.

BASS_MIDI_FONTLOAD_COMPACT	Compact loaded samples to the length amount.
BASS_MIDI_FONTLOAD_KEEPDEC	Retain the decoder after partially loading (or just parsing) an encoded SFZ sample. This will allow the remainder to be loaded more quickly but will also use more memory (for the decoder state). The difference this makes will vary depending on the codec used. Only SFZ samples are affected; SF2 decoders are always retained.
BASS_MIDI_FONTLOAD_NOLOAD	Do not load samples. If this is combined with BASS_MIDI_FONTLOAD_COMPACT then only compacting will be performed, otherwise any unparsed SFZ sample files will be parsed but no data loaded.
BASS_MIDI_FONTLOAD_NOWAIT	Load the samples asynchronously, else wait for the samples to be loaded before returning. This does not affect compacting or SFZ sample parsing, which are always done before returning.
BASS_MIDI_FONTLOAD_TIME	The length value is in milliseconds, else it is sample frames. Millisecond lengths are based on a sample's default rate. The actual duration of the loaded data may be different if the sample is played at another rate.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE	handle is not valid.
BASS_ERROR_CODEC	A supporting BASS add-on to decode the SF2 samples is not loaded.
BASS_ERROR_FILEFORM	An SFZ sample has an unknown file format. A BASS add-on may be needed to handle it.
BASS_ERROR_NOTAVAIL	The soundfont does not contain the requested preset.
BASS_ERROR_MEM	There is insufficient memory.

Remarks

This function combines the functionality of the BASS_MIDI_FontLoad and BASS_MIDI_FontUnload functions and extends it with the ability to partially load and/or unload presets, and load asynchronously.

When a sample is partially preloaded, the remainder will be loaded as needed during playback. The partially loaded part can begin playing before the rest is loaded, so it allows delays to be avoided during playback, while being faster and using less memory than preloading fully. The amount that should be preloaded to avoid any delays will depend on how fast the drive is.

When partially loading a preset's samples, any samples that already have more data loaded will retain that data unless the BASS_MIDI_FONTLOAD_COMPACT flag is used, in which case they will be reduced to the requested partial amount.

Samples that are preloaded by this function are not affected by automatic compacting via the BASS_CONFIG_MIDI_COMPACT option.

Any samples that are currently being used by a MIDI stream will not be compacted.

Platform-specific

On Android/iOS/Linux/macOS, BASSMIDI may hit the OS's per-process open file limit when asynchronously loading SFZ soundfonts with lots of unique samples. BASSMIDI will temporarily close other sample files when that happens, but it would be more efficient (and safer for other file opening elsewhere in the app) to raise the limit instead, which can be done via the setrlimit (RLIMIT_NOFILE) function. macOS and iOS have a particularly low default limit of 256, while Linux and Android usually default to 1024. SF2 soundfonts have all samples in a single file, so asynchronously loading them is not an issue, but they are never temporarily closed and reopened, so the limit should also be raised if using a lot of SF2 soundfonts.

Example

Load 1000 frames of all samples in preset 0:0, and keep any that already have more than that.

BASS_MIDI_FontLoadEx(handle, 0, 0, 1000, 0);

Load 1000 frames of all samples in preset 0:0, and reduce any already loaded samples to 1000 frames.

BASS_MIDI_FontLoadEx(handle, 0, 0, 1000, BASS_MIDI_FONTLOAD_COMPACT);

Reduce any already loaded samples in preset 0:0 to 1000 frames.

BASS_MIDI_FontLoadEx(handle, 0, 0, 1000, BASS_MIDI_FONTLOAD_COMPACT | BASS_MIDI_FONTLOAD_NOLOAD);