JUCE: MidiMessageSequence Class Reference

JUCE

Classes | Public Member Functions | List of all members
MidiMessageSequence Class Reference

A sequence of timestamped midi messages. More...

## Classes
class | MidiEventHolder
| Structure used to hold midi events in the sequence. More...

## Public Member Functions
| MidiMessageSequence ()
| Creates an empty midi sequence object. More...
| MidiMessageSequence (const MidiMessageSequence &)
| Creates a copy of another sequence. More...
MidiMessageSequence & | operator= (const MidiMessageSequence &)
| Replaces this sequence with another one. More...
| MidiMessageSequence (MidiMessageSequence &&) noexcept
| Move constructor. More...
MidiMessageSequence & | operator= (MidiMessageSequence &&) noexcept
| Move assignment operator. More...
| ~MidiMessageSequence ()
| Destructor. More...
void | clear ()
| Clears the sequence. More...
int | getNumEvents () const noexcept
| Returns the number of events in the sequence. More...
MidiEventHolder * | getEventPointer (int index) const noexcept
| Returns a pointer to one of the events. More...
MidiEventHolder ** | begin () noexcept
| Iterator for the list of MidiEventHolders. More...
MidiEventHolder *const * | begin () const noexcept
| Iterator for the list of MidiEventHolders. More...
MidiEventHolder ** | end () noexcept
| Iterator for the list of MidiEventHolders. More...
MidiEventHolder *const * | end () const noexcept
| Iterator for the list of MidiEventHolders. More...
double | getTimeOfMatchingKeyUp (int index) const noexcept
| Returns the time of the note-up that matches the note-on at this index. More...
int | getIndexOfMatchingKeyUp (int index) const noexcept
| Returns the index of the note-up that matches the note-on at this index. More...
int | getIndexOf (const MidiEventHolder *event) const noexcept
| Returns the index of an event. More...
int | getNextIndexAtTime (double timeStamp) const noexcept
| Returns the index of the first event on or after the given timestamp. More...
double | getStartTime () const noexcept
| Returns the timestamp of the first event in the sequence. More...
double | getEndTime () const noexcept
| Returns the timestamp of the last event in the sequence. More...
double | getEventTime (int index) const noexcept
| Returns the timestamp of the event at a given index. More...
MidiEventHolder * | addEvent (const MidiMessage &newMessage, double timeAdjustment=0)
| Inserts a midi message into the sequence. More...
MidiEventHolder * | addEvent (MidiMessage &&newMessage, double timeAdjustment=0)
| Inserts a midi message into the sequence. More...
void | deleteEvent (int index, bool deleteMatchingNoteUp)
| Deletes one of the events in the sequence. More...
void | addSequence (const MidiMessageSequence &other, double timeAdjustmentDelta, double firstAllowableDestTime, double endOfAllowableDestTimes)
| Merges another sequence into this one. More...
void | addSequence (const MidiMessageSequence &other, double timeAdjustmentDelta)
| Merges another sequence into this one. More...
void | updateMatchedPairs () noexcept
| Makes sure all the note-on and note-off pairs are up-to-date. More...
void | sort () noexcept
| Forces a sort of the sequence. More...
void | extractMidiChannelMessages (int channelNumberToExtract, MidiMessageSequence &destSequence, bool alsoIncludeMetaEvents) const
| Copies all the messages for a particular midi channel to another sequence. More...
void | extractSysExMessages (MidiMessageSequence &destSequence) const
| Copies all midi sys-ex messages to another sequence. More...
void | deleteMidiChannelMessages (int channelNumberToRemove)
| Removes any messages in this sequence that have a specific midi channel. More...
void | deleteSysExMessages ()
| Removes any sys-ex messages from this sequence. More...
void | addTimeToMessages (double deltaTime) noexcept
| Adds an offset to the timestamps of all events in the sequence. More...
void | createControllerUpdatesForTime (int channelNumber, double time, Array< MidiMessage > &resultMessages)
| Scans through the sequence to determine the state of any midi controllers at a given time. More...
void | swapWith (MidiMessageSequence &) noexcept
| Swaps this sequence with another one. More...

## Detailed Description

A sequence of timestamped midi messages.

This allows the sequence to be manipulated, and also to be read from and written to a standard midi file.

See also
  MidiMessage, MidiFile

## Constructor & Destructor Documentation

## ◆ MidiMessageSequence() [1/3]

MidiMessageSequence::MidiMessageSequence | ( |  | ) |

Creates an empty midi sequence object.

## ◆ MidiMessageSequence() [2/3]

MidiMessageSequence::MidiMessageSequence | ( | const MidiMessageSequence & |  | ) |

Creates a copy of another sequence.

## ◆ MidiMessageSequence() [3/3]

