MidiPlayerTK.MPTKSoundFont

When your application is running, SoundFonts can be dynamically loaded either from a local file system or directly from the web.
This means you don't need to include a SoundFont in your build, making it ideal for scenarios like in-app purchases or downloadable content.
For compatibility, the legacy mode still allows loading SoundFonts from the internal MPTK database.
Additionally, Maestro MPTK supports assigning different SoundFonts to different MIDI players, enabling flexible and customized audio rendering across multiple instruments or scenes.
More...

Public Member Functions
bool	Load (string path=null)
string	PresetName (int patch)
bool	SelectBankDrum (int bankNumber)
bool	SelectBankInstrument (int bankNumber)

Public Attributes
bool	DownloadOnly
Action< MidiSynth >	LoadedCallback = null
bool	LoadFromCache
Action< float >	ProgressCallback = null
bool	SaveToCache

Properties
List< string >	BanksName [get]
List< int >	BanksNumber [get]
int	DefaultBank [get, set]
int	DrumBank [get, set]
bool	IsDefault [get]
bool	IsInternal [get]
bool	IsReady [get]
List< MPTKListItem >	ListBank [get, set]
List< MPTKListItem >	ListPreset [get, set]
List< MPTKListItem >	ListPresetDrum [get, set]
List< string >	PresetsName [get, set]
List< int >	PresetsNumber [get, set]
float	ProgressValue [get]
ImSoundFont	SoundFont [get]
string	SoundFontName [get]
LoadingStatusSoundFontEnum	StatusSoundFont [get]
TimeSpan	TimeToDownloadSoundFont [get]
TimeSpan	TimeToLoadOverall [get]
TimeSpan	TimeToLoadSoundFont [get]
TimeSpan	TimeToLoadWave [get]

Detailed Description

When your application is running, SoundFonts can be dynamically loaded either from a local file system or directly from the web.
This means you don't need to include a SoundFont in your build, making it ideal for scenarios like in-app purchases or downloadable content.
For compatibility, the legacy mode still allows loading SoundFonts from the internal MPTK database.
Additionally, Maestro MPTK supports assigning different SoundFonts to different MIDI players, enabling flexible and customized audio rendering across multiple instruments or scenes.

Version

2.14

Note

An instance of this class is automatically created for each MPTK prefab (MidiFilePlayer, MidiStreamPlayer ...) loaded in the scene. see MidiSynth.MPTK_SoundFont

Member Function Documentation

Load()

bool MidiPlayerTK.MPTKSoundFont.Load

(

string

path = null

)

Load a SoundFont file on the fly when the application is running (MPTK Pro).

Parameters

pathSF

The path to the SoundFont, loading from: Local desktop when path starts with file:// a web resource when starts with http:// or https:// else from the internal MPTK soundfont DB with this name, if null or empty, the default internal soundfont is selected.

Returns

• true if loading is in progress. Defined LoadedCallback to get information when loading is complete.
• false if an error is detected in the parameters. The callback LoadedCallback is not called if the return value is false.

List<MidiSynth> midiSynths = new List<MidiSynth>();
midiSynths.AddRange(FindObjectsByType<MidiFilePlayer>(FindObjectsSortMode.None));
foreach (MidiSynth midiSynth in midiSynths)
{
    midiSynth.MPTK_SoundFont.ProgressCallback = (float progress) =>
    {
        SoundfontInProgress(progress, midiSynth);
    };
 
 
    // This callback will be triggered when the soundfont is ready.
    midiSynth.MPTK_SoundFont.LoadedCallback = (MidiSynth synth) =>
    {
        SoundfontIsReady(synth);
    };
 
    // Prepare switching between SoundFonts for each synths selected.
    // Here we load the SoundFont from the URI defined in the UI.
    // Set download options defined in the UI. 
    // -------------------------------------------------------------------
    midiSynth.MPTK_SoundFont.LoadFromCache = True;
    midiSynth.MPTK_SoundFont.SaveToCache = True;
    midiSynth.MPTK_SoundFont.DownloadOnly = False;
 
    bool result = midiSynth.MPTK_SoundFont.Load("https://mptkapi.paxstellar.com/GeneralUser-GS-v2.0.1.sf2");
    if (!result)
        Debug.Log($"TestLoadSF - Download canceled, status:{MidiPlayerGlobal.MPTK_StatusLastSoundFontLoaded} URI:{InputURLSoundFontAtRun.text}");
}

