From e3494a754e337eab27091b21f70141f10fa48aac Mon Sep 17 00:00:00 2001
From: alex <alex@slab.org>
Date: Sat, 30 Nov 2024 09:06:21 +0000
Subject: [PATCH] documentation updates for MIDI, OSC and MQTT

---
 website/src/pages/learn/input-output.mdx | 31 +++++++++++++-----------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/website/src/pages/learn/input-output.mdx b/website/src/pages/learn/input-output.mdx
index db0bf87f2..14e46ba7b 100644
--- a/website/src/pages/learn/input-output.mdx
+++ b/website/src/pages/learn/input-output.mdx
@@ -8,12 +8,13 @@ import { JsDoc } from '../../docs/JsDoc';
 
 # MIDI, OSC and MQTT
 
-The default audio output of Strudel uses the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API).
-It is also possible to use Strudel with MIDI, OSC / [SuperDirt](https://github.com/musikinformatik/SuperDirt/), or the MQTT protocol instead.
+Normally, Strudel is used to pattern sound, using its own '[web audio](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)'-based synthesiser called [SuperDough](https://github.com/tidalcycles/strudel/tree/main/packages/superdough).
 
-# MIDI API
+It is also possible to pattern other things with Strudel, such as software and hardware synthesisers with MIDI, other software using Open Sound Control/OSC (including the [SuperDirt](https://github.com/musikinformatik/SuperDirt/) synthesiser commonly used with Strudel's sibling [TidalCycles](https://tidalcycles.org/)), or the MQTT 'internet of things' protocol.
 
-Strudel also supports midi via [webmidi](https://npmjs.com/package/webmidi).
+# MIDI
+
+Strudel supports MIDI without any additional software (thanks to [webmidi](https://npmjs.com/package/webmidi)), just by adding methods to your pattern:
 
 ## midi(outputName?)
 
@@ -45,20 +46,22 @@ But you can also control cc messages separately like this:
 $: ccv(sine.segment(16).slow(4)).ccn(74).midi()`}
 />
 
-# OSC/SuperDirt API
+# 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.
 
-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.
+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
 
-Getting [SuperDirt](https://github.com/musikinformatik/SuperDirt/) to work with Strudel, you need to
+To get SuperDirt to work with Strudel, you need to
 
 1. install SuperCollider + sc3 plugins, see [Tidal Docs](https://tidalcycles.org/docs/) (Install Tidal) for more info.
-2. install [node.js](https://nodejs.org/en/)
-3. download [Strudel Repo](https://github.com/tidalcycles/strudel/) (or git clone, if you have git installed)
-4. run `pnpm i` in the strudel directory
-5. run `pnpm run osc` to start the osc server, which forwards OSC messages from Strudel REPL to SuperCollider
+2. install SuperDirt, or the [StrudelDirt](https://github.com/daslyfe/StrudelDirt) fork which is optimised for use with Strudel
+3. install [node.js](https://nodejs.org/en/)
+4. download [Strudel Repo](https://github.com/tidalcycles/strudel/) (or git clone, if you have git installed)
+5. run `pnpm i` in the strudel directory
+6. run `pnpm run osc` to start the osc server, which forwards OSC messages from Strudel REPL to SuperCollider
 
 Now you're all set!
 
@@ -95,6 +98,8 @@ run one yourself (e.g. by running [mosquitto](https://mosquitto.org/)), although
 your web browser will trust might be a bit tricky for those without systems administration experience.
 Alternatively, you can use [a public broker](https://www.hivemq.com/mqtt/public-mqtt-broker/).
 
+Strudel does not yet support receiving messages over MQTT, only sending them.
+
 ## Usage
 
 The following example shows how to send a pattern to an MQTT broker:
@@ -148,5 +153,3 @@ Will send messages like the following:
 ```
 
 Libraries for receiving MQTT are available for many programming languages.
-
-Strudel does not yet support receiving messages over MQTT.