source/modules/juce_audio_basics/midi/juce_MidiMessage.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /**
  28     Encapsulates a MIDI message.
  29
  30     @see MidiMessageSequence, MidiOutput, MidiInput
  31
  32     @tags{Audio}
  33 */
  34 class JUCE_API  MidiMessage
  35 {
  36 public:
  37     //==============================================================================
  38     /** Creates a 3-byte short midi message.
  39
  40         @param byte1            message byte 1
  41         @param byte2            message byte 2
  42         @param byte3            message byte 3
  43         @param timeStamp        the time to give the midi message - this value doesn't
  44                                 use any particular units, so will be application-specific
  45     */
  46     MidiMessage (int byte1, int byte2, int byte3, double timeStamp = 0) noexcept;
  47
  48     /** Creates a 2-byte short midi message.
  49
  50         @param byte1            message byte 1
  51         @param byte2            message byte 2
  52         @param timeStamp        the time to give the midi message - this value doesn't
  53                                 use any particular units, so will be application-specific
  54     */
  55     MidiMessage (int byte1, int byte2, double timeStamp = 0) noexcept;
  56
  57     /** Creates a 1-byte short midi message.
  58
  59         @param byte1            message byte 1
  60         @param timeStamp        the time to give the midi message - this value doesn't
  61                                 use any particular units, so will be application-specific
  62     */
  63     MidiMessage (int byte1, double timeStamp = 0) noexcept;
  64
  65     /** Creates a midi message from a list of bytes. */
  66     template <typename... Data>
  67     MidiMessage (int byte1, int byte2, int byte3, Data... otherBytes)  : size (3 + sizeof... (otherBytes))
  68     {
  69         // this checks that the length matches the data..
  70         jassert (size > 3 || byte1 >= 0xf0 || getMessageLengthFromFirstByte ((uint8) byte1) == size);
  71
  72         const uint8 data[] = { (uint8) byte1, (uint8) byte2, (uint8) byte3, static_cast<uint8> (otherBytes)... };
  73         memcpy (allocateSpace (size), data, (size_t) size);
  74     }
  75
  76
  77     /** Creates a midi message from a block of data. */
  78     MidiMessage (const void* data, int numBytes, double timeStamp = 0);
  79
  80     /** Reads the next midi message from some data.
  81
  82         This will read as many bytes from a data stream as it needs to make a
  83         complete message, and will return the number of bytes it used. This lets
  84         you read a sequence of midi messages from a file or stream.
  85
  86         @param data                     the data to read from
  87         @param maxBytesToUse            the maximum number of bytes it's allowed to read
  88         @param numBytesUsed             returns the number of bytes that were actually needed
  89         @param lastStatusByte           in a sequence of midi messages, the initial byte
  90                                         can be dropped from a message if it's the same as the
  91                                         first byte of the previous message, so this lets you
  92                                         supply the byte to use if the first byte of the message
  93                                         has in fact been dropped.
  94         @param timeStamp                the time to give the midi message - this value doesn't
  95                                         use any particular units, so will be application-specific
  96         @param sysexHasEmbeddedLength   when reading sysexes, this flag indicates whether
  97                                         to expect the data to begin with a variable-length
  98                                         field indicating its size
  99     */
 100     MidiMessage (const void* data, int maxBytesToUse,
 101                  int& numBytesUsed, uint8 lastStatusByte,
 102                  double timeStamp = 0,
 103                  bool sysexHasEmbeddedLength = true);
 104
 105     /** Creates an empty sysex message.
 106
 107         Since the MidiMessage has to contain a valid message, this default constructor
 108         just initialises it with an empty sysex message.
 109     */
 110     MidiMessage() noexcept;
 111
 112     /** Creates a copy of another midi message. */
 113     MidiMessage (const MidiMessage&);
 114
 115     /** Creates a copy of another midi message, with a different timestamp. */
 116     MidiMessage (const MidiMessage&, double newTimeStamp);
 117
 118     /** Destructor. */
 119     ~MidiMessage() noexcept;
 120
 121     /** Copies this message from another one. */
 122     MidiMessage& operator= (const MidiMessage& other);
 123
 124     /** Move constructor */
 125     MidiMessage (MidiMessage&&) noexcept;
 126
 127     /** Move assignment operator */
 128     MidiMessage& operator= (MidiMessage&&) noexcept;
 129
 130     //==============================================================================
 131     /** Returns a pointer to the raw midi data.
 132         @see getRawDataSize
 133     */
 134     const uint8* getRawData() const noexcept            { return getData(); }
 135
 136     /** Returns the number of bytes of data in the message.
 137         @see getRawData
 138     */
 139     int getRawDataSize() const noexcept                 { return size; }
 140
 141     //==============================================================================
 142     /** Returns a human-readable description of the midi message as a string,
 143         for example "Note On C#3 Velocity 120 Channel 1".
 144     */
 145     String getDescription() const;
 146
 147     //==============================================================================
 148     /** Returns the timestamp associated with this message.
 149
 150         The exact meaning of this time and its units will vary, as messages are used in
 151         a variety of different contexts.
 152
 153         If you're getting the message from a midi file, this could be a time in seconds, or
 154         a number of ticks - see MidiFile::convertTimestampTicksToSeconds().
 155
 156         If the message is being used in a MidiBuffer, it might indicate the number of
 157         audio samples from the start of the buffer.
 158
 159         If the message was created by a MidiInput, see MidiInputCallback::handleIncomingMidiMessage()
 160         for details of the way that it initialises this value.
 161
 162         @see setTimeStamp, addToTimeStamp
 163     */
 164     double getTimeStamp() const noexcept                { return timeStamp; }
 165
 166     /** Changes the message's associated timestamp.
 167         The units for the timestamp will be application-specific - see the notes for getTimeStamp().
 168         @see addToTimeStamp, getTimeStamp
 169     */
 170     void setTimeStamp (double newTimestamp) noexcept    { timeStamp = newTimestamp; }
 171
 172     /** Adds a value to the message's timestamp.
 173         The units for the timestamp will be application-specific.
 174     */
 175     void addToTimeStamp (double delta) noexcept         { timeStamp += delta; }
 176
 177     /** Return a copy of this message with a new timestamp.
 178         The units for the timestamp will be application-specific - see the notes for getTimeStamp().
 179     */
 180     MidiMessage withTimeStamp (double newTimestamp) const;
 181
 182     //==============================================================================
 183     /** Returns the midi channel associated with the message.
 184
 185         @returns    a value 1 to 16 if the message has a channel, or 0 if it hasn't (e.g.
 186                     if it's a sysex)
 187         @see isForChannel, setChannel
 188     */
 189     int getChannel() const noexcept;
 190
 191     /** Returns true if the message applies to the given midi channel.
 192
 193         @param channelNumber    the channel number to look for, in the range 1 to 16
 194         @see getChannel, setChannel
 195     */
 196     bool isForChannel (int channelNumber) const noexcept;
 197
 198     /** Changes the message's midi channel.
 199         This won't do anything for non-channel messages like sysexes.
 200         @param newChannelNumber    the channel number to change it to, in the range 1 to 16
 201     */
 202     void setChannel (int newChannelNumber) noexcept;
 203
 204     //==============================================================================
 205     /** Returns true if this is a system-exclusive message.
 206     */
 207     bool isSysEx() const noexcept;
 208
 209     /** Returns a pointer to the sysex data inside the message.
 210         If this event isn't a sysex event, it'll return 0.
 211         @see getSysExDataSize
 212     */
 213     const uint8* getSysExData() const noexcept;
 214
 215     /** Returns the size of the sysex data.
 216         This value excludes the 0xf0 header byte and the 0xf7 at the end.
 217         @see getSysExData
 218     */
 219     int getSysExDataSize() const noexcept;
 220
 221     //==============================================================================
 222     /** Returns true if this message is a 'key-down' event.
 223
 224         @param returnTrueForVelocity0   if true, then if this event is a note-on with
 225                         velocity 0, it will still be considered to be a note-on and the
 226                         method will return true. If returnTrueForVelocity0 is false, then
 227                         if this is a note-on event with velocity 0, it'll be regarded as
 228                         a note-off, and the method will return false
 229
 230         @see isNoteOff, getNoteNumber, getVelocity, noteOn
 231     */
 232     bool isNoteOn (bool returnTrueForVelocity0 = false) const noexcept;
 233
 234     /** Creates a key-down message (using a floating-point velocity).
 235
 236         @param channel      the midi channel, in the range 1 to 16
 237         @param noteNumber   the key number, 0 to 127
 238         @param velocity     in the range 0 to 1.0
 239         @see isNoteOn
 240     */
 241     static MidiMessage noteOn (int channel, int noteNumber, float velocity) noexcept;
 242
 243     /** Creates a key-down message (using an integer velocity).
 244
 245         @param channel      the midi channel, in the range 1 to 16
 246         @param noteNumber   the key number, 0 to 127
 247         @param velocity     in the range 0 to 127
 248         @see isNoteOn
 249     */
 250     static MidiMessage noteOn (int channel, int noteNumber, uint8 velocity) noexcept;
 251
 252     /** Returns true if this message is a 'key-up' event.
 253
 254         If returnTrueForNoteOnVelocity0 is true, then his will also return true
 255         for a note-on event with a velocity of 0.
 256
 257         @see isNoteOn, getNoteNumber, getVelocity, noteOff
 258     */
 259     bool isNoteOff (bool returnTrueForNoteOnVelocity0 = true) const noexcept;
 260
 261     /** Creates a key-up message.
 262
 263         @param channel      the midi channel, in the range 1 to 16
 264         @param noteNumber   the key number, 0 to 127
 265         @param velocity     in the range 0 to 1.0
 266         @see isNoteOff
 267     */
 268     static MidiMessage noteOff (int channel, int noteNumber, float velocity) noexcept;
 269
 270     /** Creates a key-up message.
 271
 272         @param channel      the midi channel, in the range 1 to 16
 273         @param noteNumber   the key number, 0 to 127
 274         @param velocity     in the range 0 to 127
 275         @see isNoteOff
 276     */
 277     static MidiMessage noteOff (int channel, int noteNumber, uint8 velocity) noexcept;
 278
 279     /** Creates a key-up message.
 280
 281         @param channel      the midi channel, in the range 1 to 16
 282         @param noteNumber   the key number, 0 to 127
 283         @see isNoteOff
 284     */
 285     static MidiMessage noteOff (int channel, int noteNumber) noexcept;
 286
 287     /** Returns true if this message is a 'key-down' or 'key-up' event.
 288
 289         @see isNoteOn, isNoteOff
 290     */
 291     bool isNoteOnOrOff() const noexcept;
 292
 293     /** Returns the midi note number for note-on and note-off messages.
 294         If the message isn't a note-on or off, the value returned is undefined.
 295         @see isNoteOff, getMidiNoteName, getMidiNoteInHertz, setNoteNumber
 296     */
 297     int getNoteNumber() const noexcept;
 298
 299     /** Changes the midi note number of a note-on or note-off message.
 300         If the message isn't a note on or off, this will do nothing.
 301     */
 302     void setNoteNumber (int newNoteNumber) noexcept;
 303
 304     //==============================================================================
 305     /** Returns the velocity of a note-on or note-off message.
 306
 307         The value returned will be in the range 0 to 127.
 308         If the message isn't a note-on or off event, it will return 0.
 309
 310         @see getFloatVelocity
 311     */
 312     uint8 getVelocity() const noexcept;
 313
 314     /** Returns the velocity of a note-on or note-off message.
 315
 316         The value returned will be in the range 0 to 1.0
 317         If the message isn't a note-on or off event, it will return 0.
 318
 319         @see getVelocity, setVelocity
 320     */
 321     float getFloatVelocity() const noexcept;
 322
 323     /** Changes the velocity of a note-on or note-off message.
 324
 325         If the message isn't a note on or off, this will do nothing.
 326
 327         @param newVelocity  the new velocity, in the range 0 to 1.0
 328         @see getFloatVelocity, multiplyVelocity
 329     */
 330     void setVelocity (float newVelocity) noexcept;
 331
 332     /** Multiplies the velocity of a note-on or note-off message by a given amount.
 333
 334         If the message isn't a note on or off, this will do nothing.
 335
 336         @param scaleFactor  the value by which to multiply the velocity
 337         @see setVelocity
 338     */
 339     void multiplyVelocity (float scaleFactor) noexcept;
 340
 341     //==============================================================================
 342     /** Returns true if this message is a 'sustain pedal down' controller message. */
 343     bool isSustainPedalOn() const noexcept;
 344     /** Returns true if this message is a 'sustain pedal up' controller message. */
 345     bool isSustainPedalOff() const noexcept;
 346
 347     /** Returns true if this message is a 'sostenuto pedal down' controller message. */
 348     bool isSostenutoPedalOn() const noexcept;
 349     /** Returns true if this message is a 'sostenuto pedal up' controller message. */
 350     bool isSostenutoPedalOff() const noexcept;
 351
 352     /** Returns true if this message is a 'soft pedal down' controller message. */
 353     bool isSoftPedalOn() const noexcept;
 354     /** Returns true if this message is a 'soft pedal up' controller message. */
 355     bool isSoftPedalOff() const noexcept;
 356
 357     //==============================================================================
 358     /** Returns true if the message is a program (patch) change message.
 359         @see getProgramChangeNumber, getGMInstrumentName
 360     */
 361     bool isProgramChange() const noexcept;
 362
 363     /** Returns the new program number of a program change message.
 364         If the message isn't a program change, the value returned is undefined.
 365         @see isProgramChange, getGMInstrumentName
 366     */
 367     int getProgramChangeNumber() const noexcept;
 368
 369     /** Creates a program-change message.
 370
 371         @param channel          the midi channel, in the range 1 to 16
 372         @param programNumber    the midi program number, 0 to 127
 373         @see isProgramChange, getGMInstrumentName
 374     */
 375     static MidiMessage programChange (int channel, int programNumber) noexcept;
 376
 377     //==============================================================================
 378     /** Returns true if the message is a pitch-wheel move.
 379         @see getPitchWheelValue, pitchWheel
 380     */
 381     bool isPitchWheel() const noexcept;
 382
 383     /** Returns the pitch wheel position from a pitch-wheel move message.
 384
 385         The value returned is a 14-bit number from 0 to 0x3fff, indicating the wheel position.
 386         If called for messages which aren't pitch wheel events, the number returned will be
 387         nonsense.
 388
 389         @see isPitchWheel
 390     */
 391     int getPitchWheelValue() const noexcept;
 392
 393     /** Creates a pitch-wheel move message.
 394
 395         @param channel      the midi channel, in the range 1 to 16
 396         @param position     the wheel position, in the range 0 to 16383
 397         @see isPitchWheel
 398     */
 399     static MidiMessage pitchWheel (int channel, int position) noexcept;
 400
 401     //==============================================================================
 402     /** Returns true if the message is an aftertouch event.
 403
 404         For aftertouch events, use the getNoteNumber() method to find out the key
 405         that it applies to, and getAfterTouchValue() to find out the amount. Use
 406         getChannel() to find out the channel.
 407
 408         @see getAftertouchValue, getNoteNumber
 409     */
 410     bool isAftertouch() const noexcept;
 411
 412     /** Returns the amount of aftertouch from an aftertouch messages.
 413
 414         The value returned is in the range 0 to 127, and will be nonsense for messages
 415         other than aftertouch messages.
 416
 417         @see isAftertouch
 418     */
 419     int getAfterTouchValue() const noexcept;
 420
 421     /** Creates an aftertouch message.
 422
 423         @param channel              the midi channel, in the range 1 to 16
 424         @param noteNumber           the key number, 0 to 127
 425         @param aftertouchAmount     the amount of aftertouch, 0 to 127
 426         @see isAftertouch
 427     */
 428     static MidiMessage aftertouchChange (int channel,
 429                                          int noteNumber,
 430                                          int aftertouchAmount) noexcept;
 431
 432     /** Returns true if the message is a channel-pressure change event.
 433
 434         This is like aftertouch, but common to the whole channel rather than a specific
 435         note. Use getChannelPressureValue() to find out the pressure, and getChannel()
 436         to find out the channel.
 437
 438         @see channelPressureChange
 439     */
 440     bool isChannelPressure() const noexcept;
 441
 442     /** Returns the pressure from a channel pressure change message.
 443
 444         @returns the pressure, in the range 0 to 127
 445         @see isChannelPressure, channelPressureChange
 446     */
 447     int getChannelPressureValue() const noexcept;
 448
 449     /** Creates a channel-pressure change event.
 450
 451         @param channel              the midi channel: 1 to 16
 452         @param pressure             the pressure, 0 to 127
 453         @see isChannelPressure
 454     */
 455     static MidiMessage channelPressureChange (int channel, int pressure) noexcept;
 456
 457     //==============================================================================
 458     /** Returns true if this is a midi controller message.
 459
 460         @see getControllerNumber, getControllerValue, controllerEvent
 461     */
 462     bool isController() const noexcept;
 463
 464     /** Returns the controller number of a controller message.
 465
 466         The name of the controller can be looked up using the getControllerName() method.
 467         Note that the value returned is invalid for messages that aren't controller changes.
 468
 469         @see isController, getControllerName, getControllerValue
 470     */
 471     int getControllerNumber() const noexcept;
 472
 473     /** Returns the controller value from a controller message.
 474
 475         A value 0 to 127 is returned to indicate the new controller position.
 476         Note that the value returned is invalid for messages that aren't controller changes.
 477
 478         @see isController, getControllerNumber
 479     */
 480     int getControllerValue() const noexcept;
 481
 482     /** Returns true if this message is a controller message and if it has the specified
 483         controller type.
 484     */
 485     bool isControllerOfType (int controllerType) const noexcept;
 486
 487     /** Creates a controller message.
 488         @param channel          the midi channel, in the range 1 to 16
 489         @param controllerType   the type of controller
 490         @param value            the controller value
 491         @see isController
 492     */
 493     static MidiMessage controllerEvent (int channel,
 494                                         int controllerType,
 495                                         int value) noexcept;
 496
 497     /** Checks whether this message is an all-notes-off message.
 498         @see allNotesOff
 499     */
 500     bool isAllNotesOff() const noexcept;
 501
 502     /** Checks whether this message is an all-sound-off message.
 503         @see allSoundOff
 504     */
 505     bool isAllSoundOff() const noexcept;
 506
 507     /** Checks whether this message is a reset all controllers message.
 508         @see allControllerOff
 509     */
 510     bool isResetAllControllers() const noexcept;
 511
 512     /** Creates an all-notes-off message.
 513         @param channel              the midi channel, in the range 1 to 16
 514         @see isAllNotesOff
 515     */
 516     static MidiMessage allNotesOff (int channel) noexcept;
 517
 518     /** Creates an all-sound-off message.
 519         @param channel              the midi channel, in the range 1 to 16
 520         @see isAllSoundOff
 521     */
 522     static MidiMessage allSoundOff (int channel) noexcept;
 523
 524     /** Creates an all-controllers-off message.
 525         @param channel              the midi channel, in the range 1 to 16
 526     */
 527     static MidiMessage allControllersOff (int channel) noexcept;
 528
 529     //==============================================================================
 530     /** Returns true if this event is a meta-event.
 531
 532         Meta-events are things like tempo changes, track names, etc.
 533
 534         @see getMetaEventType, isTrackMetaEvent, isEndOfTrackMetaEvent,
 535              isTextMetaEvent, isTrackNameEvent, isTempoMetaEvent, isTimeSignatureMetaEvent,
 536              isKeySignatureMetaEvent, isMidiChannelMetaEvent
 537     */
 538     bool isMetaEvent() const noexcept;
 539
 540     /** Returns a meta-event's type number.
 541
 542         If the message isn't a meta-event, this will return -1.
 543
 544         @see isMetaEvent, isTrackMetaEvent, isEndOfTrackMetaEvent,
 545              isTextMetaEvent, isTrackNameEvent, isTempoMetaEvent, isTimeSignatureMetaEvent,
 546              isKeySignatureMetaEvent, isMidiChannelMetaEvent
 547     */
 548     int getMetaEventType() const noexcept;
 549
 550     /** Returns a pointer to the data in a meta-event.
 551         @see isMetaEvent, getMetaEventLength
 552     */
 553     const uint8* getMetaEventData() const noexcept;
 554
 555     /** Returns the length of the data for a meta-event.
 556         @see isMetaEvent, getMetaEventData
 557     */
 558     int getMetaEventLength() const noexcept;
 559
 560     //==============================================================================
 561     /** Returns true if this is a 'track' meta-event. */
 562     bool isTrackMetaEvent() const noexcept;
 563
 564     /** Returns true if this is an 'end-of-track' meta-event. */
 565     bool isEndOfTrackMetaEvent() const noexcept;
 566
 567     /** Creates an end-of-track meta-event.
 568         @see isEndOfTrackMetaEvent
 569     */
 570     static MidiMessage endOfTrack() noexcept;
 571
 572     /** Returns true if this is an 'track name' meta-event.
 573         You can use the getTextFromTextMetaEvent() method to get the track's name.
 574     */
 575     bool isTrackNameEvent() const noexcept;
 576
 577     /** Returns true if this is a 'text' meta-event.
 578         @see getTextFromTextMetaEvent
 579     */
 580     bool isTextMetaEvent() const noexcept;
 581
 582     /** Returns the text from a text meta-event.
 583         @see isTextMetaEvent
 584     */
 585     String getTextFromTextMetaEvent() const;
 586
 587     /** Creates a text meta-event. */
 588     static MidiMessage textMetaEvent (int type, StringRef text);
 589
 590     //==============================================================================
 591     /** Returns true if this is a 'tempo' meta-event.
 592         @see getTempoMetaEventTickLength, getTempoSecondsPerQuarterNote
 593     */
 594     bool isTempoMetaEvent() const noexcept;
 595
 596     /** Returns the tick length from a tempo meta-event.
 597
 598         @param timeFormat   the 16-bit time format value from the midi file's header.
 599         @returns the tick length (in seconds).
 600         @see isTempoMetaEvent
 601     */
 602     double getTempoMetaEventTickLength (short timeFormat) const noexcept;
 603
 604     /** Calculates the seconds-per-quarter-note from a tempo meta-event.
 605         @see isTempoMetaEvent, getTempoMetaEventTickLength
 606     */
 607     double getTempoSecondsPerQuarterNote() const noexcept;
 608
 609     /** Creates a tempo meta-event.
 610         @see isTempoMetaEvent
 611     */
 612     static MidiMessage tempoMetaEvent (int microsecondsPerQuarterNote) noexcept;
 613
 614     //==============================================================================
 615     /** Returns true if this is a 'time-signature' meta-event.
 616         @see getTimeSignatureInfo
 617     */
 618     bool isTimeSignatureMetaEvent() const noexcept;
 619
 620     /** Returns the time-signature values from a time-signature meta-event.
 621         @see isTimeSignatureMetaEvent
 622     */
 623     void getTimeSignatureInfo (int& numerator, int& denominator) const noexcept;
 624
 625     /** Creates a time-signature meta-event.
 626         @see isTimeSignatureMetaEvent
 627     */
 628     static MidiMessage timeSignatureMetaEvent (int numerator, int denominator);
 629
 630     //==============================================================================
 631     /** Returns true if this is a 'key-signature' meta-event.
 632         @see getKeySignatureNumberOfSharpsOrFlats, isKeySignatureMajorKey
 633     */
 634     bool isKeySignatureMetaEvent() const noexcept;
 635
 636     /** Returns the key from a key-signature meta-event.
 637         This method must only be called if isKeySignatureMetaEvent() is true.
 638         A positive number here indicates the number of sharps in the key signature,
 639         and a negative number indicates a number of flats. So e.g. 3 = F# + C# + G#,
 640         -2 = Bb + Eb
 641         @see isKeySignatureMetaEvent, isKeySignatureMajorKey
 642     */
 643     int getKeySignatureNumberOfSharpsOrFlats() const noexcept;
 644
 645     /** Returns true if this key-signature event is major, or false if it's minor.
 646         This method must only be called if isKeySignatureMetaEvent() is true.
 647     */
 648     bool isKeySignatureMajorKey() const noexcept;
 649
 650     /** Creates a key-signature meta-event.
 651         @param numberOfSharpsOrFlats    if positive, this indicates the number of sharps
 652                                         in the key; if negative, the number of flats
 653         @param isMinorKey               if true, the key is minor; if false, it is major
 654         @see isKeySignatureMetaEvent
 655     */
 656     static MidiMessage keySignatureMetaEvent (int numberOfSharpsOrFlats, bool isMinorKey);
 657
 658     //==============================================================================
 659     /** Returns true if this is a 'channel' meta-event.
 660
 661         A channel meta-event specifies the midi channel that should be used
 662         for subsequent meta-events.
 663
 664         @see getMidiChannelMetaEventChannel
 665     */
 666     bool isMidiChannelMetaEvent() const noexcept;
 667
 668     /** Returns the channel number from a channel meta-event.
 669
 670         @returns the channel, in the range 1 to 16.
 671         @see isMidiChannelMetaEvent
 672     */
 673     int getMidiChannelMetaEventChannel() const noexcept;
 674
 675     /** Creates a midi channel meta-event.
 676
 677         @param channel              the midi channel, in the range 1 to 16
 678         @see isMidiChannelMetaEvent
 679     */
 680     static MidiMessage midiChannelMetaEvent (int channel) noexcept;
 681
 682     //==============================================================================
 683     /** Returns true if this is an active-sense message. */
 684     bool isActiveSense() const noexcept;
 685
 686     //==============================================================================
 687     /** Returns true if this is a midi start event.
 688         @see midiStart
 689     */
 690     bool isMidiStart() const noexcept;
 691
 692     /** Creates a midi start event. */
 693     static MidiMessage midiStart() noexcept;
 694
 695     /** Returns true if this is a midi continue event.
 696         @see midiContinue
 697     */
 698     bool isMidiContinue() const noexcept;
 699
 700     /** Creates a midi continue event. */
 701     static MidiMessage midiContinue() noexcept;
 702
 703     /** Returns true if this is a midi stop event.
 704         @see midiStop
 705     */
 706     bool isMidiStop() const noexcept;
 707
 708     /** Creates a midi stop event. */
 709     static MidiMessage midiStop() noexcept;
 710
 711     /** Returns true if this is a midi clock event.
 712         @see midiClock, songPositionPointer
 713     */
 714     bool isMidiClock() const noexcept;
 715
 716     /** Creates a midi clock event. */
 717     static MidiMessage midiClock() noexcept;
 718
 719     /** Returns true if this is a song-position-pointer message.
 720         @see getSongPositionPointerMidiBeat, songPositionPointer
 721     */
 722     bool isSongPositionPointer() const noexcept;
 723
 724     /** Returns the midi beat-number of a song-position-pointer message.
 725         @see isSongPositionPointer, songPositionPointer
 726     */
 727     int getSongPositionPointerMidiBeat() const noexcept;
 728
 729     /** Creates a song-position-pointer message.
 730
 731         The position is a number of midi beats from the start of the song, where 1 midi
 732         beat is 6 midi clocks, and there are 24 midi clocks in a quarter-note. So there
 733         are 4 midi beats in a quarter-note.
 734
 735         @see isSongPositionPointer, getSongPositionPointerMidiBeat
 736     */
 737     static MidiMessage songPositionPointer (int positionInMidiBeats) noexcept;
 738
 739     //==============================================================================
 740     /** Returns true if this is a quarter-frame midi timecode message.
 741         @see quarterFrame, getQuarterFrameSequenceNumber, getQuarterFrameValue
 742     */
 743     bool isQuarterFrame() const noexcept;
 744
 745     /** Returns the sequence number of a quarter-frame midi timecode message.
 746         This will be a value between 0 and 7.
 747         @see isQuarterFrame, getQuarterFrameValue, quarterFrame
 748     */
 749     int getQuarterFrameSequenceNumber() const noexcept;
 750
 751     /** Returns the value from a quarter-frame message.
 752         This will be the lower nybble of the message's data-byte, a value between 0 and 15
 753     */
 754     int getQuarterFrameValue() const noexcept;
 755
 756     /** Creates a quarter-frame MTC message.
 757
 758         @param sequenceNumber   a value 0 to 7 for the upper nybble of the message's data byte
 759         @param value            a value 0 to 15 for the lower nybble of the message's data byte
 760     */
 761     static MidiMessage quarterFrame (int sequenceNumber, int value) noexcept;
 762
 763     /** SMPTE timecode types.
 764         Used by the getFullFrameParameters() and fullFrame() methods.
 765     */
 766     enum SmpteTimecodeType
 767     {
 768         fps24       = 0,
 769         fps25       = 1,
 770         fps30drop   = 2,
 771         fps30       = 3
 772     };
 773
 774     /** Returns true if this is a full-frame midi timecode message. */
 775     bool isFullFrame() const noexcept;
 776
 777     /** Extracts the timecode information from a full-frame midi timecode message.
 778
 779         You should only call this on messages where you've used isFullFrame() to
 780         check that they're the right kind.
 781     */
 782     void getFullFrameParameters (int& hours,
 783                                  int& minutes,
 784                                  int& seconds,
 785                                  int& frames,
 786                                  SmpteTimecodeType& timecodeType) const noexcept;
 787
 788     /** Creates a full-frame MTC message. */
 789     static MidiMessage fullFrame (int hours,
 790                                   int minutes,
 791                                   int seconds,
 792                                   int frames,
 793                                   SmpteTimecodeType timecodeType);
 794
 795     //==============================================================================
 796     /** Types of MMC command.
 797
 798         @see isMidiMachineControlMessage, getMidiMachineControlCommand, midiMachineControlCommand
 799     */
 800     enum MidiMachineControlCommand
 801     {
 802         mmc_stop            = 1,
 803         mmc_play            = 2,
 804         mmc_deferredplay    = 3,
 805         mmc_fastforward     = 4,
 806         mmc_rewind          = 5,
 807         mmc_recordStart     = 6,
 808         mmc_recordStop      = 7,
 809         mmc_pause           = 9
 810     };
 811
 812     /** Checks whether this is an MMC message.
 813         If it is, you can use the getMidiMachineControlCommand() to find out its type.
 814     */
 815     bool isMidiMachineControlMessage() const noexcept;
 816
 817     /** For an MMC message, this returns its type.
 818
 819         Make sure it's actually an MMC message with isMidiMachineControlMessage() before
 820         calling this method.
 821     */
 822     MidiMachineControlCommand getMidiMachineControlCommand() const noexcept;
 823
 824     /** Creates an MMC message. */
 825     static MidiMessage midiMachineControlCommand (MidiMachineControlCommand command);
 826
 827     /** Checks whether this is an MMC "goto" message.
 828         If it is, the parameters passed-in are set to the time that the message contains.
 829         @see midiMachineControlGoto
 830     */
 831     bool isMidiMachineControlGoto (int& hours,
 832                                    int& minutes,
 833                                    int& seconds,
 834                                    int& frames) const noexcept;
 835
 836     /** Creates an MMC "goto" message.
 837         This messages tells the device to go to a specific frame.
 838         @see isMidiMachineControlGoto
 839     */
 840     static MidiMessage midiMachineControlGoto (int hours,
 841                                                int minutes,
 842                                                int seconds,
 843                                                int frames);
 844
 845     //==============================================================================
 846     /** Creates a master-volume change message.
 847         @param volume   the volume, 0 to 1.0
 848     */
 849     static MidiMessage masterVolume (float volume);
 850
 851     //==============================================================================
 852     /** Creates a system-exclusive message.
 853         The data passed in is wrapped with header and tail bytes of 0xf0 and 0xf7.
 854     */
 855     static MidiMessage createSysExMessage (const void* sysexData,
 856                                            int dataSize);
 857
 858
 859     //==============================================================================
 860    #ifndef DOXYGEN
 861     /** Reads a midi variable-length integer.
 862
 863         The `data` argument indicates the data to read the number from,
 864         and `numBytesUsed` is used as an out-parameter to indicate the number
 865         of bytes that were read.
 866     */
 867     [[deprecated ("This signature has been deprecated in favour of the safer readVariableLengthValue.")]]
 868     static int readVariableLengthVal (const uint8* data, int& numBytesUsed) noexcept;
 869    #endif
 870
 871     /** Holds information about a variable-length value which was parsed
 872         from a stream of bytes.
 873
 874         A valid value requires that `bytesUsed` is greater than 0.
 875     */
 876     struct VariableLengthValue
 877     {
 878         VariableLengthValue() = default;
 879
 880         VariableLengthValue (int valueIn, int bytesUsedIn)
 881             : value (valueIn), bytesUsed (bytesUsedIn) {}
 882
 883         bool isValid() const noexcept  { return bytesUsed > 0; }
 884
 885         int value = 0;
 886         int bytesUsed = 0;
 887     };
 888
 889     /** Reads a midi variable-length integer, with protection against buffer overflow.
 890
 891         @param data             the data to read the number from
 892         @param maxBytesToUse    the number of bytes in the region following `data`
 893         @returns                a struct containing the parsed value, and the number
 894                                 of bytes that were read. If parsing fails, both the
 895                                 `value` and `bytesUsed` fields will be set to 0 and
 896                                 `isValid()` will return false
 897     */
 898     static VariableLengthValue readVariableLengthValue (const uint8* data,
 899                                                         int maxBytesToUse) noexcept;
 900
 901     /** Based on the first byte of a short midi message, this uses a lookup table
 902         to return the message length (either 1, 2, or 3 bytes).
 903
 904         The value passed in must be 0x80 or higher.
 905     */
 906     static int getMessageLengthFromFirstByte (uint8 firstByte) noexcept;
 907
 908     //==============================================================================
 909     /** Returns the name of a midi note number.
 910
 911         E.g "C", "D#", etc.
 912
 913         @param noteNumber           the midi note number, 0 to 127
 914         @param useSharps            if true, sharpened notes are used, e.g. "C#", otherwise
 915                                     they'll be flattened, e.g. "Db"
 916         @param includeOctaveNumber  if true, the octave number will be appended to the string,
 917                                     e.g. "C#4"
 918         @param octaveNumForMiddleC  if an octave number is being appended, this indicates the
 919                                     number that will be used for middle C's octave
 920
 921         @see getMidiNoteInHertz
 922     */
 923     static String getMidiNoteName (int noteNumber,
 924                                    bool useSharps,
 925                                    bool includeOctaveNumber,
 926                                    int octaveNumForMiddleC);
 927
 928     /** Returns the frequency of a midi note number.
 929
 930         The frequencyOfA parameter is an optional frequency for 'A', normally 440-444Hz for concert pitch.
 931         @see getMidiNoteName
 932     */
 933     static double getMidiNoteInHertz (int noteNumber, double frequencyOfA = 440.0) noexcept;
 934
 935     /** Returns true if the given midi note number is a black key. */
 936     static bool isMidiNoteBlack (int noteNumber) noexcept;
 937
 938     /** Returns the standard name of a GM instrument, or nullptr if unknown for this index.
 939
 940         @param midiInstrumentNumber     the program number 0 to 127
 941         @see getProgramChangeNumber
 942     */
 943     static const char* getGMInstrumentName (int midiInstrumentNumber);
 944
 945     /** Returns the name of a bank of GM instruments, or nullptr if unknown for this bank number.
 946         @param midiBankNumber   the bank, 0 to 15
 947     */
 948     static const char* getGMInstrumentBankName (int midiBankNumber);
 949
 950     /** Returns the standard name of a channel 10 percussion sound, or nullptr if unknown for this note number.
 951         @param midiNoteNumber   the key number, 35 to 81
 952     */
 953     static const char* getRhythmInstrumentName (int midiNoteNumber);
 954
 955     /** Returns the name of a controller type number, or nullptr if unknown for this controller number.
 956         @see getControllerNumber
 957     */
 958     static const char* getControllerName (int controllerNumber);
 959
 960     /** Converts a floating-point value between 0 and 1 to a MIDI 7-bit value between 0 and 127. */
 961     static uint8 floatValueToMidiByte (float valueBetween0and1) noexcept;
 962
 963     /** Converts a pitchbend value in semitones to a MIDI 14-bit pitchwheel position value. */
 964     static uint16 pitchbendToPitchwheelPos (float pitchbendInSemitones,
 965                                             float pitchbendRangeInSemitones) noexcept;
 966
 967 private:
 968     //==============================================================================
 969    #ifndef DOXYGEN
 970     union PackedData
 971     {
 972         uint8* allocatedData;
 973         uint8 asBytes[sizeof (uint8*)];
 974     };
 975
 976     PackedData packedData;
 977     double timeStamp = 0;
 978     int size;
 979    #endif
 980
 981     inline bool isHeapAllocated() const noexcept  { return size > (int) sizeof (packedData); }
 982     inline uint8* getData() const noexcept        { return isHeapAllocated() ? packedData.allocatedData : const_cast<uint8*>(packedData.asBytes); }
 983     uint8* allocateSpace (int);
 984 };
 985
 986 } // namespace juce