Version document 1.0 Dec, 03 2023 Maestro Midi Player Tool Kit API Changes
API Change V2.11.0 - December 1, 2023
 
  Main API Rules
- The classes starting with Midi (MidiFilePlayer, MidiSynth, )
- Inherit from Unity classes (generally MonoBehavior).
- Theirs members start with MPTK_ to differentiate them from Unity members.
- The classes starting with MPTK (MPTKWriter, MPTKEvent, MPTKChordBuilder )
- They are standalone, don't inherit from Unity classes.
- Their members name have no specific prefix.
       
  MidiFileLoader Deprecated, replaced by MidiFilePlayer
Channel API Change New class MPTKChannel and property MPTK_Channels in MidiFilePlayer, MidiStreamPlayer,
MPTKRangeLib Renamed to MPTKScaleLib
MidiStreamPlayer Impacted by MPTKRangeLib renaming to MPTKScaleLib
MPTKEvent Rename a few members
MidiFileWriter2 Renamed to MPTKWriter,
impacted also by MPTKRangeLib renaming to MPTKScaleLib
MPTKEffectSoundFont New class MPTKEffectSoundFont and property MPTK_EffectSoundFont
MPTKEffectUnity New class MPTKEffectUnity and property MPTK_EffectUnity
MPTKTempo Remove MPTK_ prefix behind members
MPTKSignature Remove MPTK_ prefix behind members
  MIDI File Loader API Change
MidiFileLoader prefab is deprecated, please use MidiFilePlayer prefab in place. Just replace MidiFileLoader prefab by MidiFilePlayer in your scene and replace MidiFileLoader class by MidiFilePlayer in your scripts.
Before:
MidiLoader MidiLoader;
Now:
MidiFilePlayer MidiLoader;
No change for using:
MidiLoader = FindObjectOfType<MidiFilePlayer>();
MidiLoader.MPTK_PlayOnStart = false;
MidiLoader.MPTK_DirectSendToPlayer = false; // No MIDI player
MidiLoader.MPTK_MidiIndex = midiindex;
MidiLoader.MPTK_Load();
foreach (MPTKEvent mptkEvent in MidiLoader.MPTK_MidiEvents)
Debug.Log(mptkEvent.ToString());
 
  Channel API Change
Channel properties was directly accessible from MidiFilePlayer or MidiStreamPlayer instance with the counterpart of heaviness API description.

Now the iterable class MPTK_Channels is available from MidiFilePlayer or MidiStreamPlayer instance and consolidate all properties and methods for managing channels.
New: class MPTKChannel and attributes MPTK_Channels visible from MidiFilePlayer, MidiStreamPLayer, ...

Before
: midiFilePlayer.MPTK_Channelxxxx(channel);
Now: midiFilePlayer.MPTK_Channels[channel].xxxx;

Migration is easy, your variable which hold the channel number becomes the index of the MPTK_Channels instance.

When olders methods are used, a warning message is displayed:
*** {older} is deprecated and will not works. Please investigate MPTK_Channels {newer} in place.

Error Management:
Before: midiFilePlayer.MPTK_Channelxxxx(channel) with a channel < 0 or >= Length didn't return an error but an empty string or a 0 integer.
Now: midiFilePlayer.MPTK_Channels[channel] with a channel < 0 or >= Length displays a log warning and return null which can cause other exception in your code.

