OpenShot Audio Library | OpenShotAudio: juce::MPEInstrument Class Reference

OpenShot Audio Library | OpenShotAudio 0.3.2

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Protected Attributes | List of all members
juce::MPEInstrument Class Reference

`#include <juce_MPEInstrument.h>`

## Classes
class | Listener

## Public Types
enum | TrackingMode { lastNotePlayedOnChannel , lowestNoteOnChannel , highestNoteOnChannel , allNotesOnChannel }

## Public Member Functions
| MPEInstrument () noexcept
virtual | ~MPEInstrument ()
MPEZoneLayout | getZoneLayout () const noexcept
void | setZoneLayout (MPEZoneLayout newLayout)
bool | isMemberChannel (int midiChannel) const noexcept
bool | isMasterChannel (int midiChannel) const noexcept
bool | isUsingChannel (int midiChannel) const noexcept
void | setPressureTrackingMode (TrackingMode modeToUse)
void | setPitchbendTrackingMode (TrackingMode modeToUse)
void | setTimbreTrackingMode (TrackingMode modeToUse)
virtual void | processNextMidiEvent (const MidiMessage &message)
virtual void | noteOn (int midiChannel, int midiNoteNumber, MPEValue midiNoteOnVelocity)
virtual void | noteOff (int midiChannel, int midiNoteNumber, MPEValue midiNoteOffVelocity)
virtual void | pitchbend (int midiChannel, MPEValue pitchbend)
virtual void | pressure (int midiChannel, MPEValue value)
virtual void | timbre (int midiChannel, MPEValue value)
virtual void | polyAftertouch (int midiChannel, int midiNoteNumber, MPEValue value)
virtual void | sustainPedal (int midiChannel, bool isDown)
virtual void | sostenutoPedal (int midiChannel, bool isDown)
void | releaseAllNotes ()
int | getNumPlayingNotes () const noexcept
MPENote | getNote (int index) const noexcept
MPENote | getNote (int midiChannel, int midiNoteNumber) const noexcept
MPENote | getMostRecentNote (int midiChannel) const noexcept
MPENote | getMostRecentNoteOtherThan (MPENote otherThanThisNote) const noexcept
void | addListener (Listener *listenerToAdd)
void | removeListener (Listener *listenerToRemove)
void | enableLegacyMode (int pitchbendRange=2, Range< int > channelRange=Range< int >(1, 17))
bool | isLegacyModeEnabled () const noexcept
Range< int > | getLegacyModeChannelRange () const noexcept
void | setLegacyModeChannelRange (Range< int > channelRange)
int | getLegacyModePitchbendRange () const noexcept
void | setLegacyModePitchbendRange (int pitchbendRange)

## Protected Attributes
CriticalSection | lock

## Detailed Description

This class represents an instrument handling MPE.

It has an MPE zone layout and maintains a state of currently active (playing) notes and the values of their dimensions of expression.

You can trigger and modulate notes:

- by passing MIDI messages with the method processNextMidiEvent;
- by directly calling the methods noteOn, noteOff etc.

The class implements the channel and note management logic specified in MPE. If you pass it a message, it will know what notes on what channels (if any) should be affected by that message.

The class has a Listener class with the three callbacks MPENoteAdded, MPENoteChanged, and MPENoteFinished. Implement such a Listener class to react to note changes and trigger some functionality for your application that depends on the MPE note state. For example, you can use this class to write an MPE visualiser.

If you want to write a real-time audio synth with MPE functionality, you should instead use the classes MPESynthesiserBase, which adds the ability to render audio and to manage voices.

See also
  MPENote, MPEZoneLayout, MPESynthesiser

Definition at line 55 of file juce_MPEInstrument.h.

## Member Enumeration Documentation

## ◆ TrackingMode

enum juce::MPEInstrument::TrackingMode

The MPE note tracking mode. In case there is more than one note playing simultaneously on the same MIDI channel, this determines which of these notes will be modulated by an incoming MPE message on that channel (pressure, pitchbend, or timbre).

The default is lastNotePlayedOnChannel.

Enumerator
lastNotePlayedOnChannel | The most recent note on the channel that is still played (key down and/or sustained).
lowestNoteOnChannel | The lowest note (by initialNote) on the channel with the note key still down.
highestNoteOnChannel | The highest note (by initialNote) on the channel with the note key still down.
allNotesOnChannel | All notes on the channel (key down and/or sustained).

