Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/danigb/audio-contour

A 5 stage audio envelope generator
https://github.com/danigb/audio-contour

Last synced: 1 day ago
JSON representation

A 5 stage audio envelope generator

Awesome Lists containing this project

README 

        
# audio-contour [![npm](https://img.shields.io/npm/v/audio-contour.svg?style=flat-square)](https://www.npmjs.com/package/audio-contour)



[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard) [![license](https://img.shields.io/npm/l/audio-contour.svg?style=flat-square)](https://www.npmjs.com/package/audio-contour)



A 5 stage audio envelope generator. You can see the **[demo here](https://danigb.github.io/audio-contour/example)**:



```js

var Contour = require('audio-contour')

var ac = new AudioContext()



var vca = ac.createGain()

var osc = ac.createOscillator()

osc.connect(vca)



var env = Contour(ac, { t1: 0.2, t4: 0.5 })

env.connect(vca.gain)



env.start()

env.onstart = function (when) { osc.start(when) }

env.onended = function () { osc.stop() }

env.stop(ac.currentTime + 3)

```



This module implements a alpha-juno style envelope generator:



![Envelope Diagram from audiorealism.se](env.png?raw=true)



If you want to learn more about envelope generators, read [this](https://github.com/micjamking/synth-secrets/blob/master/part-8.md)



There are a lot of envelope generator implementations. Here are the standalone ones I know (there are several audio libraries that implements them):



- https://github.com/mmckegg/adsr

- https://www.npmjs.com/package/adsr-envelope

- https://github.com/itsjoesullivan/envelope-generator



Why choose this library over the others:



- Unlike others, it implements a 5 stage envelope (and can be reduced to a standard ADSR envelope)

- It supports `onstart` and `onended` events

- Can specify gate duration (for sequencer style)

- It's small (2.5Kb minified)



Why don't choose this library:



- It's very young project, still in development and not battle tested.

- Other libraries are great too!



## Installation



Via npm: `npm i --save audio-contour`



## Usage



**Create an envelope**



To create an envelope use the `Contour` function:



```js

var ac = new AudioContext()

var Contour = require('audio-contour')

var env = Contour(ac)

```



You can pass options to that function:



```js

var env = Contour(ac, { t1: 1 })

```



or change them on the object **before** start:



```js

var env = Contour(ac)

env.t1 = 1

env.t4 = 0.5

```



**Apply the envelope**



To apply the envelope, you have to connect it to something. For example, you can create a vca (voltage controlled amplifier) connecting it to a gain's gain param:



```js

var vca = ac.createGain()

env.connect(vca.gain)

```



Or create a vcf (voltage controlled filter) ocnnecting it to a filter frequency param:



```js

var vcf = ac.createBiquadFilter()

env.connect(vcf.frequency)

```



**Start and stop the envelope**



You can use `start` and `stop` function to the envelope:



```js

var now = ac.currentTime

env.start(now)

// suppose your audio source is an oscillator

osc.start(now)

var finish = env.stop(now + 1)

```



The `stop` function returns the time when the release phase ended. Can be used to stop the audio sources:



```js

osc.start(finish)

```



Remeber that **if duration is not `Infinity`, the envelope will stop automatically**:



```js

var env = Contour(ac)

env.duration = 1

env.start() // => it will automatically stop after 1 second

```



**Events**



Two events are supported: `onstart` and `onended`. The `onstart` event handler will be trigger at same time as the `start` function of the envelope, so it receives a time parameter. The `onended` event handler will be called when the envelope effectively stops:



```js

env.duration = 1

env.onstart = function (when) { osc.start(when) }

env.onended = function () { osc.stop(ac.currentTime) }

env.start() // since duration is not Infinity, both envent handlers will be called

```



**Create a standard ADSR**



When `t3` is 0, the audio-contour behaves like a normal ADSR envelope.



Additionally, you can use the standard `attack`, `decay`, `sustain` and `release` parameters in the constructor to build the envelope:



```js

var env = Contour(ac, { attack: 0.1, decay: 0.2, sustain: 0.8, release: 0.5 })

env.t1 // => 0.1 (the attack)

env.t2 // => 0.2 (the decay)

env.t3 // => 0

env.t4 // => 0.5 (the release)

```



## Run tests and examples



To run the tests, clone this repo and: `npm install && npm test`.



To run the example you need watchify installed: `npm install -g watchify`. Then, move to `examples` directory and type: `npm install && npm start`



## License



MIT License