diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 08037b1a..4aa5349d 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -892,12 +892,80 @@ const generic_params = [
    */
   ['freq'],
   // pitch envelope
+  /**
+   * Attack time of pitch envelope.
+   *
+   * @name pattack
+   * @synonyms patt
+   * @param {number | Pattern} time time in seconds
+   * @example
+   * note("<c eb g bb>").pattack("<0 .1 .25 .5>")
+   *
+   */
   ['pattack', 'patt'],
+  /**
+   * Decay time of pitch envelope.
+   *
+   * @name pdecay
+   * @synonyms pdec
+   * @param {number | Pattern} time time in seconds
+   * @example
+   * note("<c eb g bb>").pdecay("<0 .1 .25 .5>")
+   *
+   */
   ['pdecay', 'pdec'],
+  // TODO: how to use psustain?!
   ['psustain', 'psus'],
+  /**
+   * Release time of pitch envelope
+   *
+   * @name prelease
+   * @synonyms prel
+   * @param {number | Pattern} time time in seconds
+   * @example
+   * note("<c eb g bb> ~")
+   * .release(.5) // to hear the pitch release
+   * .prelease("<0 .1 .25 .5>")
+   *
+   */
   ['prelease', 'prel'],
+  /**
+   * Amount of pitch envelope. Negative values will flip the envelope.
+   * If you don't set other pitch envelope controls, `pattack:.2` will be the default.
+   *
+   * @name penv
+   * @param {number | Pattern} semitones change in semitones
+   * @example
+   * note("c")
+   * .penv("<12 7 1 .5 0 -1 -7 -12>")
+   *
+   */
   ['penv'],
+  /**
+   * Curve of envelope. Defaults to linear. exponential is good for kicks
+   *
+   * @name pcurve
+   * @param {number | Pattern} type 0 = linear, 1 = exponential
+   * @example
+   * note("g1*2")
+   * .s("sine").pdec(.5)
+   * .penv(32)
+   * .pcurve("<0 1>")
+   *
+   */
   ['pcurve'],
+  /**
+   * Sets the range anchor of the envelope:
+   * - anchor 0: range = [note, note + penv]
+   * - anchor 1: range = [note - penv, note]
+   * If you don't set an anchor, the value will default to the psustain value.
+   *
+   * @name panchor
+   * @param {number | Pattern} anchor anchor offset
+   * @example
+   * note("c").penv(12).panchor("<0 .5 1 .5>")
+   *
+   */
   ['panchor'],
   // TODO: https://tidalcycles.org/docs/configuration/MIDIOSC/control-voltage/#gate
   ['gate', 'gat'],
diff --git a/website/src/pages/learn/effects.mdx b/website/src/pages/learn/effects.mdx
index a3ae91d7..d0615dd9 100644
--- a/website/src/pages/learn/effects.mdx
+++ b/website/src/pages/learn/effects.mdx
@@ -138,6 +138,60 @@ There is one filter envelope for each filter type and thus one set of envelope f
 
 <JsDoc client:idle name="lpenv" h={0} />
 
+## Pitch Envelope
+
+You can also control the pitch with envelopes!
+Pitch envelopes can breathe life into static sounds:
+
+<MiniRepl
+  client:idle
+  tune={`n("<-4,0 5 2 1>*<2!3 4>")
+  .scale("<C F>/8:pentatonic")
+  .s("gm_electric_guitar_jazz")
+  .penv("<.5 0 7 -2>*2").vib("4:.1")
+  .phaser(2).delay(.25).room(.3)
+  .size(4).fast(.75)`}
+/>
+
+You also create some lovely chiptune-style sounds:
+
+<MiniRepl
+  client:idle
+  tune={`n(run("<4 8>/16")).jux(rev)
+.chord("<C^7 <Db^7 Fm7>>")
+.dict('ireal')
+.voicing().add(note("<0 1>/8"))
+.dec(.1).room(.2)
+.segment("<4 [2 8]>")
+.penv("<0 <2 -2>>").patt(.02)`}
+/>
+
+Let's break down all pitch envelope controls:
+
+## pattack
+
+<JsDoc client:idle name="pattack" h={0} />
+
+## pdecay
+
+<JsDoc client:idle name="pdecay" h={0} />
+
+## prelease
+
+<JsDoc client:idle name="prelease" h={0} />
+
+## penv
+
+<JsDoc client:idle name="penv" h={0} />
+
+## pcurve
+
+<JsDoc client:idle name="pcurve" h={0} />
+
+## panchor
+
+<JsDoc client:idle name="panchor" h={0} />
+
 # Dynamics
 
 ## gain