Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

MidiMessage.h 36KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910
  1. /*
  2. ==============================================================================
  3. This file is part of the Water library.
  4. Copyright (c) 2016 ROLI Ltd.
  5. Copyright (C) 2017 Filipe Coelho <falktx@falktx.com>
  6. Permission is granted to use this software under the terms of the ISC license
  7. http://www.isc.org/downloads/software-support-policy/isc-license/
  8. Permission to use, copy, modify, and/or distribute this software for any
  9. purpose with or without fee is hereby granted, provided that the above
  10. copyright notice and this permission notice appear in all copies.
  11. THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  12. TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  13. FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  14. OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  15. USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16. TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  17. OF THIS SOFTWARE.
  18. ==============================================================================
  19. */
  20. #ifndef WATER_MIDIMESSAGE_H_INCLUDED
  21. #define WATER_MIDIMESSAGE_H_INCLUDED
  22. #include "../water.h"
  23. namespace water {
  24. //==============================================================================
  25. /**
  26. Encapsulates a MIDI message.
  27. @see MidiMessageSequence, MidiOutput, MidiInput
  28. */
  29. class MidiMessage
  30. {
  31. public:
  32. //==============================================================================
  33. /** Creates a 3-byte short midi message.
  34. @param byte1 message byte 1
  35. @param byte2 message byte 2
  36. @param byte3 message byte 3
  37. @param timeStamp the time to give the midi message - this value doesn't
  38. use any particular units, so will be application-specific
  39. */
  40. MidiMessage (int byte1, int byte2, int byte3, double timeStamp = 0) noexcept;
  41. /** Creates a 2-byte short midi message.
  42. @param byte1 message byte 1
  43. @param byte2 message byte 2
  44. @param timeStamp the time to give the midi message - this value doesn't
  45. use any particular units, so will be application-specific
  46. */
  47. MidiMessage (int byte1, int byte2, double timeStamp = 0) noexcept;
  48. /** Creates a 1-byte short midi message.
  49. @param byte1 message byte 1
  50. @param timeStamp the time to give the midi message - this value doesn't
  51. use any particular units, so will be application-specific
  52. */
  53. MidiMessage (int byte1, double timeStamp = 0) noexcept;
  54. /** Creates a midi message from a block of data. */
  55. MidiMessage (const void* data, int numBytes, double timeStamp = 0);
  56. /** Reads the next midi message from some data.
  57. This will read as many bytes from a data stream as it needs to make a
  58. complete message, and will return the number of bytes it used. This lets
  59. you read a sequence of midi messages from a file or stream.
  60. @param data the data to read from
  61. @param maxBytesToUse the maximum number of bytes it's allowed to read
  62. @param numBytesUsed returns the number of bytes that were actually needed
  63. @param lastStatusByte in a sequence of midi messages, the initial byte
  64. can be dropped from a message if it's the same as the
  65. first byte of the previous message, so this lets you
  66. supply the byte to use if the first byte of the message
  67. has in fact been dropped.
  68. @param timeStamp the time to give the midi message - this value doesn't
  69. use any particular units, so will be application-specific
  70. @param sysexHasEmbeddedLength when reading sysexes, this flag indicates whether
  71. to expect the data to begin with a variable-length field
  72. indicating its size
  73. */
  74. MidiMessage (const void* data, int maxBytesToUse,
  75. int& numBytesUsed, uint8 lastStatusByte,
  76. double timeStamp = 0,
  77. bool sysexHasEmbeddedLength = true);
  78. /** Creates an active-sense message.
  79. Since the MidiMessage has to contain a valid message, this default constructor
  80. just initialises it with an empty sysex message.
  81. */
  82. MidiMessage() noexcept;
  83. /** Creates a copy of another midi message. */
  84. MidiMessage (const MidiMessage&);
  85. /** Creates a copy of another midi message, with a different timestamp. */
  86. MidiMessage (const MidiMessage&, double newTimeStamp);
  87. /** Destructor. */
  88. ~MidiMessage() noexcept;
  89. /** Copies this message from another one. */
  90. MidiMessage& operator= (const MidiMessage& other);
  91. #if WATER_COMPILER_SUPPORTS_MOVE_SEMANTICS
  92. MidiMessage (MidiMessage&&) noexcept;
  93. MidiMessage& operator= (MidiMessage&&) noexcept;
  94. #endif
  95. //==============================================================================
  96. /** Returns a pointer to the raw midi data.
  97. @see getRawDataSize
  98. */
  99. const uint8* getRawData() const noexcept { return getData(); }
  100. /** Returns the number of bytes of data in the message.
  101. @see getRawData
  102. */
  103. int getRawDataSize() const noexcept { return size; }
  104. //==============================================================================
  105. /** Returns the timestamp associated with this message.
  106. The exact meaning of this time and its units will vary, as messages are used in
  107. a variety of different contexts.
  108. If you're getting the message from a midi file, this could be a time in seconds, or
  109. a number of ticks - see MidiFile::convertTimestampTicksToSeconds().
  110. If the message is being used in a MidiBuffer, it might indicate the number of
  111. audio samples from the start of the buffer.
  112. If the message was created by a MidiInput, see MidiInputCallback::handleIncomingMidiMessage()
  113. for details of the way that it initialises this value.
  114. @see setTimeStamp, addToTimeStamp
  115. */
  116. double getTimeStamp() const noexcept { return timeStamp; }
  117. /** Changes the message's associated timestamp.
  118. The units for the timestamp will be application-specific - see the notes for getTimeStamp().
  119. @see addToTimeStamp, getTimeStamp
  120. */
  121. void setTimeStamp (double newTimestamp) noexcept { timeStamp = newTimestamp; }
  122. /** Adds a value to the message's timestamp.
  123. The units for the timestamp will be application-specific.
  124. */
  125. void addToTimeStamp (double delta) noexcept { timeStamp += delta; }
  126. //==============================================================================
  127. /** Returns the midi channel associated with the message.
  128. @returns a value 1 to 16 if the message has a channel, or 0 if it hasn't (e.g.
  129. if it's a sysex)
  130. @see isForChannel, setChannel
  131. */
  132. int getChannel() const noexcept;
  133. /** Returns true if the message applies to the given midi channel.
  134. @param channelNumber the channel number to look for, in the range 1 to 16
  135. @see getChannel, setChannel
  136. */
  137. bool isForChannel (int channelNumber) const noexcept;
  138. /** Changes the message's midi channel.
  139. This won't do anything for non-channel messages like sysexes.
  140. @param newChannelNumber the channel number to change it to, in the range 1 to 16
  141. */
  142. void setChannel (int newChannelNumber) noexcept;
  143. //==============================================================================
  144. /** Returns true if this is a system-exclusive message.
  145. */
  146. bool isSysEx() const noexcept;
  147. /** Returns a pointer to the sysex data inside the message.
  148. If this event isn't a sysex event, it'll return 0.
  149. @see getSysExDataSize
  150. */
  151. const uint8* getSysExData() const noexcept;
  152. /** Returns the size of the sysex data.
  153. This value excludes the 0xf0 header byte and the 0xf7 at the end.
  154. @see getSysExData
  155. */
  156. int getSysExDataSize() const noexcept;
  157. //==============================================================================
  158. /** Returns true if this message is a 'key-down' event.
  159. @param returnTrueForVelocity0 if true, then if this event is a note-on with
  160. velocity 0, it will still be considered to be a note-on and the
  161. method will return true. If returnTrueForVelocity0 is false, then
  162. if this is a note-on event with velocity 0, it'll be regarded as
  163. a note-off, and the method will return false
  164. @see isNoteOff, getNoteNumber, getVelocity, noteOn
  165. */
  166. bool isNoteOn (bool returnTrueForVelocity0 = false) const noexcept;
  167. /** Creates a key-down message (using a floating-point velocity).
  168. @param channel the midi channel, in the range 1 to 16
  169. @param noteNumber the key number, 0 to 127
  170. @param velocity in the range 0 to 1.0
  171. @see isNoteOn
  172. */
  173. static MidiMessage noteOn (int channel, int noteNumber, float velocity) noexcept;
  174. /** Creates a key-down message (using an integer velocity).
  175. @param channel the midi channel, in the range 1 to 16
  176. @param noteNumber the key number, 0 to 127
  177. @param velocity in the range 0 to 127
  178. @see isNoteOn
  179. */
  180. static MidiMessage noteOn (int channel, int noteNumber, uint8 velocity) noexcept;
  181. /** Returns true if this message is a 'key-up' event.
  182. If returnTrueForNoteOnVelocity0 is true, then his will also return true
  183. for a note-on event with a velocity of 0.
  184. @see isNoteOn, getNoteNumber, getVelocity, noteOff
  185. */
  186. bool isNoteOff (bool returnTrueForNoteOnVelocity0 = true) const noexcept;
  187. /** Creates a key-up message.
  188. @param channel the midi channel, in the range 1 to 16
  189. @param noteNumber the key number, 0 to 127
  190. @param velocity in the range 0 to 1.0
  191. @see isNoteOff
  192. */
  193. static MidiMessage noteOff (int channel, int noteNumber, float velocity) noexcept;
  194. /** Creates a key-up message.
  195. @param channel the midi channel, in the range 1 to 16
  196. @param noteNumber the key number, 0 to 127
  197. @param velocity in the range 0 to 127
  198. @see isNoteOff
  199. */
  200. static MidiMessage noteOff (int channel, int noteNumber, uint8 velocity) noexcept;
  201. /** Creates a key-up message.
  202. @param channel the midi channel, in the range 1 to 16
  203. @param noteNumber the key number, 0 to 127
  204. @see isNoteOff
  205. */
  206. static MidiMessage noteOff (int channel, int noteNumber) noexcept;
  207. /** Returns true if this message is a 'key-down' or 'key-up' event.
  208. @see isNoteOn, isNoteOff
  209. */
  210. bool isNoteOnOrOff() const noexcept;
  211. /** Returns the midi note number for note-on and note-off messages.
  212. If the message isn't a note-on or off, the value returned is undefined.
  213. @see isNoteOff, getMidiNoteName, getMidiNoteInHertz, setNoteNumber
  214. */
  215. int getNoteNumber() const noexcept;
  216. /** Changes the midi note number of a note-on or note-off message.
  217. If the message isn't a note on or off, this will do nothing.
  218. */
  219. void setNoteNumber (int newNoteNumber) noexcept;
  220. //==============================================================================
  221. /** Returns the velocity of a note-on or note-off message.
  222. The value returned will be in the range 0 to 127.
  223. If the message isn't a note-on or off event, it will return 0.
  224. @see getFloatVelocity
  225. */
  226. uint8 getVelocity() const noexcept;
  227. /** Returns the velocity of a note-on or note-off message.
  228. The value returned will be in the range 0 to 1.0
  229. If the message isn't a note-on or off event, it will return 0.
  230. @see getVelocity, setVelocity
  231. */
  232. float getFloatVelocity() const noexcept;
  233. /** Changes the velocity of a note-on or note-off message.
  234. If the message isn't a note on or off, this will do nothing.
  235. @param newVelocity the new velocity, in the range 0 to 1.0
  236. @see getFloatVelocity, multiplyVelocity
  237. */
  238. void setVelocity (float newVelocity) noexcept;
  239. /** Multiplies the velocity of a note-on or note-off message by a given amount.
  240. If the message isn't a note on or off, this will do nothing.
  241. @param scaleFactor the value by which to multiply the velocity
  242. @see setVelocity
  243. */
  244. void multiplyVelocity (float scaleFactor) noexcept;
  245. //==============================================================================
  246. /** Returns true if this message is a 'sustain pedal down' controller message. */
  247. bool isSustainPedalOn() const noexcept;
  248. /** Returns true if this message is a 'sustain pedal up' controller message. */
  249. bool isSustainPedalOff() const noexcept;
  250. /** Returns true if this message is a 'sostenuto pedal down' controller message. */
  251. bool isSostenutoPedalOn() const noexcept;
  252. /** Returns true if this message is a 'sostenuto pedal up' controller message. */
  253. bool isSostenutoPedalOff() const noexcept;
  254. /** Returns true if this message is a 'soft pedal down' controller message. */
  255. bool isSoftPedalOn() const noexcept;
  256. /** Returns true if this message is a 'soft pedal up' controller message. */
  257. bool isSoftPedalOff() const noexcept;
  258. //==============================================================================
  259. /** Returns true if the message is a program (patch) change message.
  260. @see getProgramChangeNumber
  261. */
  262. bool isProgramChange() const noexcept;
  263. /** Returns the new program number of a program change message.
  264. If the message isn't a program change, the value returned is undefined.
  265. @see isProgramChange
  266. */
  267. int getProgramChangeNumber() const noexcept;
  268. /** Creates a program-change message.
  269. @param channel the midi channel, in the range 1 to 16
  270. @param programNumber the midi program number, 0 to 127
  271. @see isProgramChange
  272. */
  273. static MidiMessage programChange (int channel, int programNumber) noexcept;
  274. //==============================================================================
  275. /** Returns true if the message is a pitch-wheel move.
  276. @see getPitchWheelValue, pitchWheel
  277. */
  278. bool isPitchWheel() const noexcept;
  279. /** Returns the pitch wheel position from a pitch-wheel move message.
  280. The value returned is a 14-bit number from 0 to 0x3fff, indicating the wheel position.
  281. If called for messages which aren't pitch wheel events, the number returned will be
  282. nonsense.
  283. @see isPitchWheel
  284. */
  285. int getPitchWheelValue() const noexcept;
  286. /** Creates a pitch-wheel move message.
  287. @param channel the midi channel, in the range 1 to 16
  288. @param position the wheel position, in the range 0 to 16383
  289. @see isPitchWheel
  290. */
  291. static MidiMessage pitchWheel (int channel, int position) noexcept;
  292. //==============================================================================
  293. /** Returns true if the message is an aftertouch event.
  294. For aftertouch events, use the getNoteNumber() method to find out the key
  295. that it applies to, and getAftertouchValue() to find out the amount. Use
  296. getChannel() to find out the channel.
  297. @see getAftertouchValue, getNoteNumber
  298. */
  299. bool isAftertouch() const noexcept;
  300. /** Returns the amount of aftertouch from an aftertouch messages.
  301. The value returned is in the range 0 to 127, and will be nonsense for messages
  302. other than aftertouch messages.
  303. @see isAftertouch
  304. */
  305. int getAfterTouchValue() const noexcept;
  306. /** Creates an aftertouch message.
  307. @param channel the midi channel, in the range 1 to 16
  308. @param noteNumber the key number, 0 to 127
  309. @param aftertouchAmount the amount of aftertouch, 0 to 127
  310. @see isAftertouch
  311. */
  312. static MidiMessage aftertouchChange (int channel,
  313. int noteNumber,
  314. int aftertouchAmount) noexcept;
  315. /** Returns true if the message is a channel-pressure change event.
  316. This is like aftertouch, but common to the whole channel rather than a specific
  317. note. Use getChannelPressureValue() to find out the pressure, and getChannel()
  318. to find out the channel.
  319. @see channelPressureChange
  320. */
  321. bool isChannelPressure() const noexcept;
  322. /** Returns the pressure from a channel pressure change message.
  323. @returns the pressure, in the range 0 to 127
  324. @see isChannelPressure, channelPressureChange
  325. */
  326. int getChannelPressureValue() const noexcept;
  327. /** Creates a channel-pressure change event.
  328. @param channel the midi channel: 1 to 16
  329. @param pressure the pressure, 0 to 127
  330. @see isChannelPressure
  331. */
  332. static MidiMessage channelPressureChange (int channel, int pressure) noexcept;
  333. //==============================================================================
  334. /** Returns true if this is a midi controller message.
  335. @see getControllerNumber, getControllerValue, controllerEvent
  336. */
  337. bool isController() const noexcept;
  338. /** Returns the controller number of a controller message.
  339. The name of the controller can be looked up using the getControllerName() method.
  340. Note that the value returned is invalid for messages that aren't controller changes.
  341. @see isController, getControllerName, getControllerValue
  342. */
  343. int getControllerNumber() const noexcept;
  344. /** Returns the controller value from a controller message.
  345. A value 0 to 127 is returned to indicate the new controller position.
  346. Note that the value returned is invalid for messages that aren't controller changes.
  347. @see isController, getControllerNumber
  348. */
  349. int getControllerValue() const noexcept;
  350. /** Returns true if this message is a controller message and if it has the specified
  351. controller type.
  352. */
  353. bool isControllerOfType (int controllerType) const noexcept;
  354. /** Creates a controller message.
  355. @param channel the midi channel, in the range 1 to 16
  356. @param controllerType the type of controller
  357. @param value the controller value
  358. @see isController
  359. */
  360. static MidiMessage controllerEvent (int channel,
  361. int controllerType,
  362. int value) noexcept;
  363. /** Checks whether this message is an all-notes-off message.
  364. @see allNotesOff
  365. */
  366. bool isAllNotesOff() const noexcept;
  367. /** Checks whether this message is an all-sound-off message.
  368. @see allSoundOff
  369. */
  370. bool isAllSoundOff() const noexcept;
  371. /** Creates an all-notes-off message.
  372. @param channel the midi channel, in the range 1 to 16
  373. @see isAllNotesOff
  374. */
  375. static MidiMessage allNotesOff (int channel) noexcept;
  376. /** Creates an all-sound-off message.
  377. @param channel the midi channel, in the range 1 to 16
  378. @see isAllSoundOff
  379. */
  380. static MidiMessage allSoundOff (int channel) noexcept;
  381. /** Creates an all-controllers-off message.
  382. @param channel the midi channel, in the range 1 to 16
  383. */
  384. static MidiMessage allControllersOff (int channel) noexcept;
  385. //==============================================================================
  386. /** Returns true if this event is a meta-event.
  387. Meta-events are things like tempo changes, track names, etc.
  388. @see getMetaEventType, isTrackMetaEvent, isEndOfTrackMetaEvent,
  389. isTextMetaEvent, isTrackNameEvent, isTempoMetaEvent, isTimeSignatureMetaEvent,
  390. isKeySignatureMetaEvent, isMidiChannelMetaEvent
  391. */
  392. bool isMetaEvent() const noexcept;
  393. /** Returns a meta-event's type number.
  394. If the message isn't a meta-event, this will return -1.
  395. @see isMetaEvent, isTrackMetaEvent, isEndOfTrackMetaEvent,
  396. isTextMetaEvent, isTrackNameEvent, isTempoMetaEvent, isTimeSignatureMetaEvent,
  397. isKeySignatureMetaEvent, isMidiChannelMetaEvent
  398. */
  399. int getMetaEventType() const noexcept;
  400. /** Returns a pointer to the data in a meta-event.
  401. @see isMetaEvent, getMetaEventLength
  402. */
  403. const uint8* getMetaEventData() const noexcept;
  404. /** Returns the length of the data for a meta-event.
  405. @see isMetaEvent, getMetaEventData
  406. */
  407. int getMetaEventLength() const noexcept;
  408. //==============================================================================
  409. /** Returns true if this is a 'track' meta-event. */
  410. bool isTrackMetaEvent() const noexcept;
  411. /** Returns true if this is an 'end-of-track' meta-event. */
  412. bool isEndOfTrackMetaEvent() const noexcept;
  413. /** Creates an end-of-track meta-event.
  414. @see isEndOfTrackMetaEvent
  415. */
  416. static MidiMessage endOfTrack() noexcept;
  417. /** Returns true if this is an 'track name' meta-event.
  418. You can use the getTextFromTextMetaEvent() method to get the track's name.
  419. */
  420. bool isTrackNameEvent() const noexcept;
  421. /** Returns true if this is a 'text' meta-event.
  422. @see getTextFromTextMetaEvent
  423. */
  424. bool isTextMetaEvent() const noexcept;
  425. /** Returns the text from a text meta-event.
  426. @see isTextMetaEvent
  427. */
  428. String getTextFromTextMetaEvent() const;
  429. /** Creates a text meta-event. */
  430. static MidiMessage textMetaEvent (int type, StringRef text);
  431. //==============================================================================
  432. /** Returns true if this is a 'tempo' meta-event.
  433. @see getTempoMetaEventTickLength, getTempoSecondsPerQuarterNote
  434. */
  435. bool isTempoMetaEvent() const noexcept;
  436. /** Returns the tick length from a tempo meta-event.
  437. @param timeFormat the 16-bit time format value from the midi file's header.
  438. @returns the tick length (in seconds).
  439. @see isTempoMetaEvent
  440. */
  441. double getTempoMetaEventTickLength (short timeFormat) const noexcept;
  442. /** Calculates the seconds-per-quarter-note from a tempo meta-event.
  443. @see isTempoMetaEvent, getTempoMetaEventTickLength
  444. */
  445. double getTempoSecondsPerQuarterNote() const noexcept;
  446. /** Creates a tempo meta-event.
  447. @see isTempoMetaEvent
  448. */
  449. static MidiMessage tempoMetaEvent (int microsecondsPerQuarterNote) noexcept;
  450. //==============================================================================
  451. /** Returns true if this is a 'time-signature' meta-event.
  452. @see getTimeSignatureInfo
  453. */
  454. bool isTimeSignatureMetaEvent() const noexcept;
  455. /** Returns the time-signature values from a time-signature meta-event.
  456. @see isTimeSignatureMetaEvent
  457. */
  458. void getTimeSignatureInfo (int& numerator, int& denominator) const noexcept;
  459. /** Creates a time-signature meta-event.
  460. @see isTimeSignatureMetaEvent
  461. */
  462. static MidiMessage timeSignatureMetaEvent (int numerator, int denominator);
  463. //==============================================================================
  464. /** Returns true if this is a 'key-signature' meta-event.
  465. @see getKeySignatureNumberOfSharpsOrFlats, isKeySignatureMajorKey
  466. */
  467. bool isKeySignatureMetaEvent() const noexcept;
  468. /** Returns the key from a key-signature meta-event.
  469. This method must only be called if isKeySignatureMetaEvent() is true.
  470. A positive number here indicates the number of sharps in the key signature,
  471. and a negative number indicates a number of flats. So e.g. 3 = F# + C# + G#,
  472. -2 = Bb + Eb
  473. @see isKeySignatureMetaEvent, isKeySignatureMajorKey
  474. */
  475. int getKeySignatureNumberOfSharpsOrFlats() const noexcept;
  476. /** Returns true if this key-signature event is major, or false if it's minor.
  477. This method must only be called if isKeySignatureMetaEvent() is true.
  478. */
  479. bool isKeySignatureMajorKey() const noexcept;
  480. /** Creates a key-signature meta-event.
  481. @param numberOfSharpsOrFlats if positive, this indicates the number of sharps
  482. in the key; if negative, the number of flats
  483. @param isMinorKey if true, the key is minor; if false, it is major
  484. @see isKeySignatureMetaEvent
  485. */
  486. static MidiMessage keySignatureMetaEvent (int numberOfSharpsOrFlats, bool isMinorKey);
  487. //==============================================================================
  488. /** Returns true if this is a 'channel' meta-event.
  489. A channel meta-event specifies the midi channel that should be used
  490. for subsequent meta-events.
  491. @see getMidiChannelMetaEventChannel
  492. */
  493. bool isMidiChannelMetaEvent() const noexcept;
  494. /** Returns the channel number from a channel meta-event.
  495. @returns the channel, in the range 1 to 16.
  496. @see isMidiChannelMetaEvent
  497. */
  498. int getMidiChannelMetaEventChannel() const noexcept;
  499. /** Creates a midi channel meta-event.
  500. @param channel the midi channel, in the range 1 to 16
  501. @see isMidiChannelMetaEvent
  502. */
  503. static MidiMessage midiChannelMetaEvent (int channel) noexcept;
  504. //==============================================================================
  505. /** Returns true if this is an active-sense message. */
  506. bool isActiveSense() const noexcept;
  507. //==============================================================================
  508. /** Returns true if this is a midi start event.
  509. @see midiStart
  510. */
  511. bool isMidiStart() const noexcept;
  512. /** Creates a midi start event. */
  513. static MidiMessage midiStart() noexcept;
  514. /** Returns true if this is a midi continue event.
  515. @see midiContinue
  516. */
  517. bool isMidiContinue() const noexcept;
  518. /** Creates a midi continue event. */
  519. static MidiMessage midiContinue() noexcept;
  520. /** Returns true if this is a midi stop event.
  521. @see midiStop
  522. */
  523. bool isMidiStop() const noexcept;
  524. /** Creates a midi stop event. */
  525. static MidiMessage midiStop() noexcept;
  526. /** Returns true if this is a midi clock event.
  527. @see midiClock, songPositionPointer
  528. */
  529. bool isMidiClock() const noexcept;
  530. /** Creates a midi clock event. */
  531. static MidiMessage midiClock() noexcept;
  532. /** Returns true if this is a song-position-pointer message.
  533. @see getSongPositionPointerMidiBeat, songPositionPointer
  534. */
  535. bool isSongPositionPointer() const noexcept;
  536. /** Returns the midi beat-number of a song-position-pointer message.
  537. @see isSongPositionPointer, songPositionPointer
  538. */
  539. int getSongPositionPointerMidiBeat() const noexcept;
  540. /** Creates a song-position-pointer message.
  541. The position is a number of midi beats from the start of the song, where 1 midi
  542. beat is 6 midi clocks, and there are 24 midi clocks in a quarter-note. So there
  543. are 4 midi beats in a quarter-note.
  544. @see isSongPositionPointer, getSongPositionPointerMidiBeat
  545. */
  546. static MidiMessage songPositionPointer (int positionInMidiBeats) noexcept;
  547. //==============================================================================
  548. /** Returns true if this is a quarter-frame midi timecode message.
  549. @see quarterFrame, getQuarterFrameSequenceNumber, getQuarterFrameValue
  550. */
  551. bool isQuarterFrame() const noexcept;
  552. /** Returns the sequence number of a quarter-frame midi timecode message.
  553. This will be a value between 0 and 7.
  554. @see isQuarterFrame, getQuarterFrameValue, quarterFrame
  555. */
  556. int getQuarterFrameSequenceNumber() const noexcept;
  557. /** Returns the value from a quarter-frame message.
  558. This will be the lower nybble of the message's data-byte, a value between 0 and 15
  559. */
  560. int getQuarterFrameValue() const noexcept;
  561. /** Creates a quarter-frame MTC message.
  562. @param sequenceNumber a value 0 to 7 for the upper nybble of the message's data byte
  563. @param value a value 0 to 15 for the lower nybble of the message's data byte
  564. */
  565. static MidiMessage quarterFrame (int sequenceNumber, int value) noexcept;
  566. /** SMPTE timecode types.
  567. Used by the getFullFrameParameters() and fullFrame() methods.
  568. */
  569. enum SmpteTimecodeType
  570. {
  571. fps24 = 0,
  572. fps25 = 1,
  573. fps30drop = 2,
  574. fps30 = 3
  575. };
  576. /** Returns true if this is a full-frame midi timecode message. */
  577. bool isFullFrame() const noexcept;
  578. /** Extracts the timecode information from a full-frame midi timecode message.
  579. You should only call this on messages where you've used isFullFrame() to
  580. check that they're the right kind.
  581. */
  582. void getFullFrameParameters (int& hours,
  583. int& minutes,
  584. int& seconds,
  585. int& frames,
  586. SmpteTimecodeType& timecodeType) const noexcept;
  587. /** Creates a full-frame MTC message. */
  588. static MidiMessage fullFrame (int hours,
  589. int minutes,
  590. int seconds,
  591. int frames,
  592. SmpteTimecodeType timecodeType);
  593. //==============================================================================
  594. /** Types of MMC command.
  595. @see isMidiMachineControlMessage, getMidiMachineControlCommand, midiMachineControlCommand
  596. */
  597. enum MidiMachineControlCommand
  598. {
  599. mmc_stop = 1,
  600. mmc_play = 2,
  601. mmc_deferredplay = 3,
  602. mmc_fastforward = 4,
  603. mmc_rewind = 5,
  604. mmc_recordStart = 6,
  605. mmc_recordStop = 7,
  606. mmc_pause = 9
  607. };
  608. /** Checks whether this is an MMC message.
  609. If it is, you can use the getMidiMachineControlCommand() to find out its type.
  610. */
  611. bool isMidiMachineControlMessage() const noexcept;
  612. /** For an MMC message, this returns its type.
  613. Make sure it's actually an MMC message with isMidiMachineControlMessage() before
  614. calling this method.
  615. */
  616. MidiMachineControlCommand getMidiMachineControlCommand() const noexcept;
  617. /** Creates an MMC message. */
  618. static MidiMessage midiMachineControlCommand (MidiMachineControlCommand command);
  619. /** Checks whether this is an MMC "goto" message.
  620. If it is, the parameters passed-in are set to the time that the message contains.
  621. @see midiMachineControlGoto
  622. */
  623. bool isMidiMachineControlGoto (int& hours,
  624. int& minutes,
  625. int& seconds,
  626. int& frames) const noexcept;
  627. /** Creates an MMC "goto" message.
  628. This messages tells the device to go to a specific frame.
  629. @see isMidiMachineControlGoto
  630. */
  631. static MidiMessage midiMachineControlGoto (int hours,
  632. int minutes,
  633. int seconds,
  634. int frames);
  635. //==============================================================================
  636. /** Creates a master-volume change message.
  637. @param volume the volume, 0 to 1.0
  638. */
  639. static MidiMessage masterVolume (float volume);
  640. //==============================================================================
  641. /** Creates a system-exclusive message.
  642. The data passed in is wrapped with header and tail bytes of 0xf0 and 0xf7.
  643. */
  644. static MidiMessage createSysExMessage (const void* sysexData,
  645. int dataSize);
  646. //==============================================================================
  647. /** Reads a midi variable-length integer.
  648. @param data the data to read the number from
  649. @param numBytesUsed on return, this will be set to the number of bytes that were read
  650. */
  651. static int readVariableLengthVal (const uint8* data,
  652. int& numBytesUsed) noexcept;
  653. /** Based on the first byte of a short midi message, this uses a lookup table
  654. to return the message length (either 1, 2, or 3 bytes).
  655. The value passed in must be 0x80 or higher.
  656. */
  657. static int getMessageLengthFromFirstByte (uint8 firstByte) noexcept;
  658. //==============================================================================
  659. /** Returns the name of a midi note number.
  660. E.g "C", "D#", etc.
  661. @param noteNumber the midi note number, 0 to 127
  662. @param useSharps if true, sharpened notes are used, e.g. "C#", otherwise
  663. they'll be flattened, e.g. "Db"
  664. @param includeOctaveNumber if true, the octave number will be appended to the string,
  665. e.g. "C#4"
  666. @param octaveNumForMiddleC if an octave number is being appended, this indicates the
  667. number that will be used for middle C's octave
  668. @see getMidiNoteInHertz
  669. */
  670. static String getMidiNoteName (int noteNumber,
  671. bool useSharps,
  672. bool includeOctaveNumber,
  673. int octaveNumForMiddleC);
  674. /** Returns the frequency of a midi note number.
  675. The frequencyOfA parameter is an optional frequency for 'A', normally 440-444Hz for concert pitch.
  676. @see getMidiNoteName
  677. */
  678. static double getMidiNoteInHertz (int noteNumber, double frequencyOfA = 440.0) noexcept;
  679. /** Returns true if the given midi note number is a black key. */
  680. static bool isMidiNoteBlack (int noteNumber) noexcept;
  681. /** Converts a floating-point value between 0 and 1 to a MIDI 7-bit value between 0 and 127. */
  682. static uint8 floatValueToMidiByte (float valueBetween0and1) noexcept;
  683. /** Converts a pitchbend value in semitones to a MIDI 14-bit pitchwheel position value. */
  684. static uint16 pitchbendToPitchwheelPos (float pitchbendInSemitones,
  685. float pitchbendRangeInSemitones) noexcept;
  686. private:
  687. //==============================================================================
  688. union PackedData
  689. {
  690. uint8* allocatedData;
  691. uint8 asBytes[sizeof (uint8*)];
  692. };
  693. PackedData packedData;
  694. double timeStamp;
  695. int size;
  696. inline bool isHeapAllocated() const noexcept { return size > (int) sizeof (packedData); }
  697. inline uint8* getData() const noexcept { return isHeapAllocated() ? packedData.allocatedData : (uint8*) packedData.asBytes; }
  698. uint8* allocateSpace (int);
  699. };
  700. }
  701. #endif // WATER_MIDIMESSAGE_H_INCLUDED