diff --git a/packages/midi/midi.mjs b/packages/midi/midi.mjs
index 2979684a..70df93e8 100644
--- a/packages/midi/midi.mjs
+++ b/packages/midi/midi.mjs
@@ -164,7 +164,17 @@ export async function midimaps(map) {
 
 // registry for midi sounds, converting sound names to controls
 export const midisoundMap = new Map();
-// adds multiple midimaps to the registry
+
+/**
+ * Maps a sound name to a set of controls:
+ * @example
+ * midisounds({ bd: { note: 'c2' } })
+ * $: s("bd").midi()
+ * @example
+ * // notes can be set directly to simplify typical midi drum kit mappings
+ * midisounds({ bd: 'c2', rim: 'c#2' })
+ * $: s("bd rim").midi()
+ **/
 export async function midisounds(map) {
   if (typeof map === 'object') {
     Object.entries(map).forEach(([name, mapping]) => midisoundMap.set(name, mapping));
diff --git a/test/examples.test.mjs b/test/examples.test.mjs
index 896a02f8..ccce6c2a 100644
--- a/test/examples.test.mjs
+++ b/test/examples.test.mjs
@@ -20,6 +20,7 @@ const skippedExamples = [
   'accelerationX',
   'defaultmidimap',
   'midimaps',
+  'midisounds',
 ];
 
 describe('runs examples', () => {
diff --git a/website/src/pages/learn/input-output.mdx b/website/src/pages/learn/input-output.mdx
index cec06a34..666a39f7 100644
--- a/website/src/pages/learn/input-output.mdx
+++ b/website/src/pages/learn/input-output.mdx
@@ -56,6 +56,10 @@ Instead of setting `ccn` and `ccv` directly, you can also create mappings with `
 
 <JsDoc client:idle name="defaultmidimap" h={0} />
 
+## midisounds
+
+<JsDoc client:idle name="midisounds" 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.