improve synth docs

packages/core/controls.mjs

@@ -121,6 +121,7 @@ const generic_params = [
    * note("c e g b")
    * .fm(4)
    * .fmh("<1 2 1.5 1.61>")
+   * .scope()
    *
    */
   [['fmh', 'fmi'], 'fmh'],
@@ -134,6 +135,7 @@ const generic_params = [
    * @example
    * note("c e g b")
    * .fm("<0 1 2 8 32>")
+   * .scope()
    *
    */
   [['fmi', 'fmh'], 'fm'],
@@ -149,6 +151,7 @@ const generic_params = [
    * .fmdecay(.2)
    * .fmsustain(0)
    * .fmenv("<exp lin>")
+   * .scope()
    *
    */
   ['fmenv'],
@@ -161,6 +164,7 @@ const generic_params = [
    * note("c e g b")
    * .fm(4)
    * .fmattack("<0 .05 .1 .2>")
+   * .scope()
    *
    */
   ['fmattack'],
@@ -174,6 +178,7 @@ const generic_params = [
    * .fm(4)
    * .fmdecay("<.01 .05 .1 .2>")
    * .fmsustain(.4)
+   * .scope()
    *
    */
   ['fmdecay'],
@@ -187,6 +192,7 @@ const generic_params = [
    * .fm(4)
    * .fmdecay(.1)
    * .fmsustain("<1 .75 .5 0>")
+   * .scope()
    *
    */
   ['fmsustain'],

website/src/pages/learn/synths.mdx

@@ -8,28 +8,52 @@ import { JsDoc } from '../../docs/JsDoc';
 
 # Synths
 
-For now, [samples](/learn/samples) are the main way to play with Strudel.
+In addition to the sampling engine, strudel comes with a synthesizer to create sounds on the fly.
-In the future, more powerful synthesis capabilities will be added.
-If in the meantime you want to dive deeper into audio synthesis with Tidal, you will need to [install SuperCollider and SuperDirt](https://tidalcycles.org/docs/).
 
-## Playing synths with `s`
+## Basic Waveforms
 
-We can change the sound, using the `s` function:
+The basic waveforms are `sine`, `sawtooth`, `square` and `triangle`, which can be selected via `sound` (or `s`):
 
-<MiniRepl client:idle tune={`note("c2 <eb2 <g2 g1>>").s('sawtooth')`} />
+<MiniRepl
+  client:idle
+  tune={`note("c2 <eb2 <g2 g1>>")
+.sound("<sawtooth square triangle sine>")
+.scope()`}
+/>
 
-Here, we are wrapping our notes inside `note` and set the sound using `s`, connected by a dot.
+If you don't set a `sound` but a `note` the default value for `sound` is `triangle`!
 
-Those functions are only 2 of many ways to alter the properties, or _params_ of a sound.
+### Additive Synthesis
-The power of patterns allows us to sequence any _param_ independently:
 
-<MiniRepl client:idle tune={`note("c2 <eb2 <g2 g1>>").s("<sawtooth square triangle>")`} />
+To tame the harsh sound of the basic waveforms, we can set the `n` control to limit the overtones of the waveform:
 
-Now we not only pattern the notes, but the sound as well!
+<MiniRepl
-`sawtooth` `square` and `triangle` are the basic waveforms available in `s`.
+  client:idle
+  tune={`note("c2 <eb2 <g2 g1>>")
+.sound("sawtooth")
+.n("<32 16 8 4>")
+.scope()`}
+/>
+
+When the `n` control is used on a basic waveform, it defines the number of harmonic partials the sound is getting.
+You can also set `n` directly in mini notation with `sound`:
+
+<MiniRepl
+  client:idle
+  tune={`note("c2 <eb2 <g2 g1>>")
+.sound("sawtooth:<32 16 8 4>")
+.scope()`}
+/>
+
+Note for tidal users: `n` in tidal is synonymous to `note` for synths only.
+In strudel, this is not the case, where `n` will always change timbre, be it though different samples or different waveforms.
 
 ## FM Synthesis
 
+FM Synthesis is a technique that changes the frequency of a basic waveform rapidly to alter the timbre.
+
+You can use fm with any of the above waveforms, although the below examples all use the default triangle wave.
+
 ### fm
 
 <JsDoc client:idle name="fm" h={0} />