MidiMessage Class Reference

List of all members.

---

Detailed Description

Encapsulates a MIDI message.

See also:

MidiMessageSequence, MidiOutput, MidiInput

Public Types
enum	SmpteTimecodeType { fps24 = 0, fps25 = 1, fps30drop = 2, fps30 = 3 }
	SMPTE timecode types. More...
enum	MidiMachineControlCommand {   mmc_stop = 1, mmc_play = 2, mmc_deferredplay = 3, mmc_fastforward = 4,   mmc_rewind = 5, mmc_recordStart = 6, mmc_recordStop = 7, mmc_pause = 9 }
	Types of MMC command. More...
Public Member Functions
	MidiMessage (const int byte1, const int byte2, const int byte3, const double timeStamp=0) throw ()
	Creates a 3-byte short midi message.
	MidiMessage (const int byte1, const int byte2, const double timeStamp=0) throw ()
	Creates a 2-byte short midi message.
	MidiMessage (const int byte1, const double timeStamp=0) throw ()
	Creates a 1-byte short midi message.
	MidiMessage (const uint8 *const data, const int dataSize, const double timeStamp=0) throw ()
	Creates a midi message from a block of data.
	MidiMessage (const uint8 *data, int size, int &numBytesUsed, uint8 lastStatusByte, double timeStamp=0) throw ()
	Reads the next midi message from some data.
	MidiMessage (const MidiMessage &other) throw ()
	Creates a copy of another midi message.
	MidiMessage (const MidiMessage &other, const double newTimeStamp) throw ()
	Creates a copy of another midi message, with a different timestamp.
	~MidiMessage () throw ()
	Destructor.
const MidiMessage &	operator= (const MidiMessage &other) throw ()
	Copies this message from another one.
uint8 *	getRawData () const throw ()
	Returns a pointer to the raw midi data.
int	getRawDataSize () const throw ()
	Returns the number of bytes of data in the message.
double	getTimeStamp () const throw ()
	Returns the timestamp associated with this message.
void	setTimeStamp (const double newTimestamp) throw ()
	Changes the message's associated timestamp.
void	addToTimeStamp (const double delta) throw ()
	Adds a value to the message's timestamp.
int	getChannel () const throw ()
	Returns the midi channel associated with the message.
bool	isForChannel (const int channelNumber) const throw ()
	Returns true if the message applies to the given midi channel.
void	setChannel (const int newChannelNumber) throw ()
	Changes the message's midi channel.
bool	isSysEx () const throw ()
	Returns true if this is a system-exclusive message.
const uint8 *	getSysExData () const throw ()
	Returns a pointer to the sysex data inside the message.
int	getSysExDataSize () const throw ()
	Returns the size of the sysex data.
bool	isNoteOn () const throw ()
	Returns true if this message is a 'key-down' event.
bool	isNoteOff () const throw ()
	Returns true if this message is a 'key-up' event.
bool	isNoteOnOrOff () const throw ()
	Returns true if this message is a 'key-down' or 'key-up' event.
int	getNoteNumber () const throw ()
	Returns the midi note number for note-on and note-off messages.
void	setNoteNumber (const int newNoteNumber) throw ()
	Changes the midi note number of a note-on or note-off message.
uint8	getVelocity () const throw ()
	Returns the velocity of a note-on or note-off message.
float	getFloatVelocity () const throw ()
	Returns the velocity of a note-on or note-off message.
void	setVelocity (const float newVelocity) throw ()
	Changes the velocity of a note-on or note-off message.
void	multiplyVelocity (const float scaleFactor) throw ()
	Multiplies the velocity of a note-on or note-off message by a given amount.
bool	isProgramChange () const throw ()
	Returns true if the message is a program (patch) change message.
int	getProgramChangeNumber () const throw ()
	Returns the new program number of a program change message.
bool	isPitchWheel () const throw ()
	Returns true if the message is a pitch-wheel move.
int	getPitchWheelValue () const throw ()
	Returns the pitch wheel position from a pitch-wheel move message.
bool	isAftertouch () const throw ()
	Returns true if the message is an aftertouch event.
