@arraypress/waveform-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 ArrayPress
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/README.md CHANGED
@@ -1,3 +1,124 @@
1
- # Temporary Holding Version
1
+ <div align="center">
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
+ # Waveform Sounds
4
+
5
+ **A searchable, filterable sound list for WaveformPlayer.**
6
+
7
+ Audition hundreds of sample previews: a mini waveform per row, search, type /
8
+ key / BPM filters, sort, loop, keyboard auditioning, and one shared audio
9
+ engine — never a player per row.
10
+
11
+ </div>
12
+
13
+ ---
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm install @arraypress/waveform-player @arraypress/waveform-sounds
19
+ ```
20
+
21
+ ```js
22
+ import '@arraypress/waveform-player';
23
+ import '@arraypress/waveform-sounds';
24
+ import '@arraypress/waveform-player/styles.css';
25
+ import '@arraypress/waveform-sounds/styles.css';
26
+ ```
27
+
28
+ ```html
29
+ <div data-waveform-sounds data-manifest="/sounds.json"></div>
30
+ ```
31
+
32
+ Generate the manifest from a folder of previews (BPM and key are read from
33
+ file names like `Bass_Loop_04_128_Fmin.wav`; the type is the sub-folder).
34
+ `--base-url` is the public URL the folder is served at:
35
+
36
+ ```bash
37
+ npx @arraypress/waveform-gen ./public/previews/ --recursive \
38
+ --manifest ./public/previews/sounds.json --base-url /previews/
39
+ ```
40
+
41
+ (`--manifest` needs `@arraypress/waveform-gen` 2.1.0 or later.)
42
+
43
+ ## Options
44
+
45
+ `player` (`'inline'` | `'strip'`), `search`, `filters`, `sorts`,
46
+ `loopToggle`, `showCount`, `pageSize` (50), `maxTypeChips` (10), `menuSearch` (8), `columns`,
47
+ `waveformStyle`, `waveformColor`, `progressColor`, `barWidth`, `barGap`,
48
+ `loop`, `autoAdvance`, `arrowAudition`, `playerOptions`, `strings`, and the
49
+ callbacks `onReady` / `onPlay` / `onPause` / `onEnd` / `onFilter` / `onError`.
50
+ Every option has a `data-*` form (`data-page-size="100"`); `strings` and
51
+ `playerOptions` take JSON. See `index.d.ts` for each one.
52
+
53
+ Every control can go. No BPM anywhere:
54
+
55
+ ```js
56
+ {filters: ['type', 'key'], columns: ['type', 'key', 'duration'], sorts: ['default', 'title', 'key']}
57
+ ```
58
+
59
+ ## Download links
60
+
61
+ Optional, per sound — a free sample, the `.mid` of a MIDI preview. Rows
62
+ with one get a download button; rows without carry nothing:
63
+
64
+ ```js
65
+ {url: '/previews/kick-01.mp3', title: 'Kick 01', download: '/free/kick-01.wav'}
66
+ ```
67
+
68
+ It's a plain `<a download>`: gating (an email, a login) is the site's job.
69
+
70
+ ## Filters in the address
71
+
72
+ `urlState: true` keeps the filters in the URL —
73
+ `?q=bass&type=Bass+loops&key=Fm&bpm=120-130&sort=bpm` — so a filtered list
74
+ can be shared and survives a refresh. `urlState: 'pack'` prefixes the names
75
+ (`pack-q`, `pack-type`, …) when a page has more than one list. It uses
76
+ `replaceState`, so filtering adds no back-button entries; values the data
77
+ can't use are ignored.
78
+
79
+ ## Which sounds get played (analytics)
80
+
81
+ The list plays through a regular `WaveformPlayer`, so
82
+ [`@arraypress/waveform-tracker`](https://www.npmjs.com/package/@arraypress/waveform-tracker)
83
+ tracks it with no extra code — each event carries that sound's `url` and
84
+ `title`:
85
+
86
+ ```js
87
+ import WaveformTracker from '@arraypress/waveform-tracker';
88
+ WaveformTracker.init({endpoint: '/api/listens', events: {play: 3, listen: 15}});
89
+ ```
90
+
91
+ (The engine is built when the list is ready, so the tracker is attached
92
+ before the first play.)
93
+
94
+ ## Keyboard
95
+
96
+ | Key | Does |
97
+ |---|---|
98
+ | ↑ / ↓ | Move between sounds; while one plays, play the next |
99
+ | ← / → | Seek the playing sound |
100
+ | Space / Enter | Play / pause |
101
+ | `/` | Search |
102
+
103
+ ## Server rendering
104
+
105
+ ```js
106
+ import {renderSounds} from '@arraypress/waveform-sounds/render';
107
+ const html = `<div data-waveform-sounds>${renderSounds(sounds, options)}</div>`;
108
+ ```
109
+
110
+ The runtime adopts that markup instead of rebuilding it.
111
+
112
+ ## Theming
113
+
114
+ Colour-agnostic by default, like the rest of the family: everything derives
115
+ from `currentColor`, and the "on" states (selected chip, playing row) are
116
+ inverted — white on a dark page, black on a light one. Custom properties on
117
+ `.waveform-sounds`: `--ws-accent` / `--ws-on-accent` (opt into a brand
118
+ colour), `--ws-surface` (the page background; detected, but set it for the
119
+ first server-rendered paint), `--ws-wave-color`, `--ws-progress-color`,
120
+ `--ws-border`, `--ws-radius`, `--ws-control-radius`, …
121
+
122
+ ## License
123
+
124
+ MIT © [ArrayPress](https://github.com/arraypress)