BASS_MIDI_FontInit

Initializes a soundfont.

HSOUNDFONT BASS_MIDI_FontInit(
    void *file,
    DWORD flags
);

Parameters

file

The soundfont filename.

flags

Any combination of these flags.

BASS_MIDI_FONT_LINATTMOD	Use a linear attack phase in SF2 modulation (pitch/filter) envelopes. Otherwise a convex curve is used. The attack phase is always linear in SFZ envelopes.
BASS_MIDI_FONT_LINDECVOL	Use linear decay and release phases in volume envelopes. Otherwise a concave curve is used. The attack phase is always linear.
BASS_MIDI_FONT_MINFX	Treat the reverb/chorus levels in the soundfont as minimums. The higher of them and the MIDI levels (CC91/93) will be used instead of the sum of both.
BASS_MIDI_FONT_MMAP	Map the file into memory. This flag only applies to SF2 files, not SFZ files (or their samples). It is ignored if the file is too large to be mapped into memory, or if the soundfont is packed because the sample data cannot be played directly from a mapping (it needs to be decoded).
BASS_MIDI_FONT_NOFX	Ignore the reverb/chorus levels in the soundfont and only use the MIDI levels (CC91/93).
BASS_MIDI_FONT_NORAMPIN	Never ramp-in the start of a sample in the soundfont. Otherwise a sample will be ramped-in if its data does not begin with a 0 (further away results in a longer ramp). This is only relevant when the volume envelope has no attack phase.
BASS_MIDI_FONT_NOSBLIMITS	Do not emulate Creative/SoundBlaster hardware filter and SF2 generator limits. This flag is always applied to SFZ files.
BASS_MIDI_FONT_SBLIMITS	Emulate Creative/SoundBlaster hardware filter and SF2 generator limits. This flag only applies to SF2 files. If neither this or BASS_MIDI_FONT_NOSBLIMITS are specified then emulation will be determined by how the file was created, with it being enabled if the file's "ISFT" chunk contains "SFEDT" or "E-mu Systems SoundFont Designer", and the result reflected by BASS_MIDI_FontFlags.
BASS_MIDI_FONT_XGDRUMS	Use bank 127 in the soundfont for XG drum kits. When an XG drum kit is needed, bank 127 in soundfonts that have this flag set will be checked first, before falling back to bank 128 (the standard SF2 drum kit bank) if it is not available there.
BASS_UNICODE	file is in UTF-16 form. Otherwise it is ANSI on Windows, and UTF-8 on other platforms.

Return value

If successful, the soundfont's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file's format is not recognised/supported.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_MIDI_INCLUDE	An SFZ #include directive file could not be opened.

Remarks

BASSMIDI uses SF2 and/or SFZ soundfonts to provide the sounds to use in the rendering of MIDI streams. Several soundfonts can be found on the internet, including a couple on the BASS website.

A soundfont needs to be initialized before it can be used to render MIDI streams. Information on the initialized soundfont can be retrieved from BASS_MIDI_FontGetInfo. Once initialized, a soundfont can be assigned to MIDI streams via the BASS_MIDI_StreamSetFonts function. A single soundfont can be shared by multiple MIDI streams. If a soundfont is initialized multiple times, each instance will have its own handle but share the same data. If the file's last-modified timestamp has changed since it was last loaded then it will be reloaded rather than shared.

Sample data will be loaded from soundfonts to memory as needed while rendering a MIDI stream, and can also be loaded in advance with BASS_MIDI_FontLoad or BASS_MIDI_FontLoadEx or BASS_MIDI_StreamLoadSamples.

Soundfonts use PCM sample data as standard, but BASSMIDI can accept any format that is supported by BASS or its add-ons (the add-ons need to be loaded via BASS_PluginLoad). The BASS_MIDI_FontPack function can be used to compress the sample data in SF2 files. SF3 files (another form of compressed SF2) can also be used with BASSMIDI, but not created with it. SFZ samples are in separate files and can be compressed using standard encoding tools.

Using soundfonts that are located somewhere other than the file system is possible via BASS_MIDI_FontInitUser.

SF2 support