Definition at line 118 of file juce_MPEInstrument.h.

## Constructor & Destructor Documentation

## ◆ MPEInstrument()

juce::MPEInstrument::MPEInstrument | ( |  | ) |
| noexcept

Constructor.

This will construct an MPE instrument with inactive lower and upper zones.

In order to process incoming MIDI, call setZoneLayout, define the layout via MIDI RPN messages, or set the instrument to legacy mode.

Definition at line 33 of file juce_MPEInstrument.cpp.

## ◆ ~MPEInstrument()

juce::MPEInstrument::~MPEInstrument | ( |  | ) |
| virtual

Destructor.

Definition at line 51 of file juce_MPEInstrument.cpp.

## Member Function Documentation

## ◆ addListener()

void juce::MPEInstrument::addListener | ( | Listener * | listenerToAdd | ) |

Adds a listener.

Definition at line 132 of file juce_MPEInstrument.cpp.

## ◆ enableLegacyMode()

void juce::MPEInstrument::enableLegacyMode | ( | int | pitchbendRange = `2`,
|  | Range< int > | channelRange = `Range<int> (1, 17)`
| ) |  |

Puts the instrument into legacy mode. As a side effect, this will discard all currently playing notes, and call noteReleased for all of them.

This special zone layout mode is for backwards compatibility with non-MPE MIDI devices. In this mode, the instrument will ignore the current MPE zone layout. It will instead take a range of MIDI channels (default: all channels 1-16) and treat them as note channels, with no master channel. MIDI channels outside of this range will be ignored.

Parameters

  pitchbendRange | The note pitchbend range in semitones to use when in legacy mode. Must be between 0 and 96, otherwise behaviour is undefined. The default pitchbend range in legacy mode is +/- 2 semitones.
  channelRange | The range of MIDI channels to use for notes when in legacy mode. The default is to use all MIDI channels (1-16).

To get out of legacy mode, set a new MPE zone layout using setZoneLayout.

Definition at line 71 of file juce_MPEInstrument.cpp.

## ◆ getLegacyModeChannelRange()

Range< int > juce::MPEInstrument::getLegacyModeChannelRange | ( |  | ) | const
| noexcept

Returns the range of MIDI channels (1-16) to be used for notes when in legacy mode.

Definition at line 87 of file juce_MPEInstrument.cpp.

## ◆ getLegacyModePitchbendRange()

int juce::MPEInstrument::getLegacyModePitchbendRange | ( |  | ) | const
| noexcept

Returns the pitchbend range in semitones (0-96) to be used for notes when in legacy mode.

Definition at line 101 of file juce_MPEInstrument.cpp.

## ◆ getMostRecentNote()

MPENote juce::MPEInstrument::getMostRecentNote | ( | int | midiChannel | ) | const
| noexcept

Returns the most recent note that is playing on the given midiChannel (this will be the note which has received the most recent note-on without a corresponding note-off), if there is such a note. Otherwise, this returns an invalid MPENote (check with note.isValid() before use!)

Definition at line 646 of file juce_MPEInstrument.cpp.

## ◆ getMostRecentNoteOtherThan()

MPENote juce::MPEInstrument::getMostRecentNoteOtherThan | ( | MPENote | otherThanThisNote | ) | const
| noexcept

Returns the most recent note that is not the note passed in. If there is no such note, this returns an invalid MPENote (check with note.isValid() before use!).

This helper method might be useful for some custom voice handling algorithms.

Definition at line 654 of file juce_MPEInstrument.cpp.

## ◆ getNote() [1/2]

MPENote juce::MPEInstrument::getNote | ( | int | index | ) | const
| noexcept

Returns the note at the given index.

If there is no such note, returns an invalid MPENote. The notes are sorted such that the most recently added note is the last element.

Definition at line 640 of file juce_MPEInstrument.cpp.

## ◆ getNote() [2/2]

MPENote juce::MPEInstrument::getNote | ( | int | midiChannel,
|  | int | midiNoteNumber
| ) |  | const
| noexcept

Returns the note currently playing on the given midiChannel with the specified initial MIDI note number, if there is such a note. Otherwise, this returns an invalid MPENote (check with note.isValid() before use!)

Definition at line 632 of file juce_MPEInstrument.cpp.

