source/modules/juce_audio_basics/mpe/juce_MPENote.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     This struct represents a playing MPE note.
  29
  30     A note is identified by a unique ID, or alternatively, by a MIDI channel
  31     and an initial note. It is characterised by five dimensions of continuous
  32     expressive control. Their current values are represented as
  33     MPEValue objects.
  34
  35     @see MPEValue
  36
  37     @tags{Audio}
  38 */
  39 struct JUCE_API  MPENote
  40 {
  41     //==============================================================================
  42     /** Possible values for the note key state. */
  43     enum KeyState
  44     {
  45         off                  = 0, /**< The key is up (off). */
  46         keyDown              = 1, /**< The note key is currently down (pressed). */
  47         sustained            = 2, /**< The note is sustained (by a sustain or sostenuto pedal). */
  48         keyDownAndSustained  = 3  /**< The note key is down and sustained (by a sustain or sostenuto pedal). */
  49     };
  50
  51     //==============================================================================
  52     /** Constructor.
  53
  54         @param midiChannel    The MIDI channel of the note, between 2 and 15.
  55                               (Channel 1 and channel 16 can never be note channels in MPE).
  56
  57         @param initialNote    The MIDI note number, between 0 and 127.
  58
  59         @param velocity       The note-on velocity of the note.
  60
  61         @param pitchbend      The initial per-note pitchbend of the note.
  62
  63         @param pressure       The initial pressure of the note.
  64
  65         @param timbre         The timbre value of the note.
  66
  67         @param keyState       The key state of the note (whether the key is down
  68                               and/or the note is sustained). This value must not
  69                               be MPENote::off, since you are triggering a new note.
  70                               (If not specified, the default value will be MPENote::keyDown.)
  71     */
  72     MPENote (int midiChannel,
  73              int initialNote,
  74              MPEValue velocity,
  75              MPEValue pitchbend,
  76              MPEValue pressure,
  77              MPEValue timbre,
  78              KeyState keyState = MPENote::keyDown) noexcept;
  79
  80     /** Default constructor.
  81
  82         Constructs an invalid MPE note (a note with the key state MPENote::off
  83         and an invalid MIDI channel. The only allowed use for such a note is to
  84         call isValid() on it; everything else is undefined behaviour.
  85     */
  86     MPENote() noexcept;
  87
  88     /** Checks whether the MPE note is valid. */
  89     bool isValid() const noexcept;
  90
  91     //==============================================================================
  92     // Invariants that define the note.
  93
  94     /** A unique ID. Useful to distinguish the note from other simultaneously
  95         sounding notes that may use the same note number or MIDI channel.
  96         This should never change during the lifetime of a note object.
  97     */
  98     uint16 noteID = 0;
  99
 100     /** The MIDI channel which this note uses.
 101         This should never change during the lifetime of an MPENote object.
 102     */
 103     uint8 midiChannel = 0;
 104
 105     /** The MIDI note number that was sent when the note was triggered.
 106         This should never change during the lifetime of an MPENote object.
 107     */
 108     uint8 initialNote = 0;
 109
 110     //==============================================================================
 111     // The five dimensions of continuous expressive control
 112
 113     /** The velocity ("strike") of the note-on.
 114         This dimension will stay constant after the note has been turned on.
 115     */
 116     MPEValue noteOnVelocity  { MPEValue::minValue() };
 117
 118     /** Current per-note pitchbend of the note (in units of MIDI pitchwheel
 119         position). This dimension can be modulated while the note sounds.
 120
 121         Note: This value is not aware of the currently used pitchbend range,
 122         or an additional master pitchbend that may be simultaneously applied.
 123         To compute the actual effective pitchbend of an MPENote, you should
 124         probably use the member totalPitchbendInSemitones instead.
 125
 126         @see totalPitchbendInSemitones, getFrequencyInHertz
 127     */
 128     MPEValue pitchbend       { MPEValue::centreValue() };
 129
 130     /** Current pressure with which the note is held down.
 131         This dimension can be modulated while the note sounds.
 132     */
 133     MPEValue pressure        { MPEValue::centreValue() };
 134
 135     /** Initial value of timbre when the note was triggered.
 136         This should never change during the lifetime of an MPENote object.
 137     */
 138     MPEValue initialTimbre   { MPEValue::centreValue() };
 139
 140     /** Current value of the note's third expressive dimension, typically
 141         encoding some kind of timbre parameter.
 142         This dimension can be modulated while the note sounds.
 143     */
 144     MPEValue timbre          { MPEValue::centreValue() };
 145
 146     /** The release velocity ("lift") of the note after a note-off has been
 147         received.
 148         This dimension will only have a meaningful value after a note-off has
 149         been received for the note (and keyState is set to MPENote::off or
 150         MPENote::sustained). Initially, the value is undefined.
 151     */
 152     MPEValue noteOffVelocity { MPEValue::minValue() };
 153
 154     //==============================================================================
 155     /** Current effective pitchbend of the note in units of semitones, relative
 156         to initialNote. You should use this to compute the actual effective pitch
 157         of the note. This value is computed and set by an MPEInstrument to the
 158         sum of the per-note pitchbend value (stored in MPEValue::pitchbend)
 159         and the master pitchbend of the MPE zone, weighted with the per-note
 160         pitchbend range and master pitchbend range of the zone, respectively.
 161
 162         @see getFrequencyInHertz
 163     */
 164     double totalPitchbendInSemitones;
 165
 166     /** Current key state. Indicates whether the note key is currently down (pressed)
 167         and/or the note is sustained (by a sustain or sostenuto pedal).
 168     */
 169     KeyState keyState        { MPENote::off };
 170
 171     //==============================================================================
 172     /** Returns the current frequency of the note in Hertz. This is the sum of
 173         the initialNote and the totalPitchbendInSemitones, converted to Hertz.
 174     */
 175     double getFrequencyInHertz (double frequencyOfA = 440.0) const noexcept;
 176
 177     /** Returns true if two notes are the same, determined by their unique ID. */
 178     bool operator== (const MPENote& other) const noexcept;
 179
 180     /** Returns true if two notes are different notes, determined by their unique ID. */
 181     bool operator!= (const MPENote& other) const noexcept;
 182 };
 183
 184 } // namespace juce