PresetName()

string MidiPlayerTK.MPTKSoundFont.PresetName

(

int

patch

)

Find a presets name with its preset number from the default bank.
The default bank can be changed with #MPTK_SelectBankInstrument or with the popup "SoundFont Setup Alt-F" in the Unity editor.

SelectBankDrum()

bool MidiPlayerTK.MPTKSoundFont.SelectBankDrum

(

int

bankNumber

)

This method change the default instrument drum bank and build the presets list associated. See ListPresetDrum.
Note 1: this call doesn't change the current MIDI bank used to play a drum, only the content of ListPresetDrum.
Note 2: to apply the bank to all channels, the synth must be restarted: call MidixxxPlayer.MPTK_InitSynth.
Note 3: to change the current bank, rather use MidiSynthPlayer.MPTK_ChannelPresetChange

Parameters

bankNumber

Number of the SoundFont Bank to load for drum.

Returns

true if bank has been found else false.

SelectBankInstrument()

bool MidiPlayerTK.MPTKSoundFont.SelectBankInstrument

(

int

bankNumber

)

This method change the default instrument drum bank and build the presets list associated. See ListPreset.
Note 1: this call doesn't change the current MIDI bank used to play an instrument, only the content of ListPreset.
Note 2: to apply the bank to all channels, the synth must be restarted: call MidiFilePlayer.MPTK_InitSynth.
Note 3: to change the current bank, rather use #MidiSynth.MPTK_ChannelPresetChange

Parameters

bankNumber

Number of the SoundFont Bank to load for instrument.

Returns

true if bank has been found else false.

Member Data Documentation

DownloadOnly

bool MidiPlayerTK.MPTKSoundFont.DownloadOnly

Interesting only for external soundfont. Whether to only download and save in cache the SoundFont in a local cache. Default is false. When true, the SoundFont is not loaded in the MidiSynth. Set SaveToCache to true to save the SoundFont in the local cache.
Set LoadFromCache to false to force the SoundFont download.
Could be useful to download a SoundFont in the background and load it later in many MidiSynths.

LoadedCallback

Action<MidiSynth> MidiPlayerTK.MPTKSoundFont.LoadedCallback = null

Define a callback when the SoundFont is loaded and ready to use.

// This callback will be triggered when the soundfont is ready.
midiSynth.MPTK_SoundFont.LoadedCallback = (MidiSynth synth) =>
{
    SoundfontIsReady(synth);
};

LoadFromCache

bool MidiPlayerTK.MPTKSoundFont.LoadFromCache

Whether to reuse previously downloaded SoundFonts if available. Default is true.
Folder: Application.persistentDataPath/"DownloadedSF"

ProgressCallback

Action<float> MidiPlayerTK.MPTKSoundFont.ProgressCallback = null

Call when download is in progress.

midiSynth.MPTK_SoundFont.ProgressCallback = (float progress) =>
{
      // Warning - this callback is not running inside the Unity thread.
      // It's not possible to use Unity API. So forget to directly update the UI.
      // One exception, Debug is authorized! But variable can be set and reuse in the Update() ... for example.
      // The progress percentage provided by Unity SendWebRequest seems not a percentage. So, I removed the % character ...
      Debug.Log($"<color=yellow>In Progress {midiSynth.name} {progress * 100:F0}</color>");
};

SaveToCache

bool MidiPlayerTK.MPTKSoundFont.SaveToCache

Whether to store the loaded SoundFont in a local cache. Default is true.
Folder: Application.persistentDataPath/"DownloadedSF"

Property Documentation

BanksName

List<string> MidiPlayerTK.MPTKSoundFont.BanksName

get