int	getAfterTouchValue () const throw ()
	Returns the amount of aftertouch from an aftertouch messages.
bool	isChannelPressure () const throw ()
	Returns true if the message is a channel-pressure change event.
int	getChannelPressureValue () const throw ()
	Returns the pressure from a channel pressure change message.
bool	isController () const throw ()
	Returns true if this is a midi controller message.
int	getControllerNumber () const throw ()
	Returns the controller number of a controller message.
int	getControllerValue () const throw ()
	Returns the controller value from a controller message.
bool	isAllNotesOff () const throw ()
	Checks whether this message is an all-notes-off message.
bool	isAllSoundOff () const throw ()
	Checks whether this message is an all-sound-off message.
bool	isMetaEvent () const throw ()
	Returns true if this event is a meta-event.
int	getMetaEventType () const throw ()
	Returns a meta-event's type number.
const uint8 *	getMetaEventData () const throw ()
	Returns a pointer to the data in a meta-event.
int	getMetaEventLength () const throw ()
	Returns the length of the data for a meta-event.
bool	isTrackMetaEvent () const throw ()
	Returns true if this is a 'track' meta-event.
bool	isEndOfTrackMetaEvent () const throw ()
	Returns true if this is an 'end-of-track' meta-event.
bool	isTrackNameEvent () const throw ()
	Returns true if this is an 'track name' meta-event.
bool	isTextMetaEvent () const throw ()
	Returns true if this is a 'text' meta-event.
const String	getTextFromTextMetaEvent () const throw ()
	Returns the text from a text meta-event.
bool	isTempoMetaEvent () const throw ()
	Returns true if this is a 'tempo' meta-event.
double	getTempoMetaEventTickLength (const short timeFormat) const throw ()
	Returns the tick length from a tempo meta-event.
double	getTempoSecondsPerQuarterNote () const throw ()
	Calculates the seconds-per-quarter-note from a tempo meta-event.
bool	isTimeSignatureMetaEvent () const throw ()
	Returns true if this is a 'time-signature' meta-event.
void	getTimeSignatureInfo (int &numerator, int &denominator) const throw ()
	Returns the time-signature values from a time-signature meta-event.
bool	isKeySignatureMetaEvent () const throw ()
	Returns true if this is a 'key-signature' meta-event.
int	getKeySignatureNumberOfSharpsOrFlats () const throw ()
	Returns the key from a key-signature meta-event.
bool	isMidiChannelMetaEvent () const throw ()
	Returns true if this is a 'channel' meta-event.
int	getMidiChannelMetaEventChannel () const throw ()
	Returns the channel number from a channel meta-event.
bool	isActiveSense () const throw ()
	Returns true if this is an active-sense message.
bool	isMidiStart () const throw ()
	Returns true if this is a midi start event.
bool	isMidiContinue () const throw ()
	Returns true if this is a midi continue event.
bool	isMidiStop () const throw ()
	Returns true if this is a midi stop event.
bool	isMidiClock () const throw ()
	Returns true if this is a midi clock event.
bool	isSongPositionPointer () const throw ()
	Returns true if this is a song-position-pointer message.
int	getSongPositionPointerMidiBeat () const throw ()
	Returns the midi beat-number of a song-position-pointer message.
bool	isQuarterFrame () const throw ()
	Returns true if this is a quarter-frame midi timecode message.
int	getQuarterFrameSequenceNumber () const throw ()
	Returns the sequence number of a quarter-frame midi timecode message.
int	getQuarterFrameValue () const throw ()
	Returns the value from a quarter-frame message.
bool	isFullFrame () const throw ()
	Returns true if this is a full-frame midi timecode message.
void	getFullFrameParameters (int &hours, int &minutes, int &seconds, int &frames, SmpteTimecodeType &timecodeType) const throw ()
	Extracts the timecode information from a full-frame midi timecode message.
bool	isMidiMachineControlMessage () const throw ()
	Checks whether this is an MMC message.
MidiMachineControlCommand	getMidiMachineControlCommand () const throw ()
	For an MMC message, this returns its type.
