# envelopes
defines how the envelopes properties vary by partial index - allowing individualized attack, decay, sustain, and delay across the spectrum. used for sculpting spectral motion and micro-timbral events.

### introduction
this domain governs how individual partials modify their **amplitude contour parameters** within a shared global envelope shape. the global shape is selected from a fixed family of spline-based forms (see `envelope` domain). this domain controls four parameters that modulate the behavior of those forms per partial: attack time, decay/release time, sustain level, and start delay.

each stage is implemented as a static, parametric function across partial index `n ∈ [1, N]`, defined by two parameters `a, b ∈ [0,1]`. all behaviors are statically scheduled, strictly additive, and determined without signal-domain shaping or filtering.

this domain enables construction of distinct temporal behaviors across harmonic and inharmonic partials, supporting both percussive transients and evolving textures, through systematic deformation of envelope parameters.

### overview

#### attack time maps
maps partial index `n` to time from onset to peak (or peak-aligned surrogate)
* 0: linear rise
  attack time increases linearly across partials
  * `a`: minimum attack (scaled 0…global maximum)
  * `b`: maximum attack
* 1: exponential rise
  faster attack for higher partials, shaped exponentially
  * `a`: curve shape (0 = linear, 1 = steepest)
  * `b`: total range of attack times
* 2: uniform random
  attack time is random in \[min, max] for each partial
  * `a`: minimum attack
  * `b`: maximum attack

#### decay/release time maps
maps `n` to time from peak to zero or sustain
* 0: inverse decay
  decay time ∝ 1 / nᵏ — lower partials decay faster
  * `a`: decay exponent (mapped to \[0…2])
  * `b`: decay time scale
* 1: gaussian profile
  decay centered on a target partial with bell-shaped falloff
  * `a`: center partial index (0 = lowest, 1 = highest)
  * `b`: spread width (0 = narrow, 1 = wide)
* 2: grouped steps
  partials grouped into m decay bands, each with a flat value
  * `a`: number of groups (mapped from 2 to 16)
  * `b`: intra-group time offset (local variation)

#### sustain level maps
maps `n` to the steady-state amplitude held after attack/decay
* 0: threshold gate
  sustain level is 1 below threshold index, 0 above
  * `a`: threshold index (0 = all on, 1 = all off)
  * `b`: (unused)
* 1: linear slope
  sustain level interpolates linearly between two values
  * `a`: level at lowest partial
  * `b`: level at highest partial
* 2: beta profile
  sustain follows a beta(α, β) shape across partial index
  * `a`: beta α (controls skew and peak position)
  * `b`: beta β (controls tail and curvature)

#### start delay maps
maps `n` to a delay offset before the envelope begins
* 0: no delay
  all partials begin at time zero
  * no parameters
* 1: linear spread
  delays increase evenly from first to last partial
  * `a`: maximum delay (scaled to time-base)
  * `b`: (unused)
* 2: rhythmic grid
  delays are quantized to m rhythmic positions, with swing
  * `a`: number of grid steps (mapped 1 to 32)
  * `b`: swing amount (0 = even, 1 = maximum offset)

### parameter behavior summary
each form is controlled by two parameters `a` and `b`, mapped internally to perceptually meaningful quantities:
* attack maps
  * linear rise
    * `a`: minimum attack
    * `b`: maximum attack
  * exponential rise
    * `a`: curve steepness
    * `b`: total range
  * uniform random
    * `a`: minimum attack
    * `b`: maximum attack
* decay/release maps
  * inverse decay
    * `a`: decay exponent
    * `b`: decay scale
  * gaussian profile
    * `a`: center partial index
    * `b`: spread width
  * grouped steps
    * `a`: number of groups
    * `b`: intra-group offset
* sustain level maps
  * threshold gate
    * `a`: cutoff index
    * `b`: -
  * linear slope
    * `a`: start level
    * `b`: end level
  * beta profile
    * `a`: alpha shape
    * `b`: beta shape
* start delay maps
  * no delay
    * no parameters
  * linear spead
    * `a`: maximum delay
    * `b`: -
  * rhythmic grid
    * `a`: number of grid steps
    * `b`: swing amount

### why these were chosen
this domain spans key perceptual behaviors with minimal, irreducible forms:
* linear, exponential, and random gradients over partial index
* focused, grouped, or gated shaping via gaussian, beta, or steps
* asynchronous layout via delay grids or spreads
* structured yet static modulation of global envelope parameters
each form is:
* continuous or discretely structured
* uniquely non-redundant in shaping behavior
* capable of supporting natural, synthetic, or abstract dynamic profiles

this enables precise control over the spectral evolution of a note, without requiring separate envelopes for every partial.

### what is not included
* independent envelope forms per partial (violates structural consistency)
* reactive, gated, or runtime-varying envelope modulation
* interpolation between shaping forms
* dynamic envelope topologies or user-defined breakpoints
excluded features would either compromise static scheduling or duplicate the role of the `envelope` layer.

### conclusion
the envelopes domain modulates the parameter fields of global envelope shapes across the partial spectrum. it provides a compact, statically-defined mapping from partial index to four perceptually grounded behaviors. together with the global `envelope` shape and static timing infrastructure, it enables detailed sculpting of partial-specific amplitude behavior while maintaining system clarity, determinism, and composability.