List of banks name available with the format "<number> - Bank". Unlike preset, there is no bank name defined in a Soundfont.
Index in the list is not the bank number, use the same index in BanksNumber to get the bank number.

BanksNumber

List<int> MidiPlayerTK.MPTKSoundFont.BanksNumber

get

List of banks number available. Use the same index in BanksName to get the bank name.

DefaultBank

int MidiPlayerTK.MPTKSoundFont.DefaultBank

getset

The default bank to use for instruments. Set to -1 to select the first bank.

DrumBank

int MidiPlayerTK.MPTKSoundFont.DrumBank

getset

The bank to use for the drum kit. Set to -1 to select the last bank.

IsDefault

bool MidiPlayerTK.MPTKSoundFont.IsDefault

get

True if the Soundfont is loaded from the MPTK resources (internal) and is the default (selected in "Soundfont Setup").

IsInternal

bool MidiPlayerTK.MPTKSoundFont.IsInternal

get

True if the Soundfont is loaded from the MPTK resources (internal).
False is the Soundfont is loaded from an external resources, local file or from an URL.

IsReady

bool MidiPlayerTK.MPTKSoundFont.IsReady

get

True if a Soundfont is available from internal or external.

ListBank

List<MPTKListItem> MidiPlayerTK.MPTKSoundFont.ListBank

getset

Get the list of banks available. It's a full list of 129 MPTKListItem elements with element null if a bank is missing.
MPTKListItem.Index give the number of the bank
Prefer using the BanksName to get a list of bank available and BanksNumber to get the number at same corresponding index.
The default bank can be changed with #MPTK_SelectBankInstrument or #MPTK_SelectBankDrum.

ListPreset

List<MPTKListItem> MidiPlayerTK.MPTKSoundFont.ListPreset

getset

List of presets (instrument) for the default or selected bank.
MPTKListItem.Index give the number of the preset
The default bank can be changed with #MPTK_SelectBankInstrument.

ListPresetDrum

List<MPTKListItem> MidiPlayerTK.MPTKSoundFont.ListPresetDrum

getset

List of drum preset for the default or selected bank.
MPTKListItem.Index give the number of the preset
The default bank can be changed with #MPTK_SelectBankDrum or with the menu "MPTK / SoundFont" or Alt-F in the Unity editor.

PresetsName

List<string> MidiPlayerTK.MPTKSoundFont.PresetsName

getset

List of preset name available with the format "<number> - <name>".
Index in the list is not the preset number, use the same index in PresetsNumber to get the preset number.

PresetsNumber

List<int> MidiPlayerTK.MPTKSoundFont.PresetsNumber

getset

List of preset number available. Use the same index in PresetsName to get the preset name.

ProgressValue

float MidiPlayerTK.MPTKSoundFont.ProgressValue

get

Provide a value for the progress of the download. Normalized between 0 and 1, should be a percentage but webRequest seems to provide a value not related to real percentage.

SoundFont

ImSoundFont MidiPlayerTK.MPTKSoundFont.SoundFont

get

When a Soundfont is ready, return an instance of #ImSoundfont else return null

SoundFontName

string MidiPlayerTK.MPTKSoundFont.SoundFontName

get

Name of Soundfont.

StatusSoundFont

LoadingStatusSoundFontEnum MidiPlayerTK.MPTKSoundFont.StatusSoundFont

get

Provide the status of the SoundFont loaded.

TimeToDownloadSoundFont

TimeSpan MidiPlayerTK.MPTKSoundFont.TimeToDownloadSoundFont

get

Time to download the SoundFont from a web resource or a local file.

TimeToLoadOverall

TimeSpan MidiPlayerTK.MPTKSoundFont.TimeToLoadOverall

get

Total time to load the SoundFont.

TimeToLoadSoundFont

TimeSpan MidiPlayerTK.MPTKSoundFont.TimeToLoadSoundFont

get

Time to load the SoundFont in MidiSynth prefab.

TimeToLoadWave

TimeSpan MidiPlayerTK.MPTKSoundFont.TimeToLoadWave

get

Time to loas samples in the MidiSynth.