MidiPlayerTK.MPTKEvent

Represents a MIDI event used throughout MPTK. This class is central to script-based MIDI workflows in components such as MidiStreamPlayer, MidiFilePlayer, MidiFileLoader, and MPTKWriter. More...

Public Types
enum	EnumLength
	Musical note-length categories for note duration: Whole, Half, Quarter, Eighth, Sixteenth. See https://en.wikipedia.org/wiki/Note_value.

Event Type and Message Data
Core MIDI event identity and associated message data. This section defines what the event is (Command) and the data fields interpreted from that command (Controller, Meta, Info, Value). It is the primary model used by playback, serialization, and filtering logic.
MPTKCommand	Command
	MIDI command type for this event. See MPTKCommand (NoteOn, ControlChange, PatchChange, etc.).
MPTKController	Controller
	Controller code when Command is #MPTKCommand.ControlChange (for example modulation, pan, bank select). The associated controller value is stored in Value.
MPTKMeta	Meta
	Meta-event type when Command is #MPTKCommand.MetaEvent (for example Lyric, TimeSignature, SetTempo). Related meta message data is stored in other fields (such as Value or Info).
string	Info
	Text message data for meta events (for example TextEvent or Lyric).
int	Value
	Numeric message data whose meaning depends on Command.

Note Playback Attributes
Parameters used to play and shape notes. These members describe how a note should be rendered: channel routing, velocity, note duration, and optional start delay. They are mainly used when Command is NoteOn/NoteOff.
long	Track
	Track index of this event in the source MIDI file. Track 0 is the first track. This value is informational and does not affect playback behavior.
int	Channel
	MIDI channel from 0 to 15 (channel 9 is typically used for drums).
int	Velocity
	Note velocity (0 to 127) for #MPTKCommand.NoteOn and #MPTKCommand.NoteOff.
long	Duration
	Note duration in milliseconds when Command = #MPTKCommand.NoteOn. Set to -1 for an indefinitely sustained note (until explicit note-off).
long	Delay
	Delay in milliseconds before playing a note. Used only for #MPTKCommand.NoteOn and only in Core mode.
int	Length
	Duration in MIDI ticks when Command = #MPTKCommand.NoteOn.

Musical Position and Timing
Temporal position of the event in musical and real time. These values provide timeline context: tick-based position, measure/beat, index in the source stream, and real-time timing useful for diagnostics and synchronization.
long	Tick
	Event time in MIDI ticks (fraction of a beat) from the beginning of the MIDI file. This value is independent of tempo or playback speed. Not used by MidiStreamPlayer or MidiInReader (real-time sources).
int	Measure
	Measure (bar) where this event occurs. Computed from time-signature events when a MIDI file is loaded. By default the time signature is 4/4.
int	Beat
	Beat index inside the measure for this event. Present for all events, but musically most relevant for note events. Computed from time-signature events when a MIDI file is loaded. By default the time signature is 4/4.
int	Index
	Original index of this event in the loaded MIDI event list.
long	CreateTime
	UTC timestamp (DateTime ticks) captured when this event instance is created. Divide by 10,000 to convert to milliseconds. Replaces the former TickTime field.
float	RealTime
	Absolute event time in milliseconds from the start of the MIDI sequence. Accounts for tempo changes, but not for MidiFilePlayer.MPTK_Speed. Not used by MidiStreamPlayer or MidiInReader (real-time sources).
long	LatenceTime [get]
	Elapsed system time (DateTime.UtcNow.Ticks) since this event was created. Mainly useful for latency diagnostics. One DateTime tick equals 100 nanoseconds.
long	LatenceTimeMillis [get]
	Elapsed time in milliseconds since this event was created. Mainly useful for latency diagnostics.

Source and Runtime Context
Runtime metadata attached to the event during playback. Includes source/session identifiers, user tag, associated voices, and playback state (IsOver) for voice lifecycle tracking.
uint	Source
	Origin of the message. Contains MIDI input source ID for incoming MIDI events, otherwise 0.
