mirror of
https://github.com/Tonejs/Tone.js
synced 2024-12-29 13:03:06 +00:00
654 lines
18 KiB
TypeScript
654 lines
18 KiB
TypeScript
import { InputNode, OutputNode } from "../../core/context/ToneAudioNode";
|
|
import { ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
|
|
import { NormalRange, Time } from "../../core/type/Units";
|
|
import { optionsFromArguments } from "../../core/util/Defaults";
|
|
import { isArray, isObject, isString } from "../../core/util/TypeCheck";
|
|
import { connectSignal, Signal } from "../../signal/Signal";
|
|
import { OfflineContext } from "../../core/context/OfflineContext";
|
|
import { assertRange } from "../../core/util/Debug";
|
|
import { EQ } from "../../core/util/Math";
|
|
|
|
type BasicEnvelopeCurve = "linear" | "exponential";
|
|
type InternalEnvelopeCurve = BasicEnvelopeCurve | number[];
|
|
export type EnvelopeCurve = EnvelopeCurveName | number[];
|
|
|
|
export interface EnvelopeOptions extends ToneAudioNodeOptions {
|
|
attack: Time;
|
|
decay: Time;
|
|
sustain: NormalRange;
|
|
release: Time;
|
|
attackCurve: EnvelopeCurve;
|
|
releaseCurve: EnvelopeCurve;
|
|
decayCurve: BasicEnvelopeCurve;
|
|
}
|
|
|
|
/**
|
|
* Envelope is an [ADSR](https://en.wikipedia.org/wiki/Synthesizer#ADSR_envelope)
|
|
* envelope generator. Envelope outputs a signal which
|
|
* can be connected to an AudioParam or Tone.Signal.
|
|
* ```
|
|
* /\
|
|
* / \
|
|
* / \
|
|
* / \
|
|
* / \___________
|
|
* / \
|
|
* / \
|
|
* / \
|
|
* / \
|
|
* ```
|
|
*
|
|
* @example
|
|
* import { Envelope, Gain } from "tone";
|
|
* // an amplitude envelope
|
|
* const gainNode = new Gain();
|
|
* const env = new Envelope({
|
|
* attack: 0.1,
|
|
* decay: 0.2,
|
|
* sustain: 1,
|
|
* release: 0.8,
|
|
* });
|
|
* env.connect(gainNode.gain);
|
|
* @category Component
|
|
*/
|
|
export class Envelope extends ToneAudioNode<EnvelopeOptions> {
|
|
|
|
readonly name: string = "Envelope";
|
|
|
|
/**
|
|
* Private container for the attack value
|
|
*/
|
|
private _attack!: Time;
|
|
|
|
/**
|
|
* Private holder of the decay time
|
|
*/
|
|
private _decay!: Time;
|
|
|
|
/**
|
|
* private holder for the sustain value
|
|
*/
|
|
private _sustain!: NormalRange;
|
|
|
|
/**
|
|
* private holder for the release value
|
|
*/
|
|
private _release!: Time;
|
|
|
|
/**
|
|
* The automation curve type for the attack
|
|
*/
|
|
private _attackCurve!: InternalEnvelopeCurve;
|
|
|
|
/**
|
|
* The automation curve type for the decay
|
|
*/
|
|
private _decayCurve!: BasicEnvelopeCurve;
|
|
|
|
/**
|
|
* The automation curve type for the release
|
|
*/
|
|
private _releaseCurve!: InternalEnvelopeCurve;
|
|
|
|
/**
|
|
* the signal which is output.
|
|
*/
|
|
protected _sig: Signal<"normalRange"> = new Signal({
|
|
context: this.context,
|
|
value: 0,
|
|
});
|
|
|
|
/**
|
|
* The output signal of the envelope
|
|
*/
|
|
output: OutputNode = this._sig;
|
|
|
|
/**
|
|
* Envelope has no input
|
|
*/
|
|
input: InputNode | undefined = undefined;
|
|
|
|
/**
|
|
* @param attack The amount of time it takes for the envelope to go from
|
|
* 0 to it's maximum value.
|
|
* @param decay The period of time after the attack that it takes for the envelope
|
|
* to fall to the sustain value. Value must be greater than 0.
|
|
* @param sustain The percent of the maximum value that the envelope rests at until
|
|
* the release is triggered.
|
|
* @param release The amount of time after the release is triggered it takes to reach 0.
|
|
* Value must be greater than 0.
|
|
*/
|
|
constructor(attack?: Time, decay?: Time, sustain?: NormalRange, release?: Time);
|
|
constructor(options?: Partial<EnvelopeOptions>)
|
|
constructor() {
|
|
|
|
super(optionsFromArguments(Envelope.getDefaults(), arguments, ["attack", "decay", "sustain", "release"]));
|
|
const options = optionsFromArguments(Envelope.getDefaults(), arguments, ["attack", "decay", "sustain", "release"]);
|
|
|
|
this.attack = options.attack;
|
|
this.decay = options.decay;
|
|
this.sustain = options.sustain;
|
|
this.release = options.release;
|
|
this.attackCurve = options.attackCurve;
|
|
this.releaseCurve = options.releaseCurve;
|
|
this.decayCurve = options.decayCurve;
|
|
}
|
|
|
|
static getDefaults(): EnvelopeOptions {
|
|
return Object.assign(ToneAudioNode.getDefaults(), {
|
|
attack: 0.01,
|
|
attackCurve: "linear" as EnvelopeCurveName,
|
|
decay: 0.1,
|
|
decayCurve: "exponential" as BasicEnvelopeCurve,
|
|
release: 1,
|
|
releaseCurve: "exponential" as EnvelopeCurveName,
|
|
sustain: 0.5,
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Read the current value of the envelope. Useful for
|
|
* synchronizing visual output to the envelope.
|
|
*/
|
|
get value(): NormalRange {
|
|
return this.getValueAtTime(this.now());
|
|
}
|
|
|
|
/**
|
|
* When triggerAttack is called, the attack time is the amount of
|
|
* time it takes for the envelope to reach it's maximum value.
|
|
* ```
|
|
* /\
|
|
* /X \
|
|
* /XX \
|
|
* /XXX \
|
|
* /XXXX \___________
|
|
* /XXXXX \
|
|
* /XXXXXX \
|
|
* /XXXXXXX \
|
|
* /XXXXXXXX \
|
|
* ```
|
|
* @min 0
|
|
* @max 2
|
|
*/
|
|
get attack(): Time {
|
|
return this._attack;
|
|
}
|
|
set attack(time) {
|
|
assertRange(this.toSeconds(time), 0);
|
|
this._attack = time;
|
|
}
|
|
|
|
/**
|
|
* After the attack portion of the envelope, the value will fall
|
|
* over the duration of the decay time to it's sustain value.
|
|
* ```
|
|
* /\
|
|
* / X\
|
|
* / XX\
|
|
* / XXX\
|
|
* / XXXX\___________
|
|
* / XXXXX \
|
|
* / XXXXX \
|
|
* / XXXXX \
|
|
* / XXXXX \
|
|
* ```
|
|
* @min 0
|
|
* @max 2
|
|
*/
|
|
get decay(): Time {
|
|
return this._decay;
|
|
}
|
|
set decay(time) {
|
|
assertRange(this.toSeconds(time), 0);
|
|
this._decay = time;
|
|
}
|
|
|
|
/**
|
|
* The sustain value is the value
|
|
* which the envelope rests at after triggerAttack is
|
|
* called, but before triggerRelease is invoked.
|
|
* ```
|
|
* /\
|
|
* / \
|
|
* / \
|
|
* / \
|
|
* / \___________
|
|
* / XXXXXXXXXXX\
|
|
* / XXXXXXXXXXX \
|
|
* / XXXXXXXXXXX \
|
|
* / XXXXXXXXXXX \
|
|
* ```
|
|
*/
|
|
get sustain(): NormalRange {
|
|
return this._sustain;
|
|
}
|
|
set sustain(val) {
|
|
assertRange(this.toSeconds(val), 0, 1);
|
|
this._sustain = val;
|
|
}
|
|
|
|
/**
|
|
* After triggerRelease is called, the envelope's
|
|
* value will fall to it's miminum value over the
|
|
* duration of the release time.
|
|
* ```
|
|
* /\
|
|
* / \
|
|
* / \
|
|
* / \
|
|
* / \___________
|
|
* / X\
|
|
* / XX\
|
|
* / XXX\
|
|
* / XXXX\
|
|
* ```
|
|
* @min 0
|
|
* @max 5
|
|
*/
|
|
get release(): Time {
|
|
return this._release;
|
|
}
|
|
set release(time) {
|
|
assertRange(this.toSeconds(time), 0);
|
|
this._release = time;
|
|
}
|
|
|
|
/**
|
|
* Get the curve
|
|
* @param curve
|
|
* @param direction In/Out
|
|
* @return The curve name
|
|
*/
|
|
private _getCurve(curve: InternalEnvelopeCurve, direction: EnvelopeDirection): EnvelopeCurve {
|
|
if (isString(curve)) {
|
|
return curve;
|
|
} else {
|
|
// look up the name in the curves array
|
|
let curveName: EnvelopeCurveName;
|
|
for (curveName in EnvelopeCurves) {
|
|
if (EnvelopeCurves[curveName][direction] === curve) {
|
|
return curveName;
|
|
}
|
|
}
|
|
// return the custom curve
|
|
return curve;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Assign a the curve to the given name using the direction
|
|
* @param name
|
|
* @param direction In/Out
|
|
* @param curve
|
|
*/
|
|
private _setCurve(
|
|
name: "_attackCurve" | "_decayCurve" | "_releaseCurve",
|
|
direction: EnvelopeDirection,
|
|
curve: EnvelopeCurve,
|
|
): void {
|
|
// check if it's a valid type
|
|
if (isString(curve) && Reflect.has(EnvelopeCurves, curve)) {
|
|
const curveDef = EnvelopeCurves[curve];
|
|
if (isObject(curveDef)) {
|
|
if (name !== "_decayCurve") {
|
|
this[name] = curveDef[direction];
|
|
}
|
|
} else {
|
|
this[name] = curveDef;
|
|
}
|
|
} else if (isArray(curve) && name !== "_decayCurve") {
|
|
this[name] = curve;
|
|
} else {
|
|
throw new Error("Envelope: invalid curve: " + curve);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* The shape of the attack.
|
|
* Can be any of these strings:
|
|
* * "linear"
|
|
* * "exponential"
|
|
* * "sine"
|
|
* * "cosine"
|
|
* * "bounce"
|
|
* * "ripple"
|
|
* * "step"
|
|
*
|
|
* Can also be an array which describes the curve. Values
|
|
* in the array are evenly subdivided and linearly
|
|
* interpolated over the duration of the attack.
|
|
* @example
|
|
* import { Envelope } from "tone";
|
|
* const env = new Envelope();
|
|
* env.attackCurve = "linear";
|
|
* @example
|
|
* import { Envelope } from "tone";
|
|
* const env = new Envelope();
|
|
* // can also be an array
|
|
* env.attackCurve = [0, 0.2, 0.3, 0.4, 1];
|
|
*/
|
|
get attackCurve(): EnvelopeCurve {
|
|
return this._getCurve(this._attackCurve, "In");
|
|
}
|
|
set attackCurve(curve) {
|
|
this._setCurve("_attackCurve", "In", curve);
|
|
}
|
|
|
|
/**
|
|
* The shape of the release. See the attack curve types.
|
|
* @example
|
|
* import { Envelope } from "tone";
|
|
* const env = new Envelope();
|
|
* env.releaseCurve = "linear";
|
|
*/
|
|
get releaseCurve(): EnvelopeCurve {
|
|
return this._getCurve(this._releaseCurve, "Out");
|
|
}
|
|
set releaseCurve(curve) {
|
|
this._setCurve("_releaseCurve", "Out", curve);
|
|
}
|
|
|
|
/**
|
|
* The shape of the decay either "linear" or "exponential"
|
|
* @example
|
|
* import { Envelope } from "tone";
|
|
* const env = new Envelope();
|
|
* env.decayCurve = "linear";
|
|
*/
|
|
get decayCurve(): BasicEnvelopeCurve {
|
|
return this._decayCurve;
|
|
}
|
|
set decayCurve(curve) {
|
|
this.assert(["linear", "exponential"].some(c => c === curve), `Invalid envelope curve: ${curve}`);
|
|
this._decayCurve = curve;
|
|
}
|
|
|
|
/**
|
|
* Trigger the attack/decay portion of the ADSR envelope.
|
|
* @param time When the attack should start.
|
|
* @param velocity The velocity of the envelope scales the vales.
|
|
* number between 0-1
|
|
* @example
|
|
* import { AmplitudeEnvelope, Oscillator } from "tone";
|
|
* const env = new AmplitudeEnvelope().toDestination();
|
|
* const osc = new Oscillator().connect(env).start();
|
|
* // trigger the attack 0.5 seconds from now with a velocity of 0.2
|
|
* env.triggerAttack("+0.5", 0.2);
|
|
*/
|
|
triggerAttack(time?: Time, velocity: NormalRange = 1): this {
|
|
this.log("triggerAttack", time, velocity);
|
|
time = this.toSeconds(time);
|
|
const originalAttack = this.toSeconds(this.attack);
|
|
let attack = originalAttack;
|
|
const decay = this.toSeconds(this.decay);
|
|
// check if it's not a complete attack
|
|
const currentValue = this.getValueAtTime(time);
|
|
if (currentValue > 0) {
|
|
// subtract the current value from the attack time
|
|
const attackRate = 1 / attack;
|
|
const remainingDistance = 1 - currentValue;
|
|
// the attack is now the remaining time
|
|
attack = remainingDistance / attackRate;
|
|
}
|
|
// attack
|
|
if (attack === 0) {
|
|
// case where the attack time is 0 should set instantly
|
|
this._sig.setValueAtTime(velocity, time);
|
|
} else if (this._attackCurve === "linear") {
|
|
this._sig.linearRampTo(velocity, attack, time);
|
|
} else if (this._attackCurve === "exponential") {
|
|
this._sig.targetRampTo(velocity, attack, time);
|
|
} else {
|
|
this._sig.cancelAndHoldAtTime(time);
|
|
let curve = this._attackCurve;
|
|
// find the starting position in the curve
|
|
for (let i = 1; i < curve.length; i++) {
|
|
// the starting index is between the two values
|
|
if (curve[i - 1] <= currentValue && currentValue <= curve[i]) {
|
|
curve = this._attackCurve.slice(i);
|
|
// the first index is the current value
|
|
curve[0] = currentValue;
|
|
break;
|
|
}
|
|
}
|
|
this._sig.setValueCurveAtTime(curve, time, attack, velocity);
|
|
}
|
|
// decay
|
|
if (decay) {
|
|
const decayValue = velocity * this.sustain;
|
|
const decayStart = time + attack;
|
|
this.log("decay", decayStart);
|
|
if (this._decayCurve === "linear") {
|
|
this._sig.linearRampTo(decayValue, decay, decayStart + this.sampleTime);
|
|
} else {
|
|
this.assert(this._decayCurve === "exponential",
|
|
`decayCurve can only be "linear" or "exponential", got ${this._decayCurve}`);
|
|
this._sig.exponentialApproachValueAtTime(decayValue, decayStart, decay);
|
|
}
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Triggers the release of the envelope.
|
|
* @param time When the release portion of the envelope should start.
|
|
* @example
|
|
* import { AmplitudeEnvelope, Oscillator } from "tone";
|
|
* const env = new AmplitudeEnvelope().toDestination();
|
|
* const osc = new Oscillator().connect(env).start();
|
|
* env.triggerAttack();
|
|
* // trigger the release half a second after the attack
|
|
* env.triggerRelease("+0.5");
|
|
*/
|
|
triggerRelease(time?: Time): this {
|
|
this.log("triggerRelease", time);
|
|
time = this.toSeconds(time);
|
|
const currentValue = this.getValueAtTime(time);
|
|
if (currentValue > 0) {
|
|
const release = this.toSeconds(this.release);
|
|
if (EQ(release, 0)) {
|
|
this._sig.setValueAtTime(0, time);
|
|
} else if (this._releaseCurve === "linear") {
|
|
this._sig.linearRampTo(0, release, time);
|
|
} else if (this._releaseCurve === "exponential") {
|
|
this._sig.targetRampTo(0, release, time);
|
|
} else {
|
|
this.assert(isArray(this._releaseCurve), "releaseCurve must be either 'linear', 'exponential' or an array");
|
|
this._sig.cancelAndHoldAtTime(time);
|
|
this._sig.setValueCurveAtTime(this._releaseCurve, time, release, currentValue);
|
|
}
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Get the scheduled value at the given time. This will
|
|
* return the unconverted (raw) value.
|
|
*/
|
|
getValueAtTime(time: Time): NormalRange {
|
|
return this._sig.getValueAtTime(time);
|
|
}
|
|
|
|
/**
|
|
* triggerAttackRelease is shorthand for triggerAttack, then waiting
|
|
* some duration, then triggerRelease.
|
|
* @param duration The duration of the sustain.
|
|
* @param time When the attack should be triggered.
|
|
* @param velocity The velocity of the envelope.
|
|
* @example
|
|
* import { AmplitudeEnvelope, Oscillator } from "tone";
|
|
* const env = new AmplitudeEnvelope().toDestination();
|
|
* const osc = new Oscillator().connect(env).start();
|
|
* // trigger the release 0.5 seconds after the attack
|
|
* env.triggerAttackRelease(0.5);
|
|
*/
|
|
triggerAttackRelease(duration: Time, time?: Time, velocity: NormalRange = 1): this {
|
|
time = this.toSeconds(time);
|
|
this.triggerAttack(time, velocity);
|
|
this.triggerRelease(time + this.toSeconds(duration));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Cancels all scheduled envelope changes after the given time.
|
|
*/
|
|
cancel(after?: Time): this {
|
|
this._sig.cancelScheduledValues(this.toSeconds(after));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Connect the envelope to a destination node.
|
|
*/
|
|
connect(destination: InputNode, outputNumber: number = 0, inputNumber: number = 0): this {
|
|
connectSignal(this, destination, outputNumber, inputNumber);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Render the envelope curve to an array of the given length.
|
|
* Good for visualizing the envelope curve
|
|
*/
|
|
async asArray(length: number = 1024): Promise<Float32Array> {
|
|
const duration = length / this.context.sampleRate;
|
|
const context = new OfflineContext(1, duration, this.context.sampleRate);
|
|
// normalize the ADSR for the given duration with 20% sustain time
|
|
const attackPortion = this.toSeconds(this.attack) + this.toSeconds(this.decay);
|
|
const envelopeDuration = attackPortion + this.toSeconds(this.release);
|
|
const sustainTime = envelopeDuration * 0.1;
|
|
const totalDuration = envelopeDuration + sustainTime;
|
|
// @ts-ignore
|
|
const clone = new this.constructor(Object.assign(this.get(), {
|
|
attack: duration * this.toSeconds(this.attack) / totalDuration,
|
|
decay: duration * this.toSeconds(this.decay) / totalDuration,
|
|
release: duration * this.toSeconds(this.release) / totalDuration,
|
|
context
|
|
})) as Envelope;
|
|
clone._sig.toDestination();
|
|
clone.triggerAttackRelease(duration * (attackPortion + sustainTime) / totalDuration, 0);
|
|
const buffer = await context.render();
|
|
return buffer.getChannelData(0);
|
|
}
|
|
|
|
dispose(): this {
|
|
super.dispose();
|
|
this._sig.dispose();
|
|
return this;
|
|
}
|
|
}
|
|
|
|
interface EnvelopeCurveObject {
|
|
In: number[];
|
|
Out: number[];
|
|
}
|
|
|
|
type EnvelopeDirection = keyof EnvelopeCurveObject;
|
|
|
|
interface EnvelopeCurveMap {
|
|
linear: "linear";
|
|
exponential: "exponential";
|
|
bounce: EnvelopeCurveObject;
|
|
cosine: EnvelopeCurveObject;
|
|
sine: EnvelopeCurveObject;
|
|
ripple: EnvelopeCurveObject;
|
|
step: EnvelopeCurveObject;
|
|
}
|
|
|
|
type EnvelopeCurveName = keyof EnvelopeCurveMap;
|
|
|
|
/**
|
|
* Generate some complex envelope curves.
|
|
*/
|
|
const EnvelopeCurves: EnvelopeCurveMap = (() => {
|
|
|
|
const curveLen = 128;
|
|
|
|
let i: number;
|
|
let k: number;
|
|
|
|
// cosine curve
|
|
const cosineCurve: number[] = [];
|
|
for (i = 0; i < curveLen; i++) {
|
|
cosineCurve[i] = Math.sin((i / (curveLen - 1)) * (Math.PI / 2));
|
|
}
|
|
|
|
// ripple curve
|
|
const rippleCurve: number[] = [];
|
|
const rippleCurveFreq = 6.4;
|
|
for (i = 0; i < curveLen - 1; i++) {
|
|
k = (i / (curveLen - 1));
|
|
const sineWave = Math.sin(k * (Math.PI * 2) * rippleCurveFreq - Math.PI / 2) + 1;
|
|
rippleCurve[i] = sineWave / 10 + k * 0.83;
|
|
}
|
|
rippleCurve[curveLen - 1] = 1;
|
|
|
|
// stairs curve
|
|
const stairsCurve: number[] = [];
|
|
const steps = 5;
|
|
for (i = 0; i < curveLen; i++) {
|
|
stairsCurve[i] = Math.ceil((i / (curveLen - 1)) * steps) / steps;
|
|
}
|
|
|
|
// in-out easing curve
|
|
const sineCurve: number[] = [];
|
|
for (i = 0; i < curveLen; i++) {
|
|
k = i / (curveLen - 1);
|
|
sineCurve[i] = 0.5 * (1 - Math.cos(Math.PI * k));
|
|
}
|
|
|
|
// a bounce curve
|
|
const bounceCurve: number[] = [];
|
|
for (i = 0; i < curveLen; i++) {
|
|
k = i / (curveLen - 1);
|
|
const freq = Math.pow(k, 3) * 4 + 0.2;
|
|
const val = Math.cos(freq * Math.PI * 2 * k);
|
|
bounceCurve[i] = Math.abs(val * (1 - k));
|
|
}
|
|
|
|
/**
|
|
* Invert a value curve to make it work for the release
|
|
*/
|
|
function invertCurve(curve: number[]): number[] {
|
|
const out = new Array(curve.length);
|
|
for (let j = 0; j < curve.length; j++) {
|
|
out[j] = 1 - curve[j];
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* reverse the curve
|
|
*/
|
|
function reverseCurve(curve: number[]): number[] {
|
|
return curve.slice(0).reverse();
|
|
}
|
|
|
|
/**
|
|
* attack and release curve arrays
|
|
*/
|
|
return {
|
|
bounce: {
|
|
In: invertCurve(bounceCurve),
|
|
Out: bounceCurve,
|
|
},
|
|
cosine: {
|
|
In: cosineCurve,
|
|
Out: reverseCurve(cosineCurve),
|
|
},
|
|
exponential: "exponential" as "exponential",
|
|
linear: "linear" as "linear",
|
|
ripple: {
|
|
In: rippleCurve,
|
|
Out: invertCurve(rippleCurve),
|
|
},
|
|
sine: {
|
|
In: sineCurve,
|
|
Out: invertCurve(sineCurve),
|
|
},
|
|
step: {
|
|
In: stairsCurve,
|
|
Out: invertCurve(stairsCurve),
|
|
},
|
|
};
|
|
})();
|