Same for MidiStreamPlayer and MidiInReader instance.
Old Members New Members  
MPTK_ChannelEnableSet Enable midiFilePlayer.MPTK_Channels[channel].Enable = true;
MPTK_ChannelEnableGet
MPTK_ChannelNoteCount NoteCount  
MPTK_ChannelVolumeSet Volume
VolumeAll
midiFilePlayer.MPTK_Channels[channel].Volume
MPTK_ChannelVolumeGet
MPTK_ChannelPresetGetIndex PresetNum midiFilePlayer.MPTK_Channels[channel].PresetNum
MPTK_ChannelPresetChange
MPTK_ChannelBankGetIndex BankNum midiFilePlayer.MPTK_Channels[channel].banknum
MPTK_ChannelPresetChange
MPTK_ChannelPresetGetName PresetName midiFilePlayer.MPTK_Channels[channel].PresetName
MPTK_ChannelControllerGet Controller(MPTKController) midiStreamPlayer.MPTK_Channels[StreamChannel].Controller((int)MPTKController.Sustain
MPTK_ChannelCount Length Normally return 16. An experimental features could extends the number of channel.
midiFilePlayer.Channels.Length
MPTK_ChannelForcedPresetGet ForcedPreset
ForcedBank
Before
midiFilePlayer.MPTK_ChannelForcedPresetSet(channel, forcePreset, forceBank);
Now
// it is mandatory to force bank before forcing preset
midiFilePlayer.MPTK_Channels[channel].ForcedBank = forceBank;
midiFilePlayer.MPTK_Channels[channel].ForcedPreset = forcePreset;
MPTK_ChannelForcedPresetSet
MPTK_ResetChannel EnableResetChannel if (MPTK_Channels.EnableResetChannel)
MPTK_Channels.ResetExtension();
ResetMPTKChannels ResetExtension()
 
  MPTKRangeLib class renamed - Pro only
MPTKRangeLib has been renamed to MPTKScaleLib Unity package update is not able to delete existing file from a previous version. You can delete (not mandatory) these files in Assets\MidiPlayer\Scripts\MPTKGameObject\Pro:
MPTKRangeName.cs and MPTKRangeName.cs
Old Members New Members  
Range CreateScale MPTKScaleLib mptkScaleMajor;
mptkScaleMajor = MPTKScaleLib.CreateScale(MPTKScaleName.MajorMelodic, log: true);
  MidiStreamPlayer class changed - Pro only
  Change
Old Members New Members  
MPTK_RangeName MPTK_ScaleName  
MPTK_RangeSelected MPTK_ScaleSelected Become enum MPTKScaleName (was int)
MPTK_ScaleSelected = (MPTKScaleName)CurrentScale;
MPTK_PlayChordFromRange MPTK_PlayChordFromScale  
 
 
  MPTKEvent class
Cleaning  
Old Members New Members  
MPTK_<members> members Rule applied to all members with exception below.
MPTK_BPM2MPQN BeatPerMinute2QuarterPerMicroSecond  
MPTK_MPQN2BPM QuarterPerMicroSecond2BeatPerMinute  
DurationTicks Length  
     
       
  MidiFileWriter2 class changed - Pro only
  Renamed to MPTKWriter Rename MidiFileWriter2 class with MPTKWriter in your scripts.
Remove MPTK_ prefix from members.
Writing by specifying time removed (Milli). Use now ConvertMilliToTick (see bellow) and demo.
  Old Members New Members  
Rules MPTK_<members> members Rule applied to members: remove prefix MPTK_
but properties which use a MPTK instance (MPTK_MidiEvents, MPTK_LastEvent, MPTK_LastEvent) keep prefix MPTK_
MPTK_Add<feature>Milli Add<feature> Before:
midiFileWriter2.MPTK_AddChangePresetMilli(1, 1000, 1, patch);
midiFileWriter2.MPTK_AddChannelAfterTouchMilli(1, 1500, 1, patch, 500);
Now:
long tickFromTime = midiFileWriter.ConvertMilliToTick(1000);
midiFileWriter.AddChannelAfterTouch(1, tickFromTime, 1, patch);

tickFromTime = midiFileWriter.ConvertMilliToTick(1500);
int tickDuration = (int)midiFileWriter.DurationMilliToTick(500);
midiFileWriter.AddSilence(track, tickFromTime, channel, tickDuration);
Specific Change MPTK_AddChordFromRange AddChordFromScale  
Bpm CurrentTempo  
MPTK_Tempo CurrentTempo  
MPTK_GetMicrosecondsPerQuaterNote MptkEvent.BeatPerMinute2QuarterPerMicroSecond  
MPTK_BPM2MPQN MptkEvent.BeatPerMinute2QuarterPerMicroSecond  
MPTK_MPQN2BPM MptkEvent.QuarterPerMicroSecond2BeatPerMinute  
MPTK_Debug LogWriter  
MPTK_LoadFromMPTK ImportFromEventsList  
MPTK_NumberBeatsMeasure removed Deprecated, rather use members MPTK_SignMap with MPTK_CalculateTiming
CreateTrack removed From V2.9.0 tracks are automatically created when needed.
EndTrack removed From V2.9.0 tracks are automatically closed when needed.
  MPTKEffectSoundFont new class created from MidiSynth - Pro only
All effects properties was at the same level than MidiSynth class. That was a mess to retrieve information from the documentation.
So we created MPTKEffectSoundFont class by extraction of all properties and methods from MidiSynth and remove MPTK_ before members.
Before: midiFilePlayer.MPTK_SF<members>;
Now: midiFilePlayer.MPTK_EffectSoundFont.<members>;

It was also the time to bring more consistency to the member names. The list below includes only the modified names (members with MPTK_SF removed are not listed)

Migration is easy:
- Add MPTK_EffectSoundFont before
members_related_to_effect,
- Remove MPTK_SF from the members name.

Example: the members MPTK_SFReverbAmplify becomes ReverbAmplify

Old Members New Members  
MPTK_Sf<members> members Rule applied to all members with exception below.
MPTK_ApplySFFilter EnableFilter  
MPTK_ApplySFReverb EnableReverb  
MPTK_ApplySFChorus EnableChorus  
    DefaultAll New
  DefaultFilter
  DefaultReverb
  DefaultChorus
  MPTKEffectUnity new class created from MidiSynth - Pro only
All effects properties was at the same level than MidiSynth class. That was a mess to retrieve information from the documentation.
So we created MPTKEffectSoundFont class by extraction of all properties and methods from MidiSynth and remove MPTK_ before members.
Before: midiFilePlayer.MPTK_members;
Now: midiFilePlayer.MPTK_EffectUnity.members;

It was also the time to bring more consistency to the member names. The list below includes only the modified names (members with MPTK_ removed are not listed)

Migration is easy:
- Add MPTK_EffectUnity before
members,
- Remove MPTK_ from the members name.

Example: the members MPTK_ReverbDryLevel becomes ReverbDryLevel

Old Members New Members  
MPTK_members members Rule applied to all members with exception below.
MPTK_ApplyUnityReverb EnableReverb  
MPTK_ApplyUnityChorus EnableChorus  
  DefaultAll New
DefaultReverb
DefaultChorus
  MPTKTempo class
Cleaning  
Old Members New Members  
MPTK_<members> members Rule applied to all members with exception below.
Example: MPTK_FindSegment becomes FindSegment
  MPTKSignature class
Cleaning  
Old Members New Members  
MPTK_<members> members Rule applied to all members with exception below.
Example: MPTK_TickToMeasure becomes TickToMeasure