bool	isMidiMachineControlGoto (int &hours, int &minutes, int &seconds, int &frames) const throw ()
	Checks whether this is an MMC "goto" message.
Static Public Member Functions
static const MidiMessage	noteOn (const int channel, const int noteNumber, const float velocity) throw ()
	Creates a key-down message (using a floating-point velocity).
static const MidiMessage	noteOn (const int channel, const int noteNumber, const uint8 velocity) throw ()
	Creates a key-down message (using an integer velocity).
static const MidiMessage	noteOff (const int channel, const int noteNumber) throw ()
	Creates a key-up message.
static const MidiMessage	programChange (const int channel, const int programNumber) throw ()
	Creates a program-change message.
static const MidiMessage	pitchWheel (const int channel, const int position) throw ()
	Creates a pitch-wheel move message.
static const MidiMessage	aftertouchChange (const int channel, const int noteNumber, const int aftertouchAmount) throw ()
	Creates an aftertouch message.
static const MidiMessage	channelPressureChange (const int channel, const int pressure) throw ()
	Creates a channel-pressure change event.
static const MidiMessage	controllerEvent (const int channel, const int controllerType, const int value) throw ()
	Creates a controller message.
static const MidiMessage	allNotesOff (const int channel) throw ()
	Creates an all-notes-off message.
static const MidiMessage	allSoundOff (const int channel) throw ()
	Creates an all-sound-off message.
static const MidiMessage	allControllersOff (const int channel) throw ()
	Creates an all-controllers-off message.
static const MidiMessage	endOfTrack () throw ()
	Creates an end-of-track meta-event.
static const MidiMessage	tempoMetaEvent (const int microsecondsPerQuarterNote) throw ()
	Creates a tempo meta-event.
static const MidiMessage	timeSignatureMetaEvent (const int numerator, const int denominator) throw ()
	Creates a time-signature meta-event.
static const MidiMessage	midiChannelMetaEvent (const int channel) throw ()
	Creates a midi channel meta-event.
static const MidiMessage	midiStart () throw ()
	Creates a midi start event.
static const MidiMessage	midiContinue () throw ()
	Creates a midi continue event.
static const MidiMessage	midiStop () throw ()
	Creates a midi stop event.
static const MidiMessage	midiClock () throw ()
	Creates a midi clock event.
static const MidiMessage	songPositionPointer (const int positionInMidiBeats) throw ()
	Creates a song-position-pointer message.
static const MidiMessage	quarterFrame (const int sequenceNumber, const int value) throw ()
	Creates a quarter-frame MTC message.
static const MidiMessage	fullFrame (const int hours, const int minutes, const int seconds, const int frames, SmpteTimecodeType timecodeType)
	Creates a full-frame MTC message.
static const MidiMessage	midiMachineControlCommand (MidiMachineControlCommand command)
	Creates an MMC message.
static const MidiMessage	midiMachineControlGoto (int hours, int minutes, int seconds, int frames)
	Creates an MMC "goto" message.
static const MidiMessage	masterVolume (const float volume) throw ()
	Creates a master-volume change message.
static const MidiMessage	createSysExMessage (const uint8 *sysexData, const int dataSize) throw ()
	Creates a system-exclusive message.
static int	readVariableLengthVal (const uint8 *data, int &numBytesUsed) throw ()
	Reads a midi variable-length integer.
static int	getMessageLengthFromFirstByte (const uint8 firstByte) throw ()
	Based on the first byte of a short midi message, this uses a lookup table to return the message length (either 1, 2, or 3 bytes).
static const String	getMidiNoteName (int noteNumber, bool useSharps, bool includeOctaveNumber, int octaveNumForMiddleC) throw ()
	Returns the name of a midi note number.
static const double	getMidiNoteInHertz (int noteNumber) throw ()
	Returns the frequency of a midi note number.
static const String	getGMInstrumentName (int midiInstrumentNumber) throw ()
	Returns the standard name of a GM instrument.
static const String	getGMInstrumentBankName (int midiBankNumber) throw ()
	Returns the name of a bank of GM instruments.
