spanda (स्पन्द)

procedural interface sounds for the web.

~4.2 kB minified + gzipped · zero dependencies · zero audio files · typescript types included

spanda synthesizes a small set of tactile ui sounds with the web audio api. there are no audio assets to preload. its plain api works with any framework.

the name comes from spanda (स्पन्द), sanskrit for pulse or vibration.

listen to every cue and profile

install

npm install spanda

spanda ships as esm for modern browsers.

quick start

import { createSpanda } from 'spanda'

const sound = createSpanda()

button.addEventListener('click', () => {
  sound.play('confirm')
})

create one instance for your app. spanda creates its audio context and shared graph on the first play() or resume() call, not when the module is imported.

cues

| cue | use | | --- | --- | | tap | buttons and lightweight interactions | | type | quiet, repeatable progress feedback | | toggleOn, toggleOff | binary state changes | | notify | incoming updates | | open, close | surfaces and navigation | | send | outgoing actions | | confirm | routine task completion | | error | failed actions | | complete | finishing an entire flow |

complete is a longer composed cue with different voicing for each profile.

profiles

| profile | character | | --- | --- | | tactile | balanced, compact and physical | | crisp | bright, precise and phone-speaker friendly | | lush | soft, rounded and more spacious |

change the profile without rebuilding the audio graph:

sound.setProfile('crisp')

override it for one cue without changing the instance default:

sound.play('tap', { profile: 'crisp' })
sound.play('complete', { profile: 'lush' })

custom profiles

built-in profiles are deeply frozen plain objects. copy one and change only what matters:

import { createSpanda, profiles } from 'spanda'

const muted = {
  ...profiles.tactile,
  baseFrequency: 132,
  reverb: 0.08,
  volumeVariationPercent: 2,
}

const sound = createSpanda({ profile: muted })

a profile copied from a built-in keeps its completion voice. profiles created from scratch can set completionStyle to tactile, crisp or lush; the default is tactile.

custom cues

a cue is a plain object too:

sound.play({
  hits: [
    { pitch: 1, gain: 0.42, glide: 1.04 },
    { offset: 0.07, pitch: 1.5, gain: 0.3, glide: 1.02 },
  ],
  decay: 0.8,
  reverb: 0.35,
  transient: 0.3,
  sub: 0.12,
})

profiles describe the voice. cue recipes describe the gesture. that is the whole extension model.

control

sound.setVolume(0.7)       // clamped between 0 and 1
sound.setEnabled(false)    // suspends the owned context
sound.setEnabled(true)
await sound.resume()       // useful inside an explicit user gesture
await sound.destroy()      // closes the owned context

browser behavior

start playback from a user gesture such as a click so the browser can allow audio. importing spanda during server rendering is safe. if the web audio api is unavailable or playback is blocked, sound calls become no-ops instead of interrupting the app.

development

pnpm install
pnpm demo
pnpm run check