BASS_MIDI_FontPack

Produces a compressed version of a soundfont.

BOOL BASS_MIDI_FontPack(
    HSOUNDFONT handle,
    void *outfile,
    void *encoder,
    DWORD flags
);

Parameters

handle

The soundfont to pack.

outfile

Filename for the packed soundfont.

encoder

Encoder command-line.

flags

Any combination of these flags.

BASS_MIDI_PACK_NOHEAD	Do not send a WAVE header to the encoder. If this flag is used then the sample format (mono 16-bit) must be passed to the encoder some other way, eg. via the command-line.
BASS_MIDI_PACK_16BIT	Reduce 24-bit sample data to 16-bit before encoding.
BASS_MIDI_PACK_48KHZ	Encode the sample data at 48000 Hz, else 44100 Hz. This is applied automatically if "opus" is present in the encoder command-line. The encoding rate only really makes a difference with lossy codecs.
BASS_UNICODE	outfile and encoder are in UTF-16 form. Otherwise they are ANSI on Windows, and UTF-8 on other platforms.

Return value

If successful, the 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_NOTAVAIL	This function is not applicable to SFZ soundfonts.
BASS_ERROR_FILEOPEN	Could not start the encoder. Check that the executable exists.
BASS_ERROR_CREATE	Could not create the output file, outfile.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

Standard soundfonts use PCM samples, so they can be quite large, which can be a problem if they are to be distributed. To reduce the size, BASSMIDI can compress the samples using any command-line encoder with STDIN and STDOUT support. Packed soundfonts can be used for rendering by BASSMIDI just like normal soundfonts. They can also be unpacked using BASS_MIDI_FontUnpack.

Although any command-line encoder can be used, it is best to use a lossless format like FLAC or WavPack, rather than a lossy one like OGG or MP3. Using a lossless encoder, the packed soundfont will produce exactly the same results as the original soundfont, and will be identical to the original when unpacked. As a compromise between quality and size, the WavPack hybrid/lossy mode also produces good sounding results.

The encoder must be told (via the command-line) to expect input from STDIN and to send its output to STDOUT.

Before using a packed soundfont, the appropriate BASS add-on needs to be loaded via BASS_PluginLoad. For example, if the samples are FLAC encoded, BASSFLAC would need to be loaded. During rendering, the samples are unpacked as they are needed, which could result in CPU spikes. Where smooth performance is critical, it may be wise to preload the samples using BASS_MIDI_FontLoad or BASS_MIDI_StreamLoadSamples.

A soundfont should not be packed while it is being used to render any MIDI streams, as that could delay the rendering.

This function only applies to SF2 soundfonts. SFZ samples can be compressed using standard encoding tools.

Platform-specific

This function is not available on iOS or Android.

Example

Create a FLAC encoded version of a soundfont.

HSOUNDFONT handle = BASS_MIDI_FontInit("afile.sf2", 0); // open original soundfont
BASS_MIDI_FontPack(handle, "afile.sf2pack", "flac --best -", 0); // produce packed version