Add MIDI_Pipes-Filter example

Author: tttapa

doxygen/pages/MIDI.md

@@ -868,8 +868,17 @@ void loop() {
 }
 ```
 
+### Filtering or modifying messages passing through a pipe {#midi_md-pipes-filtering}
+
+It is possible to create custom MIDI pipes that can filter out certain MIDI
+messages, or even modify the MIDI messages that pass through them (for instance,
+to change the channel of certain messages). This is done by inheriting from
+the @ref MIDI_Pipe class and overriding the @ref MIDI_Pipe::mapForwardMIDI
+functions. See @ref MIDI_Pipes-Filter.ino for more details.
+
 ### More examples {#midi_md-routing-more-examples}
 
 - @ref MIDI_Pipes-Routing.ino
 - @ref Dual-MIDI-Interface.ino
 - @ref MIDI-Monitor.ino
+- @ref MIDI_Pipes-Filter.ino

examples/3. MIDI Interfaces/MIDI_Pipes-Filter/MIDI_Pipes-Filter.ino

@@ -0,0 +1,70 @@
+/**
+ * @brief Filtering and modifying MIDI messages that travel through a MIDI_Pipe.
+ * 
+ * This example demonstrates how to create custom MIDI pipes that can filter out
+ * and modify the messages that travel through it. It uses a debug MIDI 
+ * interface for demonstration purposes, and loops back only MIDI note and
+ * real-time messages, messages of any other type are dropped. Additionally, all
+ * MIDI note messages are transposed down an octave, and their channel is set
+ * to 5.
+ * 
+ * To try it out, open the Serial monitor (at 115200 baud) and type `98 3C 7F`
+ * (Note On, channel 9, C4, full velocity). When you press enter, you'll get
+ * back the following message (note how the channel and pitch changed):
+ *
+ * ```
+ * Note On    Channel: 5    Data 1: 0x30    Data 2: 0x7F
+ * ```
+ *
+ * If you try to send a Pitch Bend message (for example, `E0 12 34`), you'll get
+ * no response, because the code filtered it out.
+ * 
+ * @boards  AVR, AVR USB, Nano Every, Due, Nano 33 IoT, Nano 33 BLE, UNO R4, Pi Pico, ESP32, Teensy 3.x
+ */
+
+#include <Control_Surface.h>
+
+USBDebugMIDI_Interface midi;
+
+// A unidirectional pipe that connects a MIDI source to a MIDI sink.
+// Messages coming from the source are handled by the `mapForwardMIDI()`
+// function, where they can be modified or filtered out, and then sent
+// to the MIDI sink by calling the `sourceMIDItoSink()` function.
+struct MyMIDIFilter : MIDI_Pipe {
+  // Pass on only Note On/Off messages, changing the channel to 5 and
+  // transposing all notes an octave down.
+  void mapForwardMIDI(ChannelMessage msg) override {
+    switch (msg.getMessageType()) {
+      case MIDIMessageType::NoteOff:  // fallthrough
+      case MIDIMessageType::NoteOn:
+        msg.setChannel(Channel_5);
+        if (msg.data1 >= 12)
+          msg.data1 -= 12;
+        sourceMIDItoSink(msg);
+        break;
+      default: break;
+    }
+  }
+  // Do not pass on System Exclusive messages.
+  void mapForwardMIDI(SysExMessage) override {}
+  // Do not pass on System Common messages.
+  void mapForwardMIDI(SysCommonMessage) override {}
+  // Pass on Real-Time messages without changes.
+  void mapForwardMIDI(RealTimeMessage msg) override {
+    sourceMIDItoSink(msg);
+  }
+};
+
+MyMIDIFilter filter;
+
+void setup() {
+  // Loop back the MIDI input to the MIDI output, through the filter:
+  // (MIDI input) -> (MIDI filter) -> (MIDI output)
+  // (source)     ->    (pipe)     ->        (sink)
+      midi        >>    filter     >>         midi;
+  midi.begin();
+}
+
+void loop() {
+  midi.update();
+}

examples/examples.dox

@@ -1498,20 +1498,20 @@
  * Program Change   Channel: 9 Data 1: 0x06
  * Channel Pressure Channel: 3 Data 1: 0x40
  * Pitch Bend       Channel: 3 Data 1: 0x7f  Data 2: 0x7f (16383)
- * System Common    MTC_QUARTER_FRAME  Data 1: 0x2f
- * System Common    SONG_POSITION_POINTER  Data 1: 0x10  Data 2: 0x4e (10000)
- * System Common    SONG_SELECT  Data 1: 0x46
- * System Common    TUNE_REQUEST
+ * System Common    MTCQuarterFrame    Data 1: 0x2f
+ * System Common    SongPositionPointer    Data 1: 0x10  Data 2: 0x4e (10000)
+ * System Common    SongSelect Data 1: 0x46
+ * System Common    TuneRequest
  * System Exclusive [10] F0 00 01 02 03 04 05 06 07 F7
  * System Exclusive [6+] F0 10 11 12 13 14
  * System Exclusive [6+] 15 16 17 18 19 1A
  * System Exclusive [6]  1B 1C 1D 1E 1F F7
- * Real-Time        TIMING_CLOCK
- * Real-Time        START
- * Real-Time        CONTINUE
- * Real-Time        STOP
- * Real-Time        ACTIVE_SENSING
- * Real-Time        SYSTEM_RESET
+ * Real-Time        TimingClock
+ * Real-Time        Start
+ * Real-Time        Continue
+ * Real-Time        Stop
+ * Real-Time        ActiveSensing
+ * Real-Time        SystemReset
  * ~~~
  *
  * @see @ref midi_md-sending "MIDI Tutorial: Sending MIDI messages"
@@ -1555,6 +1555,35 @@
  * https://github.com/tttapa/Control-Surface
  */
 
+/**
+ * @example   "MIDI_Pipes-Filter.ino"
+ * 
+ * MIDI_Pipes-Filter
+ * =================
+ *
+ * @brief Filtering and modifying MIDI messages that travel through a MIDI_Pipe.
+ * 
+ * This example demonstrates how to create custom MIDI pipes that can filter out
+ * and modify the messages that travel through it. It uses a debug MIDI 
+ * interface for demonstration purposes, and loops back only MIDI note and
+ * real-time messages, messages of any other type are dropped. Additionally, all
+ * MIDI note messages are transposed down an octave, and their channel is set
+ * to 5.
+ * 
+ * To try it out, open the Serial monitor (at 115200 baud) and type `98 3C 7F`
+ * (Note On, channel 9, C4, full velocity). When you press enter, you'll get
+ * back the following message (note how the channel and pitch changed):
+ *
+ * ```
+ * Note On    Channel: 5    Data 1: 0x30    Data 2: 0x7F
+ * ```
+ *
+ * If you try to send a Pitch Bend message (for example, `E0 12 34`), you'll get
+ * no response, because the code filtered it out.
+ * 
+ * @boards  AVR, AVR USB, Nano Every, Due, Nano 33 IoT, Nano 33 BLE, UNO R4, Pi Pico, ESP32, Teensy 3.x
+ */
+
 /**
  * @example   "Bank.ino"
  *