@link-foundation/ui-sound 0.1.1 → 0.2.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/README.md CHANGED
@@ -54,10 +54,17 @@ A theme has named voices (oscillator/noise graphs, envelopes, optional
54
54
  filters/FM/delays/repeats), event modes `random`, `cycle`, `layer`, per-event
55
55
  throttling, a shelf/compressor/reverb bus, and per-voice provenance.
56
56
  [The specification](../../docs/spec/sound.md) defines all fields and bounds.
57
- `createSoundBus(context, settings, random)` and
57
+ `createSoundBus(context, settings, random, options)` and
58
58
  `playVoice(context, voice, output, options)` also accept an offline or fake
59
59
  BaseAudioContext directly. `playVoice` returns the scheduled end time.
60
60
 
61
+ The bus defaults to `gainPlacement: 'output'`, after the dry and wet signals
62
+ meet at the compressor. Select `gainPlacement: 'input'` for presets authored
63
+ for volume before the shelf, reverb and compressor. A `destination` accepts
64
+ an AudioNode in the bus's context or a function receiving that context.
65
+ Pass the same options as `bus` to `createSoundPlayer` to route its cues and
66
+ previews. The player resolves the destination when audio activates.
67
+
61
68
  Bundled themes are `quiet` (five soft voices) and `immortality` (all 26
62
69
  patches, including noise, FM and stereo parts). The port is from
63
70
  [konard/immortality at 16a6172](https://github.com/konard/immortality/tree/16a6172c38fc120133485f805c49d980b9850bc4)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@link-foundation/ui-sound",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Opt-in synthesized UI sounds with LiNo themes and viewer-owned comfort settings",
5
5
  "type": "module",
6
6
  "exports": {
@@ -43,7 +43,7 @@
43
43
  "links-notation": "^0.31.8"
44
44
  },
45
45
  "devDependencies": {
46
- "@link-foundation/ui-components": "^0.1.2",
46
+ "@link-foundation/ui-components": "^0.5.0",
47
47
  "jsdom": "^30.1.3",
48
48
  "test-anywhere": "^0.8.48"
49
49
  },
@@ -5,6 +5,7 @@ export function audioSession({
5
5
  theme,
6
6
  state,
7
7
  createContext,
8
+ busOptions,
8
9
  random,
9
10
  onDiagnostic,
10
11
  document,
@@ -39,7 +40,12 @@ export function audioSession({
39
40
  try {
40
41
  if (!audio) {
41
42
  audio = createContext();
42
- bus = createSoundBus(audio, { ...theme.bus, room: state.room }, random);
43
+ bus = createSoundBus(
44
+ audio,
45
+ { ...theme.bus, room: state.room },
46
+ random,
47
+ busOptions
48
+ );
43
49
  // Start silent before routing the first source, then ramp to preference.
44
50
  bus.master.gain.value = 0;
45
51
  apply();
package/src/graph.js CHANGED
@@ -31,8 +31,18 @@ function noiseBuffer(audio, seconds, channels, random, decay = false) {
31
31
  return buffer;
32
32
  }
33
33
 
34
- /** Shelf → dry/reverb → compressor → master volume (including wet tails). */
35
- export function createSoundBus(audio, settings, random = Math.random) {
34
+ /** Route volume before the effects or after compression (including wet tails). */
35
+ export function createSoundBus(
36
+ audio,
37
+ settings,
38
+ random = Math.random,
39
+ { gainPlacement = 'output', destination = audio.destination } = {}
40
+ ) {
41
+ if (!['input', 'output'].includes(gainPlacement)) {
42
+ throw new RangeError('Invalid sound bus gain placement');
43
+ }
44
+ const output =
45
+ typeof destination === 'function' ? destination(audio) : destination;
36
46
  const input = audio.createGain();
37
47
  const shelf = audio.createBiquadFilter();
38
48
  shelf.type = 'highshelf';
@@ -44,13 +54,15 @@ export function createSoundBus(audio, settings, random = Math.random) {
44
54
  compressor.knee.value = 12;
45
55
  compressor.attack.value = 0.003;
46
56
  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);
57
+ const master = gainPlacement === 'input' ? input : audio.createGain();
58
+ const nodes = [input, shelf, compressor];
59
+ input.connect(shelf).connect(compressor);
60
+ if (master === input) {
61
+ compressor.connect(output);
62
+ } else {
63
+ compressor.connect(master).connect(output);
64
+ nodes.push(master);
65
+ }
54
66
  const convolver = audio.createConvolver();
55
67
  const wet = audio.createGain();
56
68
  wet.gain.value = settings.reverb ?? 0.2;
package/src/index.d.ts CHANGED
@@ -58,8 +58,15 @@ export function readSoundTheme(text: unknown): {
58
58
  theme: SoundTheme | null;
59
59
  diagnostics: Diagnostic[];
60
60
  };
61
+ export interface SoundBusOptions {
62
+ /** Volume placement relative to the shelf, wet send and compressor. Default output. */
63
+ gainPlacement?: 'input' | 'output';
64
+ /** The output node, or a factory called with the lazily created context. */
65
+ destination?: AudioNode | ((audio: BaseAudioContext) => AudioNode);
66
+ }
61
67
  export interface SoundBus {
62
68
  input: GainNode;
69
+ /** The volume node. Equal to input when gainPlacement is input. */
63
70
  master: GainNode;
64
71
  shelf: BiquadFilterNode;
65
72
  convolver: ConvolverNode;
@@ -75,7 +82,8 @@ export interface SoundBus {
75
82
  export function createSoundBus(
76
83
  audio: BaseAudioContext,
77
84
  settings: SoundTheme['bus'],
78
- random?: () => number
85
+ random?: () => number,
86
+ options?: SoundBusOptions
79
87
  ): SoundBus;
80
88
  export function playVoice(
81
89
  audio: BaseAudioContext,
@@ -140,6 +148,7 @@ export function createSoundPlayer(options: {
140
148
  now?: () => number;
141
149
  random?: () => number;
142
150
  createContext?: () => AudioContext;
151
+ bus?: SoundBusOptions;
143
152
  gestureTarget?: EventTarget & { innerWidth?: number };
144
153
  document?: Document;
145
154
  hasBeenActive?: () => boolean;
package/src/player.js CHANGED
@@ -77,6 +77,7 @@ export function createSoundPlayer({
77
77
  now = () => globalThis.performance.now(),
78
78
  random = Math.random,
79
79
  createContext = () => new globalThis.AudioContext(),
80
+ bus: busOptions,
80
81
  gestureTarget = globalThis.window,
81
82
  document = gestureTarget?.document ?? globalThis.document,
82
83
  hasBeenActive = () =>
@@ -102,6 +103,7 @@ export function createSoundPlayer({
102
103
  theme,
103
104
  state,
104
105
  createContext,
106
+ busOptions,
105
107
  random,
106
108
  onDiagnostic,
107
109
  document,