juce/source/src/audio/midi/juce_MidiMessage.h

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