## ◆ getNumPlayingNotes()

int juce::MPEInstrument::getNumPlayingNotes | ( |  | ) | const
| noexcept

Returns the number of MPE notes currently played by the instrument.

Definition at line 627 of file juce_MPEInstrument.cpp.

## ◆ getZoneLayout()

MPEZoneLayout juce::MPEInstrument::getZoneLayout | ( |  | ) | const
| noexcept

Returns the current zone layout of the instrument. This happens by value, to enforce thread-safety and class invariants.

Note: If the instrument is in legacy mode, the return value of this method is unspecified.

Definition at line 56 of file juce_MPEInstrument.cpp.

## ◆ isLegacyModeEnabled()

bool juce::MPEInstrument::isLegacyModeEnabled | ( |  | ) | const
| noexcept

Returns true if the instrument is in legacy mode, false otherwise.

Definition at line 82 of file juce_MPEInstrument.cpp.

## ◆ isMasterChannel()

bool juce::MPEInstrument::isMasterChannel | ( | int | midiChannel | ) | const
| noexcept

Returns true if the given MIDI channel (1-16) is a master channel (channel 1 or 16).

In legacy mode, this will always return false.

Definition at line 605 of file juce_MPEInstrument.cpp.

## ◆ isMemberChannel()

bool juce::MPEInstrument::isMemberChannel | ( | int | midiChannel | ) | const
| noexcept

Returns true if the given MIDI channel (1-16) is a note channel in any of the MPEInstrument's MPE zones; false otherwise.

When in legacy mode, this will return true if the given channel is contained in the current legacy mode channel range; false otherwise.

Definition at line 596 of file juce_MPEInstrument.cpp.

## ◆ isUsingChannel()

bool juce::MPEInstrument::isUsingChannel | ( | int | midiChannel | ) | const
| noexcept

Returns true if the given MIDI channel (1-16) is used by any of the MPEInstrument's MPE zones; false otherwise.

When in legacy mode, this will return true if the given channel is contained in the current legacy mode channel range; false otherwise.

Definition at line 617 of file juce_MPEInstrument.cpp.

Referenced by noteOff(), and noteOn().

## ◆ noteOff()

void juce::MPEInstrument::noteOff | ( | int | midiChannel,
|  | int | midiNoteNumber,
|  | MPEValue | midiNoteOffVelocity
| ) |  |
| virtual

Request a note-off.

If there is a matching playing note, this will release the note (except if it is sustained by a sustain or sostenuto pedal) and call the noteReleased callback.

Definition at line 325 of file juce_MPEInstrument.cpp.

## ◆ noteOn()

void juce::MPEInstrument::noteOn | ( | int | midiChannel,
|  | int | midiNoteNumber,
|  | MPEValue | midiNoteOnVelocity
| ) |  |
| virtual

Request a note-on on the given channel, with the given initial note number and velocity.

If the message arrives on a valid note channel, this will create a new MPENote and call the noteAdded callback.

Definition at line 293 of file juce_MPEInstrument.cpp.

## ◆ pitchbend()

void juce::MPEInstrument::pitchbend | ( | int | midiChannel,
|  | MPEValue | pitchbend
| ) |  |
| virtual

Request a pitchbend on the given channel with the given value (in units of MIDI pitchwheel position).

Internally, this will determine whether the pitchwheel move is a per-note pitchbend or a master pitchbend (depending on midiChannel), take the correct per-note or master pitchbend range of the affected MPE zone, and apply the resulting pitchbend to the affected note(s) (if any).

Definition at line 360 of file juce_MPEInstrument.cpp.

## ◆ polyAftertouch()

void juce::MPEInstrument::polyAftertouch | ( | int | midiChannel,
|  | int | midiNoteNumber,
|  | MPEValue | value
| ) |  |
| virtual

Request a poly-aftertouch change for a given note number.

The change will be broadcast to all notes sharing the channel and note number of the change message.

Definition at line 378 of file juce_MPEInstrument.cpp.

## ◆ pressure()

void juce::MPEInstrument::pressure | ( | int | midiChannel,
|  | MPEValue | value
| ) |  |
| virtual

Request a pressure change on the given channel with the given value.

This will modify the pressure dimension of the note currently held down on this channel (if any). If the channel is a zone master channel, the pressure change will be broadcast to all notes in this zone.

