From 1f073b29321b2448402d36318882ad01746317b1 Mon Sep 17 00:00:00 2001
From: "Alexandre G.-Raymond" <alex@ndre.gr>
Date: Sat, 28 Oct 2023 19:42:09 +0200
Subject: [PATCH] Document adsr function

---
 packages/core/controls.mjs                | 11 +++++++++++
 test/__snapshots__/examples.test.mjs.snap |  9 +++++++++
 website/src/pages/learn/effects.mdx       |  4 ++++
 3 files changed, 24 insertions(+)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 8841b4bca..f0c180126 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -1296,6 +1296,17 @@ generic_params.forEach(([names, ...aliases]) => {
 controls.createParams = (...names) =>
   names.reduce((acc, name) => Object.assign(acc, { [name]: controls.createParam(name) }), {});
 
+/**
+ * ADSR envelope: Combination of Attack, Decay, Sustain, and Release time.
+ *
+ * @name adsr
+ * @param {number | Pattern} time attack time in seconds
+ * @param {number | Pattern} time decay time in seconds
+ * @param {number | Pattern} time sustain time in seconds
+ * @param {number | Pattern} time release time in seconds
+ * @example
+ * note("<c3 bb2 f3 eb3>").sound("sawtooth").lpf(600).adsr(".1:.1:.5:.2")
+ */
 controls.adsr = register('adsr', (adsr, pat) => {
   adsr = !Array.isArray(adsr) ? [adsr] : adsr;
   const [attack, decay, sustain, release] = adsr;
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 62c2f0d89..f7956be55 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -633,6 +633,15 @@ exports[`runs examples > example "addVoicings" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "adsr" example index 0 1`] = `
+[
+  "[ 0/1 → 1/1 | note:c3 s:sawtooth cutoff:600 ]",
+  "[ 1/1 → 2/1 | note:bb2 s:sawtooth cutoff:600 ]",
+  "[ 2/1 → 3/1 | note:f3 s:sawtooth cutoff:600 ]",
+  "[ 3/1 → 4/1 | note:eb3 s:sawtooth cutoff:600 ]",
+]
+`;
+
 exports[`runs examples > example "almostAlways" example index 0 1`] = `
 [
   "[ 0/1 → 1/8 | s:hh speed:0.5 ]",
diff --git a/website/src/pages/learn/effects.mdx b/website/src/pages/learn/effects.mdx
index fb506aad4..308042409 100644
--- a/website/src/pages/learn/effects.mdx
+++ b/website/src/pages/learn/effects.mdx
@@ -82,6 +82,10 @@ Strudel uses ADSR envelopes, which are probably the most common way to describe
 
 <JsDoc client:idle name="release" h={0} />
 
+## adsr
+
+<JsDoc client:idle name="adsr" h={0} />
+
 # Filter Envelope
 
 Each filter can receive an additional filter envelope controlling the cutoff value dynamically. It uses an ADSR envelope similar to the one used for amplitude. There is an additional parameter to control the depth of the filter modulation: `lpenv`|`hpenv`|`bpenv`. This allows you to play subtle or huge filter modulations just the same by only increasing or decreasing the depth.