static const String	getRhythmInstrumentName (int midiNoteNumber) throw ()
	Returns the standard name of a channel 10 percussion sound.
static const String	getControllerName (int controllerNumber) throw ()
	Returns the name of a controller type number.

---

Member Enumeration Documentation

enum MidiMessage::SmpteTimecodeType

SMPTE timecode types. Used by the getFullFrameParameters() and fullFrame() methods. Enumerator: fps24  fps25  fps30drop  fps30

enum MidiMessage::MidiMachineControlCommand

Types of MMC command. See also: isMidiMachineControlMessage, getMidiMachineControlCommand, midiMachineControlCommand Enumerator: mmc_stop  mmc_play  mmc_deferredplay  mmc_fastforward  mmc_rewind  mmc_recordStart  mmc_recordStop  mmc_pause

---

Constructor & Destructor Documentation

MidiMessage::MidiMessage (  const int  byte1, const int  byte2, const int  byte3, const double  timeStamp = 0 )  throw ()

Creates a 3-byte short midi message. Parameters: byte1  message byte 1 byte2  message byte 2 byte3  message byte 3 timeStamp  the time to give the midi message - this value doesn't use any particular units, so will be application-specific

MidiMessage::MidiMessage (  const int  byte1, const int  byte2, const double  timeStamp = 0 )  throw ()

Creates a 2-byte short midi message. Parameters: byte1  message byte 1 byte2  message byte 2 timeStamp  the time to give the midi message - this value doesn't use any particular units, so will be application-specific

MidiMessage::MidiMessage (  const int  byte1, const double  timeStamp = 0 )  throw ()

Creates a 1-byte short midi message. Parameters: byte1  message byte 1 timeStamp  the time to give the midi message - this value doesn't use any particular units, so will be application-specific

MidiMessage::MidiMessage (  const uint8 *const   data, const int  dataSize, const double  timeStamp = 0 )  throw ()

Creates a midi message from a block of data.

MidiMessage::MidiMessage (  const uint8 *  data, int  size, int &  numBytesUsed, uint8  lastStatusByte, double  timeStamp = 0 )  throw ()

Reads the next midi message from some data. This will read as many bytes from a data stream as it needs to make a complete message, and will return the number of bytes it used. This lets you read a sequence of midi messages from a file or stream. Parameters: data  the data to read from size  the maximum number of bytes it's allowed to read numBytesUsed  returns the number of bytes that were actually needed lastStatusByte  in a sequence of midi messages, the initial byte can be dropped from a message if it's the same as the first byte of the previous message, so this lets you supply the byte to use if the first byte of the message has in fact been dropped. timeStamp  the time to give the midi message - this value doesn't use any particular units, so will be application-specific

MidiMessage::MidiMessage (  const MidiMessage &  other  )  throw ()

Creates a copy of another midi message.

MidiMessage::MidiMessage (  const MidiMessage &  other, const double  newTimeStamp )  throw ()

Creates a copy of another midi message, with a different timestamp.

MidiMessage::~MidiMessage (   )  throw ()

Destructor.

---

Member Function Documentation

const MidiMessage& MidiMessage::operator= (  const MidiMessage &  other  )  throw ()

Copies this message from another one.

uint8* MidiMessage::getRawData (   )  const throw ()

Returns a pointer to the raw midi data. See also: getRawDataSize

int MidiMessage::getRawDataSize (   )  const throw ()

Returns the number of bytes of data in the message. See also: getRawData

double MidiMessage::getTimeStamp (   )  const throw ()

Returns the timestamp associated with this message. The units for the timestamp will be application-specific. See also: setTimeStamp, addToTimeStamp

void MidiMessage::setTimeStamp (  const double  newTimestamp  )  throw ()

Changes the message's associated timestamp. The units for the timestamp will be application-specific. See also: addToTimeStamp, getTimeStamp

void MidiMessage::addToTimeStamp (  const double  delta  )  throw ()

Adds a value to the message's timestamp. The units for the timestamp will be application-specific.

int MidiMessage::getChannel (   )  const throw ()

