Usage

Simple

The simplest way to use an envelope is adsr . It provides a function which in turn gives a number from 0..1 for the amplitude of the envelope. See options for more on the options that can be passed in.

import { Envelopes } from "https://unpkg.com/ixfx/dist/modulation.js"

// Set up the envelope, getting a function to compute value
const envelope = Envelopes.adsr({
  attackDuration: 500,
  releaseDuration: 100
});

// Call envelope() whenever we want the value of the envelope
envelope();

More practically, you’d likely read the value of the envelope when you’re updating other sketch state. A limit of adsr is that you can’t control the envelope (eg re-trigger) or know exactly when it finishes. For this you want the more advanced usage…

See an example on fn-vis

Advanced

The Envelopes.Adsr class allows for more control over an envelope. See options for more on the options that can be passed in.

Tip

Note the subtle difference, new Envelopes.Adsr() for the class, Envelopes.adsr() for the function

import { Envelopes } from "https://unpkg.com/ixfx/dist/modulation.js"

// Create the envelope
const env = new Envelopes.Adsr({
  attackDuration: 1000,
  decayDuration: 200,
  sustainDuration: 100
});

In basic usage, you first trigger the envelope, and then read its value over time, probably from some kind of loop.

env.trigger();
setInterval(() => {
  console.log(env.value); // 0..1
});

You can ‘trigger-and-hold’, making the envelope stay at the sustain stage until ‘release’ is called:

// Trigger and hold at 'sustain' stage
env.trigger(true);
// ...at some point later, allow it to continue to 'release' stage.
env.release();

The value property gives you the value of the envelope at that point in time. You can get additional data with compute():

// Gets:
// name of current stage (as a string),
// scaled value (same as calling .value)
// and raw value (0 -> 1 progress *within* a stage)
const [stage, scaled, raw] = env.compute();

Other functions:

// Reset envelope
env.reset();

// True if envelope is finished
env.isDone;

Envelopes have events:

// Envelope has changed stage
env.addEventListener(`change`, ev => {
  console.log(`Old: ${evt.oldState} new: ${ev.newState}`);
})

// Envelope has finished
env.addEventListener(`complete`, () => {
  console.log(`Done.`);
})

See an example on fn-vis