BASS.NET API for the Un4seen BASS Audio Library

BassMidiBASS_MIDI_FontLoad Method (Int32, Int32, Int32, Int32, BASSMIDIFont)

BASS.NET API for the Un4seen BASS Audio Library
Preloads and/or unloads presets from a soundfont.

Namespace:  Un4seen.Bass.AddOn.Midi
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

[DllImportAttribute("bassmidi", EntryPoint = "BASS_MIDI_FontLoadEx", 
	CharSet = CharSet.Unicode)]
public static bool BASS_MIDI_FontLoad(
	int handle,
	int preset,
	int bank,
	int length,
	BASSMIDIFont flags
)

Parameters

handle
Type: SystemInt32
The soundfont handle.
preset
Type: SystemInt32
Preset number to load... -1 = all presets.
bank
Type: SystemInt32
Bank number to load... -1 = all banks.
length
Type: SystemInt32
Maximum amount of data (in sample frames or milliseconds) to load... 0 = all (or none when compacting).
flags
Type: Un4seen.Bass.AddOn.MidiBASSMIDIFont
Any combination of these flags (see BASSMIDIFont):
BASS_MIDI_FONTLOAD_COMPACTCompact loaded samples to the length amount.
BASS_MIDI_FONTLOAD_KEEPDECRetain 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_NOLOADDo 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_NOWAITLoad 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_TIMEThe 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

Type: Boolean
If successful, is returned, else is returned. Use BASS_ErrorGetCode to get the error code.
Remarks

This function combines the functionality of the BASS_MIDI_FontLoad(Int32, Int32, Int32) and BASS_MIDI_FontUnload(Int32, Int32, Int32) 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.

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_CODECThe appropriate add-on to decode the samples is not loaded.
BASS_ERROR_FILEFORMAn SFZ sample has an unknown file format. A BASS add-on may be needed to handle it.
BASS_ERROR_NOTAVAILThe soundfont does not contain the requested preset.
BASS_ERROR_MEMThere is insufficient memory.

See Also

Reference