@link-foundation/ui-sound 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/src/graph.js ADDED
@@ -0,0 +1,217 @@
1
+ /** Build bounded Web Audio graphs. Context, time and randomness are injectable. */
2
+ const bound = (n, min, max) => Math.max(min, Math.min(max, n));
3
+ const noiseBuffers = new WeakMap();
4
+
5
+ function cachedNoise(audio, random) {
6
+ let entry = noiseBuffers.get(audio);
7
+ if (!entry || entry.sampleRate !== audio.sampleRate) {
8
+ entry = {
9
+ sampleRate: audio.sampleRate,
10
+ buffer: noiseBuffer(audio, 2, 1, random),
11
+ };
12
+ noiseBuffers.set(audio, entry);
13
+ }
14
+ return entry.buffer;
15
+ }
16
+
17
+ const clamp = (n) => Math.max(-1, Math.min(1, n));
18
+
19
+ function noiseBuffer(audio, seconds, channels, random, decay = false) {
20
+ const length = Math.ceil(audio.sampleRate * seconds);
21
+ const buffer = audio.createBuffer(channels, length, audio.sampleRate);
22
+ for (let channel = 0; channel < channels; channel++) {
23
+ const data = buffer.getChannelData(channel);
24
+ let last = 0;
25
+ for (let i = 0; i < length; i++) {
26
+ const n = random() * 2 - 1;
27
+ last = decay ? last * 0.55 + n * 0.45 : n;
28
+ data[i] = last * (decay ? (1 - i / length) ** 3.2 : 1);
29
+ }
30
+ }
31
+ return buffer;
32
+ }
33
+
34
+ /** Shelf → dry/reverb → compressor → master volume (including wet tails). */
35
+ export function createSoundBus(audio, settings, random = Math.random) {
36
+ const input = audio.createGain();
37
+ const shelf = audio.createBiquadFilter();
38
+ shelf.type = 'highshelf';
39
+ shelf.frequency.value = settings.shelf[0];
40
+ shelf.gain.value = settings.shelf[1];
41
+ const compressor = audio.createDynamicsCompressor();
42
+ compressor.threshold.value = settings.compressor[0];
43
+ compressor.ratio.value = settings.compressor[1];
44
+ compressor.knee.value = 12;
45
+ compressor.attack.value = 0.003;
46
+ compressor.release.value = 0.15;
47
+ const master = audio.createGain();
48
+ const nodes = [input, shelf, compressor, master];
49
+ input
50
+ .connect(shelf)
51
+ .connect(compressor)
52
+ .connect(master)
53
+ .connect(audio.destination);
54
+ const convolver = audio.createConvolver();
55
+ const wet = audio.createGain();
56
+ wet.gain.value = settings.reverb ?? 0.2;
57
+ shelf.connect(convolver).connect(wet).connect(compressor);
58
+ nodes.push(convolver, wet);
59
+ let room = bound(settings.room ?? 1.4, 0.3, 4);
60
+ convolver.buffer = noiseBuffer(audio, room, 2, random, true);
61
+ return {
62
+ input,
63
+ master,
64
+ shelf,
65
+ convolver,
66
+ wet,
67
+ configure(values = {}) {
68
+ for (const [key, param, min, max] of [
69
+ ['volume', master.gain, 0, values.maxVolume ?? 1],
70
+ ['tone', shelf.gain, -40, 40],
71
+ ['frequency', shelf.frequency, 1, 24000],
72
+ ['reverb', wet.gain, 0, 1],
73
+ ]) {
74
+ if (Number.isFinite(values[key])) {
75
+ param.setTargetAtTime(
76
+ bound(values[key], min, max),
77
+ audio.currentTime,
78
+ 0.02
79
+ );
80
+ }
81
+ }
82
+ if (Number.isFinite(values.room) && bound(values.room, 0.3, 4) !== room) {
83
+ room = bound(values.room, 0.3, 4);
84
+ convolver.buffer = noiseBuffer(audio, room, 2, random, true);
85
+ }
86
+ },
87
+ disconnect: () => nodes.forEach((node) => node.disconnect()),
88
+ };
89
+ }
90
+
91
+ function sweep(param, from, to, start, duration) {
92
+ param.setValueAtTime(from, start);
93
+ if (to !== from) {
94
+ param.exponentialRampToValueAtTime(to, start + duration);
95
+ }
96
+ }
97
+
98
+ function createEnvelope(audio, envelope, start, peak) {
99
+ const { attack, decay, sustain, release } = envelope;
100
+ const stop = start + attack + decay + release;
101
+ const amp = audio.createGain();
102
+ amp.gain.value = 0;
103
+ amp.gain.setValueAtTime(0, 0);
104
+ amp.gain.setValueAtTime(0, start);
105
+ amp.gain.linearRampToValueAtTime(peak, start + attack);
106
+ if (envelope.curve === 'exponential' && peak > 0) {
107
+ amp.gain.exponentialRampToValueAtTime(
108
+ Math.min(0.0001, peak),
109
+ start + attack + decay
110
+ );
111
+ } else {
112
+ amp.gain.linearRampToValueAtTime(peak * sustain, start + attack + decay);
113
+ }
114
+ amp.gain.linearRampToValueAtTime(0, stop);
115
+ return amp;
116
+ }
117
+
118
+ /** Schedule a parsed voice, returning its final stop time. */
119
+ export function playVoice(
120
+ audio,
121
+ voice,
122
+ output,
123
+ {
124
+ at = audio.currentTime,
125
+ pan = 0,
126
+ gain = 1,
127
+ detune = 0,
128
+ random = Math.random,
129
+ } = {}
130
+ ) {
131
+ let end = at;
132
+ for (let repeat = 0; repeat < voice.repeat; repeat++) {
133
+ for (const part of voice.parts) {
134
+ const start = at + repeat * voice.gap + part.delay;
135
+ const { attack, decay, release } = part.envelope;
136
+ const duration = attack + decay + release;
137
+ const stop = start + duration;
138
+ end = Math.max(end, stop);
139
+ const nodes = [];
140
+ const amp = createEnvelope(
141
+ audio,
142
+ part.envelope,
143
+ start,
144
+ part.gain * gain * voice.repeatDecay ** repeat
145
+ );
146
+ nodes.push(amp);
147
+ let source;
148
+ if (part.kind === 'noise') {
149
+ source = audio.createBufferSource();
150
+ source.buffer = cachedNoise(audio, random);
151
+ source.loop = true;
152
+ source.detune.value = detune;
153
+ } else {
154
+ source = audio.createOscillator();
155
+ source.type = part.wave;
156
+ source.detune.value = part.detune + detune;
157
+ sweep(
158
+ source.frequency,
159
+ part.frequency,
160
+ part.to,
161
+ start,
162
+ part.glide ?? duration
163
+ );
164
+ if (part.fm) {
165
+ const mod = audio.createOscillator();
166
+ const depth = audio.createGain();
167
+ mod.detune.value = detune;
168
+ mod.frequency.value = part.frequency * part.fm.ratio;
169
+ depth.gain.setValueAtTime(part.frequency * part.fm.index, start);
170
+ if (part.fm.index > 0) {
171
+ depth.gain.exponentialRampToValueAtTime(1, start + attack + decay);
172
+ }
173
+ mod.connect(depth).connect(source.frequency);
174
+ mod.start(start);
175
+ mod.stop(stop);
176
+ nodes.push(mod, depth);
177
+ }
178
+ }
179
+ nodes.push(source);
180
+ let tail = source;
181
+ if (part.filter) {
182
+ const filter = audio.createBiquadFilter();
183
+ filter.type = part.filter.type;
184
+ filter.Q.value = part.filter.q;
185
+ sweep(
186
+ filter.frequency,
187
+ part.filter.from,
188
+ part.filter.to,
189
+ start,
190
+ duration
191
+ );
192
+ tail = tail.connect(filter);
193
+ nodes.push(filter);
194
+ }
195
+ tail = tail.connect(amp);
196
+ if (typeof audio.createStereoPanner === 'function') {
197
+ const panner = audio.createStereoPanner();
198
+ panner.pan.value = clamp(pan + part.pan);
199
+ tail = tail.connect(panner);
200
+ nodes.push(panner);
201
+ }
202
+ tail.connect(output);
203
+ source.onended = () => nodes.forEach((node) => node.disconnect());
204
+ startSource(source, part.kind, start, random);
205
+ source.stop(stop);
206
+ }
207
+ }
208
+ return end;
209
+ }
210
+
211
+ function startSource(source, kind, start, random) {
212
+ if (kind === 'noise') {
213
+ source.start(start, random() * 2);
214
+ } else {
215
+ source.start(start);
216
+ }
217
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,196 @@
1
+ import type { Config } from '@link-foundation/ui-config';
2
+ import type { SettingsSchema } from '@link-foundation/ui-settings';
3
+
4
+ export interface Diagnostic {
5
+ code: string;
6
+ severity: 'warning' | 'error';
7
+ message: string;
8
+ }
9
+ export interface Envelope {
10
+ attack: number;
11
+ decay: number;
12
+ sustain: number;
13
+ release: number;
14
+ curve?: 'linear' | 'exponential';
15
+ }
16
+ export interface VoicePart {
17
+ kind: 'tone' | 'noise';
18
+ wave: OscillatorType;
19
+ frequency: number;
20
+ to: number;
21
+ glide: number | null;
22
+ gain: number;
23
+ delay: number;
24
+ pan: number;
25
+ detune: number;
26
+ envelope: Envelope;
27
+ fm?: { ratio: number; index: number };
28
+ filter?: { type: BiquadFilterType; from: number; to: number; q: number };
29
+ }
30
+ export interface SoundVoice {
31
+ parts: VoicePart[];
32
+ repeat: number;
33
+ gap: number;
34
+ repeatDecay: number;
35
+ source: {
36
+ label: string;
37
+ license: string;
38
+ character?: string;
39
+ url?: string;
40
+ port?: string;
41
+ };
42
+ }
43
+ export interface SoundTheme {
44
+ name: string;
45
+ voices: Record<string, SoundVoice>;
46
+ events: Record<
47
+ string,
48
+ { mode: SoundMode; voices: string[]; throttle: number; level?: number }
49
+ >;
50
+ bus: {
51
+ shelf: [number, number];
52
+ compressor: [number, number];
53
+ reverb: number;
54
+ room?: number;
55
+ };
56
+ }
57
+ export function readSoundTheme(text: unknown): {
58
+ theme: SoundTheme | null;
59
+ diagnostics: Diagnostic[];
60
+ };
61
+ export interface SoundBus {
62
+ input: GainNode;
63
+ master: GainNode;
64
+ shelf: BiquadFilterNode;
65
+ convolver: ConvolverNode;
66
+ wet: GainNode;
67
+ configure(
68
+ values: Pick<
69
+ SoundRuntimeSettings,
70
+ 'volume' | 'tone' | 'frequency' | 'reverb' | 'room'
71
+ > & { maxVolume?: number }
72
+ ): void;
73
+ disconnect(): void;
74
+ }
75
+ export function createSoundBus(
76
+ audio: BaseAudioContext,
77
+ settings: SoundTheme['bus'],
78
+ random?: () => number
79
+ ): SoundBus;
80
+ export function playVoice(
81
+ audio: BaseAudioContext,
82
+ voice: SoundVoice,
83
+ output: AudioNode,
84
+ options?: {
85
+ at?: number;
86
+ pan?: number;
87
+ gain?: number;
88
+ detune?: number;
89
+ random?: () => number;
90
+ }
91
+ ): number;
92
+ export interface SoundConfig {
93
+ readonly schema?: SettingsSchema;
94
+ get(key: string): unknown;
95
+ set(key: string, value: unknown): unknown;
96
+ subscribe(listener: (...args: any[]) => void): () => void;
97
+ }
98
+ export interface SoundCue {
99
+ event: string;
100
+ pan: number;
101
+ }
102
+ export type SoundMode = 'random' | 'cycle' | 'layer';
103
+ export interface SoundEventSettings {
104
+ voices?: string[];
105
+ mode?: SoundMode;
106
+ level?: number;
107
+ throttle?: number;
108
+ }
109
+ export interface SoundRuntimeSettings {
110
+ enabled?: boolean;
111
+ volume?: number;
112
+ tone?: number;
113
+ frequency?: number;
114
+ reverb?: number;
115
+ room?: number;
116
+ pitchSpread?: number;
117
+ stereo?: boolean;
118
+ width?: number;
119
+ hoverGap?: number;
120
+ mode?: SoundMode | null;
121
+ events?: Record<string, SoundEventSettings>;
122
+ reducedMotionEvents?: string[];
123
+ }
124
+ export interface SoundPlayer {
125
+ play(event: string, options?: { x?: number }): string[];
126
+ cue(name: string, options?: { x?: number }): string[];
127
+ configure(values: SoundRuntimeSettings): void;
128
+ preview(voiceName: string, options?: { x?: number }): string[];
129
+ onCue(handler: (cue: SoundCue) => void): () => void;
130
+ setVolume(value: number): void;
131
+ mute(value?: boolean): void;
132
+ readonly enabled: boolean;
133
+ readonly volume: number;
134
+ readonly hoverGap: number;
135
+ dispose(): Promise<void>;
136
+ }
137
+ export function createSoundPlayer(options: {
138
+ theme: SoundTheme;
139
+ config?: SoundConfig;
140
+ now?: () => number;
141
+ random?: () => number;
142
+ createContext?: () => AudioContext;
143
+ gestureTarget?: EventTarget & { innerWidth?: number };
144
+ document?: Document;
145
+ hasBeenActive?: () => boolean;
146
+ maxVolume?: number;
147
+ reducedMotionEvents?: string[];
148
+ reducedMotion?: () => boolean;
149
+ onDiagnostic?: (diagnostic: Diagnostic) => void;
150
+ }): SoundPlayer;
151
+ export const DEFAULT_SOUND_MAPPING: string;
152
+ export function bindSound(
153
+ player: Pick<SoundPlayer, 'play'>,
154
+ options?: {
155
+ mapping?: string;
156
+ machines?: Array<{
157
+ subscribe(
158
+ listener: (snapshot: { event: { type: string } | null }) => void
159
+ ): () => void;
160
+ }>;
161
+ }
162
+ ): {
163
+ onAction(detail: { event: string }, event?: Event): void;
164
+ dispose(): void;
165
+ };
166
+ export const SOUND_SETTINGS_LINO: string;
167
+ export const SOUND_COMFORT_KEYS: readonly string[];
168
+ export function soundSettingsSchema(): SettingsSchema;
169
+ export function bindSoundConfig(
170
+ config: Config,
171
+ options?: { target?: string; schema?: SettingsSchema }
172
+ ): ReturnType<typeof import('@link-foundation/ui-settings').bindConfig> & {
173
+ readonly schema: SettingsSchema;
174
+ };
175
+
176
+ export function bindSoundToDocument(
177
+ player: Pick<SoundPlayer, 'play'> & Partial<Pick<SoundPlayer, 'hoverGap'>>,
178
+ options?: { root?: Document | Element; cueEvent?: string; now?: () => number }
179
+ ): { dispose(): void };
180
+ export interface SoundSettingsOptions {
181
+ slots?: number;
182
+ maxVolume?: number;
183
+ }
184
+ export type SoundSettingsEvent = string | { name: string; label?: string };
185
+ /** A nested LiNo schema fragment without a schema header. */
186
+ export function generateSoundSettings(
187
+ theme: SoundTheme,
188
+ events: SoundSettingsEvent[],
189
+ options?: SoundSettingsOptions
190
+ ): string;
191
+ export function createSoundSettingsSchema(
192
+ theme: SoundTheme,
193
+ events: SoundSettingsEvent[],
194
+ options?: SoundSettingsOptions
195
+ ): SettingsSchema;
196
+ export function soundEventKey(event: string, field: string): string;
package/src/index.js ADDED
@@ -0,0 +1,17 @@
1
+ export { readSoundTheme } from './theme.js';
2
+ export { createSoundBus, playVoice } from './graph.js';
3
+ export { createSoundPlayer } from './player.js';
4
+ export { bindSound, DEFAULT_SOUND_MAPPING } from './bind.js';
5
+ export {
6
+ bindSoundConfig,
7
+ soundSettingsSchema,
8
+ SOUND_SETTINGS_LINO,
9
+ SOUND_COMFORT_KEYS,
10
+ } from './comfort.js';
11
+
12
+ export {
13
+ generateSoundSettings,
14
+ createSoundSettingsSchema,
15
+ soundEventKey,
16
+ } from './settings.js';
17
+ export { bindSoundToDocument } from './document.js';
package/src/player.js ADDED
@@ -0,0 +1,214 @@
1
+ import { playVoice } from './graph.js';
2
+ import { audioSession } from './audio-session.js';
3
+ import {
4
+ bound,
5
+ chooseVoices,
6
+ configureRuntime,
7
+ runtimeSettings,
8
+ } from './runtime.js';
9
+ import { runtimeFromConfig } from './settings.js';
10
+
11
+ function trackGestures(target, state, session, update) {
12
+ const pointer = (event) => {
13
+ if (Number.isFinite(event.clientX)) {
14
+ update((event.clientX / Math.max(1, target.innerWidth ?? 1)) * 2 - 1);
15
+ }
16
+ };
17
+ const gesture = (event) => {
18
+ update();
19
+ session.retry();
20
+ pointer(event);
21
+ if (state.enabled) {
22
+ session.ensure();
23
+ }
24
+ };
25
+ target?.addEventListener('pointerdown', gesture, true);
26
+ target?.addEventListener('keydown', gesture, true);
27
+ target?.addEventListener('pointermove', pointer, true);
28
+ return () => {
29
+ target?.removeEventListener('pointerdown', gesture, true);
30
+ target?.removeEventListener('keydown', gesture, true);
31
+ target?.removeEventListener('pointermove', pointer, true);
32
+ };
33
+ }
34
+
35
+ function voiceScheduler({
36
+ state,
37
+ theme,
38
+ random,
39
+ session,
40
+ position,
41
+ isActivated,
42
+ }) {
43
+ return (names, level, options) => {
44
+ if (!state.enabled || state.volume <= 0 || !isActivated()) {
45
+ return [];
46
+ }
47
+ const context = session.ensure();
48
+ if (!context) {
49
+ return [];
50
+ }
51
+ const detune =
52
+ state.pitchSpread === 0 ? 0 : (random() * 2 - 1) * state.pitchSpread;
53
+ const variation =
54
+ state.pitchSpread === 0
55
+ ? 1
56
+ : 1 + (random() * 2 - 1) * 0.1 * Math.min(1, state.pitchSpread / 15);
57
+ for (const name of names) {
58
+ try {
59
+ playVoice(context.audio, theme.voices[name], context.bus.input, {
60
+ pan: position(options),
61
+ random,
62
+ detune,
63
+ gain: (level * variation) / Math.sqrt(names.length),
64
+ });
65
+ } catch (error) {
66
+ session.report(error);
67
+ }
68
+ }
69
+ return names;
70
+ };
71
+ }
72
+
73
+ /** Lazy opt-in player. Pre-activation plays are silent and never queued. */
74
+ export function createSoundPlayer({
75
+ theme,
76
+ config,
77
+ now = () => globalThis.performance.now(),
78
+ random = Math.random,
79
+ createContext = () => new globalThis.AudioContext(),
80
+ gestureTarget = globalThis.window,
81
+ document = gestureTarget?.document ?? globalThis.document,
82
+ hasBeenActive = () =>
83
+ globalThis.navigator?.userActivation?.hasBeenActive === true,
84
+ reducedMotion = () =>
85
+ globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ??
86
+ false,
87
+ reducedMotionEvents = ['intro', 'scan'],
88
+ maxVolume = 1,
89
+ onDiagnostic = () => {},
90
+ } = {}) {
91
+ const state = runtimeSettings(theme, bound(maxVolume, 1, 2, 1));
92
+ state.reducedMotionEvents = [...reducedMotionEvents];
93
+ configureRuntime(state, runtimeFromConfig(config, theme), theme);
94
+ let disposed = false;
95
+ let activated = false;
96
+ let pan = 0;
97
+ const listeners = new Set();
98
+ const last = new Map();
99
+ const turns = new Map();
100
+ const previous = new Map();
101
+ const session = audioSession({
102
+ theme,
103
+ state,
104
+ createContext,
105
+ random,
106
+ onDiagnostic,
107
+ document,
108
+ });
109
+ const stopGestures = trackGestures(gestureTarget, state, session, (value) => {
110
+ if (value === undefined) {
111
+ activated = true;
112
+ } else {
113
+ pan = bound(value, -1, 1);
114
+ }
115
+ });
116
+ const configure = (values = {}) => {
117
+ if (disposed) {
118
+ return;
119
+ }
120
+ configureRuntime(state, values, theme);
121
+ session.apply();
122
+ };
123
+ const stopConfig = config?.subscribe(() =>
124
+ configure(runtimeFromConfig(config, theme))
125
+ );
126
+ const position = (options) =>
127
+ state.stereo
128
+ ? (Number.isFinite(options.x) ? bound(options.x * 2 - 1, -1, 1) : pan) *
129
+ state.width
130
+ : 0;
131
+ const schedule = voiceScheduler({
132
+ state,
133
+ theme,
134
+ random,
135
+ session,
136
+ position,
137
+ isActivated: () => activated || hasBeenActive(),
138
+ });
139
+ const play = (event, options = {}) => {
140
+ const binding = Object.hasOwn(state.events, event)
141
+ ? state.events[event]
142
+ : null;
143
+ if (
144
+ disposed ||
145
+ !binding ||
146
+ (state.reducedMotionEvents.includes(event) && reducedMotion())
147
+ ) {
148
+ return [];
149
+ }
150
+ const time = now();
151
+ if (time - (last.get(event) ?? -Infinity) < binding.throttle) {
152
+ return [];
153
+ }
154
+ last.set(event, time);
155
+ for (const listener of [...listeners]) {
156
+ listener({ event, pan: position(options) });
157
+ }
158
+ if (!binding.voices.length) {
159
+ return [];
160
+ }
161
+ const turn = turns.get(event) ?? 0;
162
+ const chosen = chooseVoices(
163
+ binding,
164
+ state.mode ?? binding.mode,
165
+ turn,
166
+ previous.get(event),
167
+ random
168
+ );
169
+ const played = schedule(chosen, binding.level, options);
170
+ if (played.length) {
171
+ turns.set(event, turn + 1);
172
+ previous.set(event, chosen.at(-1));
173
+ }
174
+ return played;
175
+ };
176
+ return {
177
+ play,
178
+ cue: play,
179
+ configure,
180
+ preview(name, options = {}) {
181
+ return disposed || !Object.hasOwn(theme.voices, name)
182
+ ? []
183
+ : schedule([name], 1, options);
184
+ },
185
+ onCue(handler) {
186
+ listeners.add(handler);
187
+ return () => listeners.delete(handler);
188
+ },
189
+ setVolume(value) {
190
+ configure({ volume: bound(value, 0, state.maxVolume) });
191
+ config?.set('sound.volume', state.volume);
192
+ },
193
+ mute(value = true) {
194
+ configure({ enabled: !value });
195
+ config?.set('sound.enabled', state.enabled);
196
+ },
197
+ get enabled() {
198
+ return state.enabled;
199
+ },
200
+ get volume() {
201
+ return state.volume;
202
+ },
203
+ get hoverGap() {
204
+ return state.hoverGap;
205
+ },
206
+ async dispose() {
207
+ disposed = true;
208
+ stopGestures();
209
+ stopConfig?.();
210
+ listeners.clear();
211
+ await session.dispose();
212
+ },
213
+ };
214
+ }