Add sound to your icons.

1/**
2 * A tiny sound engine for the animated icons. It has no dependencies: copy this file, sound-kit.ts and the
3 * score of every icon you want to hear, and call playIconScore(score). Nothing is downloaded: every sound
4 * is synthesised in the browser with the Web Audio API, note by note, against the animation it belongs to.
5 */
6 
7/** Stretches or squeezes time, so a sound follows the icon's `speed` prop. */
8export type ScoreTime = (seconds: number) => number;
9 
10/** What every icon's sound file exports. */
11export type IconScore = {
12  /** How long it plays at normal speed, in seconds. */
13  length: number;
14  /** How loud it is next to the other icons (measured, so they all sound about equally loud). */
15  level: number;
16  play: (c: AudioContext, out: AudioNode, t: ScoreTime) => void;
17};
18 
19const STORAGE_KEY = "nx-icon-sounds";
20 
21let ctx: AudioContext | null = null;
22let master: GainNode | null = null;
23let noiseBuf: AudioBuffer | null = null;
24let enabled: boolean | null = null;
25const listeners = new Set<() => void>();
26 
27function audio(): AudioContext | null {
28  if (typeof window === "undefined") return null;
29  if (!ctx) {
30    const AC = window.AudioContext || (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
31    if (!AC) return null;
32    ctx = new AC();
33    master = ctx.createGain();
34    master.gain.value = 0.5;
35    const comp = ctx.createDynamicsCompressor();
36    master.connect(comp).connect(ctx.destination);
37  }
38  if (ctx.state === "suspended") void ctx.resume();
39  return ctx;
40}
41 
42function noise(c: AudioContext) {
43  if (!noiseBuf) {
44    noiseBuf = c.createBuffer(1, c.sampleRate, c.sampleRate);
45    const d = noiseBuf.getChannelData(0);
46    for (let i = 0; i < d.length; i++) d[i] = Math.random() * 2 - 1;
47  }
48  const s = c.createBufferSource();
49  s.buffer = noiseBuf;
50  return s;
51}
52 
53export type ToneOpts = { freq: number; to?: number; type?: OscillatorType; at?: number; attack?: number; decay?: number; gain?: number; glide?: number };
54 
55/** One note: an oscillator with a quick attack and an exponential fade. `to` glides the pitch. */
56export function tone(c: AudioContext, out: AudioNode, o: ToneOpts) {
57  const t0 = c.currentTime + (o.at ?? 0);
58  const osc = c.createOscillator();
59  const g = c.createGain();
60  osc.type = o.type ?? "sine";
61  osc.frequency.setValueAtTime(o.freq, t0);
62  if (o.to) osc.frequency.exponentialRampToValueAtTime(o.to, t0 + (o.glide ?? o.decay ?? 0.1));
63  const a = o.attack ?? 0.004, d = o.decay ?? 0.12, peak = o.gain ?? 0.3;
64  g.gain.value = 0.0001; // a gain node starts at 1: without this the first sample of a note can click
65  g.gain.setValueAtTime(0.0001, t0);
66  g.gain.exponentialRampToValueAtTime(peak, t0 + a);
67  g.gain.exponentialRampToValueAtTime(0.0001, t0 + a + d);
68  osc.connect(g).connect(out);
69  osc.start(t0);
70  osc.stop(t0 + a + d + 0.05);
71}
72 
73export type NoiseOpts = { at?: number; attack?: number; decay?: number; gain?: number; filter?: BiquadFilterType; freq?: number; to?: number; q?: number };
74 
75/** A burst of filtered noise: a click, a rustle, a puff of air. `to` sweeps the filter. */
76export function hiss(c: AudioContext, out: AudioNode, o: NoiseOpts) {
77  const t0 = c.currentTime + (o.at ?? 0);
78  const n = noise(c);
79  const f = c.createBiquadFilter();
80  const g = c.createGain();
81  f.type = o.filter ?? "bandpass";
82  f.frequency.setValueAtTime(o.freq ?? 2000, t0);
83  if (o.to) f.frequency.exponentialRampToValueAtTime(o.to, t0 + (o.attack ?? 0.01) + (o.decay ?? 0.1));
84  f.Q.value = o.q ?? 1;
85  const a = o.attack ?? 0.003, d = o.decay ?? 0.08, peak = o.gain ?? 0.3;
86  g.gain.value = 0.0001;
87  g.gain.setValueAtTime(0.0001, t0);
88  g.gain.exponentialRampToValueAtTime(peak, t0 + a);
89  g.gain.exponentialRampToValueAtTime(0.0001, t0 + a + d);
90  n.connect(f).connect(g).connect(out);
91  n.start(t0, Math.random() * 0.5);
92  n.stop(t0 + a + d + 0.05);
93}
94 
95function load() {
96  if (enabled !== null) return;
97  enabled = true;
98  try {
99    const v = window.localStorage.getItem(STORAGE_KEY);
100    if (v === "off") enabled = false;
101  } catch {
102    // storage is blocked: sounds stay on until switched off for this visit
103  }
104}
105 
106/** Whether icon sounds are on. They are on by default; give visitors a switch (see setIconSoundsEnabled). */
107export function getIconSoundsEnabled(): boolean {
108  if (typeof window === "undefined") return true;
109  load();
110  return enabled ?? true;
111}
112 
113/** Turns icon sounds on or off for this browser. The choice is remembered. */
114export function setIconSoundsEnabled(on: boolean) {
115  load();
116  enabled = on;
117  try {
118    window.localStorage.setItem(STORAGE_KEY, on ? "on" : "off");
119  } catch {
120    // ignore
121  }
122  listeners.forEach((l) => l());
123}
124 
125/** Calls you back when the switch changes. Returns an unsubscribe function (handy for useSyncExternalStore). */
126export function subscribeIconSounds(listener: () => void) {
127  listeners.add(listener);
128  return () => {
129    listeners.delete(listener);
130  };
131}
132 
133/**
134 * Plays an icon's sound. Call it from an event handler (a click, a tap, a key press): browsers only let a page
135 * make sound after the visitor has interacted with it.
136 *
137 * - speed: match the icon's speed prop so picture and sound stay in step.
138 * - volume: 0 to 1, on top of the icon's own measured level.
139 * - force: play even if the visitor has sounds switched off (for a button whose job is to play the sound).
140 */
141export function playIconScore(score: IconScore, opts: { speed?: number; volume?: number; force?: boolean } = {}) {
142  if (!opts.force && !getIconSoundsEnabled()) return;
143  if (typeof document !== "undefined" && document.hidden) return;
144  const c = audio();
145  if (!c || !master) return;
146  const speed = Math.min(4, Math.max(0.25, opts.speed ?? 1));
147  const g = c.createGain();
148  g.gain.value = Math.max(0, Math.min(1, (opts.volume ?? 0.9) * score.level));
149  g.connect(master);
150  score.play(c, g, (s) => s / speed);
151  window.setTimeout(() => g.disconnect(), (score.length / speed + 1.2) * 1000);
152}
153 

1import { hiss, tone } from "./sound-engine";
2 
3/**
4 * The small building blocks every icon sound is made from, drawn with the Web Audio API (no audio files).
5 * `at` is always seconds from the moment the icon is triggered, and the icon sounds pass it through `t`,
6 * which stretches or squeezes time to match the icon's `speed` prop, so a sound stays in step with its picture.
7 */
8export type Time = (seconds: number) => number;
9 
10/** Notes, in hertz, from the C major pentatonic scale plus a few friends: bright but never shrill. */
11export const N = {
12  C4: 261.63, E4: 329.63, G4: 392, A4: 440,
13  C5: 523.25, D5: 587.33, E5: 659.25, G5: 783.99, A5: 880, B5: 987.77,
14  C6: 1046.5, D6: 1174.66, E6: 1318.51, G6: 1567.98, A6: 1760, B6: 1975.53,
15  C7: 2093, D7: 2349.32, E7: 2637.02, G7: 3135.96, C8: 4186,
16} as const;
17 
18/** A glassy bell: a pure tone with a quiet octave and a faint overtone that dies first. */
19export function ding(c: AudioContext, o: AudioNode, freq: number, at: number, gain = 0.12, decay = 0.6) {
20  tone(c, o, { freq, at, attack: 0.004, decay, gain });
21  tone(c, o, { freq: freq * 2, at, attack: 0.003, decay: decay * 0.45, gain: gain * 0.28 });
22  tone(c, o, { freq: freq * 2.76, at, attack: 0.002, decay: decay * 0.18, gain: gain * 0.12 });
23}
24 
25/** A bubbly note that springs up into pitch, with a tiny bright tick on top. */
26export function plink(c: AudioContext, o: AudioNode, freq: number, at: number, gain = 0.1, decay = 0.13) {
27  tone(c, o, { freq: freq * 0.72, to: freq, glide: 0.035, at, attack: 0.003, decay, gain });
28  tone(c, o, { freq: freq * 3, at, attack: 0.001, decay: 0.025, gain: gain * 0.18 });
29}
30 
31/** A short pitched blip. Give `to` to glide, and `type` for a rougher voice (triangle, sawtooth, square). */
32export function blip(c: AudioContext, o: AudioNode, freq: number, at: number, gain = 0.1, decay = 0.08, to?: number, type: OscillatorType = "sine") {
33  tone(c, o, { freq, to, glide: decay * 0.7, at, attack: 0.003, decay, gain, type });
34}
35 
36/** A soft sweep of air between two pitches. */
37export function swish(c: AudioContext, o: AudioNode, at: number, length: number, from: number, to: number, gain = 0.05) {
38  hiss(c, o, { at, attack: length * 0.45, decay: length * 0.55, freq: from, to, gain, q: 0.8 });
39}
40 
41/** A tiny dry click. */
42export function tick(c: AudioContext, o: AudioNode, at: number, gain = 0.12, freq = 5000) {
43  hiss(c, o, { at, freq, decay: 0.012, gain, filter: "highpass" });
44}
45 
46/** A low thump: something soft landing. */
47export function thud(c: AudioContext, o: AudioNode, at: number, freq = 110, gain = 0.3, decay = 0.14) {
48  tone(c, o, { freq, to: freq * 0.55, glide: decay * 0.8, at, attack: 0.002, decay, gain });
49  hiss(c, o, { at, freq: 500, decay: 0.04, gain: gain * 0.35, filter: "lowpass" });
50}
51 
52/** A burst of noise: a crackle, a rustle, a puff of air. */
53export function puff(c: AudioContext, o: AudioNode, at: number, length = 0.08, freq = 3000, gain = 0.06, filter: BiquadFilterType = "bandpass") {
54  hiss(c, o, { at, attack: 0.004, decay: length, freq, gain, filter });
55}
56