#[non_exhaustive]
pub enum NoteEvent<S> {
Show 18 variants
NoteOn {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
velocity: f32,
},
NoteOff {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
velocity: f32,
},
Choke {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
},
VoiceTerminated {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
},
PolyModulation {
timing: u32,
voice_id: i32,
poly_modulation_id: u32,
normalized_offset: f32,
},
MonoAutomation {
timing: u32,
poly_modulation_id: u32,
normalized_value: f32,
},
PolyPressure {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
pressure: f32,
},
PolyVolume {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
gain: f32,
},
PolyPan {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
pan: f32,
},
PolyTuning {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
tuning: f32,
},
PolyVibrato {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
vibrato: f32,
},
PolyExpression {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
expression: f32,
},
PolyBrightness {
timing: u32,
voice_id: Option<i32>,
channel: u8,
note: u8,
brightness: f32,
},
MidiChannelPressure {
timing: u32,
channel: u8,
pressure: f32,
},
MidiPitchBend {
timing: u32,
channel: u8,
value: f32,
},
MidiCC {
timing: u32,
channel: u8,
cc: u8,
value: f32,
},
MidiProgramChange {
timing: u32,
channel: u8,
program: u8,
},
MidiSysEx {
timing: u32,
message: S,
},
}Expand description
Event for (incoming) notes. The set of supported note events depends on the value of
Plugin::MIDI_INPUT. Also check out the
util module for convenient conversion functions.
S is a MIDI SysEx message type that needs to implement SysExMessage to allow converting
this NoteEvent to and from raw MIDI data. () is provided as a default implementing for
plugins that don’t use SysEx.
All of the timings are sample offsets within the current buffer. Out of bound timings are clamped to the current buffer’s length. All sample, channel and note numbers are zero-indexed.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
NoteOn
Fields
A note on event, available on MidiConfig::Basic and up.
NoteOff
Fields
A note off event, available on MidiConfig::Basic and up. Bitwig Studio does not provide
a voice ID for this event.
Choke
Fields
A note choke event, available on MidiConfig::Basic and up. When the host sends this to
the plugin, it indicates that a voice or all sound associated with a note should immediately
stop playing.
VoiceTerminated
Fields
Sent by the plugin to the host to indicate that a voice has ended. This needs to be sent when a voice terminates when using polyphonic modulation. Otherwise you can ignore this event.
PolyModulation
Fields
voice_id: i32The identifier of the voice this polyphonic modulation event should affect. This voice should use the values from this and subsequent polyphonic modulation events instead of the global value.
A polyphonic modulation event, available on MidiConfig::Basic and up. This will only be
sent for parameters that were decorated with the .with_poly_modulation_id() modifier, and
only by supported hosts. This event contains a normalized offset value for the parameter’s
current, unmodulated value. That is, an offset for the current value before monophonic
modulation is applied, as polyphonic modulation overrides monophonic modulation. There are
multiple ways to incorporate this polyphonic modulation into a synthesizer, but a simple way
to incorporate this would work as follows:
- By default, a voice uses the parameter’s global value, which may or may not include
monophonic modulation. This is
parameter.valuefor unsmoothed parameters, and smoothed parameters should use block smoothing so the smoothed values can be reused by multiple voices. - If a
PolyModulationevent is emitted for the voice, that voice should use the the normalized offset contained within the event to compute the voice’s modulated value and use that in place of the global value.- This value can be obtained by calling
param.preview_plain(param.normalized_value() + event.normalized_offset). These functions automatically clamp the values as necessary. - If the parameter uses smoothing, then the parameter’s smoother can be copied to the
voice.
Smoother::set_target()can then be used to have the smoother use the modulated value. - One caveat with smoothing is that copying the smoother like this only works correctly if it last
produced a value during the sample before the
PolyModulationevent. Otherwise there may still be an audible jump in parameter values. A solution for this would be to first call theSmoother::reset()with the current sample’s global value before callingset_target(). - Finally, if the polyphonic modulation happens on the same sample as the
NoteOnevent, then the smoothing should not start at the current global value. In this case,reset()should be called with the voice’s modulated value.
- This value can be obtained by calling
- If a
MonoAutomationevent is emitted for a parameter, then the values or target values (if the parameter uses smoothing) for all voices must be updated. The normalized value from theMonoAutomationand the voice’s normalized modulation offset must be added and converted back to a plain value. This value can be used directly for unsmoothed parameters, or passed toset_target()for smoothed parameters. The global value will have already been updated, so this event only serves as a notification to update polyphonic modulation. - When a voice ends, either because the amplitude envelope has hit zero or because the voice
was stolen, the plugin must send a
VoiceTerminatedto the host to let it know that it can reuse the resources it used to modulate the value.
MonoAutomation
Fields
A notification to inform the plugin that a polyphonically modulated parameter has received a
new automation value. This is used in conjunction with the PolyModulation event. See that
event’s documentation for more details. The parameter’s global value has already been
updated when this event is emitted.
PolyPressure
Fields
A polyphonic note pressure/aftertouch event, available on MidiConfig::Basic and up. Not
all hosts may support polyphonic aftertouch.
Note
When implementing MPE support you should use MIDI channel pressure instead as polyphonic key pressure + MPE is undefined as per the MPE specification. Or as a more generic catch all, you may manually combine the polyphonic key pressure and MPE channel pressure.
PolyVolume
Fields
A volume expression event, available on MidiConfig::Basic and up. Not all hosts may
support these expressions.
PolyPan
Fields
A panning expression event, available on MidiConfig::Basic and up. Not all hosts may
support these expressions.
PolyTuning
Fields
A tuning expression event, available on MidiConfig::Basic and up. Not all hosts may support
these expressions.
PolyVibrato
Fields
A vibrato expression event, available on MidiConfig::Basic and up. Not all hosts may support
these expressions.
PolyExpression
Fields
A expression expression (yes, expression expression) event, available on
MidiConfig::Basic and up. Not all hosts may support these expressions.
PolyBrightness
Fields
A brightness expression event, available on MidiConfig::Basic and up. Not all hosts may support
these expressions.
MidiChannelPressure
Fields
A MIDI channel pressure event, available on MidiConfig::MidiCCs and up.
MidiPitchBend
Fields
A MIDI pitch bend, available on MidiConfig::MidiCCs and up.
MidiCC
Fields
cc: u8The control change number. See control_change for a list of CC numbers.
A MIDI control change event, available on MidiConfig::MidiCCs and up.
Note
The wrapper does not perform any special handling for two message 14-bit CCs (where the CC
number is in 0..32, and the next CC is that number plus 32) or for four message RPN
messages. For now you will need to handle these CCs yourself.
MidiProgramChange
Fields
A MIDI program change event, available on MidiConfig::MidiCCs and up. VST3 plugins
cannot receive these events.
MidiSysEx
A MIDI SysEx message supported by the plugin’s SysExMessage type, available on
MidiConfig::Basic and up. If the conversion from the raw byte array fails (e.g. the
plugin doesn’t support this kind of message), then this will be logged during debug builds
of the plugin, and no event is emitted.
Implementations§
source§impl<S: SysExMessage> NoteEvent<S>
impl<S: SysExMessage> NoteEvent<S>
sourcepub fn from_midi(timing: u32, midi_data: &[u8]) -> Result<Self, u8>
pub fn from_midi(timing: u32, midi_data: &[u8]) -> Result<Self, u8>
Parse MIDI into a NoteEvent. Supports both basic three bytes messages as well as SysEx.
Will return Err(event_type) if the parsing failed.
sourcepub fn as_midi(self) -> Option<MidiResult<S>>
pub fn as_midi(self) -> Option<MidiResult<S>>
Create a MIDI message from this note event. Returns None if this even does not have a
direct MIDI equivalent. PolyPressure will be converted to polyphonic key pressure, but the
other polyphonic note expression types will not be converted to MIDI CC messages.