From e19d059c0f6eaf4cd6684dc670a104191b322425 Mon Sep 17 00:00:00 2001 From: nkymut Date: Sat, 25 Jan 2025 02:29:44 +0800 Subject: [PATCH] update documents --- packages/midi/README.md | 60 ++++++++++++++++++------ website/src/pages/learn/input-output.mdx | 40 +++++++++++----- 2 files changed, 72 insertions(+), 28 deletions(-) diff --git a/packages/midi/README.md b/packages/midi/README.md index 2678ab71..524baa17 100644 --- a/packages/midi/README.md +++ b/packages/midi/README.md @@ -8,23 +8,37 @@ This package adds midi functionality to strudel Patterns. 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) -- `pc` - Sends MIDI program change messages (0-127) -- `sysex` - Sends MIDI System Exclusive messages (array of bytes 0-255) +- `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) +- `nrpnn` - Sets MIDI NRPN non-registered parameter number (array of bytes 0-127) +- `nrpv` - Sets MIDI NRPN non-registered parameter value (0-127) +- `midicmd` - Sends MIDI system real-time messages to control timing and transport on MIDI devices. +- `midibend` - Sets MIDI pitch bend (-1 - 1) +- `miditouch` - Sets MIDI key after touch (0-1) + + +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?) @@ -33,7 +47,7 @@ Either connect a midi device or use the IAC Driver (Mac) or Midi Through Port (L If no outputName is given, it uses the first midi output it finds. ```javascript -$: chord("").voicing().midi() +$: chord("").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".` @@ -44,9 +58,10 @@ Selects the MIDI channel to use. If not used, `.midi` will use channel 1 by defa ### midicmd -`midicmd` sends MIDI system real-time messages to control timing and transport on MIDI devices. +`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 @@ -60,12 +75,15 @@ stack( ) ``` -### ccn && ccv +### 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() ``` @@ -78,9 +96,9 @@ $: note("c a f e").midi() $: ccv(sine.segment(16).slow(4)).ccn(74).midi() ``` -### pc (Program Change) +### progNum (Program Change) -`pc` control sends MIDI program change messages to switch between different presets/patches on your MIDI device. +`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 @@ -91,9 +109,9 @@ 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. -## sysexid, sysexdata (System Exclusive Message) +## sysex, sysexid && sysexdata (System Exclusive Message) -`sysexid` and `sysexdata` control sends MIDI System Exclusive (SysEx) messages to your MIDI device. +`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. @@ -102,9 +120,21 @@ The value should be an array of numbers between 0-255 representing the SysEx dat 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").sysexid(id).sysexdata(data).midi(); +$: 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. \ No newline at end of file +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(); + +``` \ No newline at end of file diff --git a/website/src/pages/learn/input-output.mdx b/website/src/pages/learn/input-output.mdx index ad42c56d..aab4be49 100644 --- a/website/src/pages/learn/input-output.mdx +++ b/website/src/pages/learn/input-output.mdx @@ -50,11 +50,14 @@ It supports the following commands: )`} /> -## ccn && ccv +## 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. + + In the above snippet, `ccn` is set to 74, which is the filter cutoff for many synths. `ccv` is controlled by a saw pattern. @@ -67,37 +70,48 @@ But you can also control cc messages separately like this: $: ccv(sine.segment(16).slow(4)).ccn(74).midi()`} /> -## pc (Program Change) +## progNum (Program Change) -`pc` sends MIDI program change messages to switch between different presets/patches on your MIDI device. +`progNum` 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. ").midi() +progNum("<0 1>").midi() // Play notes while changing programs -note("c3 e3 g3").pc("<0 1 2>").midi()`} /> +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 (System Exclusive Message) +## sysex, sysexid && sysexdata (System Exclusive Message) `sysex` 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. -") -.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) + + + + + # 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.