Dot-audio NPM | npm.io

Dot

Dot is a simple web audio library for creating synthesizers and other real-time audio synthesis projects.

Installation

Install using npm

npm install dot-audio

Install using yarn:

yarn add dot-audio

Importing Dot in a project:

import * as Dot from 'dot-audio'

Importing specific nodes/classes:

import { MonoSynth, Keyboard } from 'dot-audio'

Overview

Dot includes a collection of nodes, classes, and utility functions to make creating audio projects as easy as possible, while still remaining lightweight and flexible.

A general overview of what is available:

Wrappers for most native web audio api nodes (gain, filter, delay, etc.)
ADSR envelope nodes (general-purpose envelope, gain envelope, filter envelope)
Effect nodes (chorus, distortion, reverb, etc.)
Source nodes for signal generation and modulation (oscillator, lfo, noise generator, etc.)
Custom instruments for general use (MonoSynth, PolySynth, FMSynth, etc.)
Pre-built keyboard input class (more input classes will be added in the future)

More extensive documentation is available on the docs site.

Basic Usage

Basic Example:

import * as Dot from 'dot-audio'

// Audio context of your choosing
const AC = new AudioContext()

// Props to create a square wave pluck sound
const pluckProps = {
    waveform: 'square',
    filterFrequency: 0, // Filter frequency value
    filterAmount: 1000, // Filter envelope amount
    filterDecay: 0.4, // Filter envelope decay time
    filterSustain: 0, // Filter envelope sustain value
}
// Create polyphonic synth with pluck props
const synth = new Dot.PolySynth(AC, pluckProps)

// Connect synth to destination and play Cm7 chord
synth.connect(AC.destination)
synth.noteOn(['C4', 'D#4', 'G4', 'A#4'])

Node-Chaining Example:

import * as Dot from 'dot-audio'

// Audio context
const AC = new AudioContext()

// Create polyphonic synth
const synth = new Dot.PolySynth(
    AC,
    {
        waveform: 'square',
        filterFrequency: 0,
        filterAmount: 1000,
        filterDecay: 0.4,
        filterSustain: 0,
    }
)

// Create chorus and reverb effects for a nice lush sound
const chorus = new Dot.Chorus(AC, { amount: 0.4 })
const reverb = new Dot.Reverb(AC, { amount: 0.25 })

// Create a limiter to tame the output
const limiter = new Dot.Limiter(AC)

// Connect all nodes together and play Cm7 chord
Dot.chain(synth, chorus, reverb, limiter, AC.destination)
synth.noteOn(['C4', 'D#4', 'G4', 'A#4'])

Keyboard Example:

import * as Dot from 'dot-audio'

const AC = new AudioContext()

// Nodes
const synth = new Dot.PolySynth(
    AC,
    {
        waveform: 'square',
        filterFrequency: 0,
        filterAmount: 1000,
        filterDecay: 0.4,
        filterSustain: 0,
        filterRelease: 0.1,
    }
)
const chorus = new Dot.Chorus(AC, { amount: 0.4 })
const reverb = new Dot.Reverb(AC, { amount: 0.25 })
const limiter = new Dot.Limiter(AC)

// Connect
Dot.chain(synth, chorus, reverb, limiter, AC.destination)

// Keyboard setup
const keyboard = new Dot.Keyboard({
    onPress: (noteInfo) => {
        // Start context when the user tries to play a note
        if (AC.state === 'suspended') AC.resume()

        synth.noteOn(noteInfo.fullNote)
    },
    onRelease: (noteInfo) => {
        synth.noteOff(noteInfo.fullNote)
    },
})

// Start keyboard listeners
keyboard.on()

NOTE: Browsers will not play audio by default without some form of interaction from the user (i.e. a click or key press). The above example also demonstrates a method to resume the audio context when the user attempts to play a note.

Nodes

All nodes are created using the following syntax:

const node = new Dot.NodeName(AC, props)

All DotAudioNodes have access to a ::connect and ::disconnect methods to connect to other DotAudioNodes or native audio nodes.

Warning: Native audio nodes will not be able to connect to DotAudioNodes directly, but may be connected to params via the ::getParam and ::getParams methods.

Core Nodes

Dot includes the following core nodes:

ChannelMerger
ChannelSplitter
Compressor
Convolver
Delay
Filter
Gain
StereoPanner
WaveShaper

Instruments

Instruments are pre-built general purpose sound sources for easy use in a project. All instruments have methods to set their primary properties and ::noteOn, ::noteOff, and ::noteStop methods to play notes that are passed in and trigger the instrument's envelope(s). (FMSynth is the only exception due to the algorithms having different carriers. The ::triggerAttack and ::triggerRelease methods can be used to trigger the envelope in that case)

Dot includes the following instruments:

Synth - Oscillator connected to a gain envelope
MonoSynth - Oscillator connected to a gain envelope and filter envelope
PolySynth - An 8 voice polyphonic synth built using MonoSynths
SimpleFMSynth - One modulator and one carrier connected to a gain envelope
FMSynth - Uses 4 modulators that are connected via different built-in algorithms, then connected to a gain envelope