Add MIDI Program Change, SysEx, NRPN, PitchBend and AfterTouch Output

packages/core/controls.mjs

@@ -1,5 +1,5 @@
 /*
-controls.mjs - <short description TODO>
+controls.mjs - Registers audio controls for pattern manipulation and effects.
 Copyright (C) 2022 Strudel contributors - see <https://github.com/tidalcycles/strudel/blob/main/packages/core/controls.mjs>
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
@@ -1509,20 +1509,10 @@ export const { scram } = registerControl('scram');
 export const { binshift } = registerControl('binshift');
 export const { hbrick } = registerControl('hbrick');
 export const { lbrick } = registerControl('lbrick');
-export const { midichan } = registerControl('midichan');
-export const { control } = registerControl('control');
-export const { ccn } = registerControl('ccn');
-export const { ccv } = registerControl('ccv');
-export const { polyTouch } = registerControl('polyTouch');
-export const { midibend } = registerControl('midibend');
-export const { miditouch } = registerControl('miditouch');
-export const { ctlNum } = registerControl('ctlNum');
 export const { frameRate } = registerControl('frameRate');
 export const { frames } = registerControl('frames');
 export const { hours } = registerControl('hours');
-export const { midicmd } = registerControl('midicmd');
 export const { minutes } = registerControl('minutes');
-export const { progNum } = registerControl('progNum');
 export const { seconds } = registerControl('seconds');
 export const { songPtr } = registerControl('songPtr');
 export const { uid } = registerControl('uid');
@@ -1614,3 +1604,136 @@ export const ar = register('ar', (t, pat) => {
   const [attack, release = attack] = t;
   return pat.set({ attack, release });
 });
+
+//MIDI
+
+/**
+ * MIDI channel: Sets the MIDI channel for the event.
+ *
+ * @name midichan
+ * @param {number | Pattern} channel MIDI channel number (0-15)
+ * @example
+ * note("c4").midichan(1).midi()
+ */
+export const { midichan } = registerControl('midichan');
+
+/**
+ * MIDI command: Sends a MIDI command message.
+ *
+ * @name midicmd
+ * @param {number | Pattern} command MIDI command
+ * @example
+ * midicmd("clock*48,<start stop>/2").midi()
+ */
+export const { midicmd } = registerControl('midicmd');
+
+/**
+ * MIDI control: Sends a MIDI control change message.
+ *
+ * @name control
+ * @param {number | Pattern}  MIDI control number (0-127)
+ * @param {number | Pattern}  MIDI controller value (0-127)
+ */
+export const control = register('control', (args, pat) => {
+  if (!Array.isArray(args)) {
+    throw new Error('control expects an array of [ccn, ccv]');
+  }
+  const [_ccn, _ccv] = args;
+  return pat.ccn(_ccn).ccv(_ccv);
+});
+
+/**
+ * MIDI control number: Sends a MIDI control change message.
+ *
+ * @name ccn
+ * @param {number | Pattern}  MIDI control number (0-127)
+ */
+export const { ccn } = registerControl('ccn');
+/**
+ * MIDI control value: Sends a MIDI control change message.
+ *
+ * @name ccv
+ * @param {number | Pattern}  MIDI control value (0-127)
+ */
+export const { ccv } = registerControl('ccv');
+export const { ctlNum } = registerControl('ctlNum');
+// TODO: ctlVal?
+
+/**
+ * MIDI NRPN non-registered parameter number: Sends a MIDI NRPN non-registered parameter number message.
+ * @name nrpnn
+ * @param {number | Pattern} nrpnn MIDI NRPN non-registered parameter number (0-127)
+ * @example
+ * note("c4").nrpnn("1:8").nrpv("123").midichan(1).midi()
+ */
+export const { nrpnn } = registerControl('nrpnn');
+/**
+ * MIDI NRPN non-registered parameter value: Sends a MIDI NRPN non-registered parameter value message.
+ * @name nrpv
+ * @param {number | Pattern} nrpv MIDI NRPN non-registered parameter value (0-127)
+ * @example
+ * note("c4").nrpnn("1:8").nrpv("123").midichan(1).midi()
+ */
+export const { nrpv } = registerControl('nrpv');
+
+/**
+ * MIDI program number: Sends a MIDI program change message.
+ *
+ * @name progNum
+ * @param {number | Pattern} program MIDI program number (0-127)
+ * @example
+ * note("c4").progNum(10).midichan(1).midi()
+ */
+export const { progNum } = registerControl('progNum');
+
+/**
+ * MIDI sysex: Sends a MIDI sysex message.
+ * @name sysex
+ * @param {number | Pattern} id Sysex ID
+ * @param {number | Pattern} data Sysex data
+ * @example
+ * note("c4").sysex(["0x77", "0x01:0x02:0x03:0x04"]).midichan(1).midi()
+ */
+export const sysex = register('sysex', (args, pat) => {
+  if (!Array.isArray(args)) {
+    throw new Error('sysex expects an array of [id, data]');
+  }
+  const [id, data] = args;
+  return pat.sysexid(id).sysexdata(data);
+});
+/**
+ * MIDI sysex ID: Sends a MIDI sysex identifier message.
+ * @name sysexid
+ * @param {number | Pattern} id Sysex ID
+ * @example
+ * note("c4").sysexid("0x77").sysexdata("0x01:0x02:0x03:0x04").midichan(1).midi()
+ */
+export const { sysexid } = registerControl('sysexid');
+/**
+ * MIDI sysex data: Sends a MIDI sysex message.
+ * @name sysexdata
+ * @param {number | Pattern} data Sysex data
+ * @example
+ * note("c4").sysexid("0x77").sysexdata("0x01:0x02:0x03:0x04").midichan(1).midi()
+ */
+export const { sysexdata } = registerControl('sysexdata');
+
+/**
+ * MIDI pitch bend: Sends a MIDI pitch bend message.
+ * @name midibend
+ * @param {number | Pattern} midibend MIDI pitch bend (-1 - 1)
+ * @example
+ * note("c4").midibend(sine.slow(4).range(-0.4,0.4)).midi()
+ */
+export const { midibend } = registerControl('midibend');
+/**
+ * MIDI key after touch: Sends a MIDI key after touch message.
+ * @name miditouch
+ * @param {number | Pattern} miditouch MIDI key after touch (0-1)
+ * @example
+ * note("c4").miditouch(sine.slow(4).range(0,1)).midi()
+ */
+export const { miditouch } = registerControl('miditouch');
+
+// TODO: what is this?
+export const { polyTouch } = registerControl('polyTouch');

