@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 +3 -0
- package/package.json +2 -1
- package/skills/sounds/SKILL.md +116 -0
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.
|
|
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
|