# Control envelope

> A control-rate ADSR, AD or AR envelope on a gate lane, 0 to 1, with velocity scaling and a done event.

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

Control envelope turns a gate lane into a 0 to 1 control lane that rises, holds and falls like an envelope. It is the control-rate sibling of [Envelope](https://docs.tune.toys/nodes/std.envelope/): the same stages and curves, but the result is a lane you cable into any parameter instead of a gain applied to audio.

## What it does

While the gate lane is at 0.5 or more it is held. A rising edge starts the attack; in ADSR the level then decays to Sustain and stays there until the gate falls, then Release returns it to zero. AD ignores the falling gate and runs attack then decay on its own; AR rises to full and holds until the gate falls. Curve bends every segment, Loop repeats whole cycles while the gate is held, and Retrigger chooses whether a new edge starts from the current level or from zero. The stage logic is the audio envelope's own, so the two agree.

Velocity scales the peak from the gate lane's value at the rising edge: at 0 the gate value is ignored, at 1 a gate of 0.75 peaks at 0.75. Use the velocity lane of [MIDI to control](https://docs.tune.toys/nodes/midi.to-control/), or a gate multiplied by a level, to get velocity-sensitive envelopes. The gate must still reach 0.5 to open.

### Resolution

Control runs once per audio block, and the output is the level at the block's last frame. Stage times are exact, but the lane steps about 2.7 ms at 128 frames and 48 kHz, so very short attacks look like a step. Cable the output into a parameter's cable input to let that parameter smooth it.

### Events

The `done` outlet is 1 for one block when a cycle ends: a release finishes, or an AD decay completes. A retrigger during a release is not a completed cycle. Cable it into [Counter](https://docs.tune.toys/nodes/ctl.counter/) or another trigger input.

## When to use it

Use it to shape a filter, a level or any parameter per note, or to build a one-shot modulator from a trigger. Prefer [Envelope](https://docs.tune.toys/nodes/std.envelope/) when the envelope shapes audio directly.

## Ports

<!-- ports:start -->

| Port      | Direction | Signal  | Lanes |
| --------- | --------- | ------- | ----- |
| `gate`    | Input     | Control | 1     |
| `control` | Output    | Control | 1     |
| `done`    | Output    | Control | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter    | Label     | Range      | Default | Unit | Scale  | Notes                                                                                  |
| ------------ | --------- | ---------- | ------- | ---- | ------ | -------------------------------------------------------------------------------------- |
| `type`       | Type      | 0 to 2     | 0       |      | linear | Selects the implemented algorithm. Choices are discrete. Choices: 0 ADSR, 1 AD, 2 AR.  |
| `attack_ms`  | Attack    | 0 to 10000 | 10      | ms   | linear | Time to rise to full level.                                                            |
| `decay_ms`   | Decay     | 0 to 10000 | 120     | ms   | linear | Time to fall to sustain in ADSR, or zero in AD.                                        |
| `sustain`    | Sustain   | 0 to 1     | 0.7     | %    | linear | Held ADSR level. Stored as a fraction; shown ×100 as a percentage.                     |
| `release_ms` | Release   | 0 to 10000 | 200     | ms   | linear | Time to return to zero after the gate falls.                                           |
| `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.         |
| `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 the gate is held. Choices: 0 Off, 1 While held. |
| `retrigger`  | Retrigger | 0 to 1     | 0       |      | linear | Where a new gate edge starts the attack. Choices: 0 Current level, 1 From zero.        |
| `velocity`   | Velocity  | 0 to 1     | 0       |      | linear | How much the gate lane value at the rising edge scales the peak. 0 ignores it.         |

<!-- parameters:end -->

### Type (`type`)

ADSR, AD or AR. A discrete choice.

### Attack (`attack_ms`), Decay (`decay_ms`), Sustain (`sustain`), Release (`release_ms`)

The stage times and the held level. Decay applies to ADSR and AD, Sustain to ADSR, Release to ADSR and AR.

### Loop hold (`hold_ms`)

How long a looping cycle rests at its held level before releasing. Visible when Loop is on.

### Curve (`curve`)

Concave below 0, linear at 0, convex above 0, applied to every segment.

### Loop (`loop`) and Retrigger (`retrigger`)

Loop repeats cycles while the gate is held. Retrigger picks the start of a new attack: the current level, or zero.

### Velocity (`velocity`)

How much the gate value at the rising edge scales the peak, 0 to 1.

## Tips

- A square [Control LFO](https://docs.tune.toys/nodes/ctl.lfo/) is a quick gate for trying an envelope.
- Keep Velocity at 0 for a plain gate; at 1 the gate value is the peak.
- Release only has something to do while the gate falls from above zero; `done` waits for it to finish.

## See also

[Envelope](https://docs.tune.toys/nodes/std.envelope/), [Control LFO](https://docs.tune.toys/nodes/ctl.lfo/), [Counter](https://docs.tune.toys/nodes/ctl.counter/), [MIDI to control](https://docs.tune.toys/nodes/midi.to-control/), [Cables](https://docs.tune.toys/concepts/cables/).