From bac8594c5f1db32d618696c1dacf41bb88a33fb4 Mon Sep 17 00:00:00 2001
From: Raphael Forment <raphael.forment@gmail.com>
Date: Sun, 10 Sep 2023 20:36:09 +0200
Subject: [PATCH] beginning documentation work (breaks)

---
 packages/core/controls.mjs                | 39 ++++++++++++++++-------
 test/__snapshots__/examples.test.mjs.snap | 18 +++++++++++
 website/src/pages/learn/synths.mdx        | 11 +++++++
 3 files changed, 56 insertions(+), 12 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 2b99bdb3..4d427da3 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -309,6 +309,33 @@ const generic_params = [
    *
    */
   ['loop'],
+  /**
+   * @name loopBegin
+   * @param {number | Pattern} amount between 0 and 1, where 1 is the length of the sample
+   * @synonyms loopb
+   * @example
+   * s("numbers").loopBegin("<0 .25 .5 .75>").loop(1)
+   *
+   */
+  ['loopBegin', 'loopb'],
+  /**
+   * @name loopEnd
+   * @param {number | Pattern} amount between 0 and 1, where 1 is the length of the sample
+   * @synonyms loope
+   * @example
+   * s("numbers").loopEnd("<0 .25 .5 .75>").loop(1)
+   *
+   */
+  ['loopEnd', 'loope'],
+  /**
+   * bit crusher effect.
+   *
+   * @name crush
+   * @param {number | Pattern} depth between 1 (for drastic reduction in bit-depth) to 16 (for barely no reduction).
+   * @example
+   * s("<bd sd>,hh*3").fast(2).crush("<16 8 7 6 5 4 3 2>")
+   *
+   */
   // TODO: currently duplicated with "native" legato
   // TODO: superdirt legato will do more: https://youtu.be/dQPmE1WaD1k?t=419
   /**
@@ -323,15 +350,6 @@ const generic_params = [
    */
   // ['legato'],
   // ['clhatdecay'],
-  /**
-   * bit crusher effect.
-   *
-   * @name crush
-   * @param {number | Pattern} depth between 1 (for drastic reduction in bit-depth) to 16 (for barely no reduction).
-   * @example
-   * s("<bd sd>,hh*3").fast(2).crush("<16 8 7 6 5 4 3 2>")
-   *
-   */
   ['crush'],
   /**
    * fake-resampling for lowering the sample rate. Caution: This effect seems to only work in chromium based browsers
@@ -343,7 +361,6 @@ const generic_params = [
    *
    */
   ['coarse'],
-
   /**
    * choose the channel the pattern is sent to in superdirt
    *
@@ -882,8 +899,6 @@ const generic_params = [
   ['zdelay'],
   ['tremolo'],
   ['zzfx'],
-  ['loopBegin'],
-  ['loopEnd'],
 ];
 // TODO: slice / splice https://www.youtube.com/watch?v=hKhPdO0RKDQ&list=PL2lW1zNIIwj3bDkh-Y3LUGDuRcoUigoDs&index=13
 
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 60b39c53..3e2d81bd 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -2566,6 +2566,24 @@ exports[`runs examples > example "loopAtCps" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "loopBegin" example index 0 1`] = `
+[
+  "[ 0/1 → 1/1 | s:numbers loopBegin:0 loop:1 ]",
+  "[ 1/1 → 2/1 | s:numbers loopBegin:0.25 loop:1 ]",
+  "[ 2/1 → 3/1 | s:numbers loopBegin:0.5 loop:1 ]",
+  "[ 3/1 → 4/1 | s:numbers loopBegin:0.75 loop:1 ]",
+]
+`;
+
+exports[`runs examples > example "loopEnd" example index 0 1`] = `
+[
+  "[ 0/1 → 1/1 | s:numbers loopEnd:0 loop:1 ]",
+  "[ 1/1 → 2/1 | s:numbers loopEnd:0.25 loop:1 ]",
+  "[ 2/1 → 3/1 | s:numbers loopEnd:0.5 loop:1 ]",
+  "[ 3/1 → 4/1 | s:numbers loopEnd:0.75 loop:1 ]",
+]
+`;
+
 exports[`runs examples > example "lpf" example index 0 1`] = `
 [
   "[ 0/1 → 1/3 | s:hh cutoff:4000 ]",
diff --git a/website/src/pages/learn/synths.mdx b/website/src/pages/learn/synths.mdx
index b24726cf..6a2d7395 100644
--- a/website/src/pages/learn/synths.mdx
+++ b/website/src/pages/learn/synths.mdx
@@ -78,6 +78,17 @@ You can use fm with any of the above waveforms, although the below examples all
 
 <JsDoc client:idle name="fmenv" h={0} />
 
+## Wavetable Synthesis
+
+Strudel can also use wavetables to create custom waveforms instead of the default ones used by WebAudio. There is a default set of wavetables accessible by default (approximatively 1000 coming from the [AKWF](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/) set) but you can also import/use your own. A wavetable is a one-cycle waveform, which is then repeated to create a sound at the desired frequency. It is a classic but very effective synthesis technique. Wavetable synthesis is based on sample looping, using the `loop`, `loopBegin` and `loopEnd` properties of the sampler:
+
+- `loop`: either `0` (no loop) or `1` (loop)
+- `loopBegin`: start of the loop (between 0 and 1)
+- `loopEnd`: end of the loop (between 0 and 1)
+
+<JsDoc client:idle name="loopBegin" h={0} />
+<JsDoc client:idle name="loopEnd" h={0} />
+
 ## ZZFX
 
 The "Zuper Zmall Zound Zynth" [ZZFX](https://github.com/KilledByAPixel/ZzFX) is also integrated in strudel.