hayleigh-dot-dev / elm-web-audio / WebAudio

Types


type Node

Represents a node in an audio processing singal graph. There are a handful of basic constructors: node for creating typical audio nodes, keyed for attaching a key or id to an existing node, and ref for referencing a node elsewhere in the graph by id.

There are also a number of constructors for specific audio nodes, such as oscillator and gain. These constructors mirror the low-level nodes provided by the Web Audio API: they make great building blocks!

import WebAudio
import WebAudio.Property

synth : Float -> Float -> List WebAudio.Node -> WebAudio.Node
synth freq gain connections =
    WebAudio.oscillator
        [ WebAudio.Parameters.frequency freq ]
        [ WebAudio.gain
            [ WebAudio.Parameters.gain gain ]
            connections
        ]

Basic Constructors

node : String -> List Property -> List Node -> Node

The most 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.

import WebAudio
import WebAudio.Property exposing (Property)

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

myOsc : WebAudio.Node
myOsc =
    omniOscillator
        [ WebAudio.Property.frequency 440 ]
        [ WebAudio.dac ]

ref : String -> Node

A ref node is used to refer to some other audio node by id. We can do things like create a feedback loop by connecting a node back into itself.

import WebAudio
import WebAudio.Property exposing (Property)

feedbackDelay : Float -> Float -> List WebAudio.Node -> WebAudio.Node
feedbackDelay amount time connections =
    WebAudio.keyed "feedback-delay" <|
        WebAudio.delay
            [ WebAudio.Property.delayTime time ]
            [ WebAudio.gain
                [ WebAudio.Property.gain gain ]
                -- Reference the delay node above by its key. This sends
                -- the output of the gain node back into the delay node,
                -- creating a feedback loop!
                (WebAudio.ref "feedback-delay" :: connections)
            ]

synth : Float -> Float -> WebAudio.Node
synth freq gain =
    WebAudio.oscillator
        [ WebAudio.Parameters.frequency freq ]
        [ WebAudio.gain
            [ WebAudio.Parameters.gain gain ]
            [ feedbackDelay 0.45 250 <|
                [ WebAudio.dac ]
            ]
        ]

keyed : String -> Node -> Node

Attach a key or id to an existing node. This is commonly used in conjunction with ref nodes to create feedback loops and other more complex signal graphs.

param : String -> String -> Node

Typically we chain audio nodes together either implicitly by nesting them or explicitly by using ref nodes but there is a third way to connect audio nodes: by connecting them to certain audio params!

This is useful for common synthesis techniques like AM and FM synthesis, or modulating parameters like cutoff frequencer of a filter using an oscillator.

import WebAudio
import WebAudio.Property

audio : List WebAudio.Node
audio =
    [ WebAudio.oscillator
        [ WebAudio.Property.frequency 5 ]
        -- Connect to the "frequency" parameter of the "carrier" node
        [ WebAudio.param "carrier" "frequency" ]
    , WebAudio.keyed "carrier" <|
        WebAudio.oscillator []
            [ WebAudio.dac ]
    ]

Web Audio Nodes

Common audio nodes

oscillator : List Property -> List Node -> Node

Common properties:

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

osc : List Property -> List Node -> Node

An alias for oscillator.

It turns out oscillators are pretty common in lots of audio signal graphs. It also turns out that "oscillator" is a pretty long word, so you can use osc instead to save your fingers and your eyes.

gain : List Property -> List Node -> Node

Common properties:

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

audioDestination : Node

The audio destination is... the destination of our audio! Connect to this node to get sound coming out of your speakers.

It doesn't have any parameters itself, and it doesn't make sense to connect the destination to anything else; it's the end of the line.

import WebAudio
import WebAudio.Property

audio : List WebAudio.Node
audio =
    [ WebAudio.oscillator
        [ WebAudio.Property.frequency 440 ]
        [ WebAudio.audioDestination ]
    ]

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

dac : Node

An alias for audioDestination. "dac" is another common name for an output: it stands for digital to analog converter.

delay : List Property -> List Node -> Node

Common properties:

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

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

Common properties:

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

Signal processing nodes

biquadFilter : List Property -> List Node -> Node

Common properties:

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

convolver : List Property -> List Node -> Node

Common properties:

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

dynamicsCompressor : List Property -> List Node -> Node

Common properties:

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

iirFilter : List Property -> List Node -> Node

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

panner : List Property -> List Node -> Node

Common properties:

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

stereoPanner : List Property -> List Node -> Node

Common properties:

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

waveShaper : List Property -> List Node -> Node

Common properties:

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

JSON Encoding

encode : Node -> Json.Encode.Value

Converts a Node into a value we can through a port to some JavaScript that can actually convert our signal graph into Web Audio code.

You could also go on to seriliase the graph with Json.Encode.encode and send it to a server, store it in LocalStorage, or other fun things.