Returns the midi channel associated with the message. Returns: a value 1 to 16 if the message has a channel, or 0 if it hasn't (e.g. if it's a sysex) See also: isForChannel, setChannel

bool MidiMessage::isForChannel (  const int  channelNumber  )  const throw ()

Returns true if the message applies to the given midi channel. Parameters: channelNumber  the channel number to look for, in the range 1 to 16 See also: getChannel, setChannel

void MidiMessage::setChannel (  const int  newChannelNumber  )  throw ()

Changes the message's midi channel. This won't do anything for non-channel messages like sysexes. Parameters: newChannelNumber  the channel number to change it to, in the range 1 to 16

bool MidiMessage::isSysEx (   )  const throw ()

Returns true if this is a system-exclusive message.

const uint8* MidiMessage::getSysExData (   )  const throw ()

Returns a pointer to the sysex data inside the message. If this event isn't a sysex event, it'll return 0. See also: getSysExDataSize

int MidiMessage::getSysExDataSize (   )  const throw ()

Returns the size of the sysex data. This value excludes the 0xf0 header byte and the 0xf7 at the end. See also: getSysExData

bool MidiMessage::isNoteOn (   )  const throw ()

Returns true if this message is a 'key-down' event. This will return false for a note-on event with a velocity of 0. See also: isNoteOff, getNoteNumber, getVelocity, noteOn

static const MidiMessage MidiMessage::noteOn (  const int  channel, const int  noteNumber, const float  velocity )  throw () [static]

Creates a key-down message (using a floating-point velocity). Parameters: channel  the midi channel, in the range 1 to 16 noteNumber  the key number, 0 to 127 velocity  in the range 0 to 1.0 See also: isNoteOn

static const MidiMessage MidiMessage::noteOn (  const int  channel, const int  noteNumber, const uint8  velocity )  throw () [static]

Creates a key-down message (using an integer velocity). Parameters: channel  the midi channel, in the range 1 to 16 noteNumber  the key number, 0 to 127 velocity  in the range 0 to 127 See also: isNoteOn

bool MidiMessage::isNoteOff (   )  const throw ()

Returns true if this message is a 'key-up' event. This will also return true for a note-on event with a velocity of 0. See also: isNoteOn, getNoteNumber, getVelocity, noteOff

static const MidiMessage MidiMessage::noteOff (  const int  channel, const int  noteNumber )  throw () [static]

Creates a key-up message. Parameters: channel  the midi channel, in the range 1 to 16 noteNumber  the key number, 0 to 127 See also: isNoteOff

bool MidiMessage::isNoteOnOrOff (   )  const throw ()

Returns true if this message is a 'key-down' or 'key-up' event. See also: isNoteOn, isNoteOff

int MidiMessage::getNoteNumber (   )  const throw ()

Returns the midi note number for note-on and note-off messages. If the message isn't a note-on or off, the value returned will be meaningless. See also: isNoteOff, getMidiNoteName, getMidiNoteInHertz, setNoteNumber

void MidiMessage::setNoteNumber (  const int  newNoteNumber  )  throw ()

Changes the midi note number of a note-on or note-off message. If the message isn't a note on or off, this will do nothing.

uint8 MidiMessage::getVelocity (   )  const throw ()

Returns the velocity of a note-on or note-off message. The value returned will be in the range 0 to 127. If the message isn't a note-on or off event, it will return 0. See also: getFloatVelocity

float MidiMessage::getFloatVelocity (   )  const throw ()

Returns the velocity of a note-on or note-off message. The value returned will be in the range 0 to 1.0 If the message isn't a note-on or off event, it will return 0. See also: getVelocity, setVelocity

void MidiMessage::setVelocity (  const float  newVelocity  )  throw ()

Changes the velocity of a note-on or note-off message. If the message isn't a note on or off, this will do nothing. Parameters: newVelocity  the new velocity, in the range 0 to 1.0 See also: getFloatVelocity, multiplyVelocity

void MidiMessage::multiplyVelocity (  const float  scaleFactor  )  throw ()

