OpenShot Library | OpenShotAudio 0.2.2
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
27namespace 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. */
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/** @}*/
This class represents a single value for any of the MPE dimensions of control.
Definition: juce_MPEValue.h:41
static MPEValue centreValue() noexcept
Constructs an MPEValue corresponding to the centre value.
static MPEValue minValue() noexcept
Constructs an MPEValue corresponding to the minimum value.
#define JUCE_API
This macro is added to all JUCE public class declarations.
This struct represents a playing MPE note.
Definition: juce_MPENote.h:44
KeyState
Possible values for the note key state.
Definition: juce_MPENote.h:48
@ keyDown
The note key is currently down (pressed).
Definition: juce_MPENote.h:50
@ off
The key is up (off).
Definition: juce_MPENote.h:49
double totalPitchbendInSemitones
Current effective pitchbend of the note in units of semitones, relative to initialNote.
Definition: juce_MPENote.h:168