The SF2 synthesis model is fully supported, as are all SF2 generators, but the SF2 modulator controller model is only partially supported. The following modulators are supported: note velocity to attenuation (initialAttenuation), note velocity to filter cutoff (initialFilterFc), note velocity to modulation envelope attack/decay/release (attackModEnv/decayModEnv/releaseModEnv), note velocity to modulation envelope filter cutoff (modEnvToFilterFc), note velocity to volume envelope attack/decay/release (attackVolEnv/decayVolEnv/releaseVolEnv), note velocity to start offset (startAddrsOffset), key number to attenuation, key number to filter cutoff, key number to pan, key number to start offset. MIDI CC21-24 to initialFilterFc/initialAttenuation/attackVolEnv/decayVolEnv/releaseVolEnv/releaseModEnv/modEnvToFilterFc modulators are also supported, but each CC can only have one destination per-preset. In each case, all curve types are supported and multiple modulators in the global/instrument/preset zones is supported but only if they are identical (eg. all negative unipolar linear). If different types are present on a preset then the one with the biggest absolute amount setting will be used. Secondary sources are not supported and will be ignored. The SF2 spec's slightly strange default note velocity to filter cutoff modulator is not used.

SFZ support

The following SFZ opcodes are supported: amp_keycenter, amp_keytrack, ampeg_attack, ampeg_decay, ampeg_delay, ampeg_hold, ampeg_release, ampeg_sustain, ampeg_vel2attack, ampeg_vel2decay, ampeg_vel2release, amplfo_delay, amplfo_depth, amplfo_fade, amplfo_freq, amp_veltrack, cutoff, default_path, delay, delay_beats, effect1, effect2, end, fil_keycenter, fil_keytrack, fil_type, fileg_attack/pitcheg_attack, fileg_decay/pitcheg_decay, fileg_delay/pitcheg_delay, fileg_depth, fileg_hold/pitcheg_hold, fileg_release/pitcheg_release, fileg_sustain/pitcheg_sustain, fileg_vel2attack/pitcheg_vel2attack, fileg_vel2decay/pitcheg_vel2decay, fileg_vel2depth, fileg_vel2release/pitcheg_vel2release, fillfo_delay, fillfo_depth, fillfo_fade, fillfo_freq, fil_veltrack, group, hicc1, hicc64, hicc67, hikey, hirand, hivel, key, locc1, locc64, locc67, lokey, loop_end, loop_mode, loop_start, lorand, lovel, offset, off_by, off_mode, pan, pan_keycenter, pan_keytrack, pitcheg_depth, pitchlfo_delay, pitchlfo_depth, pitchlfo_fade, pitchlfo_freq, pitch_keycenter, pitch_keytrack, pitch_random, pitch_veltrack, resonance, rt_decay, sample, seq_length, seq_position, sw_default, sw_last, sw_lokey, sw_lolast, sw_hikey, sw_hilast, transpose, trigger, tune, volume, xf_keycurve, xf_velcurve, xfin_hikey, xfin_hivel, xfin_lokey, xfin_lovel, xfout_hikey, xfout_hivel, xfout_lokey, xfout_lovel. The combined fileg/pitcheg entries in the opcode list reflect that there is a shared envelope generator for pitch and filter, as is the case in SF2 soundfonts. The fil_type opcode support includes the lpf_2p and hpf_2p options for 2 pole low/high pass filters. Higher pole low/high pass will be reduced to 2 pole, and any other filter (including 1 pole low/high pass) will be ignored. Information on these (and other) SFZ opcodes can be found at www.sfzformat.com. The #define and #include directives are also supported.

Samples can also be loaded from memory by setting the "sample" opcode to "mem:<address>:<length>", where address and length are both in hexadecimal. The memory should remain valid until the font is freed via BASS_MIDI_FontFree. When multiple SFZ files use the same sample, a single copy of the sample is loaded and shared by all of them. SFZ samples must be either mono or stereo, and not 8-bit.

An SFZ header can be set via the BASS_CONFIG_MIDI_SFZHEAD config option, which will be prepended to all SFZ files. This can be useful for defining macros for the SFZ files.

SFZ files do not have a defined preset or bank number, so they are nominally assigned to preset 0 in bank 0 when loaded, but can be assigned to other presets/banks via BASS_MIDI_StreamSetFonts.

Platform-specific

The BASS_MIDI_FONT_MMAP option is not available on big-endian systems because a soundfont's little-endian sample data cannot be played directly from a mapping.

On Android, when using Java, file may be one of the following: String, ByteBuffer, ParcelFileDescriptor (Android 3.1 and above), BASS.Asset.

Example

Initialize a soundfont.

HSOUNDFONT sfont = BASS_MIDI_FontInit("blah.sf2", 0);