Multiplies the velocity of a note-on or note-off message by a given amount. If the message isn't a note on or off, this will do nothing. Parameters: scaleFactor  the value by which to multiply the velocity See also: setVelocity

bool MidiMessage::isProgramChange (   )  const throw ()

Returns true if the message is a program (patch) change message. See also: getProgramChangeNumber, getGMInstrumentName

int MidiMessage::getProgramChangeNumber (   )  const throw ()

Returns the new program number of a program change message. If the message isn't a program change, the value returned will be nonsense. See also: isProgramChange, getGMInstrumentName

static const MidiMessage MidiMessage::programChange (  const int  channel, const int  programNumber )  throw () [static]

Creates a program-change message. Parameters: channel  the midi channel, in the range 1 to 16 programNumber  the midi program number, 0 to 127 See also: isProgramChange, getGMInstrumentName

bool MidiMessage::isPitchWheel (   )  const throw ()

Returns true if the message is a pitch-wheel move. See also: getPitchWheelValue, pitchWheel

int MidiMessage::getPitchWheelValue (   )  const throw ()

Returns the pitch wheel position from a pitch-wheel move message. The value returned is a 14-bit number from 0 to 0x3fff, indicating the wheel position. If called for messages which aren't pitch wheel events, the number returned will be nonsense. See also: isPitchWheel

static const MidiMessage MidiMessage::pitchWheel (  const int  channel, const int  position )  throw () [static]

Creates a pitch-wheel move message. Parameters: channel  the midi channel, in the range 1 to 16 position  the wheel position, in the range 0 to 16383 See also: isPitchWheel

bool MidiMessage::isAftertouch (   )  const throw ()

Returns true if the message is an aftertouch event. For aftertouch events, use the getNoteNumber() method to find out the key that it applies to, and getAftertouchValue() to find out the amount. Use getChannel() to find out the channel. See also: getAftertouchValue, getNoteNumber

int MidiMessage::getAfterTouchValue (   )  const throw ()

Returns the amount of aftertouch from an aftertouch messages. The value returned is in the range 0 to 127, and will be nonsense for messages other than aftertouch messages. See also: isAftertouch

static const MidiMessage MidiMessage::aftertouchChange (  const int  channel, const int  noteNumber, const int  aftertouchAmount )  throw () [static]

Creates an aftertouch message. Parameters: channel  the midi channel, in the range 1 to 16 noteNumber  the key number, 0 to 127 aftertouchAmount  the amount of aftertouch, 0 to 127 See also: isAftertouch

bool MidiMessage::isChannelPressure (   )  const throw ()

Returns true if the message is a channel-pressure change event. This is like aftertouch, but common to the whole channel rather than a specific note. Use getChannelPressureValue() to find out the pressure, and getChannel() to find out the channel. See also: channelPressureChange

int MidiMessage::getChannelPressureValue (   )  const throw ()

Returns the pressure from a channel pressure change message. Returns: the pressure, in the range 0 to 127 See also: isChannelPressure, channelPressureChange

static const MidiMessage MidiMessage::channelPressureChange (  const int  channel, const int  pressure )  throw () [static]

Creates a channel-pressure change event. Parameters: channel  the midi channel: 1 to 16 pressure  the pressure, 0 to 127 See also: isChannelPressure

bool MidiMessage::isController (   )  const throw ()

Returns true if this is a midi controller message. See also: getControllerNumber, getControllerValue, controllerEvent

int MidiMessage::getControllerNumber (   )  const throw ()

Returns the controller number of a controller message. The name of the controller can be looked up using the getControllerName() method. Note that the value returned is invalid for messages that aren't controller changes. See also: isController, getControllerName, getControllerValue

int MidiMessage::getControllerValue (   )  const throw ()

Returns the controller value from a controller message. A value 0 to 127 is returned to indicate the new controller position. Note that the value returned is invalid for messages that aren't controller changes. See also: isController, getControllerNumber

static const MidiMessage MidiMessage::controllerEvent (  const int  channel, const int  controllerType, const int  value )  throw () [static]

Creates a controller me