packages/midi/README.md

@@ -7,3 +7,151 @@ This package adds midi functionality to strudel Patterns.
 ```sh
 npm i @strudel/midi --save
 ```
+
+## Available Controls
+
+The following MIDI controls are available:
+
+OUTPUT:
+
+- `midi` - opens a midi output device.
+- `note` - Sends MIDI note messages. Can accept note names (e.g. "c4") or MIDI note numbers (0-127)
+- `midichan` - Sets the MIDI channel (1-16, defaults to 1)
+- `velocity` - Sets note velocity (0-1, defaults to 0.9)
+- `gain` - Modifies velocity by multiplying with it (0-1, defaults to 1)
+- `control` - Sets MIDI control change messages
+- `ccn` - Sets MIDI CC controller number (0-127)
+- `ccv` - Sets MIDI CC value (0-1)
+- `progNum` - Sends MIDI program change messages (0-127)
+- `sysex` - Sends MIDI System Exclusive messages (id: number 0-127 or array of bytes 0-127, data: array of bytes 0-127)
+- `sysexid` - Sets MIDI System Exclusive ID (number 0-127 or array of bytes 0-127)
+- `sysexdata` - Sets MIDI System Exclusive data (array of bytes 0-127)
+- `midibend` - Sets MIDI pitch bend (-1 - 1)
+- `miditouch` - Sets MIDI key after touch (0-1)
+- `midicmd` - Sends MIDI system real-time messages to control timing and transport on MIDI devices.
+- `nrpnn` - Sets MIDI NRPN non-registered parameter number (array of bytes 0-127)
+- `nrpv` - Sets MIDI NRPN non-registered parameter value (0-127)
+
+
+INPUT:
+
+- `midin` - Opens a MIDI input port to receive MIDI control change messages.
+
+Additional controls can be mapped using the mapping object passed to `.midi()`:
+
+## Examples
+
+### midi(outputName?)
+
+Either connect a midi device or use the IAC Driver (Mac) or Midi Through Port (Linux) for internal midi messages.
+If no outputName is given, it uses the first midi output it finds.
+
+```javascript
+$: chord("<C^7 A7 Dm7 G7>").voicing().midi('IAC Driver')
+```
+
+In the console, you will see a log of the available MIDI devices as soon as you run the code, e.g. `Midi connected! Using "Midi Through Port-0".`
+
+### midichan(number)
+
+Selects the MIDI channel to use. If not used, `.midi` will use channel 1 by default.
+
+### control, ccn && ccv
+
+`control` sends MIDI control change messages to your MIDI device.
+
+- `ccn` sets the cc number. Depends on your synths midi mapping
+- `ccv` sets the cc value. normalized from 0 to 1.
+
+```javascript
+$: note("c a f e").control([74, sine.slow(4)]).midi()
+$: note("c a f e").ccn(74).ccv(sine.slow(4)).midi()
+```
+
+In the above snippet, `ccn` is set to 74, which is the filter cutoff for many synths. `ccv` is controlled by a saw pattern.
+Having everything in one pattern, the `ccv` pattern will be aligned to the note pattern, because the structure comes from the left by default.
+But you can also control cc messages separately like this:
+
+```javascript
+$: note("c a f e").midi()
+$: ccv(sine.segment(16).slow(4)).ccn(74).midi()
+```
+
+### progNum (Program Change)
+
+`progNum` control sends MIDI program change messages to switch between different presets/patches on your MIDI device.
+Program change values should be numbers between 0 and 127.
+
+```javascript
+// Play notes while changing programs
+note("c3 e3 g3").progNum("<0 1 2>").midi()
+```
+
+Program change messages are useful for switching between different instrument sounds or presets during a performance. 
+The exact sound that each program number maps to depends on your MIDI device's configuration.
+
+## sysex,  sysexid && sysexdata (System Exclusive Message)
+
+`sysex`, `sysexid` and `sysexdata` control sends MIDI System Exclusive (SysEx) messages to your MIDI device. 
+sysEx messages are device-specific commands that allow deeper control over synthesizer parameters. 
+The value should be an array of numbers between 0-255 representing the SysEx data bytes.
+
+```javascript
+// Send a simple SysEx message
+let id = 0x43; //Yamaha
+//let id = "0x00:0x20:0x32"; //Behringer ID can be an array of numbers
+let data = "0x79:0x09:0x11:0x0A:0x00:0x00"; // Set NSX-39 voice to say "Aa"
+$: note("c d e f e d c").sysex(id, data).midi();
+$: note("c d e f e d c").sysexid(id).sysexdata(data).midi();
+```
+
+The exact format of SysEx messages depends on your MIDI device's specification.
+Consult your device's MIDI implementation guide for details on supported SysEx messages.
+
+### midibend && miditouch
+
+`midibend` sets MIDI pitch bend (-1 - 1)
+`miditouch` sets MIDI key after touch (0-1)
+
+```javascript
+
+$: note("c d e f e d c").midibend(sine.slow(4).range(-0.4,0.4)).midi();
+$: note("c d e f e d c").miditouch(sine.slow(4).range(0,1)).midi();
+
+```
+
+### midicmd
+
+`midicmd` sends MIDI system real-time messages to control timing and transport on MIDI devices.
+
+It supports the following commands:
+
+- `clock`/`midiClock` - Sends MIDI timing clock messages
+- `start` - Sends MIDI start message
+- `stop` - Sends MIDI stop message
+- `continue` - Sends MIDI continue message
+
+```javascript
+// You can control the clock with a pattern and ensure it starts in sync when the repl begins.
+// Note: It might act unexpectedly if MIDI isn't set up initially.
+stack(
+  midicmd("clock*48,<start stop>/2").midi('IAC Driver') 
+)
+```
+
+`midicmd` also supports sending control change, program change and sysex messages.
+
+- `cc` - sends MIDI control change messages.
+- `progNum` - sends MIDI program change messages.
+- `sysex` - sends MIDI system exclusive messages.
+
+```javascript
+stack(
+  // "cc:ccn:ccv"
+  midicmd("cc:74:1").midi('IAC Driver'),
+  // "progNum:progNum"
+  midicmd("progNum:1").midi('IAC Driver'),
+  // "sysex:[sysexid]:[sysexdata]"
+  midicmd("sysex:[0x43]:[0x79:0x09:0x11:0x0A:0x00:0x00]").midi('IAC Driver')
+)
+```