41 | /**
42 | *
43 | * @module envelopes
44 | */
45 | import { when } from './context'
46 | import { gain, scale } from './signals'
47 | import { isA, OPTS } from './utils'
48 | function eachStage (stages, fn) { stages.forEach(function (s) { fn.apply(null, s) }) }
49 |
50 | /**
51 | * Create an attack-decay envelope with fixed duration. It's composed by a
52 | * linear attack ramp and an exponential decay. This envelope doesn't
53 | * have release, so it stops after the duration (attack + decay).
54 | *
55 | * @param {Number} attack - (Optional) the attack time, defaults to 0.01
56 | * @param {Number} decay - (Optional) the decay time, defaults to 0.2
57 | * @param {Object} options - (Optional) an options with a context
58 | * @return {AudioNode} the signal envelope
59 | * @example
60 | * conn(sine(1000), perc(0.01, 0.5))
61 | * conn(sine(1000), perc(null, 1)) // default attack
62 | * conn(sine(1000), perc()) // default values
63 | */
64 | export function perc (attack, decay, opts) {
65 | if (isA('object', attack)) return perc(attack.attack, attack.decay, attack)
66 | var a = [ [0, 0, 'set'], [attack || 0.01, 1, 'lin'], [decay || 0.2, 0, 'exp'] ]
67 | return envelope(a, null, opts)
68 | }
69 |
70 | var ADSR = [0.01, 0.1, 0.8, 0.3]
71 | /**
72 | * Create an adsr envelope
73 | * @params {Object} options - (Optional) the options may include:
74 | *
75 | * - adsr: an array with the form [attack, decay, sustain, release]
76 | * - attack: the attack time (will override the a in the adsr param)
77 | * - decay: the decay time (will override the d in adsr param)
78 | * - sustain: the sustain gain value (will override the s in the adsr param)
79 | * - release: the release time (will override the r in the adsr param)
80 | */
81 | export function adsr (o) {
82 | o = o || OPTS
83 | var adsr = o.adsr || ADSR
84 | if (!isA('number', o.attack)) o.attack = adsr[0]
85 | if (!isA('number', o.decay)) o.decay = adsr[1]
86 | if (!isA('number', o.sustain)) o.sustain = adsr[2]
87 | if (!isA('number', o.release)) o.release = adsr[3]
88 | var a = [ [0, 0, 'set'], [o.attack, 1, 'lin'], [o.decay, o.sustain, 'exp'] ]
89 | var r = [ [0, o.sustain, 'set'], [o.release, 0, 'exp'] ]
90 | return envelope(a, r, o)
91 | }
92 |
93 | /**
94 | * A frequency envelope. Basically the setup to provide an adsr over a
95 | * number of octaves.
96 | * @param {Number} frequency - the initial frequency
97 | * @param {Number} octaves - (Optional) the number of octaves of the envelope (1 by default)
98 | * @param {Object} options - the same options as an ADSR envelope
99 | * @see adsr
100 | * @example
101 | * conn(saw(1200), lowpass(freqEnv(440, 2, { release: 1 })))
102 | */
103 | export function freqEnv (freq, octs, a, d, s, r, ac) {
104 | return scale(freq, freq * Math.pow(2, octs), adsr(a, d, s, 0, r, ac))
105 | }
106 |
107 | /**
108 | * Create a gain envelope
109 | * @param {Array<Stage>} attStages - the attack part of the envelope
110 | * @param {Array<Stage>} relStages - the release part of the envelope
111 | * @private
112 | */
113 | export function envelope (attEnvelope, relEnvelope, opts) {
114 | var g = gain(0, opts)
115 | g.start = apply(g.gain, attEnvelope)
116 | if (!relEnvelope) {
117 | g.duration = duration(attEnvelope)
118 | g.stop = function () {}
119 | } else {
120 | g.stop = apply(g.gain, relEnvelope)
121 | g.release = duration(relEnvelope)
122 | }
123 | return g
124 | }
125 |
126 | /**
127 | * Apply a contour to a parameter
128 | * @param {AudioParam} param - the parameter to apply the contour to
129 | * @param {Array<Stage>} contour - a list of countour stages, each of which
130 | * is composed of [time, value, type].
131 | * @example
132 | * apply(filter.frequency, [ [0, 440, 'set'], [5, 880, 'lin'] ])
133 | * @private
134 | */
135 | function apply (param, contour) {
136 | return function (t) {
137 | t = when(t, 0, param.context)
138 | eachStage(contour, function (time, value, type) {
139 | t += time
140 | if (type === 'set') param.setValueAtTime(value, t)
141 | else if (type === 'lin') param.linearRampToValueAtTime(value, t)
142 | else if (type === 'exp') param.exponentialRampToValueAtTime(value !== 0 ? value : 0.00001, t)
143 | else console.warn('Invalid stage type', time, value, type)
144 | })
145 | }
146 | }
147 |
148 | /**
149 | * Calculate the duration of a contour
150 | * @private
151 | */
152 | function duration (contour) {
153 | return contour.reduce(function (dur, stage) {
154 | return dur + stage[0]
155 | }, 0)
156 | }
157 |
158 |
159 |