Definition at line 366 of file juce_MPEInstrument.cpp.

## ◆ processNextMidiEvent()

void juce::MPEInstrument::processNextMidiEvent | ( | const MidiMessage & | message | ) |
| virtual

Process a MIDI message and trigger the appropriate method calls (noteOn, noteOff etc.)

You can override this method if you need some special MIDI message treatment on top of the standard MPE logic implemented here.

Definition at line 143 of file juce_MPEInstrument.cpp.

## ◆ releaseAllNotes()

void juce::MPEInstrument::releaseAllNotes | ( |  | ) |

Discard all currently playing notes.

This will also call the noteReleased listener callback for all of them.

Definition at line 779 of file juce_MPEInstrument.cpp.

Referenced by enableLegacyMode(), setLegacyModeChannelRange(), setLegacyModePitchbendRange(), and setZoneLayout().

## ◆ removeListener()

void juce::MPEInstrument::removeListener | ( | Listener * | listenerToRemove | ) |

Removes a listener.

Definition at line 137 of file juce_MPEInstrument.cpp.

## ◆ setLegacyModeChannelRange()

void juce::MPEInstrument::setLegacyModeChannelRange | ( | Range< int > | channelRange | ) |

Re-sets the range of MIDI channels (1-16) to be used for notes when in legacy mode.

Definition at line 92 of file juce_MPEInstrument.cpp.

## ◆ setLegacyModePitchbendRange()

void juce::MPEInstrument::setLegacyModePitchbendRange | ( | int | pitchbendRange | ) |

Re-sets the pitchbend range in semitones (0-96) to be used for notes when in legacy mode.

Definition at line 106 of file juce_MPEInstrument.cpp.

## ◆ setPitchbendTrackingMode()

void juce::MPEInstrument::setPitchbendTrackingMode | ( | TrackingMode | modeToUse | ) |

Set the MPE tracking mode for the pitchbend dimension.

Definition at line 121 of file juce_MPEInstrument.cpp.

## ◆ setPressureTrackingMode()

void juce::MPEInstrument::setPressureTrackingMode | ( | TrackingMode | modeToUse | ) |

Set the MPE tracking mode for the pressure dimension.

Definition at line 116 of file juce_MPEInstrument.cpp.

## ◆ setTimbreTrackingMode()

void juce::MPEInstrument::setTimbreTrackingMode | ( | TrackingMode | modeToUse | ) |

Set the MPE tracking mode for the timbre dimension.

Definition at line 126 of file juce_MPEInstrument.cpp.

## ◆ setZoneLayout()

void juce::MPEInstrument::setZoneLayout | ( | MPEZoneLayout | newLayout | ) |

Re-sets the zone layout of the instrument to the one passed in. As a side effect, this will discard all currently playing notes, and call noteReleased for all of them.

This will also disable legacy mode in case it was enabled previously.

Definition at line 61 of file juce_MPEInstrument.cpp.

## ◆ sostenutoPedal()

void juce::MPEInstrument::sostenutoPedal | ( | int | midiChannel,
|  | bool | isDown
| ) |  |
| virtual

Request a sostenuto pedal press or release.

If midiChannel is a zone's master channel, this will act on all notes in that zone; otherwise, nothing will happen.

Definition at line 534 of file juce_MPEInstrument.cpp.

## ◆ sustainPedal()

void juce::MPEInstrument::sustainPedal | ( | int | midiChannel,
|  | bool | isDown
| ) |  |
| virtual

Request a sustain pedal press or release.

If midiChannel is a zone's master channel, this will act on all notes in that zone; otherwise, nothing will happen.

Definition at line 528 of file juce_MPEInstrument.cpp.

## ◆ timbre()

void juce::MPEInstrument::timbre | ( | int | midiChannel,
|  | MPEValue | value
| ) |  |
| virtual

Request a third dimension (timbre) change on the given channel with the given value.

This will modify the timbre dimension of the note currently held down on this channel (if any). If the channel is a zone master channel, the timbre change will be broadcast to all notes in this zone.

Definition at line 372 of file juce_MPEInstrument.cpp.

## Member Data Documentation

## ◆ lock

CriticalSection juce::MPEInstrument::lock
| protected

Definition at line 349 of file juce_MPEInstrument.h.

The documentation for this class was generated from the following files:

- juce_MPEInstrument.h
- juce_MPEInstrument.cpp