int	IdSession
	Session identifier associated with this event. With MidiFilePlayer, this ID is unique per played MIDI session and is used by MPTK_ClearAllSound to stop only voices from that session when switching tracks. It can also be used in other components such as MidiStreamPlayer for custom grouping, but avoid overriding it while MidiFilePlayer manages playback.
object	Tag
	Free-form application tag associated with this event.
List< fluid_voice >	Voices
	Voices associated with a NoteOn event. Multiple voices can exist for one note (for example layered samples).
bool	IsOver [get]
	Indicates whether this event has finished playing (all associated voices are OFF).

Real-Time Generator Modifiers
Real-time SoundFont generator overrides at event level. These members and methods let you override generator values per event, both before note start and while voices are already playing. This enables expressive per-note timbre control in Maestro Pro. Per-generator modifiers associated with this event. Null when no modifier is defined. Version Maestro Pro
GenModifier[]	GensModifier
	list of synth modifier available.
bool	ModifySynthParameter (fluid_gen_type genType, float value, MPTKModeGeneratorChange mode)
	Applies a modification to a SoundFont generator value. The change can be applied per note before playback and in real time while the note is playing. Each generator has a specific value range, see the generator list here. The input value for this method is normalized (between 0 and 1). See here for more details. .
void	ClearSynthParameter ()
	Clears generator modifiers for this event and restores default SoundFont behavior.

Value Transposition
Utilities to transpose and restore note values safely. The original value is cached once, then reused so repeated calls apply transposition from the same base note instead of accumulating drift.
int	OriginalValue [get]
	Original (untransposed) value captured before calling TransposeValue.
void	TransposeValue (int transpose)
	Applies a transposition offset to Value. The first call stores the original value, then each call restores and reapplies the requested transpose amount from that original value.
void	ResetTransposeValue ()
	Restores Value to the original untransposed value if available.

Constructors, Clone and Message Conversion
Creation, duplication, and MIDI packed-message conversion. This section contains constructors for default and packed MIDI input, cloning support, and conversion to/from compact MIDI data representation.
	MPTKEvent ()
	Initializes a new MPTKEvent with default NoteOn-oriented values. Defaults:
virtual object	Clone ()
	Dupplicate MIDI message.
	MPTKEvent (ulong data)
	Creates an MPTKEvent from a packed MIDI input message.
ulong	ToData ()
	Builds a packed MIDI message from this MPTKEvent. Example: 0x00403C90 for NoteOn (90h), note 3Ch, velocity 40h.

Debug String Helpers
Human-readable formatting helpers for logs and diagnostics. Produces compact or detailed string representations of MPTKEvent to simplify debugging, tracing, and inspection during runtime.
override string	ToString ()
	Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.
string	ToStringBrief ()
	Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.
string	ConvertToString (bool brief)
	Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.

Generator Query Utilities
Read-only helpers for modifiable generator metadata and values. Provides access to default/current normalized generator values, generator labels, and the list of generators that support runtime changes.
float	GetSynthParameterDefaultValue (fluid_gen_type genType)
	Gets the default value for a SoundFont generator. Each generator has a specific value range, see the generator list here. The returned value is normalized (between 0 and 1).
float	GetSynthParameterCurrentValue (fluid_gen_type genType)
	Gets the current value for a generator on this event. Each generator has a specific value range, see the generator list here. The returned value is normalized (between 0 and 1).
static string	GetSynthParameterLabel (fluid_gen_type genType)
	Gets the display label for a generator.
static List< MPTKListItem >	GetSynthParameterListGenerator ()
	Gets the list of modifiable generators. Returns a list of MPTKListItem where:

Event Playback Control
Event-level playback actions for active notes. Contains direct control helpers such as StopEvent, which sends a matching NoteOff for this event when applicable.
void	StopEvent ()
	If this event is a NoteOn, sends the corresponding NoteOff event. This is equivalent to sending a note-off to the synth, so the sound enters its release phase. Has an effect only for NoteOn events.

