From 0fc394f0a764d42ec7d3edf6d3c17153db4ebf3b Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:30:39 -0500 Subject: [PATCH 1/3] Expand some note and note expression doc The comments in #380 showed some places where our note and note expression doc had too much implicit knowledge. Try to address that with a few short paragraphs explainign the protocol --- include/clap/events.h | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 0839e961..3b451e29 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -151,13 +151,28 @@ enum { typedef struct clap_event_note { clap_event_header_t header; - int32_t note_id; // -1 if unspecified, otherwise >=0 - int16_t port_index; - int16_t channel; // 0..15 - int16_t key; // 0..127 + int32_t note_id; // host provided note id, -1 if unspecified or wildcard + int16_t port_index; // Port index from ext/note-ports; -1 for wildcard + int16_t channel; // 0..15, same as MIDI1 Channel Number, -1 for wildcard + int16_t key; // 0..127, same as MIDI1 Key Number (60==Middle C), -1 for wildcard double velocity; // 0..1 } clap_event_note_t; +// Note Expressions are well named modifications of a voice targeted to +// voices using the same wildcard rules described above. Note Expressions are delivered +// as sample accurate events and should be applied at the sample when received. +// +// Note expressions are a statement of value, not cumulative. A PAN event of 0 followed by 1 +// followed by 0.5 would pan hard left, hard right, and center. They are intended as +// an offset from the non-note-expression voice default. A voice which had a volume of +// -20db absent note expressions which received a +4db note expression would move the +// voice to -16db. +// +// A plugin which receives a note expression at the same sample as a NOTE_ON event +// should apply that expression to all generated samples. A plugin which receives +// a note expression after a NOTE_ON event should initiate the voice with default +// values and then apply the note expression when received. A plugin may make a choice +// to smooth note expression streams. enum { // with 0 < x <= 4, plain = 20 * log(x) CLAP_NOTE_EXPRESSION_VOLUME = 0, @@ -165,7 +180,7 @@ enum { // pan, 0 left, 0.5 center, 1 right CLAP_NOTE_EXPRESSION_PAN = 1, - // relative tuning in semitone, from -120 to +120 + // relative tuning in semitone, from -120 to +120, in equal temperament CLAP_NOTE_EXPRESSION_TUNING = 2, // 0..1 From a0f68596be3edd8c8f5dbf0b23a89b8497510a64 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:32:33 -0500 Subject: [PATCH 2/3] small tweak --- include/clap/events.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 3b451e29..84978ad0 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -151,8 +151,8 @@ enum { typedef struct clap_event_note { clap_event_header_t header; - int32_t note_id; // host provided note id, -1 if unspecified or wildcard - int16_t port_index; // Port index from ext/note-ports; -1 for wildcard + int32_t note_id; // host provided note id >= 0, or -1 if unspecified or wildcard + int16_t port_index; // port index from ext/note-ports; -1 for wildcard int16_t channel; // 0..15, same as MIDI1 Channel Number, -1 for wildcard int16_t key; // 0..127, same as MIDI1 Key Number (60==Middle C), -1 for wildcard double velocity; // 0..1 From 1e41950725d066fef19175c3dcf01324c6b5c380 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:59:52 -0500 Subject: [PATCH 3/3] Update changelog per abique request --- ChangeLog.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index a3342bd5..2cbdf2e3 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -47,6 +47,8 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Documentation * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works +* [events.h](include/clap/events.h): Clarify how `clap_event_note` fields map to MIDI, Host, etc... +* [events.h](include/clap/events.h): Expand clap note expression documentation * [plugin.h](include/clap/plugin.h): Style cleanup * [params.h](include/clap/ext/params.h): Fix incorrect function name reference * [latency.h](include/clap/ext/latency.h): Require the plugin to be activated to get the latency and clarify that the latency can only be fetched when the plugin is activated