@hugocxl/sounds 0.1.0 → 0.1.5

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/README.md CHANGED
@@ -45,6 +45,9 @@ Browsers only start audio after a user gesture, so call `play` from an event han
45
45
  first time. The package is safe to import during server rendering. It does nothing until it
46
46
  plays.
47
47
 
48
+ AI agents: the package ships a skill in `skills/sounds/` that maps every control to its
49
+ sound.
50
+
48
51
  ## License
49
52
 
50
53
  MIT. See [NOTICE](NOTICE) for credits.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hugocxl/sounds",
3
- "version": "0.1.0",
3
+ "version": "0.1.5",
4
4
  "description": "Tactile interface sounds for the web, synthesized live with Web Audio. No audio files.",
5
5
  "keywords": [
6
6
  "sounds",
@@ -16,6 +16,7 @@
16
16
  "sideEffects": false,
17
17
  "files": [
18
18
  "dist",
19
+ "skills",
19
20
  "LICENSE",
20
21
  "NOTICE",
21
22
  "README.md"
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: sounds
3
+ description: Use @hugocxl/sounds to add tactile interface sounds and haptic feedback to a web interface — button presses, toggles, sliders, typing, menus and success, warning or error results. Covers which sound fits each control, wiring it to events, React, volume and mute, and custom sounds. Use it whenever you add audio or haptic feedback, or are tempted to add audio files or another sound library.
4
+ ---
5
+
6
+ # @hugocxl/sounds
7
+
8
+ Fifteen short interface sounds, synthesized live with Web Audio from a few layers of filtered
9
+ noise and tone. There are no audio files to host, and nothing plays the same way twice.
10
+
11
+ ## Rules
12
+
13
+ 1. **Only these sounds.** Never add audio files, another UI sound library or a hand-rolled
14
+ `AudioContext` for interface feedback.
15
+ 2. **Sound confirms what the hand did.** Play a sound for a direct action: a press, a toggle,
16
+ a step of a slider, a key, an overlay opening, the result of an action. Never for
17
+ hover, scroll, page load, timers or anything the visitor did not do.
18
+ 3. **Match the sound to the control.** Use the table below. The same control always makes the
19
+ same sound across the product.
20
+ 4. **Sound is optional.** It never carries information on its own: the interface shows every
21
+ state too. Offer a setting to turn sounds off and respect it with `setEnabled`.
22
+ 5. **Start from a gesture.** Browsers start audio only after the visitor interacts, so the
23
+ first sound must come from `pointerdown`, `click` or `keydown`.
24
+
25
+ ## Choose the sound
26
+
27
+ | Control or moment | Sound |
28
+ | --- | --- |
29
+ | A button going down and coming back up | `down` on `pointerdown`, `up` on `pointerup` |
30
+ | The page's main button | `down-primary`, then `up` |
31
+ | Checkbox, switch, toggle | `latch-down` when it turns on, `latch-up` when it turns off |
32
+ | Slider step, wheel, tab, segmented control | `tick` |
33
+ | Selection moving through a list or between screens | `blip` |
34
+ | A key in a text field | `type`; `type-space` for Space; `type-big` for Enter, Backspace, Delete and Tab; `type-up` on `keyup` |
35
+ | A menu, popover or dialog opening | `open` |
36
+ | The result of an action | `success`, `warning`, `error` |
37
+
38
+ Haptics, if you think in iOS terms: `haptic(kind)` plays the matching sound and vibrates where
39
+ the device supports it. The kinds are `selection` (tick), `light` (down), `medium` and
40
+ `heavy` (down-primary), `rigid` (latch-down), `soft` (latch-up), `success`, `warning` and
41
+ `error`.
42
+
43
+ ## Use it
44
+
45
+ ```sh
46
+ npm install @hugocxl/sounds
47
+ ```
48
+
49
+ ```ts
50
+ import { play, haptic } from '@hugocxl/sounds';
51
+
52
+ button.addEventListener('pointerdown', () => play('down'));
53
+ button.addEventListener('pointerup', () => play('up'));
54
+ form.addEventListener('submit', () => haptic('success'));
55
+ ```
56
+
57
+ Sounds are plain function calls, so React needs no provider or hook:
58
+
59
+ ```tsx
60
+ import { play } from '@hugocxl/sounds';
61
+
62
+ <button onPointerDown={() => play('down-primary')} onPointerUp={() => play('up')} onClick={save}>
63
+ Save
64
+ </button>
65
+ ```
66
+
67
+ Typing:
68
+
69
+ ```ts
70
+ input.addEventListener('keydown', event => {
71
+ if (event.repeat) return play('tick');
72
+ if (event.key === ' ') play('type-space');
73
+ else if (['Enter', 'Backspace', 'Delete', 'Tab'].includes(event.key)) play('type-big');
74
+ else if (event.key.length === 1) play('type');
75
+ });
76
+ input.addEventListener('keyup', () => play('type-up'));
77
+ ```
78
+
79
+ - Importing the package during server rendering is safe; nothing happens until a sound plays.
80
+ - `play` returns at once and never throws, so call it before the action's own work.
81
+ - Play the result sound (`success`, `warning`, `error`) when the result is known, not when the
82
+ request starts.
83
+
84
+ ## Volume and mute
85
+
86
+ ```ts
87
+ import { setEnabled, setVolume, isEnabled } from '@hugocxl/sounds';
88
+
89
+ setVolume(0.4); // 0 to 1, 0.55 by default
90
+ setEnabled(false); // mute every sound
91
+ ```
92
+
93
+ Keep the visitor's choice in your own settings and call `setEnabled` when the page loads.
94
+
95
+ ## Custom sounds and audio files
96
+
97
+ Add a new sound only when none of the fifteen fits. A sound is a list of layers: a `noise`
98
+ layer is a filtered burst of white noise (the click), a `tone` layer is an oscillator gliding
99
+ from `freq` to `to` (the body). Start from an existing one:
100
+
101
+ ```ts
102
+ import { play, sounds } from '@hugocxl/sounds';
103
+
104
+ play({ layers: [...sounds.down.layers, { kind: 'tone', freq: 784, level: 0.1, decay: 0.08 }] });
105
+ ```
106
+
107
+ `toWav(name)` renders a sound to a WAV `Blob` for native apps, videos or design tools.
108
+ `soundNames` lists every name and `feedback` maps each haptic kind to its sound.
109
+
110
+ ## Check your work
111
+
112
+ - Every sound name is one of the fifteen in the table, and each control uses its row.
113
+ - No audio files or other sound libraries were added.
114
+ - Sounds play only for direct actions, and the product has a way to turn them off.
115
+
116
+ Full documentation: https://hugocxl.github.io/sounds/docs.html