Tempo and Byte Conversion Helpers
Static helpers for tempo conversion and byte packing. Utility methods convert BPM to microseconds-per-quarter-note (and reverse), and provide low-level byte extraction/packing used by meta event data.
static int	BeatPerMinute2QuarterPerMicroSecond (double bpm)
	Converts beats per minute (BPM) to microseconds per quarter note. Example: BPM=120 gives 500000 microseconds per quarter note.
static double	QuarterPerMicroSecond2BeatPerMinute (int microsecondsPerQuaterNote)
	Converts microseconds per quarter note to beats per minute (BPM). Example: 500000 microseconds per quarter note gives BPM=120.

Detailed Description

Represents a MIDI event used throughout MPTK. This class is central to script-based MIDI workflows in components such as MidiStreamPlayer, MidiFilePlayer, MidiFileLoader, and MPTKWriter.

The key property is Command. The meaning of other fields (for example Value) depends on the selected MIDI command type.

Typical use cases:

• play/stop notes,
• change instrument (patch/preset),
• send control changes,
• handle meta events.

Related components:

• MidiFileLoader: reads MIDI events from files,
• MidiFilePlayer: processes MIDI events from the internal sequencer,
• MPTKWriter: generates MIDI content programmatically,
• MidiStreamPlayer: plays MIDI events in real time.

More information:

• https://paxstellar.fr/class-mptkevent
• https://mptkapi.paxstellar.com/d9/d50/class_midi_player_t_k_1_1_m_p_t_k_event.html

Example with MidiStreamPlayer:

// Find a MidiStreamPlayer Prefab from the scene
MidiStreamPlayer midiStreamPlayer = FindFirstObjectByType<MidiStreamPlayer>();
midiStreamPlayer.MPTK_StartMidiStream();
 
// Change instrument to Marimba for channel 0
MPTKEvent PatchChange = new MPTKEvent() {
       Command = MPTKCommand.PatchChange,
       Value = 12, // usually Marimba, depending on the selected SoundFont
       Channel = 0 }; // Instruments are assigned per channel (0 to 15).
                      // At a given time, up to 16 channel instruments can be active.
midiStreamPlayer.MPTK_PlayEvent(PatchChange);    
 
// Play a C4 during one second with the Marimba instrument
MPTKEvent NotePlaying = new MPTKEvent() {
       Command = MPTKCommand.NoteOn,
       Value = 60, // C4
       Channel = 0,
       Duration = 1000, // one second
       Velocity = 100 };
midiStreamPlayer.MPTK_PlayEvent(NotePlaying);    

Constructor & Destructor Documentation

MPTKEvent() [1/2]

MidiPlayerTK.MPTKEvent.MPTKEvent

(

)

Initializes a new MPTKEvent with default NoteOn-oriented values. Defaults:

• Command = NoteOn
• Duration = -1 (infinite)
• Channel = 0
• Delay = 0
• Velocity = 127
• IdSession = -1

MPTKEvent() [2/2]

MidiPlayerTK.MPTKEvent.MPTKEvent

(

ulong

data

)

Creates an MPTKEvent from a packed MIDI input message.

Parameters

data	Packed MIDI message data.

Member Function Documentation

TransposeValue()

void MidiPlayerTK.MPTKEvent.TransposeValue

(

int

transpose

)

Applies a transposition offset to Value. The first call stores the original value, then each call restores and reapplies the requested transpose amount from that original value.

Parameters

transpose

Semitone offset to apply.

ToData()

ulong MidiPlayerTK.MPTKEvent.ToData

(

)

Builds a packed MIDI message from this MPTKEvent. Example: 0x00403C90 for NoteOn (90h), note 3Ch, velocity 40h.

Returns

Packed MIDI message as an unsigned 64-bit value.

BeatPerMinute2QuarterPerMicroSecond()

int MidiPlayerTK.MPTKEvent.BeatPerMinute2QuarterPerMicroSecond ( double bpm )

static

Converts beats per minute (BPM) to microseconds per quarter note. Example: BPM=120 gives 500000 microseconds per quarter note.

Parameters

