pd-andy / elm-web-audio / WebAudio

Types


type Node

The core building block of any Web Audio signal graph. Keyed nodes are just like regular nodes but with an additonal Key property. This allows Ref nodes to reference them elsewhere in the graph!


type alias Type =
String

A simple type alias representing the type of Node. This could be something like "OscillatorNode" or "RefNode".


type alias Key =
String

A simple type alias representing unique key used to identify nodes. Use Keys like you would use the id attribute on a HTML element.


type alias Graph =
List Node

Basic Constructors

node : Type -> List Property -> List Node -> Node

General way to construct Web Audio nodes. This is used to create all the helper functions below. You can use this function to define custom nodes by partially applying just the type parameter. This is handy if you're using a library like Tone.js and want to use those nodes in Elm.

omniOscillator : List Property -> List Node -> Node
omniOscillator =
    node "Tone-OmniOscillatorNode"

myOsc =
    omniOscillator
        [ Property.freq 440 ]
        [ dac ]

ref : Key -> Node

A ref node is used to refer to a keyed node elsewhere in the graph. This is how we connect multiple "chains" of nodes together and represet a graph in a simple list.

key : Key -> Node -> Node

Use this function to apply a key to a node. In the case of already keyed nodes, or ref nodes, this will update the key to the new value.

a = osc [ Property.freq 440 ] [ dac ]
b = key "b" <| gain [ Property.gain 0.5 ] [ dac ]
c = ref "b"

key "myOsc" a -- Give a the key "myOsc"
key "myGain" b -- Rename b's key to "myGain"
key "myOsc" c -- c is now a RefNode to "myOsc"

param : Key -> String -> Node

Audio nodes can connect to AudioParams to modulate their value. Use this function for that. The first argument is the key of an existing keyedd node and the second argument is the name of the AudioParam to connect to.

This is commonly used for frequency modulation (FM) and amplitude modulation (AM) synthesis.

a = osc [ frequency 10 ] [ param "carrier" "frequency" ]
b = key "carrier" <| osc [] [ dac ]

Under the hood, this actually just creates a standard ref node! You could create this function yourself:

param key name = ref (key ++ "." name)

Web Audio Nodes

Common audio nodes

oscillator : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode Common properties:

osc : List Property -> List Node -> Node

An alias for oscillator.

gain : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/GainNode Common properties:

audioDestination : Node

See: https://developer.mozilla.org/en-US/docs/Web/API/AudioDestinationNode

dac : Node

An alias for audioDestination.

audioBufferSource : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode Common properties:

delay : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/DelayNode Common properties:

Utility nodes

channelMerger : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/ChannelMergerNode

channelSplitter : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/ChanneSplliterNode

constantSource : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/ConstantSourceNode Common properties:

Signal processing nodes

biquadFilter : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/BiquadFilterNode Common properties:

convolver : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/ConvolverNode Common properties:

dynamicsCompressor : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode Common properties:

iirFilter : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/

panner : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/PannerNode Common properties:

stereoPanner : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/StereoPannerNode Common properties:

waveShaper : List Property -> List Node -> Node

See: https://developer.mozilla.org/en-US/docs/Web/API/WaveShaperNode Common properties:

JSON Encoding

To turn the json in Web Audio nodes, you need to know what that data looks like. Here's a breakdown of how everything is encoded:

Node:

{
    "type": "OscillatorNode",
    "properties": [
        ...
    ],
    "connections": [
        ...
    ]
}

Keyed:

{
    "key": "myOsc",
    "type": "OscillatorNode",
    "properties": [
        ...
    ],
    "connections": [
        ...
    ]
}

Ref:

{
    "key": "myOsc",
    "type": "RefNode"
}

Properties can come in two types, AudioParam and NodeProperty. While the Web Audio API doesn't make an official distinction between the two, how they are used differs.

AudioParams represent parameters that can be updated at either audio rate (a-rate) or control rate (k-rate). Other audio nodes can connect to an AudioParam and modulate its value in real time. Examples of AudioParams include frequency, gain, and delayTime.

AudioParam:

{
    "type": "AudioParam",
    "label": "frequency",
    "value": 440
}

NodeProperties are any other parameter on an audio node. An example of a NodeProperty is an OscillatorNode's "type" parameter.

NodeProperty:

{
   "type": "NodeProperty",
   "label": "type",
   "value": "square"
}

encode : Node -> Json.Encode.Value

Converts a Node into a Json value. Use this to send a node through a port to javascipt, where it can be constructed into a Web Audio node!

encodeGraph : Graph -> Json.Encode.Value

Encode a graph of nodes into a Json value. More than likely you'll use this more than encode