# dynamics
defines time-varying transformations applied within a note's lifespan, including spectral morphing, gated filtering, and stochastic grain skipping. each follows a structured temporal contour.

## introduction
* dynamics covers effects that change continuously or stochastically while a note is sounding
* unlike envelopes (fixed per-partial shapes) or decorators (static per-partial tweaks), dynamics vary over time
* each dynamic behaviour is built from two layers:
  * an effect family (what processing occurs)
  * a progression family (how its intensity evolves across the note)
* every family exposes two parameters `a`, `b ∈ [0…1]`, remapped to musically useful ranges

## overview of effect families
* id 0: slow spectral morph
  * behaviour
    * cross-fades the current amplitude distribution toward a target amplitude or frequency shape
  * notes
    * supports morphing between any two distributions
    * smooth continuous transition
  * parameters
    * `a` = morph depth (0 = no morph, 1 = full target)
    * `b` = morph rate (0 = spans whole note, 1 = completes in first 10% of note)
* id 1: gated band-pass
  * behaviour
    * applies a band-pass filter that opens and closes according to progression
  * notes
    * isolates part of the spectrum in rhythmic or stochastic windows
  * parameters
    * `a` = band centre frequency (0 = fundamental, 1 = nyquist)
    * `b` = relative bandwidth (0 = narrow, 1 = full span)
* id 2: stochastic grain-skip
  * behaviour
    * chops the signal into short grains and mutes some randomly, creating gritty drop-outs
  * notes
    * grain length and muting probability are continuous
  * parameters
    * `a` = skip probability per grain (0 = never skip, 1 = skip all)
    * `b` = grain length fraction of note (0 = very short, 1 = long grain)

## overview of progression families
* id 0: constant
  * behaviour
    * effect intensity remains fixed throughout the note
  * parameters
    * `a` = fixed intensity (0 = bypass, 1 = full effect)
    * `b` = onset delay fraction (0 = start immediately, 1 = start at end)
* id 1: ramp in-out
  * behaviour
    * intensity rises, holds, then falls in a triangular envelope
  * parameters
    * `a` = rise duration fraction (0 = instant, 1 = entire note)
    * `b` = fall duration fraction (same mapping)
* id 2: periodic window
  * behaviour
    * toggles effect on/off in a repeating window pattern
  * parameters
    * `a` = period fraction of note (0 = very fast, 1 = one cycle)
    * `b` = duty cycle (0 = always off, 1 = always on)
* id 3: random burst
  * behaviour
    * launches bursts of effect following a poisson process
  * parameters
    * `a` = expected bursts per note (0 = none, 1 = \~20 bursts)
    * `b` = burst duration fraction (0 = very short, 1 = half the note)

## parameter behavior summary
* effects
   `a`, `b` control what* the effect does (depth, rate, centre, probability, grain length)
* progressions
   `a`, `b` control how* it changes over time (intensity, timing, period, duty, bursts)

## why these families were chosen
* completeness
  * cover smooth morphing, rhythmic gating, and stochastic variation
* continuity
  * all mappings are continuous, avoiding clicks or sudden jumps
* interoperability
  * can be combined with amplitude, frequency, envelope, decorators for rich textures
* musical relevance
  * slow morphs for pads, gated filters for rhythmic patterns, grain-skip for glitch effects

## what is not included
* global lfo vibrato or tremolo (handled by decorator dimension)
* multiband or evolving filter shapes beyond single band-pass
* note-to-note modulation (handled by per-voice or performance controllers)
* dynamic spectral resynthesis (requires additive-plus-filter or convolution)

## conclusion
the dynamics domain adds a fourth axis of in-note variation, giving designers the tools to inject motion, rhythm, and randomness into their sounds.
with its families of effects and progressions, it remains fully continuous, parameter-pure, and additive-only, fitting seamlessly into the super-instrument's architecture.