# envelope
defines the shared amplitude contour for a notes duration using parametric spline shapes (linear, exponential, power, bezier arc). forms express diverse attack and release behaviors without conditionals or gating.

## envelope families
* 0: flat
  * description: constant amplitude throughout note duration
  * implementation: single linear segment at y = 1
  * parameters:
    * a = unused
    * b = unused
* 1: natural ramp
  * description: curved rise into sustain, mimicking natural energy buildup (e.g. bow, breath, mallet)
  * implementation:
    * exponential attack curve
    * followed by linear sustain
  * parameters:
    * a = attack duration (0 = fast, 1 = slow)
    * b = curve shape (0 = steep, 1 = smooth); remapped to exponential gamma
* 2: synthetic click
  * description: narrow impulse followed by flat sustain
  * implementation:
    * power-rise to peak
    * short exponential decay
    * flat linear sustain
  * parameters:
    * a = click duration (0 = instant, 1 = wide)
    * b = spectral tilt (0 = sharp, 1 = smooth); mapped to both power and exponential gamma
* 3: tilt envelope
  * description: flexible attack and release curvature
  * implementation:
    * attack: bezier arc with curvature from a
    * release: bezier arc with curvature from b
  * parameters:
    * a = attack bend (0 = linear, 1 = curved); remapped to [–1, 1]
    * b = release bend (0 = linear, 1 = curved); remapped to [–1, 1]
* 4: multiphase
  * description: dynamic shape with attack, decay, and sustain
  * implementation:
    * power curve for attack
    * exponential decay to sustain
    * flat sustain
  * parameters:
    * a = relative attack time
    * b = relative decay time
    * both are normalized and rescaled to fit within note length
* 5: legato crossfade
  * description: overlapping transitions between notes
  * implementation:
    * linear hold phase
    * exponential fade-out
  * parameters:
    * a = fade length
    * b = fade start position (0 = note end, 1 = full blend)

## parameter behavior summary
* flat
  * a = unused
  * b = unused
* natural ramp
  * a = attack time
  * b = exponential gamma (0.01 to 100)
* synthetic click
  * a = impulse width
  * b = dual tilt (mapped to power gamma and exponential gamma)
* tilt envelope
  * a = attack bend (mapped to –1 to +1)
  * b = release bend (mapped to –1 to +1)
* multiphase
  * a = attack ratio
  * b = decay ratio
  * both time-normalized and rescaled to full duration
* legato crossfade
  * a = crossfade length
  * b = fade overlap point

## why these were chosen
* flat - minimal reference for debugging and pure tone testing
* natural ramp - models breath/bow-based gestures with curvature control
* synthetic click - produces short impulses with fine shape control
* tilt envelope - general-purpose shape with direct curvature mapping
* multiphase - covers physical gestures with distinct attack and decay
* legato crossfade - enables smooth melodic transitions without retriggering
each shape:
* covers a distinct perceptual gesture
* uses only two parameters
* supports continuous variation across the space it defines
* cannot be mimicked by another shape in the set

## what's not included
* multi-stage or sample-driven envelopes
* velocity- or controller-modulated shaping (covered by performance layer)
* gated, looping, or reactive envelopes (covered under `dynamics`)
* stochastic or expressive variation (delegated to modulation or timing layers)
excluded features are delegated to other layers to preserve static determinism and parametric clarity.

## conclusion
the envelope domain defines a single, global amplitude contour per note. each envelope family:
* uses two normalized parameters a, b ∈ [0, 1]
* is statically scheduled
* produces a `spline_path` descriptor composed of linear, exponential, power, or bezier-arc segments
* guarantees continuous, musically useful variation across its space
together, these six forms span a wide expressive range of onset, sustain, and release behaviors while remaining compact, stateless, and composable within the system.
the envelope operates in coordination with:
* `envelopes` - for per-partial shaping
* `dynamics` - for intra-note time variation
* `decorators` - for local augmentations
this layered approach ensures full control over amplitude shape from event level to fine-grain spectral detail.