noised-storm 0.0.0-stage → 1.0.0-beta.1
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 +7 -0
- package/README.md +143 -3
- package/dist/index.cjs +1927 -0
- package/dist/index.d.cts +460 -0
- package/dist/index.d.ts +460 -0
- package/dist/index.js +1890 -0
- package/dist/wasm/noised_dsp.wasm +0 -0
- package/dist/worklet/rain.worklet.js +71 -0
- package/package.json +56 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 David Portal
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,143 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# NoiseD Storm
|
|
2
|
+
|
|
3
|
+
Framework-independent procedural rain and thunder for browser ambience apps and games.
|
|
4
|
+
This package owns audio synthesis and lifecycle, with no React, UI or CSS dependency.
|
|
5
|
+
See the [workspace README](../../README.md) for monorepo commands and deployment,
|
|
6
|
+
the [demo README](../demo/README.md) for player tools, and the
|
|
7
|
+
[UI README](../../ui/README.md) for React controls and automatic styling.
|
|
8
|
+
|
|
9
|
+
## Installation and use
|
|
10
|
+
|
|
11
|
+
Release candidate: **1.0.0-beta.1**, intended for the `beta` tag. This is a 1.0
|
|
12
|
+
API candidate; beta versions may still change the public API. See the
|
|
13
|
+
[release procedure](https://github.com/stargazingdave/noised-web#publish-a-library-release)
|
|
14
|
+
for verification and publishing. The engine and UI have independent releases.
|
|
15
|
+
|
|
16
|
+
Build a local tarball with `npm run pack:library` at the monorepo root, then install the resulting `artifacts/noised-storm-1.0.0-beta.1.tgz` in another project. After publication, use `npm install noised-storm@beta`.
|
|
17
|
+
|
|
18
|
+
Initialize from a user interaction. With Vite, import the packaged assets as URLs:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import { NoiseDStorm } from 'noised-storm';
|
|
22
|
+
import workletUrl from 'noised-storm/rain.worklet.js?url';
|
|
23
|
+
import wasmUrl from 'noised-storm/noised_dsp.wasm?url';
|
|
24
|
+
|
|
25
|
+
const ctx = new AudioContext();
|
|
26
|
+
const storm = await NoiseDStorm.createWasm(ctx, {}, { workletUrl, wasmUrl });
|
|
27
|
+
await storm.start();
|
|
28
|
+
storm.updateRainParams({ dropRate: 100, noiseFilterFreq: { value: 2500 } });
|
|
29
|
+
storm.updateThunderParams({ volume: { value: 0.4 } });
|
|
30
|
+
storm.stop();
|
|
31
|
+
storm.destroy();
|
|
32
|
+
await ctx.close(); // The application owns its AudioContext.
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`NoiseDStorm` aliases `NoiseDController`. For rain alone, use `RainGenerator.createWasm(ctx, params, options)`, connect it to a destination, then await `start()`. Options also accept a repeatable rain `seed` and a fixed `maxVoices` pool of 1–256 (default 128). Thunder randomness is independent of the rain seed.
|
|
36
|
+
|
|
37
|
+
Other bundlers can copy the worklet and WASM exports to their static asset directory and supply those URLs. Consumers need no Rust toolchain. Use HTTPS or localhost, allow the asset URLs in your CSP, and enable CORS for cross-origin assets. Initialization fails explicitly when assets or AudioWorklet are unavailable.
|
|
38
|
+
|
|
39
|
+
The package exports ESM and CommonJS, TypeScript declarations, and these asset
|
|
40
|
+
subpaths: `noised-storm/rain.worklet.js` and `noised-storm/noised_dsp.wasm`.
|
|
41
|
+
The `?url` syntax in the example is Vite-specific, not part of the engine API.
|
|
42
|
+
With another build tool, provide publicly fetchable URLs yourself; they must
|
|
43
|
+
respect the deployed base path. WASM is compiled from an ArrayBuffer, so hosts
|
|
44
|
+
that omit the `application/wasm` MIME type still work. Do not inline the worklet
|
|
45
|
+
into the main bundle; it runs in AudioWorkletGlobalScope.
|
|
46
|
+
|
|
47
|
+
Importing the JS package in Node/SSR is supported, but creating or running an
|
|
48
|
+
engine requires browser Web Audio (or a compatible test implementation). Await
|
|
49
|
+
`createWasm` and `start`, catch initialization errors, and keep one controller
|
|
50
|
+
for the lifetime of a player instead of creating one for each UI component.
|
|
51
|
+
|
|
52
|
+
## Controller API
|
|
53
|
+
|
|
54
|
+
| Method | Behavior |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `NoiseDStorm.createWasm(ctx, params, options)` | Async factory; accepts nested partial parameters and caller-supplied asset URLs |
|
|
57
|
+
| `start()` | Async start/resume of enabled rain and thunder |
|
|
58
|
+
| `stop()` | Stops playback and pending thunder scheduling without destroying the graph |
|
|
59
|
+
| `startRain()` / `stopRain()` | Enables/starts or disables/stops rain; await rain startup |
|
|
60
|
+
| `startThunder()` / `stopThunder()` | Enables scheduling while the controller is running, or disables/stops thunder |
|
|
61
|
+
| `setMasterVolume(value)` | Updates output gain |
|
|
62
|
+
| `setDelayBetweenThunders({ min, max })` | Updates/reschedules the random thunder interval, in milliseconds |
|
|
63
|
+
| `setEqGain(index, gain)` | Updates a master EQ gain in dB |
|
|
64
|
+
| `updateRainParams(patch)` | Applies a nested rain patch; may return an async startup when enabling rain |
|
|
65
|
+
| `updateThunderParams(patch)` | Applies a nested thunder patch |
|
|
66
|
+
| `getAnalyser()` | Creates an AnalyserNode tapped after master gain; call once and reuse it for visualization |
|
|
67
|
+
| `exportParamsAsJSON()` | Serializes the controller's current parameters |
|
|
68
|
+
| `renderToFile(durationSec)` | Async stereo 16-bit PCM WAV Blob, rendered on an offline clock at the context's sample rate |
|
|
69
|
+
| `destroy()` | Stops/disconnects owned audio nodes; idempotent; the caller still closes its context |
|
|
70
|
+
|
|
71
|
+
Master, rain and thunder EQs have ten bands: 31, 62, 125, 250, 500, 1000,
|
|
72
|
+
2000, 4000, 8000 and 16000 Hz. Gain arrays are replaced as whole arrays in
|
|
73
|
+
patches. Object patches preserve sibling values; use the exported
|
|
74
|
+
`DeepPartial<NoiseDParams>` type for typed updates. Dedicated `setRain*` methods
|
|
75
|
+
also remain available; their declarations and parameter interfaces are in
|
|
76
|
+
[NoiseDController.ts](src/NoiseDController.ts).
|
|
77
|
+
|
|
78
|
+
### Parameters and modulation
|
|
79
|
+
|
|
80
|
+
`NoiseDParams` contains `masterVolume`, `delayBetweenThunders`, `eqGains`,
|
|
81
|
+
`rainParams` and `thunderParams`. The library's initial output gain is 0.5;
|
|
82
|
+
both layers are enabled, and thunder intervals default to 5000-15000 ms.
|
|
83
|
+
The demo uses its own saved presets, not these engine defaults.
|
|
84
|
+
|
|
85
|
+
Rain parameters include volume/EQ, white or pink noise and its level/filter,
|
|
86
|
+
drop dry/wet levels, rate, pitch, decay, resonance, reverb and pan range.
|
|
87
|
+
Modulated rain values use `{ value, osc, amp, freq }`: frequency is in Hz and
|
|
88
|
+
amplitude uses the parameter's units. Thunder values generally use
|
|
89
|
+
`{ value, rand, dist }`, randomizing around `value` within the distribution.
|
|
90
|
+
Thunder exposes volume/duration, filter/bursts/crackle, reverb, sub level,
|
|
91
|
+
pan/high-pass, rumble and EQ settings. `delayMs` and thunder intervals use
|
|
92
|
+
milliseconds; duration/decay settings use seconds and filter/pitch settings Hz.
|
|
93
|
+
Complete types and defaults are in [RainGenerator.ts](src/RainGenerator.ts) and
|
|
94
|
+
[ThunderGenerator.ts](src/ThunderGenerator.ts).
|
|
95
|
+
|
|
96
|
+
Standalone `RainGenerator` and `ThunderGenerator` instances are explicitly
|
|
97
|
+
connected by the consumer; the full controller connects its output to
|
|
98
|
+
`ctx.destination`. The application owns parameter validation, preset lists,
|
|
99
|
+
file parsing and download UI. The engine does not provide preset storage.
|
|
100
|
+
|
|
101
|
+
For a visualization, pass the analyser returned by `getAnalyser()` to any
|
|
102
|
+
compatible renderer, including the UI library's `Visualization`. Keep analyser
|
|
103
|
+
and playback state shared across the player's components. No CSS import is
|
|
104
|
+
needed by this engine; UI styling belongs to `noised-ui`.
|
|
105
|
+
|
|
106
|
+
`renderToFile` requires a finite positive duration and uses the rain backend
|
|
107
|
+
chosen by the factory. It does not turn on live playback; enabled layers and
|
|
108
|
+
current parameters determine the render. The engine does not impose the
|
|
109
|
+
demo's 300-second UI limit. Callers choose a duration appropriate to available
|
|
110
|
+
memory and handle the returned Blob/download themselves.
|
|
111
|
+
|
|
112
|
+
## Engine status
|
|
113
|
+
|
|
114
|
+
The pure JavaScript rain engine is deprecated following listening comparisons. The comparison selector and switching API have been removed from the demo. Native constructors and V2 exports remain only for compatibility; use `createWasm` for new integrations. There is no automatic fallback to native rain.
|
|
115
|
+
|
|
116
|
+
Rust generates the continuous white/pink noise and stereo drops inside an AudioWorklet. Rain retains the earlier regular drop timing and direct decay control; experimental timing, impact-level and envelope variation was reverted after listening feedback. The render loop uses preallocated memory and a fixed voice pool. Excess drops steal slots in round-robin order.
|
|
117
|
+
|
|
118
|
+
Thunder synthesis, EQ, filters and convolution still use Web Audio nodes. Thunder now combines a short bright crack with a darker, irregular rolling body, tapered noise tails and shaped sub rumble. This is a first sound-quality pass for listening feedback; it does not move thunder into Rust. No shared-memory headers or WASM threads are required.
|
|
119
|
+
|
|
120
|
+
Live controls accept nested partial patches. Parameters and presets retain their existing meanings, though synthesized sound has changed. Thunder delay controls use milliseconds. Stop/destroy cancels active and scheduled sources. `renderToFile(durationSec)` renders a stereo WAV on the offline audio clock using the controller's rain backend.
|
|
121
|
+
|
|
122
|
+
## Development
|
|
123
|
+
|
|
124
|
+
Requires Node 22.12+, npm 11.21+, Rust and its `wasm32-unknown-unknown` target. From the monorepo root:
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
npm run build
|
|
128
|
+
npm run typecheck
|
|
129
|
+
npm test
|
|
130
|
+
npm run dev
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
For this package alone, `npm run build --workspace=noised-storm` emits both JS
|
|
134
|
+
formats, declarations, the worklet and WASM binary; `npm run test
|
|
135
|
+
--workspace=noised-storm` also runs Rust tests. `npm run test:browser
|
|
136
|
+
--workspace=noised-storm` verifies browser audio and `npm run bench` at the root
|
|
137
|
+
runs the performance benchmark. The source build uses the committed Cargo.lock
|
|
138
|
+
with `--locked`; the npm tarball contains prebuilt assets. Keep generated
|
|
139
|
+
`dist` and Rust `target` directories out of Git.
|
|
140
|
+
|
|
141
|
+
The library build packages JS, declarations, the standalone worklet and the Rust release binary. Tests cover live controls, lifecycle races, WAV export, thunder sample boundaries, and the compiled WASM worklet. Rust tests check seeded block-size independence, reset behavior and finite output under overload. Existing benchmark and browser checks remain available for development.
|
|
142
|
+
|
|
143
|
+
License: ISC. Author: David Portal.
|