Layers

A single layer is enough for most UI sounds, but you can stack multiple layers for richer, more complex results. Each layer has its own source, filter, envelope, and effects. Shared effects run after the layers are mixed together.

Single layer

When you pass source at the top level, you're defining a single layer:

defineSound({
  source: { type: "sine", frequency: 440 },
  envelope: { decay: 0.1 },
  gain: 0.3,
});

Multiple layers

Use the layers array to stack signals. Each one is independent - different waveforms, different timing, different volumes.

defineSound({
  layers: [
    {
      source: { type: "triangle", frequency: 523 },
      envelope: { attack: 0.01, decay: 0.15 },
      gain: 0.25,
    },
    {
      source: { type: "triangle", frequency: 659 },
      envelope: { attack: 0.01, decay: 0.15 },
      gain: 0.25,
      delay: 0.08,
    },
    {
      source: { type: "triangle", frequency: 784 },
      envelope: { attack: 0.01, decay: 0.15 },
      gain: 0.25,
      delay: 0.16,
    },
  ],
  effects: [
    { type: "reverb", decay: 0.3, damping: 0.4, mix: 0.15 },
  ],
});

Onset delay

The delay property on a layer offsets when it starts (in seconds). This is how you create arpeggiated chords, staggered hits, and build-ups.

Per-layer vs. global effects

Per-layer effects go in each layer's effects array - they only process that layer
Global effects go at the top level - they process the combined mix of all layers

defineSound({
  layers: [
    {
      source: { type: "sine", frequency: 440 },
      envelope: { decay: 0.3 },
      gain: 0.3,
      effects: [{ type: "distortion", amount: 20, mix: 0.5 }],
    },
    {
      source: { type: "sine", frequency: 880 },
      envelope: { decay: 0.3 },
      gain: 0.2,
    },
  ],
  effects: [
    { type: "reverb", decay: 1.2, mix: 0.35 },
  ],
});

Layer reference

Property	Type	Description
`source`	`Source`	The signal source (required)
`filter`	`Filter \| Filter[]`	Biquad/IIR filter chain
`envelope`	`Envelope`	Amplitude ADSR
`gain`	`number`	Layer volume (0-1)
`pan`	`number`	Stereo pan (-1 to 1)
`panner`	`Panner3D`	3D spatial positioning
`delay`	`number`	Onset delay in seconds
`lfo`	`LFO \| LFO[]`	Modulation oscillators
`effects`	`Effect[]`	Per-layer effects chain