@hugocxl/sounds 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hugo Corta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,6 @@
1
+ @hugocxl/sounds
2
+ Copyright (c) 2026 Hugo Corta
3
+
4
+ The sound catalog grew out of a study of the interface sounds of
5
+ SPEC-01 (https://spec-01.vercel.app), then retuned. docs/STUDY.md describes what was learned
6
+ from it.
package/README.md CHANGED
@@ -1,3 +1,50 @@
1
- # Temporary Holding Version
1
+ # @hugocxl/sounds
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Tactile interface sounds for the web. Every sound is synthesized live with Web Audio from a
4
+ few layers of filtered noise and tone, so there are no audio files to load and nothing
5
+ plays the same way twice.
6
+
7
+ [Listen to the sounds](https://hugocxl.github.io/sounds/listen.html) · [Read the docs](https://hugocxl.github.io/sounds/docs.html)
8
+
9
+ ```sh
10
+ npm install @hugocxl/sounds
11
+ ```
12
+
13
+ ```ts
14
+ import { play, haptic } from "@hugocxl/sounds";
15
+
16
+ button.addEventListener("pointerdown", () => play("down"));
17
+ button.addEventListener("pointerup", () => play("up"));
18
+
19
+ haptic("success"); // plays "success" and vibrates where the device supports it
20
+ ```
21
+
22
+ ## Sounds
23
+
24
+ | Group | Sounds |
25
+ | --- | --- |
26
+ | Press | `down`, `down-primary`, `up` |
27
+ | Latch | `latch-down`, `latch-up` |
28
+ | Selection | `tick`, `blip` |
29
+ | Typing | `type`, `type-space`, `type-big`, `type-up` |
30
+ | Overlay | `open` |
31
+ | Status | `success`, `warning`, `error` |
32
+
33
+ Haptics: `selection`, `light`, `medium`, `heavy`, `rigid`, `soft`, `success`, `warning` and `error`.
34
+
35
+ ## API
36
+
37
+ - `play(sound)` plays a sound by name, or your own `{ layers }`.
38
+ - `haptic(kind)` plays the sound for an iOS-style haptic and vibrates.
39
+ - `setEnabled(on)`, `isEnabled()` and `setVolume(value)` control every sound.
40
+ - `render(context, destination, sound, time?, options?)` schedules a sound on any `BaseAudioContext`.
41
+ - `toWav(sound)` renders a sound into a WAV `Blob`.
42
+ - `sounds`, `soundNames`, `groups` and `feedback` describe the catalog.
43
+
44
+ Browsers only start audio after a user gesture, so call `play` from an event handler the
45
+ first time. The package is safe to import during server rendering. It does nothing until it
46
+ plays.
47
+
48
+ ## License
49
+
50
+ MIT. See [NOTICE](NOTICE) for credits.
@@ -0,0 +1,40 @@
1
+ export type NoiseLayer = {
2
+ kind: "noise";
3
+ /** Delay from the start of the sound, in seconds. */
4
+ at?: number;
5
+ filter?: BiquadFilterType;
6
+ /** Filter frequency in hertz. */
7
+ freq: number;
8
+ q?: number;
9
+ level: number;
10
+ decay: number;
11
+ };
12
+ export type ToneLayer = {
13
+ kind: "tone";
14
+ at?: number;
15
+ wave?: OscillatorType;
16
+ /** Start frequency in hertz. */
17
+ freq: number;
18
+ /** End frequency in hertz, reached at the end of the decay. */
19
+ to?: number;
20
+ level: number;
21
+ decay: number;
22
+ attack?: number;
23
+ };
24
+ export type Layer = NoiseLayer | ToneLayer;
25
+ export type SoundName = "down" | "down-primary" | "up" | "latch-down" | "latch-up" | "tick" | "blip" | "type" | "type-space" | "type-big" | "type-up" | "open" | "success" | "warning" | "error";
26
+ export type SoundGroup = "press" | "latch" | "selection" | "typing" | "overlay" | "status";
27
+ export type Sound = {
28
+ group?: SoundGroup;
29
+ description?: string;
30
+ layers: Layer[];
31
+ };
32
+ export declare const sounds: Record<SoundName, Sound>;
33
+ export declare const soundNames: SoundName[];
34
+ export declare const groups: Record<SoundGroup, string>;
35
+ /** iOS-style haptic feedback, each mapped to the sound it makes. */
36
+ export type Feedback = "selection" | "light" | "medium" | "heavy" | "rigid" | "soft" | "success" | "warning" | "error";
37
+ export declare const feedback: Record<Feedback, {
38
+ sound: SoundName;
39
+ vibrate: number | number[];
40
+ }>;
@@ -0,0 +1,150 @@
1
+ // Every sound is a short stack of layers, scheduled from the moment it plays.
2
+ //
3
+ // A noise layer is a burst of white noise through one biquad filter: the
4
+ // "click" of a key or a switch. A tone layer is an oscillator gliding from
5
+ // `freq` to `to`: the body of a press, or a chime. Both rise in `attack`
6
+ // seconds and fall exponentially to silence over `decay` seconds.
7
+ //
8
+ // Tones sit on notes of G major, so sounds played together never clash. The
9
+ // kit grew out of a study of the SPEC-01 interface sounds: see docs/STUDY.md.
10
+ export const sounds = {
11
+ down: {
12
+ group: "press",
13
+ description: "A button pressed down.",
14
+ layers: [
15
+ { kind: "noise", freq: 2400, q: 0.9, level: 0.3, decay: 0.024 },
16
+ { kind: "tone", freq: 196, to: 131, level: 0.4, decay: 0.055 },
17
+ ],
18
+ },
19
+ "down-primary": {
20
+ group: "press",
21
+ description: "The main button pressed down: lower and heavier.",
22
+ layers: [
23
+ { kind: "noise", freq: 1900, q: 0.8, level: 0.34, decay: 0.028 },
24
+ { kind: "tone", freq: 147, to: 98, level: 0.55, decay: 0.075 },
25
+ ],
26
+ },
27
+ up: {
28
+ group: "press",
29
+ description: "A button released.",
30
+ layers: [
31
+ { kind: "noise", freq: 3600, q: 1.2, level: 0.15, decay: 0.013 },
32
+ { kind: "tone", freq: 294, to: 262, level: 0.1, decay: 0.02 },
33
+ ],
34
+ },
35
+ "latch-down": {
36
+ group: "latch",
37
+ description: "A checkbox or toggle latching on, with a ringing spring.",
38
+ layers: [
39
+ { kind: "noise", freq: 1800, q: 0.8, level: 0.18, decay: 0.02 },
40
+ { kind: "tone", freq: 147, to: 110, level: 0.2, decay: 0.05 },
41
+ { kind: "noise", at: 0.005, freq: 1320, q: 16, level: 0.035, decay: 0.055 },
42
+ ],
43
+ },
44
+ "latch-up": {
45
+ group: "latch",
46
+ description: "A checkbox or toggle releasing.",
47
+ layers: [
48
+ { kind: "noise", freq: 3000, q: 1, level: 0.11, decay: 0.013 },
49
+ { kind: "noise", at: 0.003, freq: 1760, q: 14, level: 0.03, decay: 0.045 },
50
+ ],
51
+ },
52
+ tick: {
53
+ group: "selection",
54
+ description: "A detent: sliders, wheels, segmented controls.",
55
+ layers: [
56
+ { kind: "noise", filter: "highpass", freq: 3000, q: 0.7, level: 0.18, decay: 0.007 },
57
+ { kind: "tone", freq: 3520, level: 0.03, decay: 0.012 },
58
+ ],
59
+ },
60
+ blip: {
61
+ group: "selection",
62
+ description: "A selection moving on a screen or list: a soft triangle A6.",
63
+ layers: [{ kind: "tone", wave: "triangle", freq: 1760, level: 0.06, decay: 0.05, attack: 0.002 }],
64
+ },
65
+ type: {
66
+ group: "typing",
67
+ description: "A key pressed in a text field.",
68
+ layers: [
69
+ { kind: "noise", freq: 3100, q: 1.1, level: 0.22, decay: 0.015 },
70
+ { kind: "tone", freq: 247, to: 185, level: 0.18, decay: 0.032 },
71
+ ],
72
+ },
73
+ "type-space": {
74
+ group: "typing",
75
+ description: "The space bar, with a little stabilizer rattle.",
76
+ layers: [
77
+ { kind: "noise", freq: 2000, q: 0.8, level: 0.26, decay: 0.024 },
78
+ { kind: "tone", freq: 165, to: 117, level: 0.26, decay: 0.055 },
79
+ { kind: "noise", at: 0.007, freq: 820, q: 7, level: 0.05, decay: 0.035 },
80
+ ],
81
+ },
82
+ "type-big": {
83
+ group: "typing",
84
+ description: "Enter, Backspace, Delete and Tab.",
85
+ layers: [
86
+ { kind: "noise", freq: 2400, q: 0.9, level: 0.26, decay: 0.02 },
87
+ { kind: "tone", freq: 196, to: 139, level: 0.28, decay: 0.05 },
88
+ ],
89
+ },
90
+ "type-up": {
91
+ group: "typing",
92
+ description: "A key released.",
93
+ layers: [{ kind: "noise", freq: 4200, q: 1.3, level: 0.08, decay: 0.009 }],
94
+ },
95
+ open: {
96
+ group: "overlay",
97
+ description: "A menu, popover or dialog opening: a click and a chirp rising a fifth.",
98
+ layers: [
99
+ { kind: "noise", freq: 2400, q: 1, level: 0.1, decay: 0.013 },
100
+ { kind: "tone", freq: 440, to: 660, level: 0.045, decay: 0.07, attack: 0.004 },
101
+ ],
102
+ },
103
+ success: {
104
+ group: "status",
105
+ description: "A rising G major arpeggio: D6, G6, B6.",
106
+ layers: [
107
+ { kind: "tone", freq: 1175, level: 0.06, decay: 0.08, attack: 0.004 },
108
+ { kind: "tone", at: 0.06, freq: 1568, level: 0.06, decay: 0.09, attack: 0.004 },
109
+ { kind: "tone", at: 0.12, freq: 1976, level: 0.06, decay: 0.18, attack: 0.004 },
110
+ ],
111
+ },
112
+ warning: {
113
+ group: "status",
114
+ description: "Two even triangle beeps on F#5.",
115
+ layers: [
116
+ { kind: "tone", wave: "triangle", freq: 740, level: 0.09, decay: 0.09 },
117
+ { kind: "tone", wave: "triangle", at: 0.12, freq: 740, level: 0.09, decay: 0.09 },
118
+ ],
119
+ },
120
+ error: {
121
+ group: "status",
122
+ description: "Two falling triangle notes, B3 then G3, with a low square edge.",
123
+ layers: [
124
+ { kind: "tone", wave: "triangle", freq: 247, level: 0.12, decay: 0.1 },
125
+ { kind: "tone", wave: "square", freq: 247, level: 0.02, decay: 0.08 },
126
+ { kind: "tone", wave: "triangle", at: 0.13, freq: 196, level: 0.12, decay: 0.16 },
127
+ { kind: "tone", wave: "square", at: 0.13, freq: 196, level: 0.02, decay: 0.12 },
128
+ ],
129
+ },
130
+ };
131
+ export const soundNames = Object.keys(sounds);
132
+ export const groups = {
133
+ press: "Press",
134
+ latch: "Latch",
135
+ selection: "Selection",
136
+ typing: "Typing",
137
+ overlay: "Overlay",
138
+ status: "Status",
139
+ };
140
+ export const feedback = {
141
+ selection: { sound: "tick", vibrate: 8 },
142
+ light: { sound: "down", vibrate: 12 },
143
+ medium: { sound: "down-primary", vibrate: 22 },
144
+ heavy: { sound: "down-primary", vibrate: 36 },
145
+ rigid: { sound: "latch-down", vibrate: 14 },
146
+ soft: { sound: "latch-up", vibrate: 18 },
147
+ success: { sound: "success", vibrate: [14, 70, 22] },
148
+ warning: { sound: "warning", vibrate: [24, 90, 24] },
149
+ error: { sound: "error", vibrate: [28, 60, 28, 60, 28] },
150
+ };
@@ -0,0 +1,17 @@
1
+ import { type Feedback, type Sound, type SoundName } from "./catalog.js";
2
+ export type RenderOptions = {
3
+ /** Small random variation on every play, so repeats never sound identical. */
4
+ humanize?: boolean;
5
+ };
6
+ /** Schedule a sound, by name or your own layers, on any audio context, live or offline. */
7
+ export declare function render(ctx: BaseAudioContext, out: AudioNode, sound: SoundName | Sound, time?: number, options?: RenderOptions): void;
8
+ /** Length of a sound in seconds, tails included. */
9
+ export declare function duration(sound: SoundName | Sound): number;
10
+ /** Play a sound now. Call from a user gesture the first time, so the browser lets audio start. */
11
+ export declare function play(sound: SoundName | Sound): void;
12
+ /** Play the sound for a haptic, and vibrate where the device supports it. */
13
+ export declare function haptic(kind: Feedback): void;
14
+ export declare function setEnabled(on: boolean): void;
15
+ export declare function isEnabled(): boolean;
16
+ /** Volume of every sound, from 0 to 1. The default is 0.55. */
17
+ export declare function setVolume(value: number): void;
package/dist/engine.js ADDED
@@ -0,0 +1,106 @@
1
+ import { sounds, feedback } from "./catalog.js";
2
+ const resolve = (sound) => (typeof sound === "string" ? sounds[sound] : sound);
3
+ const noiseBuffers = new WeakMap();
4
+ function noiseBuffer(ctx) {
5
+ let buffer = noiseBuffers.get(ctx);
6
+ if (!buffer) {
7
+ buffer = ctx.createBuffer(1, ctx.sampleRate / 2, ctx.sampleRate);
8
+ const data = buffer.getChannelData(0);
9
+ for (let i = 0; i < data.length; i++)
10
+ data[i] = Math.random() * 2 - 1;
11
+ noiseBuffers.set(ctx, buffer);
12
+ }
13
+ return buffer;
14
+ }
15
+ function envelope(ctx, start, level, attack, decay) {
16
+ const gain = ctx.createGain();
17
+ gain.gain.setValueAtTime(0, start);
18
+ gain.gain.linearRampToValueAtTime(level, start + attack);
19
+ gain.gain.exponentialRampToValueAtTime(1e-4, start + decay);
20
+ return gain;
21
+ }
22
+ function scheduleLayer(ctx, out, time, layer, humanize) {
23
+ const vary = (amount) => (humanize ? 1 + (Math.random() * 2 - 1) * amount : 1);
24
+ const start = time + (layer.at ?? 0);
25
+ if (layer.kind === "noise") {
26
+ const source = ctx.createBufferSource();
27
+ source.buffer = noiseBuffer(ctx);
28
+ source.playbackRate.value = vary(0.1);
29
+ const filter = ctx.createBiquadFilter();
30
+ filter.type = layer.filter ?? "bandpass";
31
+ filter.frequency.value = layer.freq * vary(0.06);
32
+ filter.Q.value = layer.q ?? 1;
33
+ const gain = envelope(ctx, start, layer.level * vary(0.15), 8e-4, layer.decay);
34
+ source.connect(filter).connect(gain).connect(out);
35
+ source.start(start, humanize ? Math.random() * 0.4 : 0);
36
+ source.stop(start + layer.decay + 0.02);
37
+ }
38
+ else {
39
+ const osc = ctx.createOscillator();
40
+ osc.type = layer.wave ?? "sine";
41
+ const freq = layer.freq * vary(0.04);
42
+ const to = ((layer.to ?? layer.freq) / layer.freq) * freq;
43
+ osc.frequency.setValueAtTime(freq, start);
44
+ osc.frequency.exponentialRampToValueAtTime(Math.max(20, to), start + layer.decay);
45
+ const gain = envelope(ctx, start, layer.level * vary(0.12), layer.attack ?? 0.001, layer.decay);
46
+ osc.connect(gain).connect(out);
47
+ osc.start(start);
48
+ osc.stop(start + layer.decay + 0.02);
49
+ }
50
+ }
51
+ /** Schedule a sound, by name or your own layers, on any audio context, live or offline. */
52
+ export function render(ctx, out, sound, time = ctx.currentTime, options = {}) {
53
+ for (const layer of resolve(sound).layers)
54
+ scheduleLayer(ctx, out, time, layer, options.humanize ?? true);
55
+ }
56
+ /** Length of a sound in seconds, tails included. */
57
+ export function duration(sound) {
58
+ return Math.max(...resolve(sound).layers.map((l) => (l.at ?? 0) + l.decay + 0.02));
59
+ }
60
+ let ctx = null;
61
+ let master = null;
62
+ let enabled = true;
63
+ let volume = 0.55;
64
+ function context() {
65
+ if (ctx?.state === "closed")
66
+ ctx = null;
67
+ if (!ctx) {
68
+ const Ctor = globalThis.AudioContext ?? globalThis.webkitAudioContext;
69
+ if (!Ctor)
70
+ return null;
71
+ ctx = new Ctor({ latencyHint: "interactive" });
72
+ master = ctx.createGain();
73
+ master.gain.value = volume;
74
+ master.connect(ctx.destination);
75
+ }
76
+ if (ctx.state !== "running")
77
+ ctx.resume().catch(() => { });
78
+ return ctx;
79
+ }
80
+ /** Play a sound now. Call from a user gesture the first time, so the browser lets audio start. */
81
+ export function play(sound) {
82
+ if (!enabled)
83
+ return;
84
+ const c = context();
85
+ if (c && master)
86
+ render(c, master, sound, c.currentTime + 0.002);
87
+ }
88
+ /** Play the sound for a haptic, and vibrate where the device supports it. */
89
+ export function haptic(kind) {
90
+ play(feedback[kind].sound);
91
+ if (typeof navigator !== "undefined" && typeof navigator.vibrate === "function") {
92
+ navigator.vibrate(feedback[kind].vibrate);
93
+ }
94
+ }
95
+ export function setEnabled(on) {
96
+ enabled = on;
97
+ }
98
+ export function isEnabled() {
99
+ return enabled;
100
+ }
101
+ /** Volume of every sound, from 0 to 1. The default is 0.55. */
102
+ export function setVolume(value) {
103
+ volume = value;
104
+ if (master)
105
+ master.gain.value = value;
106
+ }
@@ -0,0 +1,3 @@
1
+ export * from "./catalog.js";
2
+ export * from "./engine.js";
3
+ export * from "./wav.js";
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export * from "./catalog.js";
2
+ export * from "./engine.js";
3
+ export * from "./wav.js";
package/dist/wav.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { Sound, SoundName } from "./catalog.js";
2
+ /** Render a sound offline, without variation, into a 16-bit mono WAV. */
3
+ export declare function toWav(sound: SoundName | Sound, sampleRate?: number, gain?: number): Promise<Blob>;
package/dist/wav.js ADDED
@@ -0,0 +1,27 @@
1
+ import { render, duration } from "./engine.js";
2
+ /** Render a sound offline, without variation, into a 16-bit mono WAV. */
3
+ export async function toWav(sound, sampleRate = 48000, gain = 0.55) {
4
+ const ctx = new OfflineAudioContext(1, Math.ceil(duration(sound) * sampleRate), sampleRate);
5
+ const out = ctx.createGain();
6
+ out.gain.value = gain;
7
+ out.connect(ctx.destination);
8
+ render(ctx, out, sound, 0, { humanize: false });
9
+ const samples = (await ctx.startRendering()).getChannelData(0);
10
+ const view = new DataView(new ArrayBuffer(44 + samples.length * 2));
11
+ const text = (offset, s) => [...s].forEach((ch, i) => view.setUint8(offset + i, ch.charCodeAt(0)));
12
+ text(0, "RIFF");
13
+ view.setUint32(4, 36 + samples.length * 2, true);
14
+ text(8, "WAVE");
15
+ text(12, "fmt ");
16
+ view.setUint32(16, 16, true);
17
+ view.setUint16(20, 1, true);
18
+ view.setUint16(22, 1, true);
19
+ view.setUint32(24, sampleRate, true);
20
+ view.setUint32(28, sampleRate * 2, true);
21
+ view.setUint16(32, 2, true);
22
+ view.setUint16(34, 16, true);
23
+ text(36, "data");
24
+ view.setUint32(40, samples.length * 2, true);
25
+ samples.forEach((s, i) => view.setInt16(44 + i * 2, Math.max(-1, Math.min(1, s)) * 0x7fff, true));
26
+ return new Blob([view], { type: "audio/wav" });
27
+ }
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@hugocxl/sounds",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Tactile interface sounds for the web, synthesized live with Web Audio. No audio files.",
5
+ "keywords": [
6
+ "sounds",
7
+ "ui sounds",
8
+ "interface",
9
+ "haptics",
10
+ "feedback",
11
+ "web audio",
12
+ "click",
13
+ "typing"
14
+ ],
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "files": [
18
+ "dist",
19
+ "LICENSE",
20
+ "NOTICE",
21
+ "README.md"
22
+ ],
23
+ "exports": {
24
+ ".": {
25
+ "types": "./dist/index.d.ts",
26
+ "import": "./dist/index.js",
27
+ "default": "./dist/index.js"
28
+ },
29
+ "./package.json": "./package.json"
30
+ },
31
+ "main": "./dist/index.js",
32
+ "types": "./dist/index.d.ts",
33
+ "license": "MIT",
34
+ "author": "Hugo Corta (https://hugocxl.me)",
35
+ "homepage": "https://hugocxl.github.io/sounds/",
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "https://github.com/hugocxl/sounds.git",
39
+ "directory": "packages/sounds"
40
+ },
41
+ "bugs": "https://github.com/hugocxl/sounds/issues",
42
+ "publishConfig": {
43
+ "access": "public"
44
+ },
45
+ "scripts": {
46
+ "build": "rm -rf dist && tsc -p .",
47
+ "prepack": "cp ../../LICENSE ../../NOTICE . && npm run build"
48
+ }
49
+ }