BASS_MIDI_StreamSetFonts

Applies a soundfont configuration to a MIDI stream, or sets the default soundfont configuration.

BOOL BASS_MIDI_StreamSetFonts(
    HSTREAM handle,
    void *fonts,
    DWORD count
);

Parameters

handle	The MIDI stream to apply the soundfonts to... 0 = set default soundfont configuration.
fonts	An array of BASS_MIDI_FONT or BASS_MIDI_FONTEX or BASS_MIDI_FONTEX2 containing the soundfonts to apply.
count	The number of elements in the fonts array. The BASS_MIDI_FONT_EX or BASS_MIDI_FONT_EX2 flag may also be used to specify that fonts is an array of BASS_MIDI_FONTEX or BASS_MIDI_FONTEX2 rather than BASS_MIDI_FONT.

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_ILLPARAM	Something in the fonts array is invalid, check the soundfont handles.

Remarks

Multiple soundfonts can be stacked, each providing different presets, for example. When a preset is present in multiple soundfonts, the earlier soundfont in the array has priority. When a soundfont matching the MIDI file is loaded, that remains loaded when calling this function, and has priority over all other soundfonts. When a preset is not available on a non-0 bank in any soundfont, BASSMIDI will try to fall back to bank 0; first the LSB and then the MSB if still unsuccessful.

A MIDI stream's soundfont configuration can be changed during playback. Any currently playing notes that end up using the same samples as with the previous configuration will continue playing, while other notes will be stopped during the configuration change.

Changing the default configuration only affects subsequently created MIDI streams. Existing streams that are using the previous default configuration will continue to use that previous configuration.

Platform-specific

Depending on the programming language used, the BASS_MIDI_FONT_EX or BASS_MIDI_FONT_EX2 flag may be automatically applied when the BASS_MIDI_FONTEX or BASS_MIDI_FONTEX2 structure is used, through overloading in the BASSMIDI header. That is true for C++, Delphi, and Java.

Example

Set a MIDI stream to use one soundfont for program 10 on bank 0, and all available presets from another soundfont.

BASS_MIDI_FONT fonts[2];
fonts[0].font = font1;
fonts[0].preset = 10; // preset 10
fonts[0].bank = 0; // bank 0
fonts[1].font = font2;
fonts[1].preset = -1; // all presets
fonts[1].bank = 0; // default banks
BASS_MIDI_StreamSetFonts(handle, fonts, 2); // apply it to the stream

Set a MIDI stream to use preset 20 from one soundfont for program 10 on bank 0, and all available presets from another soundfont.

BASS_MIDI_FONTEX fonts[2];
fonts[0].font = font1;
fonts[0].spreset = 20; // soundfont preset 20
fonts[0].sbank = 0; // soundfont bank 0
fonts[0].dpreset = 10; // destination preset 10
fonts[0].dbank = 0; // destination bank 0
fonts[0].dbanklsb = 0; // destination bank LSB 0
fonts[1].font = font2;
fonts[1].spreset = -1; // all presets
fonts[1].sbank = -1; // all banks
fonts[1].dpreset = -1; // all presets
fonts[1].dbank = 0; // default banks
fonts[1].dbanklsb = 0; // destination bank LSB 0
BASS_MIDI_StreamSetFonts(handle, fonts, 2 | BASS_MIDI_FONT_EX); // apply it to the stream