add documentation for pc and sysex

packages/midi/README.md

@@ -7,3 +7,89 @@ This package adds midi functionality to strudel Patterns.
 ```sh
 npm i @strudel/midi --save
 ```
+
+
+## Available Controls
+
+The following MIDI controls are available:
+
+- `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)
+- `ccn` - Sets MIDI CC controller number (0-127)
+- `ccv` - Sets MIDI CC value (0-1)
+- `pc` - Sends MIDI program change messages (0-127)
+- `sysex` - Sends MIDI System Exclusive messages (array of bytes 0-255)
+
+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()
+```
+
+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.
+
+### ccn && ccv
+
+- `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").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()
+```
+
+### pc (Program Change)
+
+The `pc` 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").pc("<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 (System Exclusive Message)
+
+The `sysex` control sends MIDI System Exclusive (SysEx) messages to your MIDI device. 
+ysEx 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
+sysex([0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7]).midi()
+```
+
+```javascript
+//Send SysEx while playing notes
+note("c3 e3 g3")
+  .sysex("<[0xF0,0x7E,0x7F,0x09,0x01,0xF7] [0xF0,0x7E,0x7F,0x09,0x02,0xF7]>")
+  .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.

website/src/pages/learn/input-output.mdx

@@ -45,10 +45,42 @@ But you can also control cc messages separately like this:
 $: ccv(sine.segment(16).slow(4)).ccn(74).midi()`}
 />
 
-# OSC/SuperDirt API
+## pc (Program Change)
 
-In mainline tidal, the actual sound is generated via [SuperDirt](https://github.com/musikinformatik/SuperDirt/), which runs inside SuperCollider.
-Strudel also supports using [SuperDirt](https://github.com/musikinformatik/SuperDirt/) as a backend, although it requires some developer tooling to run.
+The `pc` 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.
+
+<MiniRepl client:idle tune={`// Switch between programs 0 and 1 every cycle
+pc("<0 1>").midi()
+
+// Play notes while changing programs
+note("c3 e3 g3").pc("<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 (System Exclusive Message)
+
+The `sysex` control sends MIDI System Exclusive (SysEx) messages to your MIDI device.
+ysEx 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.
+
+<MiniRepl client:idle tune={`// Send a simple SysEx message
+sysex([0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7]).midi()
+
+// Send SysEx while playing notes
+note("c3 e3 g3")
+.sysex("<[0xF0,0x7E,0x7F,0x09,0x01,0xF7] [0xF0,0x7E,0x7F,0x09,0x02,0xF7]>")
+.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.
+
+# OSC/SuperDirt/StrudelDirt
+
+In TidalCycles, sound is usually generated using [SuperDirt](https://github.com/musikinformatik/SuperDirt/), which runs inside SuperCollider. Strudel also supports using SuperDirt, although it requires installing some additional software.
+
+There is also [StrudelDirt](https://github.com/daslyfe/StrudelDirt) which is SuperDirt with some optimisations for working with Strudel. (A longer term aim is to merge these optimisations back into mainline SuperDirt)
 
 ## Prequisites