From e99f229b573a1e963fd2716ebaae6d9c21e58e5e Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Mon, 3 Feb 2025 22:37:59 +0100
Subject: [PATCH] doc: defaultmidimap + midimaps

---
 packages/midi/midi.mjs                   | 27 ++++++++++++++++++++++--
 website/src/pages/learn/input-output.mdx | 10 +++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/packages/midi/midi.mjs b/packages/midi/midi.mjs
index b7650c3b..fe0829c9 100644
--- a/packages/midi/midi.mjs
+++ b/packages/midi/midi.mjs
@@ -117,13 +117,36 @@ function githubPath(base, subpath = '') {
   return `https://raw.githubusercontent.com/${path}/${subpath}`;
 }
 
-// configures the default midimap, which is used when no "midimap" port is set
+/**
+ * configures the default midimap, which is used when no "midimap" port is set
+ * @example
+ * defaultmidimap({ lpf: 74 })
+ * $: note("c a f e").midi();
+ * $: lpf(sine.slow(4).segment(16)).midi();
+ */
 export function defaultmidimap(mapping) {
   midicontrolMap.set('default', unifyMapping(mapping));
 }
 
 let loadCache = {};
-// adds multiple midimaps to the registry
+
+/**
+ * Adds midimaps to the registry. Inside each midimap, control names (e.g. lpf) are mapped to cc numbers.
+ * @example
+ * midimaps({ mymap: { lpf: 74 } })
+ * $: note("c a f e")
+ * .lpf(sine.slow(4))
+ * .midimap('mymap')
+ * .midi()
+ * @example
+ * midimaps({ mymap: {
+ *   lpf: { ccn: 74, min: 0, max: 20000, exp: 0.5 }
+ * }})
+ * $: note("c a f e")
+ * .lpf(sine.slow(2).range(400,2000))
+ * .midimap('mymap')
+ * .midi()
+ */
 export async function midimaps(map) {
   if (typeof map === 'string') {
     if (map.startsWith('github:')) {
diff --git a/website/src/pages/learn/input-output.mdx b/website/src/pages/learn/input-output.mdx
index 14e46ba7..cec06a34 100644
--- a/website/src/pages/learn/input-output.mdx
+++ b/website/src/pages/learn/input-output.mdx
@@ -46,6 +46,16 @@ But you can also control cc messages separately like this:
 $: ccv(sine.segment(16).slow(4)).ccn(74).midi()`}
 />
 
+Instead of setting `ccn` and `ccv` directly, you can also create mappings with `midimaps`:
+
+## midimaps
+
+<JsDoc client:idle name="midimaps" h={0} />
+
+## defaultmidimap
+
+<JsDoc client:idle name="defaultmidimap" h={0} />
+
 # 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.