MidiMessageSequence::MidiMessageSequence | ( | MidiMessageSequence && |  | ) |
| noexcept

Move constructor.

## ◆ ~MidiMessageSequence()

MidiMessageSequence::~MidiMessageSequence | ( |  | ) |

Destructor.

## Member Function Documentation

## ◆ operator=() [1/2]

MidiMessageSequence& MidiMessageSequence::operator= | ( | const MidiMessageSequence & |  | ) |

Replaces this sequence with another one.

## ◆ operator=() [2/2]

MidiMessageSequence& MidiMessageSequence::operator= | ( | MidiMessageSequence && |  | ) |
| noexcept

Move assignment operator.

## ◆ clear()

void MidiMessageSequence::clear | ( |  | ) |

Clears the sequence.

## ◆ getNumEvents()

int MidiMessageSequence::getNumEvents | ( |  | ) | const
| noexcept

Returns the number of events in the sequence.

## ◆ getEventPointer()

MidiEventHolder* MidiMessageSequence::getEventPointer | ( | int | index | ) | const
| noexcept

Returns a pointer to one of the events.

## ◆ begin() [1/2]

MidiEventHolder** MidiMessageSequence::begin | ( |  | ) |
| noexcept

Iterator for the list of MidiEventHolders.

## ◆ begin() [2/2]

MidiEventHolder* const* MidiMessageSequence::begin | ( |  | ) | const
| noexcept

Iterator for the list of MidiEventHolders.

## ◆ end() [1/2]

MidiEventHolder** MidiMessageSequence::end | ( |  | ) |
| noexcept

Iterator for the list of MidiEventHolders.

## ◆ end() [2/2]

MidiEventHolder* const* MidiMessageSequence::end | ( |  | ) | const
| noexcept

Iterator for the list of MidiEventHolders.

## ◆ getTimeOfMatchingKeyUp()

double MidiMessageSequence::getTimeOfMatchingKeyUp | ( | int | index | ) | const
| noexcept

Returns the time of the note-up that matches the note-on at this index.

If the event at this index isn't a note-on, it'll just return 0.

See also
  MidiMessageSequence::MidiEventHolder::noteOffObject

## ◆ getIndexOfMatchingKeyUp()

int MidiMessageSequence::getIndexOfMatchingKeyUp | ( | int | index | ) | const
| noexcept

Returns the index of the note-up that matches the note-on at this index.

If the event at this index isn't a note-on, it'll just return -1.

See also
  MidiMessageSequence::MidiEventHolder::noteOffObject

## ◆ getIndexOf()

int MidiMessageSequence::getIndexOf | ( | const MidiEventHolder * | event | ) | const
| noexcept

Returns the index of an event.

## ◆ getNextIndexAtTime()

int MidiMessageSequence::getNextIndexAtTime | ( | double | timeStamp | ) | const
| noexcept

Returns the index of the first event on or after the given timestamp.

If the time is beyond the end of the sequence, this will return the number of events.

## ◆ getStartTime()

double MidiMessageSequence::getStartTime | ( |  | ) | const
| noexcept

Returns the timestamp of the first event in the sequence.

See also
  getEndTime

## ◆ getEndTime()

double MidiMessageSequence::getEndTime | ( |  | ) | const
| noexcept

Returns the timestamp of the last event in the sequence.

See also
  getStartTime

## ◆ getEventTime()

double MidiMessageSequence::getEventTime | ( | int | index | ) | const
| noexcept

Returns the timestamp of the event at a given index.

If the index is out-of-range, this will return 0.0

## ◆ addEvent() [1/2]

MidiEventHolder* MidiMessageSequence::addEvent | ( | const MidiMessage & | newMessage,
|  | double | timeAdjustment = `0`
| ) |  |

Inserts a midi message into the sequence.

The index at which the new message gets inserted will depend on its timestamp, because the sequence is kept sorted.

Remember to call updateMatchedPairs() after adding note-on events.

Parameters

  newMessage | the new message to add (an internal copy will be made)
  timeAdjustment | an optional value to add to the timestamp of the message that will be inserted

See also
  updateMatchedPairs

## ◆ addEvent() [2/2]

MidiEventHolder* MidiMessageSequence::addEvent | ( | MidiMessage && | newMessage,
|  | double | timeAdjustment = `0`
| ) |  |

Inserts a midi message into the sequence.

The index at which the new message gets inserted will depend on its timestamp, because the sequence is kept sorted.

Remember to call updateMatchedPairs() after adding note-on events.

Parameters

  newMessage | the new message to add (an internal copy will be made)
  timeAdjustment | an optional value to add to the timestamp of the message that will be inserted

See also
  updateMatchedPairs

## ◆ deleteEvent()

void MidiMessageSequence::deleteEvent | ( | int | index,
|  | bool | deleteMatchingNoteUp
| ) |  |

