OpenShot Library | OpenShotAudio  0.2.2
juce_MidiMessageSequence.h
1 
2 /** @weakgroup juce_audio_basics-midi
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  A sequence of timestamped midi messages.
33 
34  This allows the sequence to be manipulated, and also to be read from and
35  written to a standard midi file.
36 
37  @see MidiMessage, MidiFile
38 
39  @tags{Audio}
40 */
42 {
43 public:
44  //==============================================================================
45  /** Creates an empty midi sequence object. */
47 
48  /** Creates a copy of another sequence. */
50 
51  /** Replaces this sequence with another one. */
52  MidiMessageSequence& operator= (const MidiMessageSequence&);
53 
54  /** Move constructor */
56 
57  /** Move assignment operator */
58  MidiMessageSequence& operator= (MidiMessageSequence&&) noexcept;
59 
60  /** Destructor. */
62 
63  //==============================================================================
64  /** Structure used to hold midi events in the sequence.
65 
66  These structures act as 'handles' on the events as they are moved about in
67  the list, and make it quick to find the matching note-offs for note-on events.
68 
69  @see MidiMessageSequence::getEventPointer
70  */
72  {
73  public:
74  //==============================================================================
75  /** Destructor. */
76  ~MidiEventHolder();
77 
78  /** The message itself, whose timestamp is used to specify the event's time. */
80 
81  /** The matching note-off event (if this is a note-on event).
82 
83  If this isn't a note-on, this pointer will be nullptr.
84 
85  Use the MidiMessageSequence::updateMatchedPairs() method to keep these
86  note-offs up-to-date after events have been moved around in the sequence
87  or deleted.
88  */
89  MidiEventHolder* noteOffObject = nullptr;
90 
91  private:
92  //==============================================================================
93  friend class MidiMessageSequence;
96  JUCE_LEAK_DETECTOR (MidiEventHolder)
97  };
98 
99  //==============================================================================
100  /** Clears the sequence. */
101  void clear();
102 
103  /** Returns the number of events in the sequence. */
104  int getNumEvents() const noexcept;
105 
106  /** Returns a pointer to one of the events. */
107  MidiEventHolder* getEventPointer (int index) const noexcept;
108 
109  /** Iterator for the list of MidiEventHolders */
110  MidiEventHolder** begin() noexcept;
111 
112  /** Iterator for the list of MidiEventHolders */
113  MidiEventHolder* const* begin() const noexcept;
114 
115  /** Iterator for the list of MidiEventHolders */
116  MidiEventHolder** end() noexcept;
117 
118  /** Iterator for the list of MidiEventHolders */
119  MidiEventHolder* const* end() const noexcept;
120 
121  /** Returns the time of the note-up that matches the note-on at this index.
122  If the event at this index isn't a note-on, it'll just return 0.
123  @see MidiMessageSequence::MidiEventHolder::noteOffObject
124  */
125  double getTimeOfMatchingKeyUp (int index) const noexcept;
126 
127  /** Returns the index of the note-up that matches the note-on at this index.
128  If the event at this index isn't a note-on, it'll just return -1.
129  @see MidiMessageSequence::MidiEventHolder::noteOffObject
130  */
131  int getIndexOfMatchingKeyUp (int index) const noexcept;
132 
133  /** Returns the index of an event. */
134  int getIndexOf (const MidiEventHolder* event) const noexcept;
135 
136  /** Returns the index of the first event on or after the given timestamp.
137  If the time is beyond the end of the sequence, this will return the
138  number of events.
139  */
140  int getNextIndexAtTime (double timeStamp) const noexcept;
141 
142  //==============================================================================
143  /** Returns the timestamp of the first event in the sequence.
144  @see getEndTime
145  */
146  double getStartTime() const noexcept;
147 
148  /** Returns the timestamp of the last event in the sequence.
149  @see getStartTime
150  */
151  double getEndTime() const noexcept;
152 
153  /** Returns the timestamp of the event at a given index.
154  If the index is out-of-range, this will return 0.0
155  */
156  double getEventTime (int index) const noexcept;
157 
158  //==============================================================================
159  /** Inserts a midi message into the sequence.
160 
161  The index at which the new message gets inserted will depend on its timestamp,
162  because the sequence is kept sorted.
163 
164  Remember to call updateMatchedPairs() after adding note-on events.
165 
166  @param newMessage the new message to add (an internal copy will be made)
167  @param timeAdjustment an optional value to add to the timestamp of the message
168  that will be inserted
169  @see updateMatchedPairs
170  */
171  MidiEventHolder* addEvent (const MidiMessage& newMessage, double timeAdjustment = 0);
172 
173  /** Inserts a midi message into the sequence.
174 
175  The index at which the new message gets inserted will depend on its timestamp,
176  because the sequence is kept sorted.
177 
178  Remember to call updateMatchedPairs() after adding note-on events.
179 
180  @param newMessage the new message to add (an internal copy will be made)
181  @param timeAdjustment an optional value to add to the timestamp of the message
182  that will be inserted
183  @see updateMatchedPairs
184  */
185  MidiEventHolder* addEvent (MidiMessage&& newMessage, double timeAdjustment = 0);
186 
187  /** Deletes one of the events in the sequence.
188 
189  Remember to call updateMatchedPairs() after removing events.
190 
191  @param index the index of the event to delete
192  @param deleteMatchingNoteUp whether to also remove the matching note-off
193  if the event you're removing is a note-on
194  */
195  void deleteEvent (int index, bool deleteMatchingNoteUp);
196 
197  /** Merges another sequence into this one.
198  Remember to call updateMatchedPairs() after using this method.
199 
200  @param other the sequence to add from
201  @param timeAdjustmentDelta an amount to add to the timestamps of the midi events
202  as they are read from the other sequence
203  @param firstAllowableDestTime events will not be added if their time is earlier
204  than this time. (This is after their time has been adjusted
205  by the timeAdjustmentDelta)
206  @param endOfAllowableDestTimes events will not be added if their time is equal to
207  or greater than this time. (This is after their time has
208  been adjusted by the timeAdjustmentDelta)
209  */
210  void addSequence (const MidiMessageSequence& other,
211  double timeAdjustmentDelta,
212  double firstAllowableDestTime,
213  double endOfAllowableDestTimes);
214 
215  /** Merges another sequence into this one.
216  Remember to call updateMatchedPairs() after using this method.
217 
218  @param other the sequence to add from
219  @param timeAdjustmentDelta an amount to add to the timestamps of the midi events
220  as they are read from the other sequence
221  */
222  void addSequence (const MidiMessageSequence& other,
223  double timeAdjustmentDelta);
224 
225  //==============================================================================
226  /** Makes sure all the note-on and note-off pairs are up-to-date.
227 
228  Call this after re-ordering messages or deleting/adding messages, and it
229  will scan the list and make sure all the note-offs in the MidiEventHolder
230  structures are pointing at the correct ones.
231  */
232  void updateMatchedPairs() noexcept;
233 
234  /** Forces a sort of the sequence.
235  You may need to call this if you've manually modified the timestamps of some
236  events such that the overall order now needs updating.
237  */
238  void sort() noexcept;
239 
240  //==============================================================================
241  /** Copies all the messages for a particular midi channel to another sequence.
242 
243  @param channelNumberToExtract the midi channel to look for, in the range 1 to 16
244  @param destSequence the sequence that the chosen events should be copied to
245  @param alsoIncludeMetaEvents if true, any meta-events (which don't apply to a specific
246  channel) will also be copied across.
247  @see extractSysExMessages
248  */
249  void extractMidiChannelMessages (int channelNumberToExtract,
250  MidiMessageSequence& destSequence,
251  bool alsoIncludeMetaEvents) const;
252 
253  /** Copies all midi sys-ex messages to another sequence.
254  @param destSequence this is the sequence to which any sys-exes in this sequence
255  will be added
256  @see extractMidiChannelMessages
257  */
258  void extractSysExMessages (MidiMessageSequence& destSequence) const;
259 
260  /** Removes any messages in this sequence that have a specific midi channel.
261  @param channelNumberToRemove the midi channel to look for, in the range 1 to 16
262  */
263  void deleteMidiChannelMessages (int channelNumberToRemove);
264 
265  /** Removes any sys-ex messages from this sequence. */
266  void deleteSysExMessages();
267 
268  /** Adds an offset to the timestamps of all events in the sequence.
269  @param deltaTime the amount to add to each timestamp.
270  */
271  void addTimeToMessages (double deltaTime) noexcept;
272 
273  //==============================================================================
274  /** Scans through the sequence to determine the state of any midi controllers at
275  a given time.
276 
277  This will create a sequence of midi controller changes that can be
278  used to set all midi controllers to the state they would be in at the
279  specified time within this sequence.
280 
281  As well as controllers, it will also recreate the midi program number
282  and pitch bend position.
283 
284  @param channelNumber the midi channel to look for, in the range 1 to 16. Controllers
285  for other channels will be ignored.
286  @param time the time at which you want to find out the state - there are
287  no explicit units for this time measurement, it's the same units
288  as used for the timestamps of the messages
289  @param resultMessages an array to which midi controller-change messages will be added. This
290  will be the minimum number of controller changes to recreate the
291  state at the required time.
292  */
293  void createControllerUpdatesForTime (int channelNumber, double time,
294  Array<MidiMessage>& resultMessages);
295 
296  //==============================================================================
297  /** Swaps this sequence with another one. */
298  void swapWith (MidiMessageSequence&) noexcept;
299 
300 private:
301  //==============================================================================
302  friend class MidiFile;
304 
305  MidiEventHolder* addEvent (MidiEventHolder*, double);
306 
307  JUCE_LEAK_DETECTOR (MidiMessageSequence)
308 };
309 
310 } // namespace juce
311 
312 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Reads/writes standard midi format files.
Definition: juce_MidiFile.h:45
Encapsulates a MIDI message.
MidiMessage message
The message itself, whose timestamp is used to specify the event&#39;s time.
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
A sequence of timestamped midi messages.
Structure used to hold midi events in the sequence.
An array designed for holding objects.