waver-js - JavaScript "shaders" for audio

Contents:
1. Install
0. Usage
0. API
0. Language rules

__Install:__

``bash
npm install waver-js --save
`

__Usage:__

test.wv:
`text
input media iSound;

node pan nPan;
node gain nGain;

param float pRange;

iSound => nPan => nGain => wv_audioDestination;

nPan.pan {
Math.sin(Math.PI 0.5 Date.now() 0.001) this.pRange
}

nGain.gain {
((Date.now() * 0.001) % 1.35) / 1.35
}
`

index.js:
`javascript
import { createWaver, createAudioContext } from 'waver-js';

const context = createAudioContext();
const sound = document.getElementById("sound");

function startup(source) {
sound.play();

const waver = createWaver(context, source);
const soundSource = context.createMediaElementSource(sound);

waver.bindInput('iSound', soundSource);
waver.setParam('pRange', 0.65);
waver.enabled = true;
}

fetch('./test.wv')
.then(response => response.text())
.then(source => startup(source));
`

API

__Waver.createAudioContext()__
- return: AudioContext instance;

Creates instance of AudioContext.

------

__Waver.createWaver()__
- return: Waver instance;

Creates instance od Waver.

------

__Waver(context, source)__
- context: AudioContext instance;
- source: string with waver program code;

Waver class constructor. It compile source program or throw an error on failure.

------

__Waver.dispose()__

Release resources of this instance.

------

__Waver.bindOutput(id, value)__
- id: string with output id;
- value: AudioNode instance used as output.

Binds given AudioNode as output.

------

__Waver.bindInput(id, value)__
- id: string with input id;
- value: AudioNode instance used as input.

Binds given AudioNode as input.

------

__Waver.setParam(id, value)__
- id: string with param id;
- value: parameter value.

Apply given value to waver parameter.

------

__Waver.start()__

Start playing waver inputs.

------

__Waver.stop()__

Stop playing waver inputs.

------

__get Waver.valid__
- value: boolean;

It tells if this waver is valid (it's properly compiled)

------

__get Waver.outputs__
- value: array[string];

It tells what outputs are used by this waver.

------

__get Waver.inputs__
- value: array[string];

It tells what inputs are used by this waver.

------

__get Waver.params__
- value: array[string];

It tells what params are used by this waver.

------

__get Waver.nodes__
- value: array[string];

It tells what nodes are used by this waver.

------

__get/set Waver.enabled__
- value: boolean;

Tell or change it's enabled state (if this waver is able to process).

Language Rules

There are 3 types of operations:
- Node/param declarations;
- Connection chains;
- Nodes setup/update;

$3

There are 4 declaration modes:
- output - Tells about output node;
- input - Tells about input node;
- node - Tells about internal processing node;
- param - Tells about manipulation parameter;

__Example__
`text
output destination oTarget;
input buffer iSound;
node gain nGain;
param float pVolume;
`

__output__ (output ;)
_It's used as last node in connection chain._
type: available types and their WebAudio API mappings:
- destination: AudioDestinationNode
- stream: MediaStreamAudioDestinationNode
- audio: AudioNode

__input__ (input ;)
_It's used as first node in connection chain._
type: available types and their WebAudio API mappings:
- buffer: AudioBufferSourceNode
- constant: ConstantSourceNode
- media: MediaElementAudioSourceNode
- MediaStreamAudioSourceNode: ConstantSourceNode
- audio: AudioNode

__node__ (node [()];)
_It's used as intermediate node in connection chain._
_You can set initialization parameter in parenthesis after it's name._
type: available types and their WebAudio API mappings:
- biquadFilter: BiquadFilterNode - Initialization parameter is a type name (node biquadFilter nFilter(highpass);)
- delay: DelayNode - Initialization parameter is a delay value in seconds (node delay nDelay(0.5);)
- compressor: DynamicsCompressorNode
- gain: GainNode - Initialization parameter is a gain value in factor units (node gain nGain(0.5);)
- oscillator: OscillatorNode - Initialization parameter is a type name (node oscillator nOscillator(sine);)
- pan: StereoPannerNode - Initialization parameter is a pan value in [-1; 1] space (node pan nPan(-1);)

__param__ (param ;)
_It's used as node manipulation parameter as a way to control nodes from outside of waver._
_You can set initialization parameter in parenthesis after it's name._
type: available types and their JavaScript mappings:
- float: number

$3

Nodes are connected in chains where all node names are separated by arrow (=>).

__Example__
`text
iSound => nGain => nPan => oTarget;
`

$3

Here you assign expression to node properties (a-rate AudioParam or node property) or declare JavaScript lambda to update it.
When use lambda, you can access params by this context (nPan { this.pPanning }).

__Example__
`text
nPan.pan = pPanning;
nGain.gain = 0.5;
nPan2.pan {
Math.sin(Math.PI 0.5 Date.now() 0.001) this.pRange
}
``