sonance

Interaction sounds for the web. No audio files. No config. One import.

npm i sonance

usage

import { sonance } from "sonance";

sonance.play("confirm");
sonance.play("error");
sonance.play("success");

options

sonance.play("confirm", { gain: 0.6 }); // quieter
sonance.play("confirm", { pitch: +4 }); // 4 semitones up
sonance.play("confirm", { speed: 1.5 }); // faster
sonance.play("confirm", { pitch: -2, gain: 0.8, speed: 0.9 });

| option | type | default | description | | ------- | ------ | ------- | ------------------------- | | gain | number | 1 | volume multiplier | | pitch | number | 0 | semitones — +12 octave up | | speed | number | 1 | 2.0 = double speed |

chain API

Every sonance.play() returns a handle you can chain off:

sonance.play("confirm").then("success", 300); // play success 300ms later
sonance.play("error").repeat(3, 100); // repeat 3 times, 100ms gap
sonance.play("ambient").fade(0, 2000); // fade out over 2s
sonance.play("confirm").pitch(+4).speed(0.8); // mutate then play

const s = sonance.play("ambient");
s.stop(); // stop this sound

global controls

sonance.stop(); // stop all playing sounds
sonance.volume(0.5); // global volume, 0–1
sonance.volume(0); // mute

sounds

feedback

| name | when to use | | --------------- | ------------------------------ | | confirm | primary action, form submit | | success | async operation completed | | saved | auto-save, state persisted | | sent | message sent, email delivered | | complete | multi-step flow finished | | error | something failed | | criticalError | system failure, data loss risk | | denied | permission refused, blocked | | warn | proceed with caution |

interaction

| name | when to use | | ----------- | ------------------------------- | | click | button press | | softClick | checkbox, toggle, minor action | | hover | important interactive element | | toggle | switch activated | | destroy | delete, irreversible action | | countdown | timer tick — use with .repeat() |

ui

| name | when to use | | -------------- | -------------------------- | | notification | background alert | | ping | real-time event arrived | | upload | file uploading | | copy | clipboard confirmed | | drop | drag and drop landed | | pop | toast / snackbar dismissed | | swipe | gesture feedback | | unlock | auth success, modal open | | timer | countdown end |

texture

| name | character | | ----------- | -------------------------- | | dewdrop | water drop, soft transient | | breathIn | rising filtered noise | | whoosh | air, fast motion | | staticPop | vinyl, radio crackle |

synthesis

| name | character | | ------------- | -------------------------- | | glassChime | FM bell, long ring | | metalPing | struck metal, inharmonic | | organicBlip | plucked string attack | | deepThud | kick drum, physical impact |

filter

| name | character | | ----------------- | ------------------------ | | ribbonUp | analog synth filter open | | crystalRise | shimmer cluster rising | | filterSweepDown | power down, closing |

harmonic

| name | character | | -------------- | ---------------------------- | | zenBell | ring mod, alien bell tones | | warmConfirm | tube warmth, soft saturation | | morphSuccess | FM chord, noise into tone |

custom sounds

import { sonance, osc } from "sonance";

sonance.register({
  id: "mySound",
  pitchRange: [-1, 1], // auto micro-vary ±1 semitone each play
  gainRange: [0.9, 1.0], // auto micro-vary gain ±10%
  fn(v) {
    v({ freq: 400, freqEnd: 180, type: "sine", dur: 0.1, gain: 0.3 });
  },
});

sonance.play("mySound");
sonance.play("mySound").pitch(+2).repeat(3, 80);

how it works

Pure Web Audio API synthesis at runtime. No audio files are fetched or bundled. Every sound is generated from oscillators, noise buffers, FM operators, and filter sweeps — all math, no assets.

Requires a browser with Web Audio API support. The AudioContext starts on first interaction (browser requirement).

MIT · npm