Deletes one of the events in the sequence.

Remember to call updateMatchedPairs() after removing events.

Parameters

  index | the index of the event to delete
  deleteMatchingNoteUp | whether to also remove the matching note-off if the event you're removing is a note-on

## ◆ addSequence() [1/2]

void MidiMessageSequence::addSequence | ( | const MidiMessageSequence & | other,
|  | double | timeAdjustmentDelta,
|  | double | firstAllowableDestTime,
|  | double | endOfAllowableDestTimes
| ) |  |

Merges another sequence into this one.

Remember to call updateMatchedPairs() after using this method.

Parameters

  other | the sequence to add from
  timeAdjustmentDelta | an amount to add to the timestamps of the midi events as they are read from the other sequence
  firstAllowableDestTime | events will not be added if their time is earlier than this time. (This is after their time has been adjusted by the timeAdjustmentDelta)
  endOfAllowableDestTimes | events will not be added if their time is equal to or greater than this time. (This is after their time has been adjusted by the timeAdjustmentDelta)

## ◆ addSequence() [2/2]

void MidiMessageSequence::addSequence | ( | const MidiMessageSequence & | other,
|  | double | timeAdjustmentDelta
| ) |  |

Merges another sequence into this one.

Remember to call updateMatchedPairs() after using this method.

Parameters

  other | the sequence to add from
  timeAdjustmentDelta | an amount to add to the timestamps of the midi events as they are read from the other sequence

## ◆ updateMatchedPairs()

void MidiMessageSequence::updateMatchedPairs | ( |  | ) |
| noexcept

Makes sure all the note-on and note-off pairs are up-to-date.

Call this after re-ordering messages or deleting/adding messages, and it will scan the list and make sure all the note-offs in the MidiEventHolder structures are pointing at the correct ones.

## ◆ sort()

void MidiMessageSequence::sort | ( |  | ) |
| noexcept

Forces a sort of the sequence.

You may need to call this if you've manually modified the timestamps of some events such that the overall order now needs updating.

## ◆ extractMidiChannelMessages()

void MidiMessageSequence::extractMidiChannelMessages | ( | int | channelNumberToExtract,
|  | MidiMessageSequence & | destSequence,
|  | bool | alsoIncludeMetaEvents
| ) |  | const

Copies all the messages for a particular midi channel to another sequence.

Parameters

  channelNumberToExtract | the midi channel to look for, in the range 1 to 16
  destSequence | the sequence that the chosen events should be copied to
  alsoIncludeMetaEvents | if true, any meta-events (which don't apply to a specific channel) will also be copied across.

See also
  extractSysExMessages

## ◆ extractSysExMessages()

void MidiMessageSequence::extractSysExMessages | ( | MidiMessageSequence & | destSequence | ) | const

Copies all midi sys-ex messages to another sequence.

Parameters

  destSequence | this is the sequence to which any sys-exes in this sequence will be added

See also
  extractMidiChannelMessages

## ◆ deleteMidiChannelMessages()

void MidiMessageSequence::deleteMidiChannelMessages | ( | int | channelNumberToRemove | ) |

Removes any messages in this sequence that have a specific midi channel.

Parameters

  channelNumberToRemove | the midi channel to look for, in the range 1 to 16

## ◆ deleteSysExMessages()

void MidiMessageSequence::deleteSysExMessages | ( |  | ) |

Removes any sys-ex messages from this sequence.

## ◆ addTimeToMessages()

void MidiMessageSequence::addTimeToMessages | ( | double | deltaTime | ) |
| noexcept

Adds an offset to the timestamps of all events in the sequence.

Parameters

  deltaTime | the amount to add to each timestamp.

## ◆ createControllerUpdatesForTime()

void MidiMessageSequence::createControllerUpdatesForTime | ( | int | channelNumber,
|  | double | time,
|  | Array< MidiMessage > & | resultMessages
| ) |  |

Scans through the sequence to determine the state of any midi controllers at a given time.

This will create a sequence of midi controller changes that can be used to set all midi controllers to the state they would be in at the specified time within this sequence.

As well as controllers, it will also recreate the midi program number and pitch bend position.

Parameters

  channelNumber | the midi channel to look for, in the range 1 to 16. Controllers for other channels will be ignored.
  time | the time at which you want to find out the state - there are no explicit units for this time measurement, it's the same units as used for the timestamps of the messages
  resultMessages | an array to which midi controller-change messages will be added. This will be the minimum number of controller changes to recreate the state at the required time.

## ◆ swapWith()

void MidiMessageSequence::swapWith | ( | MidiMessageSequence & |  | ) |
| noexcept

Swaps this sequence with another one.

The documentation for this class was generated from the following file:

- juce_MidiMessageSequence.h