waver-js - JavaScript "shaders" for audio

Contents:

1. Install
2. Usage
3. API
4. Language rules

Install:

npm install waver-js --save

Usage:

test.wv:

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:

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;

Node/param declaration

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

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

output (output <type> <name>;) 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 <type> <name>;) 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 <type> <name> [(<param>)];) 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 <type> <name>;) 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

Connection chain

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

Example

iSound => nGain => nPan => oTarget;

Node setup/update

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

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