# Envelope

> Curved AD, AR and ADSR gain envelopes with looping and explicit retrigger behavior.

Source: https://docs.tune.toys/nodes/std.envelope/

An envelope shapes how loud a sound is over time. It listens to a gate: when the gate turns on the sound rises, and when it turns off the sound dies away.

## What it does

The envelope multiplies the audio passing through it by a gain that follows an attack, decay, sustain and release shape. A rising edge on Gate starts the envelope. Depending on Type it can be a full ADSR (attack, decay, sustain, release), an AD (attack then decay to zero) or an AR (attack, hold while the gate stays on, release). Curve bends every segment between concave, linear and convex. It can loop for as long as the gate is held.

It is a gain stage for audio, not a control signal: put it on the sound path.

### Events

The `done` outlet sends an event: it is 1 for one block when the envelope finishes and returns to silence, that is when the release ends after Gate turned off or an AD cycle completes, and 0 otherwise. A looping envelope never finishes, and a Gate that rises during the release restarts it without a `done`. Cable it into a trigger input, such as [Counter](https://docs.tune.toys/nodes/ctl.counter/) or [Sample and hold](https://docs.tune.toys/nodes/ctl.hold/), to advance something each time a note has fully died away.

## When to use it

Use it to turn a continuous source such as [Oscillator](https://docs.tune.toys/nodes/std.oscillator/) into notes, to make plucks and swells, or to build rhythmic gating. The [Polyphonic instrument](https://docs.tune.toys/nodes/std.poly/) already has an envelope for each voice.

## Ports

<!-- ports:start -->

| Port    | Direction | Signal  | Lanes                   |
| ------- | --------- | ------- | ----------------------- |
| `audio` | Input     | Audio   | Inferred from the cable |
| `audio` | Output    | Audio   | Inferred from the cable |
| `done`  | Output    | Control | 1                       |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter    | Label     | Range      | Default | Unit | Scale  | Notes                                                                                                             |
| ------------ | --------- | ---------- | ------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `attack_ms`  | Attack    | 0 to 10000 | 10      | ms   | linear | Time to rise to full gain.                                                                                        |
| `decay_ms`   | Decay     | 0 to 10000 | 120     | ms   | linear | Time to fall to sustain in ADSR, or zero in AD. Shown when `type` is 0 or 1.                                      |
| `sustain`    | Sustain   | 0 to 1     | 0.7     | %    | linear | Held ADSR gain. Shown when `type` is 0. Stored as a fraction; shown ×100 as a percentage.                         |
| `release_ms` | Release   | 0 to 10000 | 200     | ms   | linear | Time to return to zero. Shown when `type` is 0 or 2.                                                              |
| `gate`       | Gate      | 0 to 1     | 0       |      | linear | On or off. A rising edge retriggers; held on runs the oscillator or envelope. A control cable switches it at 0.5. |
| `type`       | Type      | 0 to 2     | 0       |      | linear | Selects the implemented algorithm. Choices are discrete and are not LFO targets. Choices: 0 ADSR, 1 AD, 2 AR.     |
| `curve`      | Curve     | -1 to 1    | 0       |      | linear | Continuous concave/linear/convex segment curvature.                                                               |
| `loop`       | Loop      | 0 to 1     | 0       |      | linear | Repeats complete envelope cycles while Gate is held. Choices: 0 Off, 1 While held.                                |
| `retrigger`  | Retrigger | 0 to 1     | 0       |      | linear | Restart from the current gain or reset to zero on a rising Gate. Choices: 0 Current level, 1 From zero.           |
| `hold_ms`    | Loop hold | 0 to 10000 | 100     | ms   | linear | Duration of the held part in repeating ADSR/AR cycles. Shown when `loop` is 1.                                    |

<!-- parameters:end -->

### Attack (`attack_ms`)

The time, from 0 to 10000 ms, taken to rise to full gain after the gate turns on.

### Decay (`decay_ms`)

The time to fall to the sustain level in ADSR, or to zero in AD. It applies to the ADSR and AD types.

### Sustain (`sustain`)

The held gain while the gate stays on in an ADSR envelope, shown from 0 to 100 % of full gain (stored as a fraction from 0 to 1).

### Release (`release_ms`)

The time to return to zero after the gate turns off. It applies to the ADSR and AR types.

### Gate (`gate`)

The trigger, on (1) or off (0). Turning it on starts the envelope and holding it on keeps it running. Bind it to a momentary button or toggle in a Frame, or cable a control signal in: it counts as on from 0.5.

### Type (`type`)

Chooses ADSR, AD or AR. It is a discrete choice.

### Curve (`curve`)

Bends the segments, from -1 to 1. Zero is linear; values on either side give concave or convex curvature.

### Loop (`loop`)

When On, complete envelope cycles repeat while Gate is held.

### Retrigger (`retrigger`)

On a rising Gate edge, either restart from the current gain (smooth) or reset to zero first.

### Loop hold (`hold_ms`)

The time the held part lasts in each repeat of a looping ADSR or AR cycle. It is shown only while Loop is on.

## Tips

- A short Attack with a medium Decay and zero Sustain makes a pluck.
- Looping an AD envelope is a quick way to make a repeating sound for testing effects.
- The envelope works on any channel count.
- `done` is a one-block pulse, like [Compare](https://docs.tune.toys/nodes/std.compare/) in Trigger mode. Cable it into a trigger input; to sequence notes, let it clock a [Counter](https://docs.tune.toys/nodes/ctl.counter/) that picks the next pitch.

## See also

[Oscillator](https://docs.tune.toys/nodes/std.oscillator/), [Polyphonic instrument](https://docs.tune.toys/nodes/std.poly/), [Compressor](https://docs.tune.toys/nodes/std.compressor/).