OpenShot Library | libopenshot-audio  0.2.0
juce_MPENote.h
1 
2 /** @weakgroup juce_audio_basics-mpe
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  This struct represents a playing MPE note.
33 
34  A note is identified by a unique ID, or alternatively, by a MIDI channel
35  and an initial note. It is characterised by five dimensions of continuous
36  expressive control. Their current values are represented as
37  MPEValue objects.
38 
39  @see MPEValue
40 
41  @tags{Audio}
42 */
44 {
45  //==============================================================================
46  /** Possible values for the note key state. */
47  enum KeyState
48  {
49  off = 0, /**< The key is up (off). */
50  keyDown = 1, /**< The note key is currently down (pressed). */
51  sustained = 2, /**< The note is sustained (by a sustain or sostenuto pedal). */
52  keyDownAndSustained = 3 /**< The note key is down and sustained (by a sustain or sostenuto pedal). */
53  };
54 
55  //==============================================================================
56  /** Constructor.
57 
58  @param midiChannel The MIDI channel of the note, between 2 and 15.
59  (Channel 1 and channel 16 can never be note channels in MPE).
60 
61  @param initialNote The MIDI note number, between 0 and 127.
62 
63  @param velocity The note-on velocity of the note.
64 
65  @param pitchbend The initial per-note pitchbend of the note.
66 
67  @param pressure The initial pressure of the note.
68 
69  @param timbre The timbre value of the note.
70 
71  @param keyState The key state of the note (whether the key is down
72  and/or the note is sustained). This value must not
73  be MPENote::off, since you are triggering a new note.
74  (If not specified, the default value will be MPENote::keyDown.)
75  */
76  MPENote (int midiChannel,
77  int initialNote,
78  MPEValue velocity,
79  MPEValue pitchbend,
80  MPEValue pressure,
81  MPEValue timbre,
82  KeyState keyState = MPENote::keyDown) noexcept;
83 
84  /** Default constructor.
85 
86  Constructs an invalid MPE note (a note with the key state MPENote::off
87  and an invalid MIDI channel. The only allowed use for such a note is to
88  call isValid() on it; everything else is undefined behaviour.
89  */
90  MPENote() noexcept;
91 
92  /** Checks whether the MPE note is valid. */
93  bool isValid() const noexcept;
94 
95  //==============================================================================
96  // Invariants that define the note.
97 
98  /** A unique ID. Useful to distinguish the note from other simultaneously
99  sounding notes that may use the same note number or MIDI channel.
100  This should never change during the lifetime of a note object.
101  */
102  uint16 noteID = 0;
103 
104  /** The MIDI channel which this note uses.
105  This should never change during the lifetime of an MPENote object.
106  */
107  uint8 midiChannel = 0;
108 
109  /** The MIDI note number that was sent when the note was triggered.
110  This should never change during the lifetime of an MPENote object.
111  */
112  uint8 initialNote = 0;
113 
114  //==============================================================================
115  // The five dimensions of continuous expressive control
116 
117  /** The velocity ("strike") of the note-on.
118  This dimension will stay constant after the note has been turned on.
119  */
120  MPEValue noteOnVelocity { MPEValue::minValue() };
121 
122  /** Current per-note pitchbend of the note (in units of MIDI pitchwheel
123  position). This dimension can be modulated while the note sounds.
124 
125  Note: This value is not aware of the currently used pitchbend range,
126  or an additional master pitchbend that may be simultaneously applied.
127  To compute the actual effective pitchbend of an MPENote, you should
128  probably use the member totalPitchbendInSemitones instead.
129 
130  @see totalPitchbendInSemitones, getFrequencyInHertz
131  */
133 
134  /** Current pressure with which the note is held down.
135  This dimension can be modulated while the note sounds.
136  */
138 
139  /** Initial value of timbre when the note was triggered.
140  This should never change during the lifetime of an MPENote object.
141  */
142  MPEValue initialTimbre { MPEValue::centreValue() };
143 
144  /** Current value of the note's third expressive dimension, typically
145  encoding some kind of timbre parameter.
146  This dimension can be modulated while the note sounds.
147  */
149 
150  /** The release velocity ("lift") of the note after a note-off has been
151  received.
152  This dimension will only have a meaningful value after a note-off has
153  been received for the note (and keyState is set to MPENote::off or
154  MPENote::sustained). Initially, the value is undefined.
155  */
156  MPEValue noteOffVelocity { MPEValue::minValue() };
157 
158  //==============================================================================
159  /** Current effective pitchbend of the note in units of semitones, relative
160  to initialNote. You should use this to compute the actual effective pitch
161  of the note. This value is computed and set by an MPEInstrument to the
162  sum of the per-note pitchbend value (stored in MPEValue::pitchbend)
163  and the master pitchbend of the MPE zone, weighted with the per-note
164  pitchbend range and master pitchbend range of the zone, respectively.
165 
166  @see getFrequencyInHertz
167  */
169 
170  /** Current key state. Indicates whether the note key is currently down (pressed)
171  and/or the note is sustained (by a sustain or sostenuto pedal).
172  */
173  KeyState keyState { MPENote::off };
174 
175  //==============================================================================
176  /** Returns the current frequency of the note in Hertz. This is the sum of
177  the initialNote and the totalPitchbendInSemitones, converted to Hertz.
178  */
179  double getFrequencyInHertz (double frequencyOfA = 440.0) const noexcept;
180 
181  /** Returns true if two notes are the same, determined by their unique ID. */
182  bool operator== (const MPENote& other) const noexcept;
183 
184  /** Returns true if two notes are different notes, determined by their unique ID. */
185  bool operator!= (const MPENote& other) const noexcept;
186 };
187 
188 } // namespace juce
189 
190 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
The key is up (off).
Definition: juce_MPENote.h:49
KeyState
Possible values for the note key state.
Definition: juce_MPENote.h:47
The note key is currently down (pressed).
Definition: juce_MPENote.h:50
static MPEValue centreValue() noexcept
Constructs an MPEValue corresponding to the centre value.
double totalPitchbendInSemitones
Current effective pitchbend of the note in units of semitones, relative to initialNote.
Definition: juce_MPENote.h:168
This struct represents a playing MPE note.
Definition: juce_MPENote.h:43
This class represents a single value for any of the MPE dimensions of control.
Definition: juce_MPEValue.h:40
static MPEValue minValue() noexcept
Constructs an MPEValue corresponding to the minimum value.