Skip to content

Commit 9f8734e

Browse files
alemanguialemangui
committed
Changes property 'sustain' for 'release'. Sustain remains usable but is now deprecated. Solves PR #20.
1 parent ebae63b commit 9f8734e

8 files changed

Lines changed: 151 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Pizzicato aims to simplify the way you create and manipulate sounds via the Web
2323
- [removeEffect()](#sounds-remove-effect)
2424
- [volume](#sounds-volume)
2525
- [attack](#sounds-attack)
26-
- [sustain](#sounds-sustain)
26+
- [release](#sounds-release)
2727
- [frequency](#sounds-frequency)
2828
- [Connecting sounds to AudioNodes](#sounds-connect)
2929
- [Effects](#effects)
@@ -133,7 +133,7 @@ To create a sound from an oscillator with a certain waveform, use the ```source:
133133
* ```type``` _(Optional; ```sine```, ```square```, ```triangle``` or ```sawtooth```, defaults to ```sine```)_: Specifies the type of waveform.
134134
* ```frequency``` _(Optional; defaults to 440)_: Indicates the frequency of the wave (i.e., a 440 value will yield an A note).
135135
* ```volume``` _(Optional; min: 0, max: 1, defaults to 1)_: Loudness of the sound.
136-
* ```sustain``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-out time when the sound is stopped.
136+
* ```release``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-out time when the sound is stopped.
137137
* ```attack``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-in time when the sound is played.
138138
* ```detached``` _(Optional; defaults to false)_: If true, the sound will not be connected to the context's destination, and thus, will not be audible.
139139

@@ -156,7 +156,7 @@ In order to load a sound from a file, include the ```source: file``` in your des
156156
* ```path``` _(Mandatory; string or array of strings)_: Specifies the path of the sound file. It is also possible to have an array of paths to fallback on. Pizzicato will attempt to load the paths in order, passing on to the next one in case of failure.
157157
* ```loop``` _(Optional; boolean, defaults to false)_: If set, the file will start playing again after the end.
158158
* ```volume``` _(Optional; min: 0, max: 1, defaults to 1)_: Loudness of the sound.
159-
* ```sustain``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
159+
* ```release``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
160160
* ```attack``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-in time when the sound is played.
161161
* ```detached``` _(Optional; defaults to false)_: If true, the sound will not be connected to the context's destination, and thus, will not be audible.
162162

@@ -188,7 +188,7 @@ Check the [supported audio files](#audio-formats) that can be played with Pizzic
188188
### Sounds from the user input ([example](https://alemangui.github.io/pizzicato/#sound-from-input))
189189
It is also possible to use the sound input from the computer. This is usually the microphone, but it could also be a line-in input. To use this, add ```source: input``` in your description. The following optional parameters are possible inside ```options``` object:
190190
* ```volume``` _(Optional; min: 0, max: 1, defaults to 1)_: Loudness of the sound.
191-
* ```sustain``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
191+
* ```release``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
192192
* ```attack``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-in time when the sound is played.
193193
* ```detached``` _(Optional; defaults to false)_: If true, the sound will not be connected to the context's destination, and thus, will not be audible.
194194

@@ -205,7 +205,7 @@ For more creative freedom, Pizzicato also allows direct audio processing. Sounds
205205
* ```audioFunction``` _(Mandatory; function(<audio processing event>))_: Function that will be called with the audio processing event.
206206
* ```bufferSize``` _(Optional; number - must be a power of 2.)_: This value controls how many sample frames will be processed at each audio process event. Lower values will result in lower latency, higher values help prevent glitches.
207207
* ```volume``` _(Optional; min: 0, max: 1, defaults to 1)_: Loudness of the sound.
208-
* ```sustain``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
208+
* ```release``` _(Optional; defaults to 0)_: Value in seconds that indicates the fade-out time once the sound is stopped.
209209
* ```attack``` _(Optional; defaults to 0.4)_: Value in seconds that indicates the fade-in time when the sound is played.
210210
* ```detached``` _(Optional; defaults to false)_: If true, the sound will not be connected to the context's destination, and thus, will not be audible.
211211

@@ -311,7 +311,7 @@ sound.volume = 0.5;
311311
```
312312

313313
<a name="sounds-attack"/>
314-
### Attack ([example](https://alemangui.github.io/pizzicato/#attack-sustain))
314+
### Attack ([example](https://alemangui.github.io/pizzicato/#attack-release))
315315

316316
Use the sound's ```attack``` property to modify its attack (or fade-in) value. This value eases the beginning of the sound, often avoiding unwanted clicks.
317317

@@ -323,17 +323,17 @@ var sound = new Pizzicato.Sound();
323323
sound.attack = 0.9;
324324
```
325325

326-
<a name="sounds-sustain"/>
327-
### Sustain ([example](https://alemangui.github.io/pizzicato/#attack-sustain))
326+
<a name="sounds-release"/>
327+
### Release ([example](https://alemangui.github.io/pizzicato/#attack-release))
328328

329-
Use the sound's ```sustain``` property to modify its sustain (or fade-out) value. This value eases the end of the sound, often avoiding unwanted clicks.
329+
Use the sound's ```release``` property to modify its release (or fade-out) value. This value eases the end of the sound, often avoiding unwanted clicks.
330330

331-
* ```sustain``` _(min: 0, max: 10, defaults to 0.04)_: The sound's sustain.
331+
* ```release``` _(min: 0, max: 10, defaults to 0.04)_: The sound's release.
332332

333333
Example:
334334
```javascript
335335
var sound = new Pizzicato.Sound();
336-
sound.sustain = 0.9;
336+
sound.release = 0.9;
337337
```
338338

339339
<a name="sounds-frequency"/>

‎distr/Pizzicato.js‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@
200200
var descriptionError = getDescriptionError(description);
201201
var hasOptions = util.isObject(description) && util.isObject(description.options);
202202
var defaultAttack = 0.04;
203-
var defaultSustain = 0.04;
203+
var defaultRelease = 0.04;
204204

205205
if (descriptionError) {
206206
console.error(descriptionError);
@@ -218,9 +218,17 @@
218218
this.playing = this.paused = false;
219219
this.loop = hasOptions && description.options.loop;
220220
this.attack = hasOptions && util.isNumber(description.options.attack) ? description.options.attack : defaultAttack;
221-
this.sustain = hasOptions && util.isNumber(description.options.sustain) ? description.options.sustain : defaultSustain;
222221
this.volume = hasOptions && util.isNumber(description.options.volume) ? description.options.volume : 1;
223222

223+
if (hasOptions && util.isNumber(description.options.release)) {
224+
this.release = description.options.release;
225+
} else if (hasOptions && util.isNumber(description.options.sustain)) {
226+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
227+
this.release = description.options.sustain;
228+
} else {
229+
this.release = defaultRelease;
230+
}
231+
224232
if (!description)
225233
(initializeWithWave.bind(this))({}, callback);
226234

@@ -422,7 +430,7 @@
422430
return;
423431

424432
this.paused = this.playing = false;
425-
this.stopWithSustain();
433+
this.stopWithRelease();
426434

427435
this.offsetTime = 0;
428436
this.trigger('stop');
@@ -440,7 +448,7 @@
440448
this.paused = true;
441449
this.playing = false;
442450

443-
this.stopWithSustain();
451+
this.stopWithRelease();
444452

445453
var elapsedTime = Pz.context.currentTime - this.lastTimePlayed;
446454

@@ -465,7 +473,7 @@
465473
options: {
466474
loop: this.loop,
467475
attack: this.attack,
468-
sustain: this.sustain,
476+
release: this.release,
469477
volume: this.volume,
470478
sound: this
471479
}
@@ -608,6 +616,25 @@
608616
}
609617
},
610618

619+
/**
620+
* @deprecated - Use "release"
621+
*/
622+
sustain: {
623+
enumerable: true,
624+
625+
get: function() {
626+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
627+
return this.release;
628+
},
629+
630+
set: function(sustain){
631+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
632+
633+
if (Pz.Util.isInRange(sustain, 0, 10))
634+
this.release = sustain;
635+
}
636+
},
637+
611638

612639
/**
613640
* Returns the node that produces the sound. For example, an oscillator
@@ -689,10 +716,10 @@
689716

690717
/**
691718
* Will take the current source node and work down the volume
692-
* gradually in as much time as specified in the sustain property
719+
* gradually in as much time as specified in the release property
693720
* of the sound before stopping the source node.
694721
*/
695-
stopWithSustain: {
722+
stopWithRelease: {
696723
enumerable: false,
697724

698725
value: function(callback) {
@@ -702,14 +729,14 @@
702729
return Pz.Util.isFunction(node.stop) ? node.stop(0) : node.disconnect();
703730
};
704731

705-
if (!this.sustain)
732+
if (!this.release)
706733
stopSound();
707734

708735
this.fadeNode.gain.setValueAtTime(this.fadeNode.gain.value, Pizzicato.context.currentTime);
709-
this.fadeNode.gain.linearRampToValueAtTime(0.00001, Pizzicato.context.currentTime + this.sustain);
736+
this.fadeNode.gain.linearRampToValueAtTime(0.00001, Pizzicato.context.currentTime + this.release);
710737
window.setTimeout(function() {
711738
stopSound();
712-
}, this.sustain * 1000);
739+
}, this.release * 1000);
713740
}
714741
}
715742
});

‎distr/Pizzicato.min.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎site/Pizzicato.js‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@
200200
var descriptionError = getDescriptionError(description);
201201
var hasOptions = util.isObject(description) && util.isObject(description.options);
202202
var defaultAttack = 0.04;
203-
var defaultSustain = 0.04;
203+
var defaultRelease = 0.04;
204204

205205
if (descriptionError) {
206206
console.error(descriptionError);
@@ -218,9 +218,17 @@
218218
this.playing = this.paused = false;
219219
this.loop = hasOptions && description.options.loop;
220220
this.attack = hasOptions && util.isNumber(description.options.attack) ? description.options.attack : defaultAttack;
221-
this.sustain = hasOptions && util.isNumber(description.options.sustain) ? description.options.sustain : defaultSustain;
222221
this.volume = hasOptions && util.isNumber(description.options.volume) ? description.options.volume : 1;
223222

223+
if (hasOptions && util.isNumber(description.options.release)) {
224+
this.release = description.options.release;
225+
} else if (hasOptions && util.isNumber(description.options.sustain)) {
226+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
227+
this.release = description.options.sustain;
228+
} else {
229+
this.release = defaultRelease;
230+
}
231+
224232
if (!description)
225233
(initializeWithWave.bind(this))({}, callback);
226234

@@ -422,7 +430,7 @@
422430
return;
423431

424432
this.paused = this.playing = false;
425-
this.stopWithSustain();
433+
this.stopWithRelease();
426434

427435
this.offsetTime = 0;
428436
this.trigger('stop');
@@ -440,7 +448,7 @@
440448
this.paused = true;
441449
this.playing = false;
442450

443-
this.stopWithSustain();
451+
this.stopWithRelease();
444452

445453
var elapsedTime = Pz.context.currentTime - this.lastTimePlayed;
446454

@@ -465,7 +473,7 @@
465473
options: {
466474
loop: this.loop,
467475
attack: this.attack,
468-
sustain: this.sustain,
476+
release: this.release,
469477
volume: this.volume,
470478
sound: this
471479
}
@@ -608,6 +616,25 @@
608616
}
609617
},
610618

619+
/**
620+
* @deprecated - Use "release"
621+
*/
622+
sustain: {
623+
enumerable: true,
624+
625+
get: function() {
626+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
627+
return this.release;
628+
},
629+
630+
set: function(sustain){
631+
console.warn('\'sustain\' is deprecated. Use \'release\' instead.');
632+
633+
if (Pz.Util.isInRange(sustain, 0, 10))
634+
this.release = sustain;
635+
}
636+
},
637+
611638

612639
/**
613640
* Returns the node that produces the sound. For example, an oscillator
@@ -689,10 +716,10 @@
689716

690717
/**
691718
* Will take the current source node and work down the volume
692-
* gradually in as much time as specified in the sustain property
719+
* gradually in as much time as specified in the release property
693720
* of the sound before stopping the source node.
694721
*/
695-
stopWithSustain: {
722+
stopWithRelease: {
696723
enumerable: false,
697724

698725
value: function(callback) {
@@ -702,14 +729,14 @@
702729
return Pz.Util.isFunction(node.stop) ? node.stop(0) : node.disconnect();
703730
};
704731

705-
if (!this.sustain)
732+
if (!this.release)
706733
stopSound();
707734

708735
this.fadeNode.gain.setValueAtTime(this.fadeNode.gain.value, Pizzicato.context.currentTime);
709-
this.fadeNode.gain.linearRampToValueAtTime(0.00001, Pizzicato.context.currentTime + this.sustain);
736+
this.fadeNode.gain.linearRampToValueAtTime(0.00001, Pizzicato.context.currentTime + this.release);
710737
window.setTimeout(function() {
711738
stopSound();
712-
}, this.sustain * 1000);
739+
}, this.release * 1000);
713740
}
714741
}
715742
});

‎site/index.html‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -178,21 +178,21 @@ <h3 id="sound-from-function">Create your own audio function</h3>
178178

179179
<h3>Add effects</h3>
180180

181-
<h4 id="attack-sustain">Attack/Sustain</h4>
181+
<h4 id="attack-release">Attack/Release</h4>
182182
<pre><code class="language-javascript">
183183
var sineWave = new Pizzicato.Sound({
184184
source: 'wave'
185185
});
186186

187187
sineWave.attack = 0.5;
188-
sineWave.sustain = 1;
188+
sineWave.release = 1;
189189
sound.play();
190190
</code></pre>
191191

192192
<div class="slider-group">
193193
<div class="slider">
194-
<label for="volume-sustain">Volume</label>
195-
<input type="range" min="0" max="1" step="0.01" value="1" id="volume-sustain" />
194+
<label for="volume-release">Volume</label>
195+
<input type="range" min="0" max="1" step="0.01" value="1" id="volume-release" />
196196
<div class="slider-value">1</div>
197197
</div>
198198
<div class="slider">
@@ -201,15 +201,15 @@ <h4 id="attack-sustain">Attack/Sustain</h4>
201201
<div class="slider-value">0.5</div>
202202
</div>
203203
<div class="slider">
204-
<label for="value-sustain">Sustain</label>
205-
<input type="range" min="0" max="3" step="0.01" value="1" id="value-sustain" />
204+
<label for="value-release">Release</label>
205+
<input type="range" min="0" max="3" step="0.01" value="1" id="value-release" />
206206
<div class="slider-value">1</div>
207207
</div>
208208
</div>
209209

210210
<div class="controls">
211-
<button id="stop-sustain" class="stop action"></button>
212-
<button id="play-sustain" class="play action"></button>
211+
<button id="stop-release" class="stop action"></button>
212+
<button id="play-release" class="play action"></button>
213213
</div>
214214

215215

‎site/js/main.js‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ var ringModulator = new Pizzicato.Effects.RingModulator({
5252

5353
// Sounds
5454
var sineWave = new Pz.Sound();
55-
var sineWaveSustain = new Pz.Sound({ source: 'wave', options: { frequency: 220, sustain: 1, attack:0.5 } });
55+
var sineWaveRelease = new Pz.Sound({ source: 'wave', options: { frequency: 220, release: 1, attack:0.5 } });
5656
var acoustic = new Pz.Sound(dolbySupported ? './audio/acoustic_Dolby.mp4' : './audio/acoustic.m4a');
5757

5858
var timba = new Pz.Sound({
@@ -209,11 +209,11 @@ var segments = [
209209
volumeSlider: document.getElementById('volume-white')
210210
},
211211
{
212-
audio: sineWaveSustain,
213-
playButton: document.getElementById('play-sustain'),
214-
stopButton: document.getElementById('stop-sustain'),
215-
volumeSlider: document.getElementById('volume-sustain'),
216-
sustainSlider: document.getElementById('value-sustain'),
212+
audio: sineWaveRelease,
213+
playButton: document.getElementById('play-release'),
214+
stopButton: document.getElementById('stop-release'),
215+
volumeSlider: document.getElementById('volume-release'),
216+
releaseSlider: document.getElementById('value-release'),
217217
attackSlider: document.getElementById('value-attack')
218218
},
219219
{
@@ -456,10 +456,10 @@ for (var i = 0; i < segments.length; i++) {
456456
volumeDisplay.innerHTML = segment.audio.volume = e.target.valueAsNumber;
457457
});
458458

459-
if (segment.sustainSlider) {
460-
segment.sustainSlider.addEventListener('input', function(e) {
461-
var sustainDisplay = segment.sustainSlider.parentNode.getElementsByClassName('slider-value')[0];
462-
sustainDisplay.innerHTML = segment.audio.sustain = e.target.valueAsNumber;
459+
if (segment.releaseSlider) {
460+
segment.releaseSlider.addEventListener('input', function(e) {
461+
var releaseDisplay = segment.releaseSlider.parentNode.getElementsByClassName('slider-value')[0];
462+
releaseDisplay.innerHTML = segment.audio.release = e.target.valueAsNumber;
463463
});
464464
}
465465

0 commit comments

Comments
 (0)