bpm	Beats per minute (assuming one beat = quarter note).

Returns

60000000 / bpm, or 500000 when bpm <= 0.

QuarterPerMicroSecond2BeatPerMinute()

double MidiPlayerTK.MPTKEvent.QuarterPerMicroSecond2BeatPerMinute ( int microsecondsPerQuaterNote )

static

Converts microseconds per quarter note to beats per minute (BPM). Example: 500000 microseconds per quarter note gives BPM=120.

Parameters

microsecondsPerQuaterNote

Microseconds per quarter note.

Returns

60000000 / microsecondsPerQuaterNote, or 120 when input <= 0.

ToString()

override string MidiPlayerTK.MPTKEvent.ToString

(

)

Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.

Returns

Formatted event description.

ToStringBrief()

string MidiPlayerTK.MPTKEvent.ToStringBrief

(

)

Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.

Returns

Formatted event description.

ConvertToString()

string MidiPlayerTK.MPTKEvent.ConvertToString

(

bool

brief

)

Builds a string description of this MIDI event. Since v2.83, returned strings no longer contain trailing end-of-line markers. For improved alignment in Debug.Log, enable a monospace font in the Unity console settings.

Returns

Formatted event description.

ModifySynthParameter()

bool MidiPlayerTK.MPTKEvent.ModifySynthParameter	(	fluid_gen_type	genType,
		float	value,
		MPTKModeGeneratorChange	mode )

Applies a modification to a SoundFont generator value. The change can be applied per note before playback and in real time while the note is playing.
Each generator has a specific value range, see the generator list here.
The input value for this method is normalized (between 0 and 1). See here for more details.
.

Version

Maestro Pro

// Create a midi event for a C5 note (60) with default value: infinite duration, channel = 0, and velocity = 127 (max)
mptkEvent = new MPTKEvent() { Value = 60 };
 
// Fine tuning (pitch)
mptkEvent.ModifySynthParameter(fluid_gen_type.GEN_FINETUNE, 0.52f, MPTKModeGeneratorChange.Override);
 
// Change low pass filter frequency
mptkEvent.ModifySynthParameter(fluid_gen_type.GEN_FILTERFC, 0.6f, MPTKModeGeneratorChange.Override);
 
midiStream.MPTK_PlayDirectEvent(mptkEvent);

Parameters

genType	Type of generator to modify. Not all generators support real-time updates. GEN_MODLFOTOPITCH Modulation LFO to pitch GEN_VIBLFOTOPITCH Vibrato LFO to pitch GEN_MODENVTOPITCH Modulation envelope to pitch GEN_FILTERFC Filter cutoff GEN_FILTERQ Filter Q GEN_MODLFOTOFILTERFC Modulation LFO to filter cutoff GEN_MODENVTOFILTERFC Modulation envelope to filter cutoff GEN_MODLFOTOVOL Modulation LFO to volume GEN_CHORUSSEND Chorus send amount GEN_REVERBSEND Reverb send amount GEN_PAN Stereo panning GEN_MODLFODELAY Modulation LFO delay GEN_MODLFOFREQ Modulation LFO frequency GEN_VIBLFODELAY Vibrato LFO delay GEN_VIBLFOFREQ Vibrato LFO frequency GEN_MODENVDELAY Modulation envelope delay GEN_MODENVATTACK Modulation envelope attack GEN_MODENVHOLD Modulation envelope hold GEN_MODENVDECAY Modulation envelope decay GEN_MODENVSUSTAIN Modulation envelope sustain GEN_MODENVRELEASE Modulation envelope release GEN_VOLENVDELAY Volume envelope delay GEN_VOLENVATTACK Volume envelope attack GEN_VOLENVHOLD Volume envelope hold GEN_VOLENVDECAY Volume envelope decay GEN_VOLENVSUSTAIN Volume envelope sustain GEN_VOLENVRELEASE Volume envelope release GEN_ATTENUATION Volume attenuation GEN_COARSETUNE Coarse tuning GEN_FINETUNE Fine tuning
value	Normalized value for the generator between 0 and 1. See the actual value range for each parameter here. 0 sets the minimum value for the generator. For example, with an envelope parameter, 0 sets -12000 (minimum for this type of parameter). 1 sets the maximum value for the generator. For example, with an envelope parameter, 1 sets 12000 (maximum for this type of parameter).
mode	Defines how the value is applied. Override: replaces the SoundFont value. Reinforce: adds to the default value. Restore: uses the default SoundFont value.

