Sound definition JSON reference

Every field of the JSON format that describes an audx sound: sources, envelopes, filters, LFOs, effects, layers and 3D panning.

A SoundDefinition is either a single layer or a multi-layer sound. It’s plain JSON, so the same shape works in defineSound, generated sound files and theme files. Times are in seconds, frequencies in Hz, and detune in cents.

Layer

source · Source · required

The signal generator. See sources.

envelope · Envelope

Amplitude envelope. Defaults to a short 0.5 second fade. See envelope.

filter · Filter | Filter[]

Filters applied before the envelope. See filters.

gain · number · default: "0.5"

Output gain, 0 to 1.

pan · number

Stereo pan, -1 to 1. Don’t combine with panner.

panner · Panner3D

3D position. See 3D panner.

delay · number

Start delay relative to when the sound is triggered.

lfo · LFO | LFO[]

Periodic modulation. See LFO.

effects · Effect[]

Effects chain applied after the envelope. See effects.

Multi-layer sound

{
  "layers": [{ "source": { "type": "noise" }, "envelope": { "decay": 0.01 } }],
  "effects": [{ "type": "reverb", "mix": 0.1 }]
}

layers · Layer[] · required

Layers that play together.

effects · Effect[]

Effects applied to the sum of all layers.

Sources

Oscillator: sine, triangle, square, sawtooth

{ "type": "sine", "frequency": { "start": 1800, "end": 400 }, "detune": 0, "fm": { "ratio": 2, "depth": 100 } }

• frequency (required): a fixed value, or { start, end } for a pitch sweep.
• detune: cents.
• fm: frequency modulation. ratio is modulator to carrier, depth is the modulation index.

Noise

{ "type": "noise", "color": "pink" }

color: white (default), pink or brown.

Wavetable

{ "type": "wavetable", "harmonics": [1, 0.5, 0.25], "frequency": 440 }

harmonics lists the amplitude of each harmonic, starting with the fundamental. frequency works like an oscillator’s.

Sample

{ "type": "sample", "url": "/sounds/whoosh.mp3", "playbackRate": 1.2 }

• url: fetched, decoded and cached after the first load. Or pass a decoded buffer in code.
• playbackRate (default 1), detune.
• loop, loopStart, loopEnd.

Stream

{ type: "stream", stream: MediaStream } plays live input such as a microphone. Code only, and only with a real-time AudioContext.

Constant

{ "type": "constant", "offset": 1 }

A DC offset (default 1), useful as a control signal.

Envelope

Field	Default	Description
attack	0	Time to ramp from silence to peak.
decay	required	Time for the decay phase.
sustain	0	Level held after the decay, as a fraction of peak.
release	0	Time for the release after the sustain.

Filters

A biquad filter:

{ "type": "lowpass", "frequency": 2000, "resonance": 4, "envelope": { "attack": 0, "peak": 6000, "decay": 0.1 } }

Field	Description
type	lowpass, highpass, bandpass, notch, allpass, peaking, lowshelf or highshelf
frequency	Cutoff or center frequency
resonance	Q factor, default 1
gain	dB, for peaking and shelf types
envelope	Sweeps the cutoff to peak over attack (default 0), then back over decay

Or an IIR filter: { "type": "iir", "feedforward": number[], "feedback": number[] }.

LFO

{ "type": "sine", "frequency": 6, "depth": 20, "target": "detune" }

Field	Description
type	sine, triangle, square or sawtooth
frequency	Rate in Hz
depth	Amount, in the units of the target
target	frequency, detune, gain, pan, filter.frequency, filter.detune, filter.Q, filter.gain or playbackRate

Effects

Most effects take a mix from 0 (dry) to 1 (wet).

type	Fields (defaults)
reverb	decay (0.5), preDelay (0), damping (0), roomSize (1), mix (0.3)
convolver	url or buffer of an impulse response, mix (0.5)
delay	time (0.25), feedback (0.3), feedbackFilter ({ type, frequency, Q? }), mix (0.3)
distortion	amount (50), mix (0.5)
chorus	rate (1.5), depth (0.003), mix (0.3)
flanger	rate (0.5), depth (0.002), feedback (0.5), mix (0.5)
phaser	rate (0.5), depth (1000), stages (4), feedback (0.5), mix (0.5)
tremolo	rate (4), depth (0.5)
vibrato	rate (5), depth (0.002)
bitcrusher	bits (8), sampleRateReduction (1), mix (1)
compressor	threshold (-24), knee (30), ratio (4), attack (0.003), release (0.25)
eq	bands: list of { type: "lowshelf" | "highshelf" | "peaking", frequency, gain, Q? }
gain	value (required, linear)
pan	value (required, -1 to 1)

3D panner

{ "positionX": 2, "positionY": 0, "positionZ": -1 }

positionX, positionY and positionZ are required. Optional: orientationX/Y/Z, panningModel (HRTF default, or equalpower), distanceModel (inverse default, linear, exponential), maxDistance, refDistance, rolloffFactor, coneInnerAngle, coneOuterAngle, coneOuterGain.

Position the listener with setListener or useListener.