BASS_MIDI_FontPack


Produces a compressed version of a soundfont.

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

Parameters

handleThe soundfont to pack.
outfileFilename for the packed soundfont.
encoderEncoder command-line.
flagsAny combination of these flags.
BASS_MIDI_PACK_NOHEADDon't 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_16BITReduce 24-bit sample data to 16-bit before encoding.
BASS_UNICODEoutfile 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_HANDLEhandle is not valid.
BASS_ERROR_FILEOPENCould not start the encoder. Check that the executable exists.
BASS_ERROR_CREATECould not create the output file, outfile.
BASS_ERROR_UNKNOWNSome 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

See also

BASS_MIDI_FontInit, BASS_MIDI_FontLoad, BASS_MIDI_FontUnpack