Returns

True when the change is accepted and applied; otherwise false.

GetSynthParameterDefaultValue()

float MidiPlayerTK.MPTKEvent.GetSynthParameterDefaultValue

(

fluid_gen_type

genType

)

Gets the default value for a SoundFont generator.
Each generator has a specific value range, see the generator list here.
The returned value is normalized (between 0 and 1).

Version

Maestro Pro

Parameters

genType

Generator type. See ModifySynthParameter.

Returns

Normalized default value for the generator.

GetSynthParameterLabel()

string MidiPlayerTK.MPTKEvent.GetSynthParameterLabel ( fluid_gen_type genType )

static

Gets the display label for a generator.

Version

Maestro Pro

Parameters

genType

Generator type. See ModifySynthParameter.

Returns

Generator label, or "not found" if unavailable.

StopEvent()

void MidiPlayerTK.MPTKEvent.StopEvent

(

)

If this event is a NoteOn, sends the corresponding NoteOff event. This is equivalent to sending a note-off to the synth, so the sound enters its release phase. Has an effect only for NoteOn events.

Version

2.9.0 Pro

Member Data Documentation

Value

int MidiPlayerTK.MPTKEvent.Value

Numeric message data whose meaning depends on Command.

• Command = #MPTKCommand.NoteOn
  • Value contains the MIDI note number (Middle C is 60 / C4).
    See: http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html#BMA1_3
• Command = #MPTKCommand.ControlChange
  • Value contains controller value, see MPTKController
• Command = #MPTKCommand.PatchChange
  • Value contains patch/preset/instrument number.
    Use the active SoundFont to resolve instrument names.
    If your SoundFont follows the General MIDI (GM) map, the patch map is similar to:
    http://www.music.mcgill.ca/~ich/classes/mumt306/StandardMIDIfileformat.html#BMA1_4
    
• Command = #MPTKCommand.MetaEvent and Meta equal:
  • #MPTKMeta.SetTempo
    • Value contains microseconds per quarter note
  • #MPTKMeta.TimeSignature. See #MPTKMeta.TimeSignature
  • #MPTKMeta.KeySignature. See #MPTKMeta.KeySignature

Duration

long MidiPlayerTK.MPTKEvent.Duration

Note duration in milliseconds when Command = #MPTKCommand.NoteOn. Set to -1 for an indefinitely sustained note (until explicit note-off).

Version

2.10.0

Note

Previous non-note usages were removed:

• SetTempo no longer stores tempo in this field,
• TimeSignature no longer stores denominator in this field,
• KeySignature no longer stores major/minor flag in this field.

Length

int MidiPlayerTK.MPTKEvent.Length

Duration in MIDI ticks when Command = #MPTKCommand.NoteOn.

Tick duration is converted to milliseconds (Duration) when a MIDI file is loaded.

Note

Maestro playback uses Duration in milliseconds rather than this tick field. https://en.wikipedia.org/wiki/Note_value

Property Documentation

LatenceTime

long MidiPlayerTK.MPTKEvent.LatenceTime

get

Elapsed system time (DateTime.UtcNow.Ticks) since this event was created. Mainly useful for latency diagnostics. One DateTime tick equals 100 nanoseconds.

Note

Disabled by default. Define DEBUG_PERF_AUDIO in MidiSynth for debug-only use.

LatenceTimeMillis

long MidiPlayerTK.MPTKEvent.LatenceTimeMillis

get

Elapsed time in milliseconds since this event was created. Mainly useful for latency diagnostics.

Note

Disabled by default. Define DEBUG_PERF_AUDIO in MidiSynth for debug-only use.